chore: record session journal - 握力环训练趣味化
This commit is contained in:
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: before-dev
|
||||
description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
|
||||
---
|
||||
|
||||
Read the relevant development guidelines before starting your task.
|
||||
|
||||
Execute these steps:
|
||||
|
||||
1. **Discover packages and their spec layers**:
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
2. **Identify which specs apply** to your task based on:
|
||||
- Which package you're modifying (e.g., `cli/`, `docs-site/`)
|
||||
- What type of work (backend, frontend, unit-test, docs, etc.)
|
||||
|
||||
3. **Read the spec index** for each relevant module:
|
||||
```bash
|
||||
cat .trellis/spec/<package>/<layer>/index.md
|
||||
```
|
||||
Follow the **"Pre-Development Checklist"** section in the index.
|
||||
|
||||
4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
|
||||
|
||||
5. **Always read shared guides**:
|
||||
```bash
|
||||
cat .trellis/spec/guides/index.md
|
||||
```
|
||||
|
||||
6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
|
||||
|
||||
This step is **mandatory** before writing any code.
|
||||
@@ -0,0 +1,492 @@
|
||||
---
|
||||
name: brainstorm
|
||||
description: "Collaborative requirements discovery session optimized for AI coding workflows. Creates task directories, seeds PRDs, runs codebase research, proposes concrete implementation approaches with trade-offs, and converges on MVP scope through structured Q&A. Use when requirements are unclear, multiple implementation paths exist, trade-offs need evaluation, or a complex feature needs scoping before development."
|
||||
---
|
||||
|
||||
# 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 `/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 |
|
||||
|---------|-------------|
|
||||
| `/start` | Entry point that triggers brainstorm |
|
||||
| `/finish-work` | After implementation is complete |
|
||||
| `/update-spec` | If new patterns emerge during work |
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: break-loop
|
||||
description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
|
||||
---
|
||||
|
||||
# Break the Loop - Deep Bug Analysis
|
||||
|
||||
When debug is complete, use this skill 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 skills 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,158 @@
|
||||
---
|
||||
name: check-cross-layer
|
||||
description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
|
||||
---
|
||||
|
||||
# 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 |
|
||||
| **`/check-cross-layer`** (this skill) | 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,30 @@
|
||||
---
|
||||
name: check
|
||||
description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
|
||||
---
|
||||
|
||||
Check if the code you just wrote follows the development guidelines.
|
||||
|
||||
Execute these steps:
|
||||
|
||||
1. **Identify changed files**:
|
||||
```bash
|
||||
git diff --name-only HEAD
|
||||
```
|
||||
|
||||
2. **Determine which spec modules apply** based on the changed file paths:
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
3. **Read the spec index** for each relevant module:
|
||||
```bash
|
||||
cat .trellis/spec/<package>/<layer>/index.md
|
||||
```
|
||||
Follow the **"Quality Check"** section in the index.
|
||||
|
||||
4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them.
|
||||
|
||||
5. **Run lint and typecheck** for the affected package.
|
||||
|
||||
6. **Report any violations** and fix them if found.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: create-command
|
||||
description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
|
||||
---
|
||||
|
||||
# Create New Workflow
|
||||
|
||||
Create a new Antigravity workflow in `.agent/workflows/<workflow-name>.md` based on user requirements.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/create-command <skill-name> <description>
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/create-command review-pr Check PR code changes against project guidelines
|
||||
```
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Parse Input
|
||||
|
||||
Extract from user input:
|
||||
- **Skill name**: Use kebab-case (e.g., `review-pr`)
|
||||
- **Description**: What the skill should accomplish
|
||||
|
||||
### 2. Analyze Requirements
|
||||
|
||||
Determine skill 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 or code templates
|
||||
|
||||
### 3. Generate Skill Content
|
||||
|
||||
Minimum `SKILL.md` structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <skill-name>
|
||||
description: "<description>"
|
||||
---
|
||||
|
||||
# <Skill Title>
|
||||
|
||||
<Instructions for when and how to use this skill>
|
||||
```
|
||||
|
||||
### 4. Create Files
|
||||
|
||||
Create:
|
||||
- `.agent/workflows/<workflow-name>.md`
|
||||
|
||||
### 5. Confirm Creation
|
||||
|
||||
Output result:
|
||||
|
||||
```text
|
||||
[OK] Created Skill: <skill-name>
|
||||
|
||||
File path:
|
||||
- .agent/workflows/<workflow-name>.md
|
||||
|
||||
Usage:
|
||||
- Trigger directly with /<workflow-name>
|
||||
- Or type / and select it
|
||||
|
||||
Description:
|
||||
<description>
|
||||
```
|
||||
|
||||
## Skill Content Guidelines
|
||||
|
||||
### [OK] Good skill 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 skill should not exceed 100 lines
|
||||
3. **Duplicate functionality**: Check if similar skill exists first
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| Skill Type | Prefix | Example |
|
||||
|------------|--------|---------|
|
||||
| Session Start | `start` | `start` |
|
||||
| Pre-development | `before-` | `before-dev` |
|
||||
| Check | `check-` | `check` |
|
||||
| Record | `record-` | `record-session` |
|
||||
| Generate | `generate-` | `generate-api-doc` |
|
||||
| Update | `update-` | `update-changelog` |
|
||||
| Other | Verb-first | `review-code`, `sync-data` |
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: finish-work
|
||||
description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
|
||||
---
|
||||
|
||||
# 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**:
|
||||
If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `/update-spec` manually first.
|
||||
|
||||
### 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 -> /finish-work -> git commit -> /record-session
|
||||
| |
|
||||
Ensure completeness Record progress
|
||||
|
||||
Debug Flow:
|
||||
Hit bug -> Fix -> /break-loop -> Knowledge capture
|
||||
|
|
||||
Deep analysis
|
||||
```
|
||||
|
||||
- `/finish-work` - Check work completeness (this skill)
|
||||
- `/record-session` - Record session and commits
|
||||
- `/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,69 @@
|
||||
---
|
||||
name: improve-ut
|
||||
description: "Analyzes changed files and improves unit test coverage using project-specific testing conventions from .trellis/spec/ unit-test specs. Determines test scope (unit vs integration vs regression), adds or updates tests following existing patterns, and runs validation. Use when code changes need test coverage, after implementing a feature, after fixing a bug, or when test gaps are identified."
|
||||
---
|
||||
|
||||
# Improve Unit Tests (UT)
|
||||
|
||||
Use this skill to improve test coverage after code changes.
|
||||
|
||||
## Usage
|
||||
|
||||
```text
|
||||
/improve-ut
|
||||
```
|
||||
|
||||
## Source of Truth
|
||||
|
||||
Discover and read unit-test specs dynamically:
|
||||
|
||||
```bash
|
||||
# Discover available packages and their spec layers
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
Look for packages with `unit-test` spec layer in the output. For each discovered `unit-test/` directory, read all relevant spec files inside it (for example `index.md`, `conventions.md`, `integration-patterns.md`, `mock-strategies.md`).
|
||||
|
||||
> If this skill conflicts with the unit-test specs, the specs win.
|
||||
|
||||
---
|
||||
|
||||
## Execution Flow
|
||||
|
||||
1. Inspect changed files:
|
||||
- `git diff --name-only`
|
||||
2. Decide test scope using unit-test specs:
|
||||
- unit vs integration vs regression
|
||||
- mock vs real filesystem flow
|
||||
3. Add/update tests using existing project test patterns
|
||||
4. Run validation:
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
5. Summarize decisions, updates, and remaining test gaps.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```markdown
|
||||
## UT Coverage Plan
|
||||
- Changed areas: ...
|
||||
- Test scope (unit/integration/regression): ...
|
||||
|
||||
## Test Updates
|
||||
- Added: ...
|
||||
- Updated: ...
|
||||
|
||||
## Validation
|
||||
- pnpm lint: pass/fail
|
||||
- pnpm typecheck: pass/fail
|
||||
- pnpm test: pass/fail
|
||||
|
||||
## Gaps / Follow-ups
|
||||
- <none or explicit rationale>
|
||||
```
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: integrate-skill
|
||||
description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
|
||||
---
|
||||
|
||||
# Integrate Skill into Project Guidelines
|
||||
|
||||
Adapt and integrate a reusable skill into your project's development guidelines (not directly into project code).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/integrate-skill <skill-name>
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
/integrate-skill frontend-design
|
||||
/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
|
||||
|
||||
Locate and read the skill instructions:
|
||||
- `.agent/workflows/<workflow-name>.md` in the repository
|
||||
- Skill list in `AGENTS.md` (when available in current context)
|
||||
|
||||
If the skill cannot be found, ask the user for the source path or repository.
|
||||
|
||||
### 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 Skill
|
||||
|
||||
If this skill is frequently used, create a shortcut skill:
|
||||
|
||||
```bash
|
||||
/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,363 @@
|
||||
---
|
||||
name: onboard
|
||||
description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
|
||||
---
|
||||
|
||||
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 skill 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, SKILL DEEP DIVE)
|
||||
- Explain WHY this workflow exists
|
||||
- Explain WHAT each skill 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 skill 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 `/start` skill 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` skills 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-*` skills re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/finish-work` skill 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
|
||||
|
||||
---
|
||||
|
||||
## SKILL DEEP DIVE
|
||||
|
||||
### /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 /start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
|
||||
- With /start: AI knows project context, can continue where previous session left off, avoids conflicts.
|
||||
|
||||
---
|
||||
|
||||
### /before-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. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### /check - 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.
|
||||
|
||||
---
|
||||
|
||||
### /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
|
||||
|
||||
---
|
||||
|
||||
### /finish-work - Holistic Pre-Commit Review
|
||||
|
||||
**WHY IT EXISTS**:
|
||||
The `/check-*` skills 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
|
||||
|
||||
---
|
||||
|
||||
### /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 `/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] /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] /before-dev** - Inject project-specific development guidelines
|
||||
**[4/8] Investigate and fix the bug** - Actual development work
|
||||
**[5/8] /check** - Re-verify code against guidelines
|
||||
**[6/8] /finish-work** - Holistic cross-layer review
|
||||
**[7/8] Human tests and commits** - Human validates before code enters repo
|
||||
**[8/8] /record-session** - Persist memory for future sessions
|
||||
|
||||
### Example 2: Planning Session (No Code)
|
||||
|
||||
**[1/4] /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] /record-session (with --summary)** - Planning decisions must be recorded
|
||||
|
||||
### Example 3: Code Review Fixes
|
||||
|
||||
**[1/6] /start** - Resume context from previous session
|
||||
**[2/6] /before-dev** - Re-inject guidelines before fixes
|
||||
**[3/6] Fix each CR issue** - Address feedback with guidelines in context
|
||||
**[4/6] /check** - Verify fixes did not introduce new issues
|
||||
**[5/6] /finish-work** - Document lessons from CR
|
||||
**[6/6] Human commits, then /record-session** - Preserve CR lessons
|
||||
|
||||
### Example 4: Large Refactoring
|
||||
|
||||
**[1/5] /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] /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] /start** - See if this bug was investigated before
|
||||
**[2/6] /before-dev** - Guidelines might document known gotchas
|
||||
**[3/6] Investigation** - Actual debugging work
|
||||
**[4/6] /check** - Verify debug changes do not break other things
|
||||
**[5/6] /finish-work** - Debug findings might need documentation
|
||||
**[6/6] Human commits, then /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` skills inject project knowledge.
|
||||
3. **Check after code** - `/check-*` skills catch context drift.
|
||||
4. **Record everything** - /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` skills 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` skills 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 `/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,67 @@
|
||||
---
|
||||
name: record-session
|
||||
description: "Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions."
|
||||
---
|
||||
|
||||
[!] **Prerequisite**: This skill 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 --stdin --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] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
|
||||
- [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, branch auto-complete)** |
|
||||
| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
|
||||
| `python3 ./.trellis/scripts/task.py list` | List active tasks |
|
||||
@@ -0,0 +1,351 @@
|
||||
---
|
||||
name: start
|
||||
description: "Initializes an AI development session by reading workflow guides, developer identity, git status, active tasks, and project guidelines from .trellis/. Classifies incoming tasks and routes to brainstorm, direct edit, or task workflow. Use when beginning a new coding session, resuming work, starting a new task, or re-establishing project context."
|
||||
---
|
||||
|
||||
# Start Session
|
||||
|
||||
Initialize your AI development session and begin working on tasks.
|
||||
|
||||
---
|
||||
|
||||
## Operation Types
|
||||
|
||||
| Marker | Meaning | Executor |
|
||||
|--------|---------|----------|
|
||||
| `[AI]` | Bash scripts or tool calls executed by AI | You (AI) |
|
||||
| `[USER]` | Skills 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
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
This shows available packages and their spec layers. Read the relevant spec indexes:
|
||||
|
||||
```bash
|
||||
cat .trellis/spec/<package>/<layer>/index.md # Package-specific guidelines
|
||||
cat .trellis/spec/guides/index.md # Thinking guides (always read)
|
||||
```
|
||||
|
||||
> **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-specs are injected to the right context, resulting in higher quality code.
|
||||
> The overhead is minimal, but the benefit is significant.
|
||||
|
||||
> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
|
||||
> consider creating subtasks using `--parent` flag or `add-subtask` command.
|
||||
> See the brainstorm skill's Step 8 for details.
|
||||
|
||||
---
|
||||
|
||||
## 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 `/finish-work`
|
||||
|
||||
---
|
||||
|
||||
## Simple Task
|
||||
|
||||
For simple, well-defined tasks:
|
||||
|
||||
1. Quick confirm: "I understand you want to [goal]. Shall I proceed?"
|
||||
2. If no, clarify and confirm again
|
||||
3. **If yes: execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.**
|
||||
- Create task directory (Phase 1 Path B, Step 2)
|
||||
- Write PRD (Step 3)
|
||||
- Research codebase (Phase 2, Step 5)
|
||||
- Configure context (Step 6)
|
||||
- Activate task (Step 7)
|
||||
- Implement (Phase 3, Step 8)
|
||||
- Check quality (Step 9)
|
||||
- Complete (Step 10)
|
||||
|
||||
---
|
||||
|
||||
## Complex Task - Brainstorm First
|
||||
|
||||
For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
|
||||
|
||||
See `/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
|
||||
|
||||
---
|
||||
|
||||
## Task Workflow (Development Tasks)
|
||||
|
||||
**Why this workflow?**
|
||||
- Run a dedicated research pass before coding
|
||||
- Configure specs in jsonl context files
|
||||
- Implement using injected context
|
||||
- Verify with a separate check pass
|
||||
- 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?
|
||||
|
||||
If unclear, ask clarifying questions.
|
||||
|
||||
**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, run a focused research pass and produce:
|
||||
|
||||
1. Relevant spec files in `.trellis/spec/`
|
||||
2. Existing code patterns to follow (2-3 examples)
|
||||
3. Files that will likely need modification
|
||||
|
||||
Use this output format:
|
||||
|
||||
```markdown
|
||||
## Relevant Specs
|
||||
- <path>: <why it's relevant>
|
||||
|
||||
## Code Patterns Found
|
||||
- <pattern>: <example file path>
|
||||
|
||||
## Files to Modify
|
||||
- <path>: <what change>
|
||||
```
|
||||
|
||||
**Step 6: Configure Context** `[AI]`
|
||||
|
||||
Initialize default context:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
|
||||
# type: backend | frontend | fullstack
|
||||
```
|
||||
|
||||
Add specs found in your research pass:
|
||||
|
||||
```bash
|
||||
# For each relevant 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]`
|
||||
|
||||
Implement the task described in `prd.md`.
|
||||
|
||||
- Follow all specs injected into implement context
|
||||
- Keep changes scoped to requirements
|
||||
- Run lint and typecheck before finishing
|
||||
|
||||
**Step 9: Check Quality** `[AI]`
|
||||
|
||||
Run a quality pass against check context:
|
||||
|
||||
- Review all code changes against the specs
|
||||
- Fix issues directly
|
||||
- Ensure lint and typecheck pass
|
||||
|
||||
**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 `/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).
|
||||
|
||||
---
|
||||
|
||||
## Skills Reference
|
||||
|
||||
### User Skills `[USER]`
|
||||
|
||||
| Skill | When to Use |
|
||||
|---------|-------------|
|
||||
| `/start` | Begin a session (this skill) |
|
||||
| `/finish-work` | Before committing changes |
|
||||
| `/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 spec 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 |
|
||||
|
||||
### Workflow Phases `[AI]`
|
||||
|
||||
| Phase | Purpose | Context Source |
|
||||
|-------|---------|----------------|
|
||||
| research | Analyze codebase | direct repo inspection |
|
||||
| implement | Write code | `implement.jsonl` |
|
||||
| check | Review & fix | `check.jsonl` |
|
||||
| debug | Fix specific issues | `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,335 @@
|
||||
---
|
||||
name: update-spec
|
||||
description: "Captures executable contracts and coding knowledge into .trellis/spec/ documents after implementation, debugging, or design decisions. Enforces code-spec depth for infra and cross-layer changes with mandatory sections for signatures, contracts, validation matrices, and test points. Use when a feature is implemented, a bug is fixed, a design decision is made, a new pattern is discovered, or cross-layer contracts change."
|
||||
---
|
||||
|
||||
# Update Code-Spec - Capture Executable Contracts
|
||||
|
||||
When you learn something valuable (from debugging, implementing, or discussion), use this skill 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.
|
||||
|
||||
Required sections for infra/cross-layer specs:
|
||||
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
|
||||
### 3. Contracts
|
||||
### 4. Validation & Error Matrix
|
||||
### 5. Good/Base/Bad Cases
|
||||
### 6. Tests Required
|
||||
### 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 → /update-spec → Knowledge captured
|
||||
↑ ↓
|
||||
/break-loop ←──────────────────── Future sessions benefit
|
||||
(deep bug analysis)
|
||||
```
|
||||
|
||||
- `/break-loop` - Analyzes bugs deeply, often reveals spec updates needed
|
||||
- `/update-spec` - Actually makes the updates (this skill)
|
||||
- `/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