docs: 更新 HTTP 错误码、用户积分、占卜运行及用户资料协议文档
This commit is contained in:
qzl
@@ -0,0 +1,13 @@
|
||||
Read the backend development guidelines before starting your development task.
|
||||
|
||||
Execute these steps:
|
||||
1. Read `.trellis/spec/backend/index.md` to understand available guidelines
|
||||
2. Based on your task, read the relevant guideline files:
|
||||
- Database work → `.trellis/spec/backend/database-guidelines.md`
|
||||
- Error handling → `.trellis/spec/backend/error-handling.md`
|
||||
- Logging → `.trellis/spec/backend/logging-guidelines.md`
|
||||
- Type questions → `.trellis/spec/backend/type-safety.md`
|
||||
3. Understand the coding standards and patterns you need to follow
|
||||
4. Then proceed with your development plan
|
||||
|
||||
This step is **mandatory** before writing any backend code.
|
||||
@@ -0,0 +1,13 @@
|
||||
Read the frontend development guidelines before starting your development task.
|
||||
|
||||
Execute these steps:
|
||||
1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
|
||||
2. Based on your task, read the relevant guideline files:
|
||||
- Component work → `.trellis/spec/frontend/component-guidelines.md`
|
||||
- Hook work → `.trellis/spec/frontend/hook-guidelines.md`
|
||||
- State management → `.trellis/spec/frontend/state-management.md`
|
||||
- Type questions → `.trellis/spec/frontend/type-safety.md`
|
||||
3. Understand the coding standards and patterns you need to follow
|
||||
4. Then proceed with your development plan
|
||||
|
||||
This step is **mandatory** before writing any frontend code.
|
||||
@@ -0,0 +1,487 @@
|
||||
# Brainstorm - Requirements Discovery (AI Coding Enhanced)
|
||||
|
||||
Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
|
||||
|
||||
* **Task-first** (capture ideas immediately)
|
||||
* **Action-before-asking** (reduce low-value questions)
|
||||
* **Research-first** for technical choices (avoid asking users to invent options)
|
||||
* **Diverge → Converge** (expand thinking, then lock MVP)
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
Triggered from `/trellis:start` when the user describes a development task, especially when:
|
||||
|
||||
* requirements are unclear or evolving
|
||||
* there are multiple valid implementation paths
|
||||
* trade-offs matter (UX, reliability, maintainability, cost, performance)
|
||||
* the user might not know the best options up front
|
||||
|
||||
---
|
||||
|
||||
## Core Principles (Non-negotiable)
|
||||
|
||||
1. **Task-first (capture early)**
|
||||
Always ensure a task exists at the start so the user's ideas are recorded immediately.
|
||||
|
||||
2. **Action before asking**
|
||||
If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
|
||||
|
||||
3. **One question per message**
|
||||
Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
|
||||
|
||||
4. **Prefer concrete options**
|
||||
For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
|
||||
|
||||
5. **Research-first for technical choices**
|
||||
If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
|
||||
|
||||
6. **Diverge → Converge**
|
||||
After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
|
||||
|
||||
7. **No meta questions**
|
||||
Do not ask "should I search?" or "can you paste the code so I can continue?"
|
||||
If you need information: search/inspect. If blocked: ask the minimal blocking question.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Ensure Task Exists (ALWAYS)
|
||||
|
||||
Before any Q&A, ensure a task exists. If none exists, create one immediately.
|
||||
|
||||
* Use a **temporary working title** derived from the user's message.
|
||||
* It's OK if the title is imperfect — refine later in PRD.
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
|
||||
```
|
||||
|
||||
Create/seed `prd.md` immediately with what you know:
|
||||
|
||||
```markdown
|
||||
# brainstorm: <short goal>
|
||||
|
||||
## Goal
|
||||
|
||||
<one paragraph: what + why>
|
||||
|
||||
## What I already know
|
||||
|
||||
* <facts from user message>
|
||||
* <facts discovered from repo/docs>
|
||||
|
||||
## Assumptions (temporary)
|
||||
|
||||
* <assumptions to validate>
|
||||
|
||||
## Open Questions
|
||||
|
||||
* <ONLY Blocking / Preference questions; keep list short>
|
||||
|
||||
## Requirements (evolving)
|
||||
|
||||
* <start with what is known>
|
||||
|
||||
## Acceptance Criteria (evolving)
|
||||
|
||||
* [ ] <testable criterion>
|
||||
|
||||
## Definition of Done (team quality bar)
|
||||
|
||||
* Tests added/updated (unit/integration where appropriate)
|
||||
* Lint / typecheck / CI green
|
||||
* Docs/notes updated if behavior changes
|
||||
* Rollout/rollback considered if risky
|
||||
|
||||
## Out of Scope (explicit)
|
||||
|
||||
* <what we will not do in this task>
|
||||
|
||||
## Technical Notes
|
||||
|
||||
* <files inspected, constraints, links, references>
|
||||
* <research notes summary if applicable>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
|
||||
|
||||
Before asking questions like "what does the code look like?", gather context yourself:
|
||||
|
||||
### Repo inspection checklist
|
||||
|
||||
* Identify likely modules/files impacted
|
||||
* Locate existing patterns (similar features, conventions, error handling style)
|
||||
* Check configs, scripts, existing command definitions
|
||||
* Note any constraints (runtime, dependency policy, build tooling)
|
||||
|
||||
### Documentation checklist
|
||||
|
||||
* Look for existing PRDs/specs/templates
|
||||
* Look for command usage examples, README, ADRs if any
|
||||
|
||||
Write findings into PRD:
|
||||
|
||||
* Add to `What I already know`
|
||||
* Add constraints/links to `Technical Notes`
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Classify Complexity (still useful, not gating task creation)
|
||||
|
||||
| Complexity | Criteria | Action |
|
||||
| ------------ | ------------------------------------------------------ | ------------------------------------------- |
|
||||
| **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly |
|
||||
| **Simple** | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement |
|
||||
| **Moderate** | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) |
|
||||
| **Complex** | Vague goal, architectural choices, multiple approaches | Full brainstorm |
|
||||
|
||||
> Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Question Gate (Ask ONLY high-value questions)
|
||||
|
||||
Before asking ANY question, run the following gate:
|
||||
|
||||
### Gate A — Can I derive this without the user?
|
||||
|
||||
If answer is available via:
|
||||
|
||||
* repo inspection (code/config)
|
||||
* docs/specs/conventions
|
||||
* quick market/OSS research
|
||||
|
||||
→ **Do not ask.** Fetch it, summarize, update PRD.
|
||||
|
||||
### Gate B — Is this a meta/lazy question?
|
||||
|
||||
Examples:
|
||||
|
||||
* "Should I search?"
|
||||
* "Can you paste the code so I can proceed?"
|
||||
* "What does the code look like?" (when repo is available)
|
||||
|
||||
→ **Do not ask.** Take action.
|
||||
|
||||
### Gate C — What type of question is it?
|
||||
|
||||
* **Blocking**: cannot proceed without user input
|
||||
* **Preference**: multiple valid choices, depends on product/UX/risk preference
|
||||
* **Derivable**: should be answered by inspection/research
|
||||
|
||||
→ Only ask **Blocking** or **Preference**.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Research-first Mode (Mandatory for technical choices)
|
||||
|
||||
### Trigger conditions (any → research-first)
|
||||
|
||||
* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
|
||||
* The user asks for "best practice", "how others do it", "recommendation"
|
||||
* The user can't reasonably enumerate options
|
||||
|
||||
### Research steps
|
||||
|
||||
1. Identify 2–4 comparable tools/patterns
|
||||
2. Summarize common conventions and why they exist
|
||||
3. Map conventions onto our repo constraints
|
||||
4. Produce **2–3 feasible approaches** for our project
|
||||
|
||||
### Research output format (PRD)
|
||||
|
||||
Add a section in PRD (either within Technical Notes or as its own):
|
||||
|
||||
```markdown
|
||||
## Research Notes
|
||||
|
||||
### What similar tools do
|
||||
|
||||
* ...
|
||||
* ...
|
||||
|
||||
### Constraints from our repo/project
|
||||
|
||||
* ...
|
||||
|
||||
### Feasible approaches here
|
||||
|
||||
**Approach A: <name>** (Recommended)
|
||||
|
||||
* How it works:
|
||||
* Pros:
|
||||
* Cons:
|
||||
|
||||
**Approach B: <name>**
|
||||
|
||||
* How it works:
|
||||
* Pros:
|
||||
* Cons:
|
||||
|
||||
**Approach C: <name>** (optional)
|
||||
|
||||
* ...
|
||||
```
|
||||
|
||||
Then ask **one** preference question:
|
||||
|
||||
* "Which approach do you prefer: A / B / C (or other)?"
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding
|
||||
|
||||
After you can summarize the goal, proactively broaden thinking before converging.
|
||||
|
||||
### Expansion categories (keep to 1–2 bullets each)
|
||||
|
||||
1. **Future evolution**
|
||||
|
||||
* What might this feature become in 1–3 months?
|
||||
* What extension points are worth preserving now?
|
||||
|
||||
2. **Related scenarios**
|
||||
|
||||
* What adjacent commands/flows should remain consistent with this?
|
||||
* Are there parity expectations (create vs update, import vs export, etc.)?
|
||||
|
||||
3. **Failure & edge cases**
|
||||
|
||||
* Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
|
||||
* Input validation, security boundaries, permission checks
|
||||
|
||||
### Expansion message template (to user)
|
||||
|
||||
```markdown
|
||||
I understand you want to implement: <current goal>.
|
||||
|
||||
Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
|
||||
|
||||
1. Future evolution: <1–2 bullets>
|
||||
2. Related scenarios: <1–2 bullets>
|
||||
3. Failure/edge cases: <1–2 bullets>
|
||||
|
||||
For this MVP, which would you like to include (or none)?
|
||||
|
||||
1. Current requirement only (minimal viable)
|
||||
2. Add <X> (reserve for future extension)
|
||||
3. Add <Y> (improve robustness/consistency)
|
||||
4. Other: describe your preference
|
||||
```
|
||||
|
||||
Then update PRD:
|
||||
|
||||
* What's in MVP → `Requirements`
|
||||
* What's excluded → `Out of Scope`
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Q&A Loop (CONVERGE)
|
||||
|
||||
### Rules
|
||||
|
||||
* One question per message
|
||||
* Prefer multiple-choice when possible
|
||||
* After each user answer:
|
||||
|
||||
* Update PRD immediately
|
||||
* Move answered items from `Open Questions` → `Requirements`
|
||||
* Update `Acceptance Criteria` with testable checkboxes
|
||||
* Clarify `Out of Scope`
|
||||
|
||||
### Question priority (recommended)
|
||||
|
||||
1. **MVP scope boundary** (what is included/excluded)
|
||||
2. **Preference decisions** (after presenting concrete options)
|
||||
3. **Failure/edge behavior** (only for MVP-critical paths)
|
||||
4. **Success metrics & Acceptance Criteria** (what proves it works)
|
||||
|
||||
### Preferred question format (multiple choice)
|
||||
|
||||
```markdown
|
||||
For <topic>, which approach do you prefer?
|
||||
|
||||
1. **Option A** — <what it means + trade-off>
|
||||
2. **Option B** — <what it means + trade-off>
|
||||
3. **Option C** — <what it means + trade-off>
|
||||
4. **Other** — describe your preference
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Propose Approaches + Record Decisions (Complex tasks)
|
||||
|
||||
After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
|
||||
|
||||
```markdown
|
||||
Based on current information, here are 2–3 feasible approaches:
|
||||
|
||||
**Approach A: <name>** (Recommended)
|
||||
|
||||
* How:
|
||||
* Pros:
|
||||
* Cons:
|
||||
|
||||
**Approach B: <name>**
|
||||
|
||||
* How:
|
||||
* Pros:
|
||||
* Cons:
|
||||
|
||||
Which direction do you prefer?
|
||||
```
|
||||
|
||||
Record the outcome in PRD as an ADR-lite section:
|
||||
|
||||
```markdown
|
||||
## Decision (ADR-lite)
|
||||
|
||||
**Context**: Why this decision was needed
|
||||
**Decision**: Which approach was chosen
|
||||
**Consequences**: Trade-offs, risks, potential future improvements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Final Confirmation + Implementation Plan
|
||||
|
||||
When open questions are resolved, confirm complete requirements with a structured summary:
|
||||
|
||||
### Final confirmation format
|
||||
|
||||
```markdown
|
||||
Here's my understanding of the complete requirements:
|
||||
|
||||
**Goal**: <one sentence>
|
||||
|
||||
**Requirements**:
|
||||
|
||||
* ...
|
||||
* ...
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
* [ ] ...
|
||||
* [ ] ...
|
||||
|
||||
**Definition of Done**:
|
||||
|
||||
* ...
|
||||
|
||||
**Out of Scope**:
|
||||
|
||||
* ...
|
||||
|
||||
**Technical Approach**:
|
||||
<brief summary + key decisions>
|
||||
|
||||
**Implementation Plan (small PRs)**:
|
||||
|
||||
* PR1: <scaffolding + tests + minimal plumbing>
|
||||
* PR2: <core behavior>
|
||||
* PR3: <edge cases + docs + cleanup>
|
||||
|
||||
Does this look correct? If yes, I'll proceed with implementation.
|
||||
```
|
||||
|
||||
### Subtask Decomposition (Complex Tasks)
|
||||
|
||||
For complex tasks with multiple independent work items, create subtasks:
|
||||
|
||||
```bash
|
||||
# Create child tasks
|
||||
CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
|
||||
CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
|
||||
|
||||
# Or link existing tasks
|
||||
python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PRD Target Structure (final)
|
||||
|
||||
`prd.md` should converge to:
|
||||
|
||||
```markdown
|
||||
# <Task Title>
|
||||
|
||||
## Goal
|
||||
|
||||
<why + what>
|
||||
|
||||
## Requirements
|
||||
|
||||
* ...
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* [ ] ...
|
||||
|
||||
## Definition of Done
|
||||
|
||||
* ...
|
||||
|
||||
## Technical Approach
|
||||
|
||||
<key design + decisions>
|
||||
|
||||
## Decision (ADR-lite)
|
||||
|
||||
Context / Decision / Consequences
|
||||
|
||||
## Out of Scope
|
||||
|
||||
* ...
|
||||
|
||||
## Technical Notes
|
||||
|
||||
<constraints, references, files, research notes>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns (Hard Avoid)
|
||||
|
||||
* Asking user for code/context that can be derived from repo
|
||||
* Asking user to choose an approach before presenting concrete options
|
||||
* Meta questions about whether to research
|
||||
* Staying narrowly on the initial request without considering evolution/edges
|
||||
* Letting brainstorming drift without updating PRD
|
||||
|
||||
---
|
||||
|
||||
## Integration with Start Workflow
|
||||
|
||||
After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
|
||||
|
||||
```text
|
||||
Brainstorm
|
||||
Step 0: Create task directory + seed PRD
|
||||
Step 1–7: Discover requirements, research, converge
|
||||
Step 8: Final confirmation → user approves
|
||||
↓
|
||||
Task Workflow Phase 2 (Prepare for Implementation)
|
||||
Code-Spec Depth Check (if applicable)
|
||||
→ Research codebase (based on confirmed PRD)
|
||||
→ Configure code-spec context (jsonl files)
|
||||
→ Activate task
|
||||
↓
|
||||
Task Workflow Phase 3 (Execute)
|
||||
Implement → Check → Complete
|
||||
```
|
||||
|
||||
The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
| Command | When to Use |
|
||||
|---------|-------------|
|
||||
| `/trellis:start` | Entry point that triggers brainstorm |
|
||||
| `/trellis:finish-work` | After implementation is complete |
|
||||
| `/trellis:update-spec` | If new patterns emerge during work |
|
||||
@@ -0,0 +1,125 @@
|
||||
# Break the Loop - Deep Bug Analysis
|
||||
|
||||
When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
|
||||
|
||||
---
|
||||
|
||||
## Analysis Framework
|
||||
|
||||
Analyze the bug you just fixed from these 5 dimensions:
|
||||
|
||||
### 1. Root Cause Category
|
||||
|
||||
Which category does this bug belong to?
|
||||
|
||||
| Category | Characteristics | Example |
|
||||
|----------|-----------------|---------|
|
||||
| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
|
||||
| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
|
||||
| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
|
||||
| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
|
||||
| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
|
||||
|
||||
### 2. Why Fixes Failed (if applicable)
|
||||
|
||||
If you tried multiple fixes before succeeding, analyze each failure:
|
||||
|
||||
- **Surface Fix**: Fixed symptom, not root cause
|
||||
- **Incomplete Scope**: Found root cause, didn't cover all cases
|
||||
- **Tool Limitation**: grep missed it, type check wasn't strict
|
||||
- **Mental Model**: Kept looking in same layer, didn't think cross-layer
|
||||
|
||||
### 3. Prevention Mechanisms
|
||||
|
||||
What mechanisms would prevent this from happening again?
|
||||
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| **Documentation** | Write it down so people know | Update thinking guide |
|
||||
| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
|
||||
| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
|
||||
| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
|
||||
| **Test Coverage** | E2E tests, integration tests | Verify full flow |
|
||||
| **Code Review** | Checklist, PR template | "Did you check X?" |
|
||||
|
||||
### 4. Systematic Expansion
|
||||
|
||||
What broader problems does this bug reveal?
|
||||
|
||||
- **Similar Issues**: Where else might this problem exist?
|
||||
- **Design Flaw**: Is there a fundamental architecture issue?
|
||||
- **Process Flaw**: Is there a development process improvement?
|
||||
- **Knowledge Gap**: Is the team missing some understanding?
|
||||
|
||||
### 5. Knowledge Capture
|
||||
|
||||
Solidify insights into the system:
|
||||
|
||||
- [ ] Update `.trellis/spec/guides/` thinking guides
|
||||
- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
|
||||
- [ ] Create issue record (if applicable)
|
||||
- [ ] Create feature ticket for root fix
|
||||
- [ ] Update check commands if needed
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Please output analysis in this format:
|
||||
|
||||
```markdown
|
||||
## Bug Analysis: [Short Description]
|
||||
|
||||
### 1. Root Cause Category
|
||||
- **Category**: [A/B/C/D/E] - [Category Name]
|
||||
- **Specific Cause**: [Detailed description]
|
||||
|
||||
### 2. Why Fixes Failed (if applicable)
|
||||
1. [First attempt]: [Why it failed]
|
||||
2. [Second attempt]: [Why it failed]
|
||||
...
|
||||
|
||||
### 3. Prevention Mechanisms
|
||||
| Priority | Mechanism | Specific Action | Status |
|
||||
|----------|-----------|-----------------|--------|
|
||||
| P0 | ... | ... | TODO/DONE |
|
||||
|
||||
### 4. Systematic Expansion
|
||||
- **Similar Issues**: [List places with similar problems]
|
||||
- **Design Improvement**: [Architecture-level suggestions]
|
||||
- **Process Improvement**: [Development process suggestions]
|
||||
|
||||
### 5. Knowledge Capture
|
||||
- [ ] [Documents to update / tickets to create]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
|
||||
|
||||
Three levels of insight:
|
||||
1. **Tactical**: How to fix THIS bug
|
||||
2. **Strategic**: How to prevent THIS CLASS of bugs
|
||||
3. **Philosophical**: How to expand thinking patterns
|
||||
|
||||
30 minutes of analysis saves 30 hours of future debugging.
|
||||
|
||||
---
|
||||
|
||||
## After Analysis: Immediate Actions
|
||||
|
||||
**IMPORTANT**: After completing the analysis above, you MUST immediately:
|
||||
|
||||
1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
|
||||
- If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
|
||||
- If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
|
||||
- If it's a code reuse issue → update `code-reuse-thinking-guide.md`
|
||||
- If it's domain-specific → update `backend/*.md` or `frontend/*.md`
|
||||
|
||||
2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
|
||||
|
||||
3. **Commit the spec updates** - This is the primary output, not just the analysis text
|
||||
|
||||
> **The analysis is worthless if it stays in chat. The value is in the updated specs.**
|
||||
@@ -0,0 +1,13 @@
|
||||
Check if the code you just wrote follows the backend development guidelines.
|
||||
|
||||
Execute these steps:
|
||||
1. Run `git status` to see modified files
|
||||
2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
|
||||
3. Based on what you changed, read the relevant guideline files:
|
||||
- Database changes → `.trellis/spec/backend/database-guidelines.md`
|
||||
- Error handling → `.trellis/spec/backend/error-handling.md`
|
||||
- Logging changes → `.trellis/spec/backend/logging-guidelines.md`
|
||||
- Type changes → `.trellis/spec/backend/type-safety.md`
|
||||
- Any changes → `.trellis/spec/backend/quality-guidelines.md`
|
||||
4. Review your code against the guidelines
|
||||
5. Report any violations and fix them if found
|
||||
@@ -0,0 +1,153 @@
|
||||
# Cross-Layer Check
|
||||
|
||||
Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
|
||||
|
||||
> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code.
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
| Document | Purpose | Timing |
|
||||
|----------|---------|--------|
|
||||
| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
|
||||
| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
|
||||
| **`/trellis:check-cross-layer`** (this) | Verification check | **After** implementation |
|
||||
|
||||
---
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Identify Change Scope
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff --name-only
|
||||
```
|
||||
|
||||
### 2. Select Applicable Check Dimensions
|
||||
|
||||
Based on your change type, execute relevant checks below:
|
||||
|
||||
---
|
||||
|
||||
## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
|
||||
|
||||
**Trigger**: Changes involve 3 or more layers
|
||||
|
||||
| Layer | Common Locations |
|
||||
|-------|------------------|
|
||||
| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
|
||||
| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
|
||||
| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
|
||||
| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
|
||||
| Utility | `utils/`, `helpers/`, `common/` |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Read flow: Database -> Service -> API -> UI
|
||||
- [ ] Write flow: UI -> API -> Service -> Database
|
||||
- [ ] Types/schemas correctly passed between layers?
|
||||
- [ ] Errors properly propagated to caller?
|
||||
- [ ] Loading/pending states handled at each layer?
|
||||
|
||||
**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## Dimension B: Code Reuse (Required when modifying constants/config)
|
||||
|
||||
**Trigger**:
|
||||
- Modifying UI constants (label, icon, color)
|
||||
- Modifying any hardcoded value
|
||||
- Seeing similar code in multiple places
|
||||
- Creating a new utility/helper function
|
||||
- Just finished batch modifications across files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search first: How many places define this value?
|
||||
```bash
|
||||
# Search in source files (adjust extensions for your project)
|
||||
grep -r "value-to-change" src/
|
||||
```
|
||||
- [ ] If 2+ places define same value -> Should extract to shared constant
|
||||
- [ ] After modification, all usage sites updated?
|
||||
- [ ] If creating utility: Does similar utility already exist?
|
||||
|
||||
**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md`
|
||||
|
||||
---
|
||||
|
||||
## Dimension B2: New Utility Functions
|
||||
|
||||
**Trigger**: About to create a new utility/helper function
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search for existing similar utilities first
|
||||
```bash
|
||||
grep -r "functionNamePattern" src/
|
||||
```
|
||||
- [ ] If similar exists, can you extend it instead?
|
||||
- [ ] If creating new, is it in the right location (shared vs domain-specific)?
|
||||
|
||||
---
|
||||
|
||||
## Dimension B3: After Batch Modifications
|
||||
|
||||
**Trigger**: Just modified similar patterns in multiple files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Did you check ALL files with similar patterns?
|
||||
```bash
|
||||
grep -r "patternYouChanged" src/
|
||||
```
|
||||
- [ ] Any files missed that should also be updated?
|
||||
- [ ] Should this pattern be abstracted to prevent future duplication?
|
||||
|
||||
---
|
||||
|
||||
## Dimension C: Import/Dependency Paths (Required when creating new files)
|
||||
|
||||
**Trigger**: Creating new source files
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Using correct import paths (relative vs absolute)?
|
||||
- [ ] No circular dependencies?
|
||||
- [ ] Consistent with project's module organization?
|
||||
|
||||
---
|
||||
|
||||
## Dimension D: Same-Layer Consistency
|
||||
|
||||
**Trigger**:
|
||||
- Modifying display logic or formatting
|
||||
- Same domain concept used in multiple places
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Search for other places using same concept
|
||||
```bash
|
||||
grep -r "ConceptName" src/
|
||||
```
|
||||
- [ ] Are these usages consistent?
|
||||
- [ ] Should they share configuration/constants?
|
||||
|
||||
---
|
||||
|
||||
## Common Issues Quick Reference
|
||||
|
||||
| Issue | Root Cause | Prevention |
|
||||
|-------|------------|------------|
|
||||
| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
|
||||
| Data lost at some layer | Didn't check data flow | Trace data source to destination |
|
||||
| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
|
||||
| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
|
||||
| Similar utility exists | Didn't search first | Search before creating |
|
||||
| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Report:
|
||||
1. Which dimensions your changes involve
|
||||
2. Check results for each dimension
|
||||
3. Issues found and fix suggestions
|
||||
@@ -0,0 +1,13 @@
|
||||
Check if the code you just wrote follows the frontend development guidelines.
|
||||
|
||||
Execute these steps:
|
||||
1. Run `git status` to see modified files
|
||||
2. Read `.trellis/spec/frontend/index.md` to understand which guidelines apply
|
||||
3. Based on what you changed, read the relevant guideline files:
|
||||
- Component changes → `.trellis/spec/frontend/component-guidelines.md`
|
||||
- Hook changes → `.trellis/spec/frontend/hook-guidelines.md`
|
||||
- State changes → `.trellis/spec/frontend/state-management.md`
|
||||
- Type changes → `.trellis/spec/frontend/type-safety.md`
|
||||
- Any changes → `.trellis/spec/frontend/quality-guidelines.md`
|
||||
4. Review your code against the guidelines
|
||||
5. Report any violations and fix them if found
|
||||
@@ -0,0 +1,154 @@
|
||||
# Create New Slash Command
|
||||
|
||||
Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.opencode/commands/trellis/` directories based on user requirements.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/trellis:create-command <command-name> <description>
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
/trellis:create-command review-pr Check PR code changes against project guidelines
|
||||
```
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Parse Input
|
||||
|
||||
Extract from user input:
|
||||
- **Command name**: Use kebab-case (e.g., `review-pr`)
|
||||
- **Description**: What the command should accomplish
|
||||
|
||||
### 2. Analyze Requirements
|
||||
|
||||
Determine command type based on description:
|
||||
- **Initialization**: Read docs, establish context
|
||||
- **Pre-development**: Read guidelines, check dependencies
|
||||
- **Code check**: Validate code quality and guideline compliance
|
||||
- **Recording**: Record progress, questions, structure changes
|
||||
- **Generation**: Generate docs, code templates
|
||||
|
||||
### 3. Generate Command Content
|
||||
|
||||
Based on command type, generate appropriate content:
|
||||
|
||||
**Simple command** (1-3 lines):
|
||||
```markdown
|
||||
Concise instruction describing what to do
|
||||
```
|
||||
|
||||
**Complex command** (with steps):
|
||||
```markdown
|
||||
# Command Title
|
||||
|
||||
Command description
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. First Step
|
||||
Specific action
|
||||
|
||||
### 2. Second Step
|
||||
Specific action
|
||||
|
||||
## Output Format (if needed)
|
||||
|
||||
Template
|
||||
```
|
||||
|
||||
### 4. Create Files
|
||||
|
||||
Create in both directories:
|
||||
- `.cursor/commands/trellis-<command-name>.md`
|
||||
- `.opencode/commands/trellis/<command-name>.md`
|
||||
|
||||
### 5. Confirm Creation
|
||||
|
||||
Output result:
|
||||
```
|
||||
[OK] Created Slash Command: /<command-name>
|
||||
|
||||
File paths:
|
||||
- .cursor/commands/trellis-<command-name>.md
|
||||
- .opencode/commands/trellis/<command-name>.md
|
||||
|
||||
Usage:
|
||||
/trellis:<command-name>
|
||||
|
||||
Description:
|
||||
<description>
|
||||
```
|
||||
|
||||
## Command Content Guidelines
|
||||
|
||||
### [OK] Good command content
|
||||
|
||||
1. **Clear and concise**: Immediately understandable
|
||||
2. **Executable**: AI can follow steps directly
|
||||
3. **Well-scoped**: Clear boundaries of what to do and not do
|
||||
4. **Has output**: Specifies expected output format (if needed)
|
||||
|
||||
### [X] Avoid
|
||||
|
||||
1. **Too vague**: e.g., "optimize code"
|
||||
2. **Too complex**: Single command should not exceed 100 lines
|
||||
3. **Duplicate functionality**: Check if similar command exists first
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Command Type | Prefix | Example |
|
||||
|--------------|--------|---------|
|
||||
| Session Start | `start` | `start` |
|
||||
| Pre-development | `before-` | `before-frontend-dev` |
|
||||
| Check | `check-` | `check-frontend` |
|
||||
| Record | `record-` | `record-session` |
|
||||
| Generate | `generate-` | `generate-api-doc` |
|
||||
| Update | `update-` | `update-changelog` |
|
||||
| Other | Verb-first | `review-code`, `sync-data` |
|
||||
|
||||
## Example
|
||||
|
||||
### Input
|
||||
```
|
||||
/trellis:create-command review-pr Check PR code changes against project guidelines
|
||||
```
|
||||
|
||||
### Generated Command Content
|
||||
```markdown
|
||||
# PR Code Review
|
||||
|
||||
Check current PR code changes against project guidelines.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Get Changed Files
|
||||
```bash
|
||||
git diff main...HEAD --name-only
|
||||
```
|
||||
|
||||
### 2. Categorized Review
|
||||
|
||||
**Frontend files** (`apps/web/`):
|
||||
- Reference `.trellis/spec/frontend/index.md`
|
||||
|
||||
**Backend files** (`packages/api/`):
|
||||
- Reference `.trellis/spec/backend/index.md`
|
||||
|
||||
### 3. Output Review Report
|
||||
|
||||
Format:
|
||||
|
||||
## PR Review Report
|
||||
|
||||
### Changed Files
|
||||
- [file list]
|
||||
|
||||
### Check Results
|
||||
- [OK] Passed items
|
||||
- [X] Issues found
|
||||
|
||||
### Suggestions
|
||||
- [improvement suggestions]
|
||||
```
|
||||
@@ -0,0 +1,144 @@
|
||||
# Finish Work - Pre-Commit Checklist
|
||||
|
||||
Before submitting or committing, use this checklist to ensure work completeness.
|
||||
|
||||
**Timing**: After code is written and tested, before commit
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
### 1. Code Quality
|
||||
|
||||
```bash
|
||||
# Must pass
|
||||
pnpm lint
|
||||
pnpm type-check
|
||||
pnpm test
|
||||
```
|
||||
|
||||
- [ ] `pnpm lint` passes with 0 errors?
|
||||
- [ ] `pnpm type-check` passes with no type errors?
|
||||
- [ ] Tests pass?
|
||||
- [ ] No `console.log` statements (use logger)?
|
||||
- [ ] No non-null assertions (the `x!` operator)?
|
||||
- [ ] No `any` types?
|
||||
|
||||
### 2. Code-Spec Sync
|
||||
|
||||
**Code-Spec Docs**:
|
||||
- [ ] Does `.trellis/spec/backend/` need updates?
|
||||
- New patterns, new modules, new conventions
|
||||
- [ ] Does `.trellis/spec/frontend/` need updates?
|
||||
- New components, new hooks, new patterns
|
||||
- [ ] Does `.trellis/spec/guides/` need updates?
|
||||
- New cross-layer flows, lessons from bugs
|
||||
|
||||
**Key Question**:
|
||||
> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
|
||||
|
||||
If YES -> Update the relevant code-spec doc.
|
||||
|
||||
### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
|
||||
|
||||
If this change touches infra or cross-layer contracts, this is a blocking checklist:
|
||||
|
||||
- [ ] Spec content is executable (real signatures/contracts), not principle-only text
|
||||
- [ ] Includes file path + command/API name + payload field names
|
||||
- [ ] Includes validation and error matrix
|
||||
- [ ] Includes Good/Base/Bad cases
|
||||
- [ ] Includes required tests and assertion points
|
||||
|
||||
**Block Rule**:
|
||||
In pipeline mode, the finish agent will automatically detect and execute spec updates when gaps are found.
|
||||
If running this checklist manually, ensure spec sync is complete before committing — run `/trellis:update-spec` if needed.
|
||||
|
||||
### 3. API Changes
|
||||
|
||||
If you modified API endpoints:
|
||||
|
||||
- [ ] Input schema updated?
|
||||
- [ ] Output schema updated?
|
||||
- [ ] API documentation updated?
|
||||
- [ ] Client code updated to match?
|
||||
|
||||
### 4. Database Changes
|
||||
|
||||
If you modified database schema:
|
||||
|
||||
- [ ] Migration file created?
|
||||
- [ ] Schema file updated?
|
||||
- [ ] Related queries updated?
|
||||
- [ ] Seed data updated (if applicable)?
|
||||
|
||||
### 5. Cross-Layer Verification
|
||||
|
||||
If the change spans multiple layers:
|
||||
|
||||
- [ ] Data flows correctly through all layers?
|
||||
- [ ] Error handling works at each boundary?
|
||||
- [ ] Types are consistent across layers?
|
||||
- [ ] Loading states handled?
|
||||
|
||||
### 6. Manual Testing
|
||||
|
||||
- [ ] Feature works in browser/app?
|
||||
- [ ] Edge cases tested?
|
||||
- [ ] Error states tested?
|
||||
- [ ] Works after page refresh?
|
||||
|
||||
---
|
||||
|
||||
## Quick Check Flow
|
||||
|
||||
```bash
|
||||
# 1. Code checks
|
||||
pnpm lint && pnpm type-check
|
||||
|
||||
# 2. View changes
|
||||
git status
|
||||
git diff --name-only
|
||||
|
||||
# 3. Based on changed files, check relevant items above
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Oversights
|
||||
|
||||
| Oversight | Consequence | Check |
|
||||
|-----------|-------------|-------|
|
||||
| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
|
||||
| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
|
||||
| Migration not created | Schema out of sync | Check db/migrations/ |
|
||||
| Types not synced | Runtime errors | Check shared types |
|
||||
| Tests not updated | False confidence | Run full test suite |
|
||||
| Console.log left in | Noisy production logs | Search for console.log |
|
||||
|
||||
---
|
||||
|
||||
## Relationship to Other Commands
|
||||
|
||||
```
|
||||
Development Flow:
|
||||
Write code -> Test -> /trellis:finish-work -> git commit -> /trellis:record-session
|
||||
| |
|
||||
Ensure completeness Record progress
|
||||
|
||||
Debug Flow:
|
||||
Hit bug -> Fix -> /trellis:break-loop -> Knowledge capture
|
||||
|
|
||||
Deep analysis
|
||||
```
|
||||
|
||||
- `/trellis:finish-work` - Check work completeness (this command)
|
||||
- `/trellis:record-session` - Record session and commits
|
||||
- `/trellis:break-loop` - Deep analysis after debugging
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
|
||||
|
||||
Complete work = Code + Docs + Tests + Verification
|
||||
@@ -0,0 +1,219 @@
|
||||
# Integrate Claude Skill into Project Guidelines
|
||||
|
||||
Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/trellis:integrate-skill <skill-name>
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
/trellis:integrate-skill frontend-design
|
||||
/trellis:integrate-skill mcp-builder
|
||||
```
|
||||
|
||||
## Core Principle
|
||||
|
||||
> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly.
|
||||
>
|
||||
> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md`
|
||||
> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/`
|
||||
> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors
|
||||
>
|
||||
> Where `{target}` is `frontend` or `backend`, determined by skill type.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Read Skill Content
|
||||
|
||||
```bash
|
||||
openskills read <skill-name>
|
||||
```
|
||||
|
||||
If the skill doesn't exist, prompt user to check available skills:
|
||||
```bash
|
||||
# Available skills are listed in AGENTS.md under <available_skills>
|
||||
```
|
||||
|
||||
### 2. Determine Integration Target
|
||||
|
||||
Based on skill type, determine which guidelines to update:
|
||||
|
||||
| Skill Category | Integration Target |
|
||||
|----------------|-------------------|
|
||||
| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` |
|
||||
| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` |
|
||||
| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines |
|
||||
| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) |
|
||||
|
||||
### 3. Analyze Skill Content
|
||||
|
||||
Extract from the skill:
|
||||
- **Core concepts**: How the skill works and key concepts
|
||||
- **Best practices**: Recommended approaches
|
||||
- **Code patterns**: Reusable code templates
|
||||
- **Caveats**: Common issues and solutions
|
||||
|
||||
### 4. Execute Integration
|
||||
|
||||
#### 4.1 Update Guidelines Document
|
||||
|
||||
Add a new section to the corresponding `doc.md`:
|
||||
|
||||
```markdown
|
||||
@@@section:skill-<skill-name>
|
||||
## # <Skill Name> Integration Guide
|
||||
|
||||
### Overview
|
||||
[Core functionality and use cases of the skill]
|
||||
|
||||
### Project Adaptation
|
||||
[How to use this skill in the current project]
|
||||
|
||||
### Usage Steps
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
|
||||
### Caveats
|
||||
- [Project-specific constraints]
|
||||
- [Differences from default behavior]
|
||||
|
||||
### Reference Examples
|
||||
See `examples/skills/<skill-name>/`
|
||||
|
||||
@@@/section:skill-<skill-name>
|
||||
```
|
||||
|
||||
#### 4.2 Create Examples Directory (if code examples exist)
|
||||
|
||||
```bash
|
||||
# Directory structure ({target} = frontend or backend)
|
||||
.trellis/spec/{target}/
|
||||
|-- doc.md # Add skill-related section
|
||||
|-- index.md # Update index
|
||||
+-- examples/
|
||||
+-- skills/
|
||||
+-- <skill-name>/
|
||||
|-- README.md # Example documentation
|
||||
|-- example-1.ts.template # Code example (use .template suffix)
|
||||
+-- example-2.tsx.template
|
||||
```
|
||||
|
||||
**File naming conventions**:
|
||||
- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
|
||||
- Config files: `<name>.config.template` (e.g., `tailwind.config.template`)
|
||||
- Documentation: `README.md` (normal suffix)
|
||||
|
||||
#### 4.3 Update Index File
|
||||
|
||||
Add to the Quick Navigation table in `index.md`:
|
||||
|
||||
```markdown
|
||||
| <Skill-related task> | <Section name> | `skill-<skill-name>` |
|
||||
```
|
||||
|
||||
### 5. Generate Integration Report
|
||||
|
||||
---
|
||||
|
||||
## Skill Integration Report: `<skill-name>`
|
||||
|
||||
### # Overview
|
||||
- **Skill description**: [Functionality description]
|
||||
- **Integration target**: `.trellis/spec/{target}/`
|
||||
|
||||
### # Tech Stack Compatibility
|
||||
|
||||
| Skill Requirement | Project Status | Compatibility |
|
||||
|-------------------|----------------|---------------|
|
||||
| [Tech 1] | [Project tech] | [OK]/[!]/[X] |
|
||||
|
||||
### # Integration Locations
|
||||
|
||||
| Type | Path |
|
||||
|------|------|
|
||||
| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) |
|
||||
| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
|
||||
| Index update | `.trellis/spec/{target}/index.md` |
|
||||
|
||||
> `{target}` = `frontend` or `backend`
|
||||
|
||||
### # Dependencies (if needed)
|
||||
|
||||
```bash
|
||||
# Install required dependencies (adjust for your package manager)
|
||||
npm install <package>
|
||||
# or
|
||||
pnpm add <package>
|
||||
# or
|
||||
yarn add <package>
|
||||
```
|
||||
|
||||
### [OK] Completed Changes
|
||||
|
||||
- [ ] Added `@@@section:skill-<name>` section to `doc.md`
|
||||
- [ ] Added index entry to `index.md`
|
||||
- [ ] Created example files in `examples/skills/<name>/`
|
||||
- [ ] Example files use `.template` suffix
|
||||
|
||||
### # Related Guidelines
|
||||
|
||||
- [Existing related section IDs]
|
||||
|
||||
---
|
||||
|
||||
## 6. Optional: Create Usage Command
|
||||
|
||||
If this skill is frequently used, create a shortcut command:
|
||||
|
||||
```bash
|
||||
/trellis:create-command use-<skill-name> Use <skill-name> skill following project guidelines
|
||||
```
|
||||
|
||||
## Common Skill Integration Reference
|
||||
|
||||
| Skill | Integration Target | Examples Directory |
|
||||
|-------|-------------------|-------------------|
|
||||
| `frontend-design` | `frontend` | `examples/skills/frontend-design/` |
|
||||
| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` |
|
||||
| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` |
|
||||
| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) |
|
||||
|
||||
## Example: Integrating `mcp-builder` Skill
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.trellis/spec/backend/
|
||||
|-- doc.md # Add MCP section
|
||||
|-- index.md # Add index entry
|
||||
+-- examples/
|
||||
+-- skills/
|
||||
+-- mcp-builder/
|
||||
|-- README.md
|
||||
|-- server.ts.template
|
||||
|-- tools.ts.template
|
||||
+-- types.ts.template
|
||||
```
|
||||
|
||||
### New Section in doc.md
|
||||
|
||||
```markdown
|
||||
@@@section:skill-mcp-builder
|
||||
## # MCP Server Development Guide
|
||||
|
||||
### Overview
|
||||
Create LLM-callable tool services using MCP (Model Context Protocol).
|
||||
|
||||
### Project Adaptation
|
||||
- Place services in a dedicated directory
|
||||
- Follow existing TypeScript and type definition conventions
|
||||
- Use project's logging system
|
||||
|
||||
### Reference Examples
|
||||
See `examples/skills/mcp-builder/`
|
||||
|
||||
@@@/section:skill-mcp-builder
|
||||
```
|
||||
@@ -0,0 +1,358 @@
|
||||
You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
|
||||
|
||||
YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level.
|
||||
|
||||
## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
|
||||
|
||||
This onboarding has THREE equally important parts:
|
||||
|
||||
**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
|
||||
- Explain WHY this workflow exists
|
||||
- Explain WHAT each command does and WHY
|
||||
|
||||
**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
|
||||
- Walk through ALL 5 examples in detail
|
||||
- For EACH step in EACH example, explain:
|
||||
- PRINCIPLE: Why this step exists
|
||||
- WHAT HAPPENS: What the command actually does
|
||||
- IF SKIPPED: What goes wrong without it
|
||||
|
||||
**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
|
||||
- Check if project guidelines are still empty templates
|
||||
- If empty, guide the developer to fill them with project-specific content
|
||||
- Explain the customization workflow
|
||||
|
||||
DO NOT skip any part. All three parts are essential:
|
||||
- Part 1 teaches the concepts
|
||||
- Part 2 shows how concepts work in practice
|
||||
- Part 3 ensures the project has proper guidelines for AI to follow
|
||||
|
||||
After completing ALL THREE parts, ask the developer about their first task.
|
||||
|
||||
---
|
||||
|
||||
## CORE PHILOSOPHY: Why This Workflow Exists
|
||||
|
||||
AI-assisted development has three fundamental challenges:
|
||||
|
||||
### Challenge 1: AI Has No Memory
|
||||
|
||||
Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
|
||||
|
||||
**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
|
||||
|
||||
**The Solution**: The `.trellis/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/trellis:start` command reads this history at session start, giving AI "artificial memory."
|
||||
|
||||
### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
|
||||
|
||||
AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
|
||||
|
||||
**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
|
||||
|
||||
**The Solution**: The `.trellis/spec/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
|
||||
|
||||
### Challenge 3: AI Context Window Is Limited
|
||||
|
||||
Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
|
||||
|
||||
**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
|
||||
|
||||
**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis:finish-work` command does a final holistic review.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM STRUCTURE
|
||||
|
||||
```
|
||||
.trellis/
|
||||
|-- .developer # Your identity (gitignored)
|
||||
|-- workflow.md # Complete workflow documentation
|
||||
|-- workspace/ # "AI Memory" - session history
|
||||
| |-- index.md # All developers' progress
|
||||
| +-- {developer}/ # Per-developer directory
|
||||
| |-- index.md # Personal progress index
|
||||
| +-- journal-N.md # Session records (max 2000 lines)
|
||||
|-- tasks/ # Task tracking (unified)
|
||||
| +-- {MM}-{DD}-{slug}/ # Task directory
|
||||
| |-- task.json # Task metadata
|
||||
| +-- prd.md # Requirements doc
|
||||
|-- spec/ # "AI Training Data" - project knowledge
|
||||
| |-- frontend/ # Frontend conventions
|
||||
| |-- backend/ # Backend conventions
|
||||
| +-- guides/ # Thinking patterns
|
||||
+-- scripts/ # Automation tools
|
||||
```
|
||||
|
||||
### Understanding spec/ subdirectories
|
||||
|
||||
**frontend/** - Single-layer frontend knowledge:
|
||||
- Component patterns (how to write components in THIS project)
|
||||
- State management rules (Redux? Zustand? Context?)
|
||||
- Styling conventions (CSS modules? Tailwind? Styled-components?)
|
||||
- Hook patterns (custom hooks, data fetching)
|
||||
|
||||
**backend/** - Single-layer backend knowledge:
|
||||
- API design patterns (REST? GraphQL? tRPC?)
|
||||
- Database conventions (query patterns, migrations)
|
||||
- Error handling standards
|
||||
- Logging and monitoring rules
|
||||
|
||||
**guides/** - Cross-layer thinking guides:
|
||||
- Code reuse thinking guide
|
||||
- Cross-layer thinking guide
|
||||
- Pre-implementation checklists
|
||||
|
||||
---
|
||||
|
||||
## COMMAND DEEP DIVE
|
||||
|
||||
### /trellis:start - Restore AI Memory
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
|
||||
|
||||
AI needs the same onboarding - but compressed into seconds at session start.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Reads developer identity (who am I in this project?)
|
||||
2. Checks git status (what branch? uncommitted changes?)
|
||||
3. Reads recent session history from `workspace/` (what happened before?)
|
||||
4. Identifies active features (what's in progress?)
|
||||
5. Understands current project state before making any changes
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without /trellis:start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
|
||||
- With /trellis:start: AI knows project context, can continue where previous session left off, avoids conflicts.
|
||||
|
||||
---
|
||||
|
||||
### /trellis:before-frontend-dev and /trellis:before-backend-dev - Inject Specialized Knowledge
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
|
||||
2. Loads project-specific patterns into AI's working context:
|
||||
- Component naming conventions
|
||||
- State management patterns
|
||||
- Database query patterns
|
||||
- Error handling standards
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without before-*-dev: AI writes generic code that doesn't match project style.
|
||||
- With before-*-dev: AI writes code that looks like the rest of the codebase.
|
||||
|
||||
---
|
||||
|
||||
### /trellis:check-frontend and /trellis:check-backend - Combat Context Drift
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Re-reads the guidelines that were injected earlier
|
||||
2. Compares written code against those guidelines
|
||||
3. Runs type checker and linter
|
||||
4. Identifies violations and suggests fixes
|
||||
|
||||
**WHY THIS MATTERS**:
|
||||
- Without check-*: Context drift goes unnoticed, code quality degrades.
|
||||
- With check-*: Drift is caught and corrected before commit.
|
||||
|
||||
---
|
||||
|
||||
### /trellis:check-cross-layer - Multi-Dimension Verification
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
Most bugs don't come from lack of technical skill - they come from "didn't think of it":
|
||||
- Changed a constant in one place, missed 5 other places
|
||||
- Modified database schema, forgot to update the API layer
|
||||
- Created a utility function, but similar one already exists
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Identifies which dimensions your change involves
|
||||
2. For each dimension, runs targeted checks:
|
||||
- Cross-layer data flow
|
||||
- Code reuse analysis
|
||||
- Import path validation
|
||||
- Consistency checks
|
||||
|
||||
---
|
||||
|
||||
### /trellis:finish-work - Holistic Pre-Commit Review
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
The `/check-*` commands focus on code quality within a single layer. But real changes often have cross-cutting concerns.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Reviews all changes holistically
|
||||
2. Checks cross-layer consistency
|
||||
3. Identifies broader impacts
|
||||
4. Checks if new patterns should be documented
|
||||
|
||||
---
|
||||
|
||||
### /trellis:record-session - Persist Memory for Future
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
All the context AI built during this session will be lost when session ends. The next session's `/trellis:start` needs this information.
|
||||
|
||||
**WHAT IT ACTUALLY DOES**:
|
||||
1. Records session summary to `workspace/{developer}/journal-N.md`
|
||||
2. Captures what was done, learned, and what's remaining
|
||||
3. Updates index files for quick lookup
|
||||
|
||||
---
|
||||
|
||||
## REAL-WORLD WORKFLOW EXAMPLES
|
||||
|
||||
### Example 1: Bug Fix Session
|
||||
|
||||
**[1/8] /trellis:start** - AI needs project context before touching code
|
||||
**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
|
||||
**[3/8] /trellis:before-frontend-dev** - Inject project-specific frontend knowledge
|
||||
**[4/8] Investigate and fix the bug** - Actual development work
|
||||
**[5/8] /trellis:check-frontend** - Re-verify code against guidelines
|
||||
**[6/8] /trellis:finish-work** - Holistic cross-layer review
|
||||
**[7/8] Human tests and commits** - Human validates before code enters repo
|
||||
**[8/8] /trellis:record-session** - Persist memory for future sessions
|
||||
|
||||
### Example 2: Planning Session (No Code)
|
||||
|
||||
**[1/4] /trellis:start** - Context needed even for non-coding work
|
||||
**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work
|
||||
**[3/4] Review docs, create subtask list** - Actual planning work
|
||||
**[4/4] /trellis:record-session (with --summary)** - Planning decisions must be recorded
|
||||
|
||||
### Example 3: Code Review Fixes
|
||||
|
||||
**[1/6] /trellis:start** - Resume context from previous session
|
||||
**[2/6] /trellis:before-backend-dev** - Re-inject guidelines before fixes
|
||||
**[3/6] Fix each CR issue** - Address feedback with guidelines in context
|
||||
**[4/6] /trellis:check-backend** - Verify fixes didn't introduce new issues
|
||||
**[5/6] /trellis:finish-work** - Document lessons from CR
|
||||
**[6/6] Human commits, then /trellis:record-session** - Preserve CR lessons
|
||||
|
||||
### Example 4: Large Refactoring
|
||||
|
||||
**[1/5] /trellis:start** - Clear baseline before major changes
|
||||
**[2/5] Plan phases** - Break into verifiable chunks
|
||||
**[3/5] Execute phase by phase with /check-* after each** - Incremental verification
|
||||
**[4/5] /trellis:finish-work** - Check if new patterns should be documented
|
||||
**[5/5] Record with multiple commit hashes** - Link all commits to one feature
|
||||
|
||||
### Example 5: Debug Session
|
||||
|
||||
**[1/6] /trellis:start** - See if this bug was investigated before
|
||||
**[2/6] /trellis:before-backend-dev** - Guidelines might document known gotchas
|
||||
**[3/6] Investigation** - Actual debugging work
|
||||
**[4/6] /trellis:check-backend** - Verify debug changes don't break other things
|
||||
**[5/6] /trellis:finish-work** - Debug findings might need documentation
|
||||
**[6/6] Human commits, then /trellis:record-session** - Debug knowledge is valuable
|
||||
|
||||
---
|
||||
|
||||
## KEY RULES TO EMPHASIZE
|
||||
|
||||
1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
|
||||
2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
|
||||
3. **Check after code** - /check-* commands catch context drift.
|
||||
4. **Record everything** - /trellis:record-session persists memory.
|
||||
|
||||
---
|
||||
|
||||
# PART 3: Customize Your Development Guidelines
|
||||
|
||||
After explaining Part 1 and Part 2, check if the project's development guidelines need customization.
|
||||
|
||||
## Step 1: Check Current Guidelines Status
|
||||
|
||||
Check if `.trellis/spec/` contains empty templates or customized guidelines:
|
||||
|
||||
```bash
|
||||
# Check if files are still empty templates (look for placeholder text)
|
||||
grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l
|
||||
grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
## Step 2: Determine Situation
|
||||
|
||||
**Situation A: First-time setup (empty templates)**
|
||||
|
||||
If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project.
|
||||
|
||||
Explain to the developer:
|
||||
|
||||
"I see that the development guidelines in `.trellis/spec/` are still empty templates. This is normal for a new Trellis setup!
|
||||
|
||||
The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `/before-*-dev` commands won't provide useful guidance.
|
||||
|
||||
**Your first task should be to fill in these guidelines:**
|
||||
|
||||
1. Look at your existing codebase
|
||||
2. Identify the patterns and conventions already in use
|
||||
3. Document them in the guideline files
|
||||
|
||||
For example, for `.trellis/spec/backend/database-guidelines.md`:
|
||||
- What ORM/query library does your project use?
|
||||
- How are migrations managed?
|
||||
- What naming conventions for tables/columns?
|
||||
|
||||
Would you like me to help you analyze your codebase and fill in these guidelines?"
|
||||
|
||||
**Situation B: Guidelines already customized**
|
||||
|
||||
If guidelines have real content (no "To be filled" placeholders), this is an existing setup.
|
||||
|
||||
Explain to the developer:
|
||||
|
||||
"Great! Your team has already customized the development guidelines. You can start using `/before-*-dev` commands right away.
|
||||
|
||||
I recommend reading through `.trellis/spec/` to familiarize yourself with the team's coding standards."
|
||||
|
||||
## Step 3: Help Fill Guidelines (If Empty)
|
||||
|
||||
If the developer wants help filling guidelines, create a feature to track this:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-guidelines
|
||||
```
|
||||
|
||||
Then systematically analyze the codebase and fill each guideline file:
|
||||
|
||||
1. **Analyze the codebase** - Look at existing code patterns
|
||||
2. **Document conventions** - Write what you observe, not ideals
|
||||
3. **Include examples** - Reference actual files in the project
|
||||
4. **List forbidden patterns** - Document anti-patterns the team avoids
|
||||
|
||||
Work through one file at a time:
|
||||
- `backend/directory-structure.md`
|
||||
- `backend/database-guidelines.md`
|
||||
- `backend/error-handling.md`
|
||||
- `backend/quality-guidelines.md`
|
||||
- `backend/logging-guidelines.md`
|
||||
- `frontend/directory-structure.md`
|
||||
- `frontend/component-guidelines.md`
|
||||
- `frontend/hook-guidelines.md`
|
||||
- `frontend/state-management.md`
|
||||
- `frontend/quality-guidelines.md`
|
||||
- `frontend/type-safety.md`
|
||||
|
||||
---
|
||||
|
||||
## Completing the Onboard Session
|
||||
|
||||
After covering all three parts, summarize:
|
||||
|
||||
"You're now onboarded to the Trellis workflow system! Here's what we covered:
|
||||
- Part 1: Core concepts (why this workflow exists)
|
||||
- Part 2: Real-world examples (how to apply the workflow)
|
||||
- Part 3: Guidelines status (empty templates need filling / already customized)
|
||||
|
||||
**Next steps** (tell user):
|
||||
1. Run `/trellis:record-session` to record this onboard session
|
||||
2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines
|
||||
3. [If guidelines ready] Start your first development task
|
||||
|
||||
What would you like to do first?"
|
||||
@@ -0,0 +1,194 @@
|
||||
# Multi-Agent Pipeline Orchestrator
|
||||
|
||||
You are the Multi-Agent Pipeline Orchestrator Agent, running in the main repository, responsible for collaborating with users to manage parallel development tasks.
|
||||
|
||||
## Role Definition
|
||||
|
||||
- **You are in the main repository**, not in a worktree
|
||||
- **You don't write code directly** - code work is done by agents in worktrees
|
||||
- **You are responsible for planning and dispatching**: discuss requirements, create plans, configure context, start worktree agents
|
||||
- **Delegate complex analysis to research agent**: finding specs, analyzing code structure
|
||||
|
||||
---
|
||||
|
||||
## Operation Types
|
||||
|
||||
Operations in this document are categorized as:
|
||||
|
||||
| Marker | Meaning | Executor |
|
||||
|--------|---------|----------|
|
||||
| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
|
||||
| `[USER]` | Slash commands executed by user | User |
|
||||
|
||||
---
|
||||
|
||||
## Startup Flow
|
||||
|
||||
### Step 1: Understand Trellis Workflow `[AI]`
|
||||
|
||||
First, read the workflow guide to understand the development process:
|
||||
|
||||
```bash
|
||||
cat .trellis/workflow.md # Development process, conventions, and quick start guide
|
||||
```
|
||||
|
||||
### Step 2: Get Current Status `[AI]`
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
### Step 3: Read Project Guidelines `[AI]`
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/frontend/index.md # Frontend guidelines index
|
||||
cat .trellis/spec/backend/index.md # Backend guidelines index
|
||||
cat .trellis/spec/guides/index.md # Thinking guides
|
||||
```
|
||||
|
||||
### Step 4: Ask User for Requirements
|
||||
|
||||
Ask the user:
|
||||
|
||||
1. What feature to develop?
|
||||
2. Which modules are involved?
|
||||
3. Development type? (backend / frontend / fullstack)
|
||||
|
||||
---
|
||||
|
||||
## Planning: Choose Your Approach
|
||||
|
||||
Based on requirement complexity, choose one of these approaches:
|
||||
|
||||
### Option A: Plan Agent (Recommended for complex features) `[AI]`
|
||||
|
||||
Use when:
|
||||
- Requirements need analysis and validation
|
||||
- Multiple modules or cross-layer changes
|
||||
- Unclear scope that needs research
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/multi_agent/plan.py \
|
||||
--name "<feature-name>" \
|
||||
--type "<backend|frontend|fullstack>" \
|
||||
--requirement "<user requirement description>" \
|
||||
--platform opencode
|
||||
```
|
||||
|
||||
Plan Agent will:
|
||||
1. Evaluate requirement validity (may reject if unclear/too large)
|
||||
2. Call research agent to analyze codebase
|
||||
3. Create and configure task directory
|
||||
4. Write prd.md with acceptance criteria
|
||||
5. Output ready-to-use task directory
|
||||
|
||||
After plan.py completes, start the worktree agent:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" --platform opencode
|
||||
```
|
||||
|
||||
### Option B: Manual Configuration (For simple/clear features) `[AI]`
|
||||
|
||||
Use when:
|
||||
- Requirements are already clear and specific
|
||||
- You know exactly which files are involved
|
||||
- Simple, well-scoped changes
|
||||
|
||||
#### Step 1: Create Task Directory
|
||||
|
||||
```bash
|
||||
# title is task description, --slug for task directory name
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>)
|
||||
```
|
||||
|
||||
#### Step 2: Configure Task
|
||||
|
||||
```bash
|
||||
# Initialize jsonl context files
|
||||
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type>
|
||||
|
||||
# Set branch and scope
|
||||
python3 ./.trellis/scripts/task.py set-branch "$TASK_DIR" feature/<name>
|
||||
python3 ./.trellis/scripts/task.py set-scope "$TASK_DIR" <scope>
|
||||
```
|
||||
|
||||
#### Step 3: Add Context (optional: use research agent)
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
|
||||
```
|
||||
|
||||
#### Step 4: Create prd.md
|
||||
|
||||
```bash
|
||||
cat > "$TASK_DIR/prd.md" << 'EOF'
|
||||
# Feature: <name>
|
||||
|
||||
## Requirements
|
||||
- ...
|
||||
|
||||
## Acceptance Criteria
|
||||
- ...
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Step 5: Validate and Start
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py validate "$TASK_DIR"
|
||||
python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR" --platform opencode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## After Starting: Report Status
|
||||
|
||||
Tell the user the agent has started and provide monitoring commands.
|
||||
|
||||
---
|
||||
|
||||
## User Available Commands `[USER]`
|
||||
|
||||
The following slash commands are for users (not AI):
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/trellis:parallel` | Start Multi-Agent Pipeline (this command) |
|
||||
| `/trellis:start` | Start normal development mode (single process) |
|
||||
| `/trellis:record-session` | Record session progress |
|
||||
| `/trellis:finish-work` | Pre-completion checklist |
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Commands (for user reference)
|
||||
|
||||
Tell the user they can use these commands to monitor:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/multi_agent/status.py # Overview
|
||||
python3 ./.trellis/scripts/multi_agent/status.py --log <name> # View log
|
||||
python3 ./.trellis/scripts/multi_agent/status.py --watch <name> # Real-time monitoring
|
||||
python3 ./.trellis/scripts/multi_agent/cleanup.py <branch> # Cleanup worktree
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Phases
|
||||
|
||||
The dispatch agent in worktree will automatically execute:
|
||||
|
||||
1. implement → Implement feature
|
||||
2. check → Check code quality
|
||||
3. finish → Final verification
|
||||
4. create-pr → Create PR
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
- **Don't write code directly** - delegate to agents in worktree
|
||||
- **Don't execute git commit** - agent does it via create-pr action
|
||||
- **Delegate complex analysis to research** - finding specs, analyzing code structure
|
||||
- **Subagents use globally configured model** - inherits from user's OpenCode config
|
||||
@@ -0,0 +1,61 @@
|
||||
[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
|
||||
|
||||
**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
|
||||
|
||||
---
|
||||
|
||||
## Record Work Progress
|
||||
|
||||
### Step 1: Get Context & Check Tasks
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode record
|
||||
```
|
||||
|
||||
[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
|
||||
- Code committed? → Archive it (don't wait for PR)
|
||||
- All acceptance criteria met? → Archive it
|
||||
- Don't skip archiving just because `status` still says `planning` or `in_progress`
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-name>
|
||||
```
|
||||
|
||||
### Step 2: One-Click Add Session
|
||||
|
||||
```bash
|
||||
# Method 1: Simple parameters
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "Session Title" \
|
||||
--commit "hash1,hash2" \
|
||||
--summary "Brief summary of what was done"
|
||||
|
||||
# Method 2: Pass detailed content via stdin
|
||||
cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| New API | Added user authentication endpoint |
|
||||
| Frontend | Updated login form |
|
||||
|
||||
**Updated Files**:
|
||||
- `packages/api/modules/auth/router.ts`
|
||||
- `apps/web/modules/auth/components/login-form.tsx`
|
||||
EOF
|
||||
```
|
||||
|
||||
**Auto-completes**:
|
||||
- [OK] Appends session to journal-N.md
|
||||
- [OK] Auto-detects line count, creates new file if >2000 lines
|
||||
- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
|
||||
- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
|
||||
|
||||
---
|
||||
|
||||
## Script Command Reference
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
|
||||
| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
|
||||
| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
|
||||
| `python3 ./.trellis/scripts/task.py list` | List active tasks |
|
||||
@@ -0,0 +1,346 @@
|
||||
# Start Session
|
||||
|
||||
Initialize your AI development session and begin working on tasks.
|
||||
|
||||
---
|
||||
|
||||
## Operation Types
|
||||
|
||||
| Marker | Meaning | Executor |
|
||||
|--------|---------|----------|
|
||||
| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
|
||||
| `[USER]` | Slash commands executed by user | User |
|
||||
|
||||
---
|
||||
|
||||
## Initialization `[AI]`
|
||||
|
||||
### Step 1: Understand Development Workflow
|
||||
|
||||
First, read the workflow guide to understand the development process:
|
||||
|
||||
```bash
|
||||
cat .trellis/workflow.md
|
||||
```
|
||||
|
||||
**Follow the instructions in workflow.md** - it contains:
|
||||
- Core principles (Read Before Write, Follow Standards, etc.)
|
||||
- File system structure
|
||||
- Development process
|
||||
- Best practices
|
||||
|
||||
### Step 2: Get Current Context
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py
|
||||
```
|
||||
|
||||
This shows: developer identity, git status, current task (if any), active tasks.
|
||||
|
||||
### Step 3: Read Guidelines Index
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/frontend/index.md # Frontend guidelines
|
||||
cat .trellis/spec/backend/index.md # Backend guidelines
|
||||
cat .trellis/spec/guides/index.md # Thinking guides
|
||||
```
|
||||
|
||||
> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
|
||||
> At this step, just read the indexes to understand what's available.
|
||||
> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
|
||||
|
||||
### Step 4: Report and Ask
|
||||
|
||||
Report what you learned and ask: "What would you like to work on?"
|
||||
|
||||
---
|
||||
|
||||
## Task Classification
|
||||
|
||||
When user describes a task, classify it:
|
||||
|
||||
| Type | Criteria | Workflow |
|
||||
|------|----------|----------|
|
||||
| **Question** | User asks about code, architecture, or how something works | Answer directly |
|
||||
| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
|
||||
| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
|
||||
| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
|
||||
|
||||
### Decision Rule
|
||||
|
||||
> **If in doubt, use Brainstorm + Task Workflow.**
|
||||
>
|
||||
> Task Workflow ensures code-spec context is injected to agents, resulting in higher quality code.
|
||||
> The overhead is minimal, but the benefit is significant.
|
||||
|
||||
---
|
||||
|
||||
## Question / Trivial Fix
|
||||
|
||||
For questions or trivial fixes, work directly:
|
||||
|
||||
1. Answer question or make the fix
|
||||
2. If code was changed, remind user to run `/trellis:finish-work`
|
||||
|
||||
---
|
||||
|
||||
## Complex Task - Brainstorm First
|
||||
|
||||
For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
|
||||
|
||||
See `/trellis:brainstorm` for the full process. Summary:
|
||||
|
||||
1. **Acknowledge and classify** - State your understanding
|
||||
2. **Create task directory** - Track evolving requirements in `prd.md`
|
||||
3. **Ask questions one at a time** - Update PRD after each answer
|
||||
4. **Propose approaches** - For architectural decisions
|
||||
5. **Confirm final requirements** - Get explicit approval
|
||||
6. **Proceed to Task Workflow** - With clear requirements in PRD
|
||||
|
||||
> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
|
||||
> consider creating subtasks using `--parent` flag or `add-subtask` command.
|
||||
> See `/trellis:brainstorm` Step 8 for details.
|
||||
|
||||
---
|
||||
|
||||
## Task Workflow (Development Tasks)
|
||||
|
||||
**Why this workflow?**
|
||||
- Research Agent analyzes what code-spec files are needed
|
||||
- Code-spec files are configured in jsonl files
|
||||
- Implement Agent receives code-spec context via Hook injection
|
||||
- Check Agent verifies against code-spec requirements
|
||||
- Result: Code that follows project conventions automatically
|
||||
|
||||
### Overview: Two Entry Points
|
||||
|
||||
```
|
||||
From Brainstorm (Complex Task):
|
||||
PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
|
||||
|
||||
From Simple Task:
|
||||
Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
|
||||
```
|
||||
|
||||
**Key principle: Research happens AFTER requirements are clear (PRD exists).**
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Establish Requirements
|
||||
|
||||
#### Path A: From Brainstorm (skip to Phase 2)
|
||||
|
||||
PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
|
||||
|
||||
#### Path B: From Simple Task
|
||||
|
||||
**Step 1: Confirm Understanding** `[AI]`
|
||||
|
||||
Quick confirm:
|
||||
- What is the goal?
|
||||
- What type of development? (frontend / backend / fullstack)
|
||||
- Any specific requirements or constraints?
|
||||
|
||||
**Step 2: Create Task Directory** `[AI]`
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
|
||||
```
|
||||
|
||||
**Step 3: Write PRD** `[AI]`
|
||||
|
||||
Create `prd.md` in the task directory with:
|
||||
|
||||
```markdown
|
||||
# <Task Title>
|
||||
|
||||
## Goal
|
||||
<What we're trying to achieve>
|
||||
|
||||
## Requirements
|
||||
- <Requirement 1>
|
||||
- <Requirement 2>
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] <Criterion 1>
|
||||
- [ ] <Criterion 2>
|
||||
|
||||
## Technical Notes
|
||||
<Any technical decisions or constraints>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Prepare for Implementation (shared)
|
||||
|
||||
> Both paths converge here. PRD and task directory must exist before proceeding.
|
||||
|
||||
**Step 4: Code-Spec Depth Check** `[AI]`
|
||||
|
||||
If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
|
||||
|
||||
Trigger this requirement when the change includes any of:
|
||||
- New or changed command/API signatures
|
||||
- Database schema or migration changes
|
||||
- Infra integrations (storage, queue, cache, secrets, env contracts)
|
||||
- Cross-layer payload transformations
|
||||
|
||||
Must-have before proceeding:
|
||||
- [ ] Target code-spec files to update are identified
|
||||
- [ ] Concrete contract is defined (signature, fields, env keys)
|
||||
- [ ] Validation and error matrix is defined
|
||||
- [ ] At least one Good/Base/Bad case is defined
|
||||
|
||||
**Step 5: Research the Codebase** `[AI]`
|
||||
|
||||
Based on the confirmed PRD, call Research Agent to find relevant specs and patterns:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "research",
|
||||
prompt: "Analyze the codebase for this task:
|
||||
|
||||
Task: <goal from PRD>
|
||||
Type: <frontend/backend/fullstack>
|
||||
|
||||
Please find:
|
||||
1. Relevant code-spec files in .trellis/spec/
|
||||
2. Existing code patterns to follow (find 2-3 examples)
|
||||
3. Files that will likely need modification
|
||||
|
||||
Output:
|
||||
## Relevant Code-Specs
|
||||
- <path>: <why it's relevant>
|
||||
|
||||
## Code Patterns Found
|
||||
- <pattern>: <example file path>
|
||||
|
||||
## Files to Modify
|
||||
- <path>: <what change>",
|
||||
model: "opus"
|
||||
)
|
||||
```
|
||||
|
||||
**Step 6: Configure Context** `[AI]`
|
||||
|
||||
Initialize default context:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
|
||||
# type: backend | frontend | fullstack
|
||||
```
|
||||
|
||||
Add code-spec files found by Research Agent:
|
||||
|
||||
```bash
|
||||
# For each relevant code-spec and code pattern:
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
|
||||
```
|
||||
|
||||
**Step 7: Activate Task** `[AI]`
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py start "$TASK_DIR"
|
||||
```
|
||||
|
||||
This sets `.current-task` so hooks can inject context.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Execute (shared)
|
||||
|
||||
**Step 8: Implement** `[AI]`
|
||||
|
||||
Call Implement Agent (code-spec context is auto-injected by hook):
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "implement",
|
||||
prompt: "Implement the task described in prd.md.
|
||||
|
||||
Follow all code-spec files that have been injected into your context.
|
||||
Run lint and typecheck before finishing.",
|
||||
model: "opus"
|
||||
)
|
||||
```
|
||||
|
||||
**Step 9: Check Quality** `[AI]`
|
||||
|
||||
Call Check Agent (code-spec context is auto-injected by hook):
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "check",
|
||||
prompt: "Review all code changes against the code-spec requirements.
|
||||
|
||||
Fix any issues you find directly.
|
||||
Ensure lint and typecheck pass.",
|
||||
model: "opus"
|
||||
)
|
||||
```
|
||||
|
||||
**Step 10: Complete** `[AI]`
|
||||
|
||||
1. Verify lint and typecheck pass
|
||||
2. Report what was implemented
|
||||
3. Remind user to:
|
||||
- Test the changes
|
||||
- Commit when ready
|
||||
- Run `/trellis:record-session` to record this session
|
||||
|
||||
---
|
||||
|
||||
## Continuing Existing Task
|
||||
|
||||
If `get_context.py` shows a current task:
|
||||
|
||||
1. Read the task's `prd.md` to understand the goal
|
||||
2. Check `task.json` for current status and phase
|
||||
3. Ask user: "Continue working on <task-name>?"
|
||||
|
||||
If yes, resume from the appropriate step (usually Step 7 or 8).
|
||||
|
||||
---
|
||||
|
||||
## Commands Reference
|
||||
|
||||
### User Commands `[USER]`
|
||||
|
||||
| Command | When to Use |
|
||||
|---------|-------------|
|
||||
| `/trellis:start` | Begin a session (this command) |
|
||||
| `/trellis:brainstorm` | Clarify vague requirements (called from start) |
|
||||
| `/trellis:parallel` | Complex tasks needing isolated worktree |
|
||||
| `/trellis:finish-work` | Before committing changes |
|
||||
| `/trellis:record-session` | After completing a task |
|
||||
|
||||
### AI Scripts `[AI]`
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `python3 ./.trellis/scripts/get_context.py` | Get session context |
|
||||
| `python3 ./.trellis/scripts/task.py create` | Create task directory |
|
||||
| `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files |
|
||||
| `python3 ./.trellis/scripts/task.py add-context` | Add code-spec/context file to jsonl |
|
||||
| `python3 ./.trellis/scripts/task.py start` | Set current task |
|
||||
| `python3 ./.trellis/scripts/task.py finish` | Clear current task |
|
||||
| `python3 ./.trellis/scripts/task.py archive` | Archive completed task |
|
||||
|
||||
### Sub Agents `[AI]`
|
||||
|
||||
| Agent | Purpose | Hook Injection |
|
||||
|-------|---------|----------------|
|
||||
| research | Analyze codebase | No (reads directly) |
|
||||
| implement | Write code | Yes (implement.jsonl) |
|
||||
| check | Review & fix | Yes (check.jsonl) |
|
||||
| debug | Fix specific issues | Yes (debug.jsonl) |
|
||||
|
||||
---
|
||||
|
||||
## Key Principle
|
||||
|
||||
> **Code-spec context is injected, not remembered.**
|
||||
>
|
||||
> The Task Workflow ensures agents receive relevant code-spec context automatically.
|
||||
> This is more reliable than hoping the AI "remembers" conventions.
|
||||
@@ -0,0 +1,354 @@
|
||||
# Update Code-Spec - Capture Executable Contracts
|
||||
|
||||
When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.
|
||||
|
||||
**Timing**: After completing a task, fixing a bug, or discovering a new pattern
|
||||
|
||||
---
|
||||
|
||||
## Code-Spec First Rule (CRITICAL)
|
||||
|
||||
In this project, "spec" for implementation work means **code-spec**:
|
||||
- Executable contracts (not principle-only text)
|
||||
- Concrete signatures, payload fields, env keys, and boundary behavior
|
||||
- Testable validation/error behavior
|
||||
|
||||
If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
|
||||
|
||||
### Mandatory Triggers
|
||||
|
||||
Apply code-spec depth when the change includes any of:
|
||||
- New/changed command or API signature
|
||||
- Cross-layer request/response contract change
|
||||
- Database schema/migration change
|
||||
- Infra integration (storage, queue, cache, secrets, env wiring)
|
||||
|
||||
### Mandatory Output (7 Sections)
|
||||
|
||||
For triggered tasks, include all sections below:
|
||||
1. Scope / Trigger
|
||||
2. Signatures (command/API/DB)
|
||||
3. Contracts (request/response/env)
|
||||
4. Validation & Error Matrix
|
||||
5. Good/Base/Bad Cases
|
||||
6. Tests Required (with assertion points)
|
||||
7. Wrong vs Correct (at least one pair)
|
||||
|
||||
---
|
||||
|
||||
## When to Update Code-Specs
|
||||
|
||||
| Trigger | Example | Target Spec |
|
||||
|---------|---------|-------------|
|
||||
| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
|
||||
| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section |
|
||||
| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
|
||||
| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
|
||||
| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section |
|
||||
| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
|
||||
| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
|
||||
|
||||
**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
|
||||
|
||||
---
|
||||
|
||||
## Spec Structure Overview
|
||||
|
||||
```
|
||||
.trellis/spec/
|
||||
├── backend/ # Backend coding standards
|
||||
│ ├── index.md # Overview and links
|
||||
│ └── *.md # Topic-specific guidelines
|
||||
├── frontend/ # Frontend coding standards
|
||||
│ ├── index.md # Overview and links
|
||||
│ └── *.md # Topic-specific guidelines
|
||||
└── guides/ # Thinking checklists (NOT coding specs!)
|
||||
├── index.md # Guide index
|
||||
└── *.md # Topic-specific guides
|
||||
```
|
||||
|
||||
### CRITICAL: Code-Spec vs Guide - Know the Difference
|
||||
|
||||
| Type | Location | Purpose | Content Style |
|
||||
|------|----------|---------|---------------|
|
||||
| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
|
||||
| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
|
||||
|
||||
**Decision Rule**: Ask yourself:
|
||||
|
||||
- "This is **how to write** the code" → Put in `backend/` or `frontend/`
|
||||
- "This is **what to consider** before writing" → Put in `guides/`
|
||||
|
||||
**Example**:
|
||||
|
||||
| Learning | Wrong Location | Correct Location |
|
||||
|----------|----------------|------------------|
|
||||
| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` |
|
||||
| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` |
|
||||
|
||||
**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
|
||||
|
||||
---
|
||||
|
||||
## Update Process
|
||||
|
||||
### Step 1: Identify What You Learned
|
||||
|
||||
Answer these questions:
|
||||
|
||||
1. **What did you learn?** (Be specific)
|
||||
2. **Why is it important?** (What problem does it prevent?)
|
||||
3. **Where does it belong?** (Which spec file?)
|
||||
|
||||
### Step 2: Classify the Update Type
|
||||
|
||||
| Type | Description | Action |
|
||||
|------|-------------|--------|
|
||||
| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
|
||||
| **Project Convention** | How we do X in this project | Add to relevant section with examples |
|
||||
| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
|
||||
| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
|
||||
| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
|
||||
| **Convention** | Agreed-upon standard | Add to relevant section |
|
||||
| **Gotcha** | Non-obvious behavior | Add warning callout |
|
||||
|
||||
### Step 3: Read the Target Code-Spec
|
||||
|
||||
Before editing, read the current code-spec to:
|
||||
- Understand existing structure
|
||||
- Avoid duplicating content
|
||||
- Find the right section for your update
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/<category>/<file>.md
|
||||
```
|
||||
|
||||
### Step 4: Make the Update
|
||||
|
||||
Follow these principles:
|
||||
|
||||
1. **Be Specific**: Include concrete examples, not just abstract rules
|
||||
2. **Explain Why**: State the problem this prevents
|
||||
3. **Show Contracts**: Add signatures, payload fields, and error behavior
|
||||
4. **Show Code**: Add code snippets for key patterns
|
||||
5. **Keep it Short**: One concept per section
|
||||
|
||||
### Step 5: Update the Index (if needed)
|
||||
|
||||
If you added a new section or the code-spec status changed, update the category's `index.md`.
|
||||
|
||||
---
|
||||
|
||||
## Update Templates
|
||||
|
||||
### Mandatory Template for Infra/Cross-Layer Work
|
||||
|
||||
```markdown
|
||||
## Scenario: <name>
|
||||
|
||||
### 1. Scope / Trigger
|
||||
- Trigger: <why this requires code-spec depth>
|
||||
|
||||
### 2. Signatures
|
||||
- Backend command/API/DB signature(s)
|
||||
|
||||
### 3. Contracts
|
||||
- Request fields (name, type, constraints)
|
||||
- Response fields (name, type, constraints)
|
||||
- Environment keys (required/optional)
|
||||
|
||||
### 4. Validation & Error Matrix
|
||||
- <condition> -> <error>
|
||||
|
||||
### 5. Good/Base/Bad Cases
|
||||
- Good: ...
|
||||
- Base: ...
|
||||
- Bad: ...
|
||||
|
||||
### 6. Tests Required
|
||||
- Unit/Integration/E2E with assertion points
|
||||
|
||||
### 7. Wrong vs Correct
|
||||
#### Wrong
|
||||
...
|
||||
#### Correct
|
||||
...
|
||||
```
|
||||
|
||||
### Adding a Design Decision
|
||||
|
||||
```markdown
|
||||
### Design Decision: [Decision Name]
|
||||
|
||||
**Context**: What problem were we solving?
|
||||
|
||||
**Options Considered**:
|
||||
1. Option A - brief description
|
||||
2. Option B - brief description
|
||||
|
||||
**Decision**: We chose Option X because...
|
||||
|
||||
**Example**:
|
||||
\`\`\`typescript
|
||||
// How it's implemented
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Extensibility**: How to extend this in the future...
|
||||
```
|
||||
|
||||
### Adding a Project Convention
|
||||
|
||||
```markdown
|
||||
### Convention: [Convention Name]
|
||||
|
||||
**What**: Brief description of the convention.
|
||||
|
||||
**Why**: Why we do it this way in this project.
|
||||
|
||||
**Example**:
|
||||
\`\`\`typescript
|
||||
// How to follow this convention
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Related**: Links to related conventions or specs.
|
||||
```
|
||||
|
||||
### Adding a New Pattern
|
||||
|
||||
```markdown
|
||||
### Pattern Name
|
||||
|
||||
**Problem**: What problem does this solve?
|
||||
|
||||
**Solution**: Brief description of the approach.
|
||||
|
||||
**Example**:
|
||||
\`\`\`
|
||||
// Good
|
||||
code example
|
||||
|
||||
// Bad
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
**Why**: Explanation of why this works better.
|
||||
```
|
||||
|
||||
### Adding a Forbidden Pattern
|
||||
|
||||
```markdown
|
||||
### Don't: Pattern Name
|
||||
|
||||
**Problem**:
|
||||
\`\`\`
|
||||
// Don't do this
|
||||
bad code example
|
||||
\`\`\`
|
||||
|
||||
**Why it's bad**: Explanation of the issue.
|
||||
|
||||
**Instead**:
|
||||
\`\`\`
|
||||
// Do this instead
|
||||
good code example
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Adding a Common Mistake
|
||||
|
||||
```markdown
|
||||
### Common Mistake: Description
|
||||
|
||||
**Symptom**: What goes wrong
|
||||
|
||||
**Cause**: Why this happens
|
||||
|
||||
**Fix**: How to correct it
|
||||
|
||||
**Prevention**: How to avoid it in the future
|
||||
```
|
||||
|
||||
### Adding a Gotcha
|
||||
|
||||
```markdown
|
||||
> **Warning**: Brief description of the non-obvious behavior.
|
||||
>
|
||||
> Details about when this happens and how to handle it.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
If you're unsure what to update, answer these prompts:
|
||||
|
||||
1. **What did you just finish?**
|
||||
- [ ] Fixed a bug
|
||||
- [ ] Implemented a feature
|
||||
- [ ] Refactored code
|
||||
- [ ] Had a discussion about approach
|
||||
|
||||
2. **What did you learn or decide?**
|
||||
- Design decision (why X over Y)
|
||||
- Project convention (how we do X)
|
||||
- Non-obvious behavior (gotcha)
|
||||
- Better approach (pattern)
|
||||
|
||||
3. **Would future AI/developers need to know this?**
|
||||
- To understand how the code works → Yes, update spec
|
||||
- To maintain or extend the feature → Yes, update spec
|
||||
- To avoid repeating mistakes → Yes, update spec
|
||||
- Purely one-off implementation detail → Maybe skip
|
||||
|
||||
4. **Which area does it relate to?**
|
||||
- [ ] Backend code
|
||||
- [ ] Frontend code
|
||||
- [ ] Cross-layer data flow
|
||||
- [ ] Code organization/reuse
|
||||
- [ ] Quality/testing
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finishing your code-spec update:
|
||||
|
||||
- [ ] Is the content specific and actionable?
|
||||
- [ ] Did you include a code example?
|
||||
- [ ] Did you explain WHY, not just WHAT?
|
||||
- [ ] Did you include executable signatures/contracts?
|
||||
- [ ] Did you include validation and error matrix?
|
||||
- [ ] Did you include Good/Base/Bad cases?
|
||||
- [ ] Did you include required tests with assertion points?
|
||||
- [ ] Is it in the right code-spec file?
|
||||
- [ ] Does it duplicate existing content?
|
||||
- [ ] Would a new team member understand it?
|
||||
|
||||
---
|
||||
|
||||
## Relationship to Other Commands
|
||||
|
||||
```
|
||||
Development Flow:
|
||||
Learn something → /trellis:update-spec → Knowledge captured
|
||||
↑ ↓
|
||||
/trellis:break-loop ←──────────────────── Future sessions benefit
|
||||
(deep bug analysis)
|
||||
```
|
||||
|
||||
- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
|
||||
- `/trellis:update-spec` - Actually makes the updates (this command)
|
||||
- `/trellis:finish-work` - Reminds you to check if specs need updates
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
|
||||
|
||||
The goal is **institutional memory**:
|
||||
- What one person learns, everyone benefits from
|
||||
- What AI learns in one session, persists to future sessions
|
||||
- Mistakes become documented guardrails
|
||||
Reference in New Issue
Block a user