zhongwei/gh-anexpn-claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:54:56 +08:00
commit 5f5aff96e9
26 changed files with 3398 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
skills/dev-guided/SKILL.md Normal file
View File

@@ -0,0 +1,208 @@
---
name: dev-guided
description: Guided development workflow for human-in-the-loop iterative implementation. Use this skill for development work where the human wants to maintain control over key decisions, the problem is exploratory rather than well-defined, or when working incrementally with frequent human feedback. This skill creates problem_statement.md, decisions.md, runbook.md, and progress.md artifacts in a development session folder, then guides iterative implementation sessions where the agent plans work, implements, and records progress.
---
# Guided Development
## Overview
Guided development is a workflow designed for iterative, human-in-the-loop software development. Unlike traditional planning approaches that create detailed upfront plans, this workflow establishes problem boundaries, captures explicit human decisions, and enables incremental implementation with continuous feedback.
**Use this skill when:**
- The problem is exploratory and not fully understood upfront
- Human input is needed for key technical decisions
- Development will proceed iteratively across multiple sessions
- The human wants to maintain control rather than delegate to autonomous execution
## Workflow Decision Tree
When the skill is invoked, determine which phase to enter:
```
Does docs/development/NNN-<name>/ exist with materials?
├─ NO → Initial Setup Phase (create problem_statement, decisions, runbook, progress)
└─ YES → Implementation Session Phase (load context, plan, implement, update progress)
```
## Initial Setup Phase
When no materials exist, guide the human through creating foundational documents via structured Q&A.
### Process
1. **Determine folder location**
- Check for existing development session folders: `docs/development/`
- Determine next number: `NNN` (e.g., 001, 002, etc.)
- Ask human for feature name
- Create folder: `docs/development/NNN-<name>/`
2. **Create problem_statement.md**
- Load the template from `references/template-problem_statement.md`
- Ask questions to understand the problem:
- "What problem are you trying to solve?"
- "What is the scope of this work? What's explicitly out of scope?"
- "What does success look like?"
- "Are there any constraints or requirements?"
- Fill in the template with responses
- Save as `problem_statement.md`
3. **Create decisions.md**
- Load the template from `references/template-decisions.md`
- **CRITICAL RULE:** MUST ask about every unclear aspect. MUST NOT assume "sensible defaults" or "de facto standards"
- Probe for decisions on:
- Language/framework choices
- Library/dependency choices
- Architectural patterns
- Data storage approaches
- Testing strategies
- Error handling approaches
- Security considerations
- For each unclear aspect:
- Explain why a decision is needed
- Present options if helpful (without bias)
- Ask for the human's choice
- Record the decision with rationale
- Save as `decisions.md`
4. **Create runbook.md**
- Load the template from `references/template-runbook.md`
- Ask questions:
- "How should this code be built/compiled?"
- "How should this code be run/tested?"
- "Are there any other validation steps?"
- "At what points during implementation should I pause and ask for your feedback?"
- Fill in build, test, run, and validation instructions
- Create structured feedback points
- Save as `runbook.md`
5. **Create empty progress.md**
- Load the template from `references/template-progress.md`
- Create empty file (will be populated after first implementation session)
- Save as `progress.md`
6. **Complete setup**
- Inform human that setup is complete
- Ask if they want to start the first implementation session now or later
- If now, proceed to Implementation Session Phase
### Reference Materials
For detailed guidance on the initial setup phase, read `references/initial-setup.md`.
## Implementation Session Phase
When materials already exist, start an implementation session to continue development work.
### Process
1. **Load context**
- Read `problem_statement.md` to understand the problem scope
- Read `decisions.md` to understand what choices have been made
- Read `runbook.md` to understand validation and feedback points
- Read `progress.md` to understand what's been done and what's outstanding
- Check for existing `plan-N.md` files to understand previous approaches
2. **Determine session number**
- List existing `plan-N.md` files
- Next session number = max(N) + 1
- If no plan files exist, this is session 1
3. **Enter plan mode**
- Based on loaded context, create a plan for this session
- Plan should include:
- What will be accomplished
- Specific steps to take
- Dependencies between steps
- Expected validation points from runbook
- Outstanding questions or uncertainties
- Present plan to human for approval
4. **Save approved plan**
- After human approves the plan, save as `plan-N.md` where N is the session number
- Proceed with implementation
5. **Implement according to plan**
- Follow the approved plan
- **Respect feedback points:** When reaching a feedback point in runbook.md, MUST pause and ask for human input
- **Document new decisions:** If new unclear aspects arise, update decisions.md and ask for human input
- **Update runbook if needed:** If build/test/validation steps change, update runbook.md
- **Follow existing decisions:** Use the choices recorded in decisions.md
- Perform validation steps from runbook.md
- Ensure all tests pass
6. **Update progress.md**
- Add a new session entry using this format:
```markdown
## Session N (YYYY-MM-DD)
### Accomplished
- [What was implemented/completed]
- [Tests that now pass]
- [Issues that were resolved]
### Outstanding
- [What still needs to be done]
- [Known issues or blockers]
### Questions
- [New unclear aspects that need decisions]
- [Uncertainties or concerns]
```
7. **Session completion**
- Verify all changes are recorded in progress.md
- Verify any new decisions are in decisions.md
- Verify runbook.md is current
- Inform human that session is complete
- Summarize what was accomplished and what's next
### Reference Materials
For detailed guidance on implementation sessions, read `references/implementation-session.md`.
## Key Principles
1. **No Assumptions**: Never assume "sensible defaults" or "de facto standards". Always ask for explicit human decisions.
2. **Respect Feedback Points**: Feedback points in runbook.md are mandatory pause points. Never skip them.
3. **Living Documents**: decisions.md, runbook.md, and progress.md are living documents that evolve throughout the development session.
4. **Session-Scoped Plans**: Each implementation session gets its own plan file. Plans are ephemeral and session-specific, not long-term roadmaps.
5. **Problem-Focused**: problem_statement.md defines the problem and scope, not the solution. It provides boundaries, not prescriptions.
## Example Usage
**Starting new work:**
```
Human: "I want to add OAuth authentication to the app"
Agent: [Invokes dev-guided skill]
Agent: [Creates docs/development/001-oauth-auth/ folder]
Agent: [Guides through creating problem_statement, decisions, runbook, progress]
Agent: "Setup complete. Ready to start first implementation session?"
```
**Continuing existing work:**
```
Human: "Continue working on OAuth" [in directory with existing materials]
Agent: [Invokes dev-guided skill]
Agent: [Loads problem_statement, decisions, runbook, progress]
Agent: [Enters plan mode]
Agent: "Based on progress, I plan to implement token storage. Here's my plan..."
Agent: [After approval, saves as plan-2.md and implements]
Agent: [Updates progress.md with session 2 summary]
```
## Resources
This skill includes reference materials with detailed phase guidance and templates:
### references/
- `initial-setup.md` - Detailed guidance for the initial setup phase
- `implementation-session.md` - Detailed guidance for implementation sessions
- `template-problem_statement.md` - Template for problem statements
- `template-decisions.md` - Template for decisions with examples
- `template-runbook.md` - Template for runbook with feedback point examples
- `template-progress.md` - Template for progress tracking

92
skills/dev-guided/references/implementation-session.md Normal file
View File

@@ -0,0 +1,92 @@
# Implementation Session Phase
When materials already exist in the docs folder, start an implementation session to continue the development work.
## Session Flow
1. Load context from existing materials
2. Enter plan mode and create session plan
3. Implement according to plan
4. Update progress and other materials
## 1. Load Context
Read all existing materials in order:
1. **problem_statement.md** - Understand the problem scope
2. **decisions.md** - Understand what choices have been made
3. **runbook.md** - Understand how to validate work and when to get feedback
4. **progress.md** - Understand what has been done and what's outstanding
Additionally, check for existing plan files (plan-1.md, plan-2.md, etc.) to understand previous approaches.
## 2. Create Session Plan
Enter plan mode and create a plan for this implementation session:
**Plan should include:**
- What will be accomplished in this session
- Specific steps to take
- Dependencies between steps
- Expected validation points from runbook.md
- Outstanding questions or uncertainties
**Determine session number:**
- Count existing plan-N.md files
- Next session number = max(N) + 1
- If no plan files exist, this is session 1
**After plan is approved by human:**
- Save plan as `plan-N.md` where N is the session number
- Proceed with implementation
## 3. Implement According to Plan
Follow the plan created in step 2.
**During implementation:**
- **Respect feedback points:** When reaching a feedback point defined in runbook.md, MUST pause and ask for human input
- **Document new decisions:** If new unclear aspects arise, update decisions.md and ask for human input
- **Update runbook if needed:** If build/test/validation steps change, update runbook.md
- **Follow existing decisions:** Use the choices recorded in decisions.md
**Testing and validation:**
- Follow the build/test instructions in runbook.md
- Perform validation steps defined in runbook.md
- Ensure all tests pass before completing session
## 4. Update Progress
At the end of the session, update progress.md with a new entry:
**Entry format:**
```markdown
## Session N (YYYY-MM-DD)
### Accomplished
- [What was implemented/completed]
- [Tests that now pass]
- [Issues that were resolved]
### Outstanding
- [What still needs to be done]
- [Known issues or blockers]
### Questions
- [New unclear aspects that need decisions]
- [Uncertainties or concerns]
```
**Also update if needed:**
- **decisions.md** - If new decisions were made
- **runbook.md** - If validation steps changed
## Session Completion
After updating all materials:
1. Verify all changes are recorded in progress.md
2. Verify any new decisions are in decisions.md
3. Verify runbook.md is current
4. Inform human that the session is complete
5. Summarize what was accomplished and what's next

82
skills/dev-guided/references/initial-setup.md Normal file
View File

@@ -0,0 +1,82 @@
# Initial Setup Phase
When starting a new development session (no materials exist in the docs folder), guide the human through creating the foundational documents through structured Q&A.
## Phase Flow
1. Create problem_statement.md
2. Create decisions.md
3. Create runbook.md
4. Create empty progress.md
## 1. Problem Statement Creation
**Purpose:** Define what problem is being solved, providing scope without prescribing solution.
**Questions to ask:**
- "What problem are you trying to solve?"
- "What is the scope of this work? What's explicitly out of scope?"
- "What does success look like for this work?"
- "Are there any constraints or requirements I should know about?"
**Format:** Use the template in `template-problem_statement.md`
**Key principle:** Focus on the WHAT and WHY, not the HOW.
## 2. Decisions Creation
**Purpose:** Explicitly capture human choices on unclear aspects. NO assumptions or defaults.
**Critical rule:** MUST ask about every unclear aspect. MUST NOT assume "sensible defaults" or "de facto standards."
**Areas to probe:**
- Language/framework choices
- Library/dependency choices
- Architectural patterns
- Data storage approaches
- Testing strategies
- Error handling approaches
- Security considerations
**Questions format:**
- "Which [language/library/pattern] should be used for X?"
- "How should Y be handled?"
- "What approach should be taken for Z?"
**For each unclear aspect:**
1. Explain why a decision is needed
2. Present options if helpful (but don't bias toward one)
3. Ask for the human's choice
4. Record the decision and rationale in decisions.md
**Format:** Use the template in `template-decisions.md`
**Key principle:** Capture explicit human choices, not assumptions.
## 3. Runbook Creation
**Purpose:** Document how to validate work and when to get feedback during implementation.
**Questions to ask:**
- "How should this code be built/compiled?"
- "How should this code be run/tested?"
- "Are there any other validation steps I should perform?"
- "At what points during implementation should I pause and ask for your feedback?"
**Format:** Use the template in `template-runbook.md`
**Key sections:**
- Build instructions
- Test instructions
- Feedback points (structured list of when to pause for human input)
- Other validation steps
**Key principle:** Establish clear validation and feedback loops.
## 4. Progress Initialization
Create an empty progress.md file using the template in `template-progress.md`. This will be populated after the first implementation session.
## Completing Initial Setup
After creating all four files, inform the human that the setup is complete and ask if they want to start the first implementation session now or later.

65
skills/dev-guided/references/template-decisions.md Normal file
View File

@@ -0,0 +1,65 @@
# Decisions
This document captures explicit human choices on unclear aspects of the implementation. Each decision includes the context, options considered, and the chosen approach with rationale.
## Decision Template
Use this format for each decision:
```markdown
## [Decision Topic]
**Context:** [Why does this decision need to be made?]
**Options Considered:**
1. [Option A] - [Brief description]
2. [Option B] - [Brief description]
**Decision:** [Chosen option]
**Rationale:** [Why this choice was made]
**Date:** YYYY-MM-DD
```
---
## Example Decisions
### Language Choice
**Context:** Need to choose implementation language for the new service.
**Options Considered:**
1. Python - Good for rapid development, rich ecosystem
2. Go - Better performance, strong concurrency support
3. Rust - Maximum performance and safety
**Decision:** Python
**Rationale:** Team is most familiar with Python, and performance requirements don't justify the learning curve of Go or Rust. We can optimize later if needed.
**Date:** 2025-11-24
---
### Database Storage
**Context:** Need to store user session data.
**Options Considered:**
1. PostgreSQL - Relational, ACID guarantees
2. Redis - In-memory, fast but volatile
3. DynamoDB - Managed NoSQL, scalable
**Decision:** Redis with PostgreSQL backup
**Rationale:** Redis for fast session access, PostgreSQL for persistence. Hybrid approach gives us speed and durability.
**Date:** 2025-11-24
---
## Current Decisions
[Add decisions here as they are made during the development session]

30
skills/dev-guided/references/template-problem_statement.md Normal file
View File

@@ -0,0 +1,30 @@
# Problem Statement
## Problem
[Describe the problem being solved in 2-4 sentences. Focus on WHAT needs to be accomplished and WHY, not HOW it will be done.]
## Scope
### In Scope
- [What is included in this work]
- [Specific features or capabilities to be added]
### Out of Scope
- [What is explicitly not included]
- [Future work or related features that won't be addressed]
## Success Criteria
[What does success look like? How will you know this is complete?]
- [Measurable outcome 1]
- [Measurable outcome 2]
## Constraints
[Any constraints or requirements that must be respected]
- [Technical constraints]
- [Time or resource constraints]
- [Compatibility requirements]

41
skills/dev-guided/references/template-progress.md Normal file
View File

@@ -0,0 +1,41 @@
# Progress
This document tracks the progress of implementation sessions. Each session adds a new entry describing what was accomplished, what's outstanding, and any questions that arose.
---
## Session 1 (YYYY-MM-DD)
### Accomplished
- [What was implemented or completed]
- [Tests that now pass]
- [Issues that were resolved]
### Outstanding
- [What still needs to be done]
- [Known issues or blockers]
### Questions
- [New unclear aspects that need decisions]
- [Uncertainties or concerns]
---
## Session 2 (YYYY-MM-DD)
### Accomplished
- [What was implemented or completed]
- [Tests that now pass]
- [Issues that were resolved]
### Outstanding
- [What still needs to be done]
- [Known issues or blockers]
### Questions
- [New unclear aspects that need decisions]
- [Uncertainties or concerns]
---
[Continue adding session entries chronologically]

80
skills/dev-guided/references/template-runbook.md Normal file
View File

@@ -0,0 +1,80 @@
# Runbook
This document describes how to build, test, and validate the work in this development session, as well as when to pause for human feedback.
## Build Instructions
[How to build/compile the code]
```bash
# Example:
npm install
npm run build
```
## Test Instructions
[How to run tests]
```bash
# Example:
npm test
npm run test:integration
```
## Run Instructions
[How to run the application locally for manual testing]
```bash
# Example:
npm run dev
# Then visit http://localhost:3000
```
## Validation Steps
[Any additional validation steps beyond automated tests]
- [ ] Manual testing checklist item 1
- [ ] Manual testing checklist item 2
- [ ] Performance check
- [ ] Security review
## Feedback Points
These are structured points where the agent must pause and ask for human input during implementation.
### After [specific milestone or step]
**Purpose:** [Why feedback is needed at this point]
**Questions to ask:** [What specifically to verify or get approval on]
### Before [specific action]
**Purpose:** [Why approval is needed before proceeding]
**Questions to ask:** [What to confirm with human]
### When [specific condition occurs]
**Purpose:** [Why this situation requires human input]
**Questions to ask:** [What guidance is needed]
---
## Example Feedback Points
### After implementing core authentication logic
**Purpose:** Verify the authentication approach matches expectations before building dependent features
**Questions to ask:**
- Does the login flow work as expected?
- Should we add any additional authentication factors?
### Before making database schema changes
**Purpose:** Schema changes are hard to reverse, need approval
**Questions to ask:**
- Review proposed schema changes
- Confirm migration strategy
### When encountering an unclear requirement
**Purpose:** Avoid making assumptions about product behavior
**Questions to ask:**
- Clarify the expected behavior for [specific scenario]
- Get decision on [unclear aspect]

121
skills/dev-impl/SKILL.md Normal file
View File

@@ -0,0 +1,121 @@
---
name: dev-impl
description: Execute implementation of a single task from a development plan in an isolated session. This skill should be used when implementing one task from a task list created by dev-spec. Use this for focused, context-efficient implementation that strictly follows the plan.
---
# Development Implementation
## Overview
Execute the implementation of a single task from a development plan. This skill operates in an isolated session with minimal context, focusing exclusively on completing one task according to the detailed plan.
## When to Use This Skill
Use this skill when:
- Implementing a task from a task list (created by dev-spec)
- Starting a fresh implementation session without carrying over unnecessary context
- Following a detailed plan that has already been created
- Working on one specific unit of work that will be reviewed separately
## Core Principle
**DO NOT DEVIATE FROM THE PLAN.** The planning phase has already determined the approach. This phase is strictly about execution according to the plan.
## Workflow
### Step 1: Identify the Task
1. Ask the user to provide the path to the task list file
2. Read the task list file
3. Identify the next uncompleted task (first `- [ ]` item)
4. Note the plan line numbers referenced for this task
### Step 2: Load Context
Read ONLY the necessary context:
1. **Task list** (`docs/development/NNN-<name>/tasks.md`) - to identify the task
2. **Spec file** (path specified at top of task list) - to understand the overall goal
3. **Plan section** (path and line numbers specified in task list) - to get detailed instructions for this specific task
**Important:** Do NOT read unrelated code or explore beyond what the plan specifies. Keep the context focused and minimal.
### Step 3: Implement According to Plan
Follow the plan section for this task exactly:
1. Touch the files specified in the plan
2. Follow the code structure and patterns described
3. Implement tests as specified (TDD approach)
4. Follow the testing approach described
5. Make changes incrementally
6. Test as you go
**Key principles during implementation:**
- DRY (Don't Repeat Yourself)
- YAGNI (You Aren't Gonna Need It)
- TDD (Test-Driven Development)
- Follow the plan's guidance on file organization, patterns, and test design
- Make small, focused changes
- DO NOT add features not in the plan
- DO NOT refactor beyond what the plan specifies
### Step 4: Self-Review
Before declaring the task complete:
1. Verify all requirements from the plan section are met
2. Run the tests
3. Check that the implementation matches the plan's intent
4. Ensure code follows project conventions
### Step 5: Await Review
After implementation is complete:
1. Inform the user the task is complete
2. DO NOT mark the task as complete in the task list yet
3. Wait for the user to run the dev-review skill
4. The user will either:
- Provide reviewer feedback (return to Step 3 to address it)
- Confirm sign-off (proceed to Step 6)
### Step 6: Mark Complete and Commit
Only after receiving explicit sign-off from the reviewer:
1. Mark the task as complete in the task list (change `- [ ]` to `- [x]`)
2. Create a git commit with a clear message describing what was implemented
3. Include reference to the task number or description
**Commit message format:**
```
Implement [task description]
- Brief summary of what was done
- Reference to task list item
Related to: docs/development/NNN-<name>/tasks.md
```
## Important Constraints
1. **One task only** - Do not proceed to the next task automatically
2. **No deviation** - Follow the plan exactly; don't improvise or "improve" unless the plan says to
3. **Isolated session** - This should be a fresh session without unrelated context
4. **No premature completion** - Only mark complete after reviewer sign-off
5. **Always commit** - Every completed task gets its own commit
## Handling Issues
If you encounter problems during implementation:
- **Plan is unclear:** Ask the user to clarify (may need to update the plan)
- **Plan approach doesn't work:** Stop and inform the user (may need to update the plan)
- **Tests are failing:** This is your responsibility - fix them before completing
- **Unexpected conflicts:** Stop and ask the user for guidance
**DO NOT** solve problems by deviating from the plan without explicit permission.
## Context Awareness
This skill is part of a larger workflow:
- **dev-spec** creates the spec, plan, and task list
- **dev-impl** (this skill) implements individual tasks
- **dev-review** reviews completed work
The implementer role is deliberately constrained and focused. Strategic thinking and design decisions have already been made in the planning phase.

180
skills/dev-review/SKILL.md Normal file
View File

@@ -0,0 +1,180 @@
---
name: dev-review
description: Review and validate implementation work against the spec and plan. This skill should be used after an implementer completes a task (using dev-impl) or when checking final deliverables. Use this to ensure work meets requirements before sign-off.
---
# Development Review
## Overview
Review completed implementation work to ensure it meets the specification and plan requirements. This skill provides thorough checking with fresh eyes, catching issues before work is marked complete.
## When to Use This Skill
Use this skill when:
- An implementer has completed a task and needs review before sign-off
- Checking a single task implementation (task-level review)
- Checking all completed work at the end (final review)
- Validating that implementation matches the spec and plan
## Review Types
### Type 1: Task-Level Review
Review a single completed task before it gets marked complete and committed.
**When:** After the implementer completes one task using dev-impl
**Process:**
1. Read the task list to identify which task was just completed
2. Read the spec file for overall context
3. Read the relevant plan section for this specific task
4. Examine the implementation work (code changes, tests, etc.)
5. Verify the implementation against requirements
6. Provide feedback
### Type 2: Final Review
Review all completed work at the end of the development session.
**When:** After all tasks in the task list are marked complete
**Process:**
1. Read the complete spec
2. Read the complete plan
3. Read the task list to see all completed work
4. Examine the entire implementation
5. Verify everything works together as intended
6. Generate a final report or identify remaining issues
## Review Workflow
### Step 1: Load Context
For **task-level review**, read:
1. Task list (`docs/development/NNN-<name>/tasks.md`)
2. Spec file (path at top of task list)
3. Plan section for the specific task (line numbers in task list)
4. The actual implementation (files modified)
For **final review**, read:
1. Complete spec (`docs/development/NNN-<name>/spec.md`)
2. Complete plan (`docs/development/NNN-<name>/plan.md`)
3. Task list to understand what was done (`docs/development/NNN-<name>/tasks.md`)
4. All implementation work
### Step 2: Check Against Requirements
Verify that the implementation:
1. **Meets the spec** - Does it implement what was designed?
2. **Follows the plan** - Does it follow the specified approach?
3. **Has proper tests** - Are there adequate tests? Do they pass?
4. **Follows conventions** - Does it match project code style and patterns?
5. **Is complete** - Are there any missing pieces?
6. **Works correctly** - Run tests, check functionality
### Step 3: Check Code Quality
Look for:
1. **DRY violations** - Is there unnecessary duplication?
2. **YAGNI violations** - Are there features that weren't in the plan?
3. **Poor test design** - Are tests actually testing logic or just mocking?
4. **Edge cases** - Are edge cases handled?
5. **Error handling** - Is error handling appropriate?
6. **Documentation** - Are complex parts documented?
### Step 4: Provide Feedback
**If issues are found:**
1. Document specific problems clearly
2. Reference exact locations (file:line)
3. Explain what needs to change and why
4. Prioritize issues (blocking vs. nice-to-have)
5. Return feedback to the user
**If no issues are found:**
1. Confirm the work meets all requirements
2. Explicitly state sign-off
3. For task-level review: Tell user to inform implementer to mark complete and commit
4. For final review: Generate a completion report
### Step 5: Follow-Up
**For task-level review with issues:**
- User will copy feedback to the implementer session
- Implementer will fix and resubmit
- Repeat review process
**For task-level review with sign-off:**
- Implementer marks task complete in task list
- Implementer creates commit
- Move to next task
**For final review with issues:**
- User spawns new implementer session to address issues
- Repeat until all issues resolved
**For final review with sign-off:**
- Generate final report documenting what was delivered
- Confirm all tasks complete and requirements met
## Review Principles
1. **Fresh perspective** - Review with no assumptions about what should be there
2. **Spec is truth** - The spec defines what needs to be done
3. **Plan is guidance** - The plan defines how it should be done
4. **Be thorough** - Don't just skim; actually check the work
5. **Be specific** - Vague feedback wastes everyone's time
6. **Be fair** - Don't ask for changes beyond the spec/plan without good reason
## What NOT to Do
1. **Don't accept insufficient work** - If it doesn't meet requirements, don't sign off
2. **Don't scope creep** - Don't ask for features not in the spec unless there's a genuine issue
3. **Don't skip testing** - Always verify tests exist and pass
4. **Don't assume** - Actually read the code; don't just trust it works
5. **Don't be vague** - "This looks wrong" is not helpful; "Line 42: this should handle null values" is helpful
## Final Report Format
For final reviews that pass, generate a report like:
```markdown
# Final Review Report: [Feature/Fix Name]
**Date:** [Date]
**Spec:** docs/development/NNN-<name>/spec.md
**Plan:** docs/development/NNN-<name>/plan.md
**Tasks:** docs/development/NNN-<name>/tasks.md
## Summary
[Brief overview of what was implemented]
## Review Results
✅ All requirements from spec met
✅ Implementation follows plan
✅ Tests present and passing
✅ Code quality acceptable
✅ All tasks completed
## Deliverables
- [List of files created/modified]
- [Number of tests added]
- [Any documentation updated]
## Sign-Off
Implementation complete and ready for integration.
```
## Context Awareness
This skill is part of a larger workflow:
- **dev-spec** creates the spec, plan, and task list
- **dev-impl** implements individual tasks
- **dev-review** (this skill) reviews completed work
The reviewer role is deliberately independent and critical. Provide honest assessment without worrying about hurting feelings - the goal is quality work.

130
skills/dev-spec/SKILL.md Normal file
View File

@@ -0,0 +1,130 @@
---
name: dev-spec
description: Guide a complete design and planning session for development work (features, bugfixes, hotfixes). This skill should be used when starting new development work that requires a spec, detailed implementation plan, and task breakdown. Use this for substantial changes that need careful planning and tracking.
---
# Development Spec & Planning
## Overview
Guide the creation of a complete development specification, implementation plan, and task list for new features, bugfixes, or hotfixes. This skill covers three phases: specification generation, detailed planning, and task breakdown.
## Execution Model
**This skill runs in the main conversation, not as a subagent.**
The specification phase requires back-and-forth interaction with the user (asking questions, getting approval for each section). Subagents cannot interact with users, so this phase must run directly in the main conversation.
For the planning and task extraction phases, you have two options:
1. **Continue in main conversation** - Simpler, maintains context
2. **Spawn subagents** - Use when you want isolated context for planning
If spawning subagents for planning/tasks, you must embed all necessary context in the prompt (see dev-workflow skill for templates).
## When to Use This Skill
Use this skill when:
- Starting a new feature, bugfix, or hotfix that requires planning
- The work is substantial enough to benefit from a written spec and plan
- Multiple implementation steps need to be tracked
- An implementation will happen in separate sessions requiring clear guidance
## Workflow
### Phase 1: Specification Generation
Start by gathering context and refining the user's idea into a fully-formed specification.
**Approach:**
1. Examine the current project state to understand the starting point
2. Ask clarifying questions ONE AT A TIME to refine the idea
- Prefer multiple-choice questions for efficiency
- Open-ended questions are acceptable when necessary
- NEVER ask more than one question per message
3. Continue until the requirements are fully understood
4. Present the design specification in sections of 200-300 words
5. Ask for confirmation after EACH section before proceeding
**Initial prompt to use:**
> I've got an idea I want to talk through with you. I'd like you to help me turn it into a fully formed design and spec (and eventually an implementation plan). Check out the current state of the project in our working directory to understand where we're starting off, then ask me questions, one at a time, to help refine the idea. Ideally, the questions would be multiple choice, but open-ended questions are OK, too. Don't forget: only one question per message. Once you believe you understand what we're doing, stop and describe the design to me, in sections of maybe 200-300 words at a time, asking after each section whether it looks right so far.
**Output:** Write the complete specification to `docs/development/NNN-<name>/spec.md` where:
- `NNN` is a sequential number (ask user for the number or determine the next available)
- `<name>` is a short descriptive name (feature name, fix name, etc.)
### Phase 2: Implementation Planning
After the spec is approved, create a comprehensive implementation plan.
**The plan answers:** "In what order do I build this and where does each piece go?"
**CRITICAL: No code in the plan.** No snippets, pseudocode, or implementation sketches. Code belongs in dev-impl where it can be written, tested, and iterated immediately.
**Approach:**
1. **Tech stack selection** (when needed) - If new libraries/frameworks are required:
- Research options and evaluate against project needs
- Document the choice and rationale
- Get approval before proceeding
2. **File/module mapping** - Where new code lives (exact paths)
3. **Dependency order** - What to build first so later pieces have foundations
4. **Integration points** - Where new code connects to existing code, patterns to follow
5. **Risk flags** - Parts that might be tricky or need investigation
6. **Testing guidance** - What to test, where test files go, scenarios to cover
**Prompt to use:**
> Great. I need your help to write out an implementation plan. The plan should answer: "In what order do I build this and where does each piece go?" Do NOT write any code—describe what needs to be built, not how to code it. Include: tech stack decisions (if new dependencies needed), file paths for all new/modified code, dependency order between tasks, integration points with existing code, and risk flags. Break work into bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
**Output:** Write the complete plan to `docs/development/NNN-<name>/plan.md`
### Phase 3: Task List Extraction
Extract a structured task list from the implementation plan.
**Task granularity:** Each task should deliver a coherent piece of functionality that can be tested on its own. Tasks are NOT file operations ("create directory", "create file") or single-line changes. If you find yourself writing tasks like "Create src/models directory" and "Create User.ts file" - combine them into "Create User model with validation".
**Task list format:**
```markdown
# Task List: <Feature/Fix Name>
**Spec:** docs/development/NNN-<name>/spec.md
**Plan:** docs/development/NNN-<name>/plan.md
## Tasks
- [ ] Task 1 description (Plan lines: XX-YY)
- [ ] Task 2 description (Plan lines: ZZ-AA)
- [ ] Task 3 description (Plan lines: BB-CC)
...
## Instructions for Implementer
1. Implement ONE task at a time
2. Read the corresponding plan section (line numbers provided)
3. Follow the plan - DO NOT DEVIATE
4. After completing a task and getting sign-off, mark it complete with [x]
5. Commit after each completed task
```
**Output:** Write the task list to `docs/development/NNN-<name>/tasks.md`
## File Structure
All files for a development session are stored in:
```
docs/development/NNN-<name>/
├── spec.md # Design specification
├── plan.md # Detailed implementation plan
└── tasks.md # Task tracking list
```
## Next Steps
After completing all three phases, guide the user to use:
- **dev-impl** skill: For implementing individual tasks in isolated sessions
- **dev-review** skill: For reviewing completed work
Remind the user:
1. Implementation should happen in separate sessions (one task at a time)
2. The implementer should read: task list → spec → relevant plan section
3. After implementation, spawn a checker session using dev-review
4. Only mark tasks complete after review sign-off

313
skills/dev-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,313 @@
---
name: dev-workflow
description: Complete development workflow from specification to implementation to review. Use this skill for any substantial development work (features, bugfixes, hotfixes) that requires planning, isolated implementation, and review. Orchestrates the entire process using specialized subagents.
---
# Development Workflow
## Overview
Orchestrate a complete, structured development workflow from initial design through final delivery. This skill manages the entire process: specification generation, detailed planning, task breakdown, isolated implementation, and thorough review.
## When to Use This Skill
Use this skill when:
- Starting any substantial development work (feature, bugfix, hotfix)
- Need a structured approach with clear planning and review
- Want isolated implementation sessions to minimize context pollution
- Working on changes that benefit from systematic tracking
**Don't use for:** Trivial changes, exploratory work, or when a quick iteration is more appropriate.
## Architecture: Interactive vs Automated Phases
This workflow has two types of phases:
**Interactive phases (run in main conversation):**
- Specification - Requires back-and-forth Q&A with user
- Review - Requires routing feedback and getting sign-off
**Automated phases (run as subagents):**
- Planning - Transforms spec into detailed plan
- Task extraction - Breaks plan into trackable tasks
- Implementation - Executes one task per subagent
**Why this split:** Subagents cannot interact with the user. They run autonomously and return a single result. Interactive phases must run in the main conversation.
## Workflow Phases
### Phase 1: Specification (Interactive - Main Conversation)
Generate a comprehensive design specification through iterative questioning.
**How to run:** Follow the instructions in `references/spec_phase.md` directly in the main conversation.
**Process:**
1. Examine the project to understand current state
2. Ask ONE question at a time (preferring multiple choice)
3. Refine understanding through Q&A until certain
4. Present specification in 200-300 word sections
5. Get approval for each section before proceeding
6. Write final spec to `docs/development/NNN-<name>/spec.md`
**User involvement:** Answer questions, approve spec sections
### Phase 2: Planning (Automated - Subagent)
Create detailed implementation plan assuming implementer has minimal context.
**How to run:** Spawn a subagent with rich context embedded in the prompt.
**Subagent prompt must include:**
1. Full content of the approved spec (not just the path)
2. Project structure summary (key directories, technologies)
3. Relevant existing code patterns to follow
4. The complete instructions from `references/plan_phase.md`
5. Output path: `docs/development/NNN-<name>/plan.md`
**User involvement:** Review and approve the plan
### Phase 3: Task Extraction (Automated - Subagent)
Break down the plan into trackable tasks.
**How to run:** Spawn a subagent with rich context embedded in the prompt.
**Subagent prompt must include:**
1. Full content of the plan (not just the path)
2. The complete instructions from `references/tasks_phase.md`
3. Output path: `docs/development/NNN-<name>/tasks.md`
**User involvement:** Review task list
### Phase 4: Implementation (Automated - Subagent per Task)
Implement tasks one at a time in fresh, isolated sessions.
**Implementation Options:**
**Option A: Claude Subagent (Recommended)**
For each task, spawn a fresh subagent with rich context.
**Subagent prompt must include:**
1. The specific task description and number
2. Relevant sections from the spec (not the whole spec unless needed)
3. The specific plan section for this task (extract by line numbers)
4. The complete instructions from `references/impl_phase.md`
5. Key project context: file locations, patterns, test commands
The subagent implements according to plan (NO deviation), follows TDD/DRY/YAGNI, completes one task, then stops.
**Option B: External Coding Agent**
1. Provide the external agent with:
- Task list file path: `docs/development/NNN-<name>/tasks.md`
- Spec file path: `docs/development/NNN-<name>/spec.md`
- Plan file path: `docs/development/NNN-<name>/plan.md`
- Implementation instructions: `references/impl_phase.md` (from this skill)
2. Direct the agent to implement the next uncompleted task
3. Agent reads task → spec → relevant plan section → implements
4. Agent reports completion (but does NOT mark complete or commit yet)
**Option C: Human Implementation**
1. Human reads the next task from tasks.md
2. Human reads corresponding spec and plan sections
3. Human implements according to plan
4. Human reports completion for review
**User involvement:** Choose implementation method, trigger each task, provide clarifications if needed
### Phase 5: Review (Interactive - Main Conversation)
Review completed work before marking complete.
**How to run:** Follow the instructions in `references/review_phase.md` directly in the main conversation.
**Process:**
1. Read the spec, plan section, and implementation
2. Check against requirements, code quality, tests
3. Provide specific feedback OR sign-off
4. Route feedback to implementer if issues found
5. After sign-off, authorize task completion and commit
**User involvement:**
- Trigger review after implementation completes
- Authorize task completion and commit after sign-off
- Decide when to do final review
## Using This Skill
### Quick Start
Invoke this skill and say:
> "I want to implement [feature/fix description]"
The skill will guide you through each phase, running interactive phases in the main conversation and spawning subagents for automated phases.
### Manual Phase Control
You can also invoke specific phases:
- **"Start spec phase"** - Begin specification (runs in main conversation)
- **"Generate plan"** - Create plan from existing spec (spawns subagent)
- **"Extract tasks"** - Break plan into tasks (spawns subagent)
- **"Implement next task"** - Implement next uncompleted task (spawns subagent)
- **"Review last implementation"** - Review completed work (runs in main conversation)
- **"Final review"** - Check all completed work together (runs in main conversation)
## Subagent Context Requirements
**Critical:** Subagents start with NO context. They cannot read files unless you tell them to, and even then they may not find the right information. For reliable results, **embed all necessary content directly in the subagent prompt**.
### Planning Subagent Prompt Template
```
You are a planning agent. Create a comprehensive implementation plan.
## Instructions
[Paste full content of references/plan_phase.md]
## Approved Specification
[Paste full content of docs/development/NNN-<name>/spec.md]
## Project Context
- Technologies: [list]
- Key directories: [list with descriptions]
- Relevant patterns: [describe existing patterns to follow]
- Test command: [command]
## Output
Write the plan to: docs/development/NNN-<name>/plan.md
```
### Task Extraction Subagent Prompt Template
```
You are a task extraction agent. Break down the plan into trackable tasks.
## Instructions
[Paste full content of references/tasks_phase.md]
## Implementation Plan
[Paste full content of docs/development/NNN-<name>/plan.md]
## Output
Write the task list to: docs/development/NNN-<name>/tasks.md
```
### Implementation Subagent Prompt Template
```
You are an implementation agent. Implement ONE task exactly as specified.
## Instructions
[Paste full content of references/impl_phase.md]
## Your Task
Task [N]: [description]
## Relevant Specification
[Paste relevant sections from spec.md]
## Plan Section for This Task
[Paste lines XX-YY from plan.md]
## Project Context
- Test command: [command]
- Files to modify: [list from plan]
- Patterns to follow: [describe]
## Constraints
- DO NOT DEVIATE FROM THE PLAN
- Implement this ONE task only
- Report completion but do NOT mark complete or commit
```
## File Structure
All workflow artifacts are stored in:
```
docs/development/NNN-<name>/
├── spec.md # Design specification
├── plan.md # Implementation plan
└── tasks.md # Task tracking list
```
The NNN-<name> directory structure is created in Phase 1.
## Key Principles
1. **Separation of concerns** - Design, implementation, and review are distinct phases
2. **Interactive vs automated** - User-facing phases run in main conversation; automated phases use subagents
3. **Rich subagent context** - Embed all necessary content in subagent prompts, not just file paths
4. **Plan adherence** - Implementers follow the plan strictly
5. **Incremental commits** - Each task gets its own commit after review
6. **Quality gates** - Nothing is marked complete without review sign-off
## Workflow State Management
Track workflow progress through:
- Task list checkboxes (`- [ ]` → `- [x]`)
- Commit history (one commit per completed task)
- File timestamps in docs/development/NNN-<name>/
## Advanced Usage
### Resuming After Interruption
If interrupted mid-workflow:
1. Read the task list to see completed tasks
2. Use "Implement next task" to continue
3. The subagent will pick up from the first uncompleted task
### Modifying the Plan
If the plan needs adjustment:
1. Edit `docs/development/NNN-<name>/plan.md`
2. Update affected tasks in `tasks.md`
3. Continue implementation with updated plan
### Parallel Implementation
For independent tasks, spawn multiple implementation agents in parallel:
> "Implement tasks 1, 3, and 5 in parallel"
Review each independently before marking complete.
### Using External Coding Agents
To use external agents (Cursor, Windsurf, Aider, etc.) for implementation:
1. **Complete spec, plan, and task phases** in Claude (phases 1-3)
2. **Export the context** to the external agent:
- Task list: `docs/development/NNN-<name>/tasks.md`
- Spec: `docs/development/NNN-<name>/spec.md`
- Plan: `docs/development/NNN-<name>/plan.md`
- Implementation guide: Extract `references/impl_phase.md` from this skill
3. **Instruct the external agent:**
```
Read the task list at [path]. Implement the next uncompleted task.
Follow the implementation guide in impl_phase.md strictly.
Read the spec and the plan section referenced in the task.
DO NOT mark the task complete or commit - report completion only.
```
4. **After implementation**, return to Claude for review (phase 5)
5. **Route feedback** between Claude reviewer and external implementer
6. **After sign-off**, external agent (or human) marks complete and commits
This approach allows you to:
- Use Claude for planning and review (its strength)
- Use external agents for implementation (potentially faster or with different capabilities)
- Maintain the structured workflow and quality gates
## References
Detailed instructions for each phase are in `references/`:
- `spec_phase.md` - Specification generation guidance (used directly in main conversation)
- `plan_phase.md` - Planning requirements and format (embedded in subagent prompt)
- `tasks_phase.md` - Task extraction rules (embedded in subagent prompt)
- `impl_phase.md` - Implementation constraints and workflow (embedded in subagent prompt)
- `review_phase.md` - Review checklist and standards (used directly in main conversation)
**For interactive phases:** Read the reference file and follow its instructions directly.
**For automated phases:** Read the reference file and embed its content in the subagent prompt.

244
skills/dev-workflow/references/impl_phase.md Normal file
View File

@@ -0,0 +1,244 @@
# Implementation Phase Instructions
You are an implementation agent executing a single task from a development plan.
> **Note:** These instructions are agent-agnostic. Whether you are a Claude subagent, an external coding agent (Cursor, Windsurf, Aider, etc.), or a human developer, follow these instructions exactly.
## Your Mission
Implement ONE task according to the detailed plan. Your session has isolated context to avoid pollution. Follow the plan exactly - do not deviate.
## Core Principle
**DO NOT DEVIATE FROM THE PLAN.**
The planning phase has already determined the approach. Your job is execution, not strategy.
## Process
### Step 1: Identify Your Task
1. Ask the user for the task list path (if not provided)
2. Read `docs/development/NNN-<name>/tasks.md`
3. Find the first uncompleted task (first `- [ ]` item)
4. Note the plan line numbers for this task
**Output:**
```
I will implement: Task [N]: [description]
Plan reference: lines XX-YY
```
### Step 2: Load Minimal Context
Read ONLY what you need:
1. **Task list** - To identify the task (already read)
2. **Spec file** - To understand the overall goal (path in task list)
3. **Plan section** - For detailed instructions (specific lines only)
**DO NOT:**
- Read unrelated code
- Explore beyond what the plan specifies
- Load unnecessary context
- "Get familiar" with the codebase
Keep your context focused and minimal.
### Step 3: Implement Following TDD
Use Test-Driven Development:
1. **Red** - Write a failing test first
- Test what the plan specifies
- Use real data, not mocks (especially for E2E)
- Follow test structure from the plan
2. **Green** - Implement the minimal code to pass
- Follow file structure from the plan
- Use patterns specified in the plan
- Touch only files mentioned in the plan
3. **Refactor** - Clean up if needed
- Eliminate duplication (DRY)
- But only within scope of this task
- Don't refactor beyond what the plan specifies
4. **Repeat** - For each requirement in this task
### Step 4: Follow Key Principles
Throughout implementation:
- **DRY** - Don't repeat yourself (within this task's scope)
- **YAGNI** - Only implement what's in the plan, nothing more
- **TDD** - Tests first, always
- **Small changes** - Incremental progress
- **Plan adherence** - The plan is your guide
### Step 5: Self-Review
Before declaring complete:
1. ✅ All requirements from the plan section are met
2. ✅ Tests are written and passing
3. ✅ Code follows project conventions
4. ✅ No errors or warnings
5. ✅ Implementation matches plan's intent
Run the tests:
```bash
[Use test command from plan]
```
### Step 6: Report Completion
When done:
```
Task [N] implementation complete.
Changes made:
- [File 1]: [what changed]
- [File 2]: [what changed]
Tests: [N] passing
Ready for review.
```
**DO NOT:**
- Mark the task as complete in tasks.md (reviewer does this after sign-off)
- Commit (happens after sign-off)
- Proceed to the next task
### Step 7: Handle Review Feedback
After the user runs dev-review:
**If reviewer has issues:**
- User will provide specific feedback
- Address the feedback
- Return to Step 5 (self-review)
- Report completion again
**If reviewer signs off:**
- User will confirm sign-off
- Proceed to Step 8
### Step 8: Mark Complete and Commit
Only after explicit sign-off:
1. **Update task list:**
- Change `- [ ]` to `- [x]` for this task
- Update progress counts
- Save the file
2. **Create commit:**
```bash
git add [files]
git commit -m "$(cat <<'EOF'
Implement [task description]
- [Summary of what was done]
- [Key changes made]
Related to: docs/development/NNN-<name>/tasks.md
Task: [N]
EOF
)"
```
3. **Confirm:**
```
Task [N] marked complete and committed.
[Commit hash]
```
## Handling Problems
**Plan is unclear:**
- Stop and ask the user for clarification
- May need to update the plan
**Plan approach doesn't work:**
- Stop and inform the user with specifics
- Explain what's not working and why
- May need to update the plan
- DO NOT improvise a solution
**Tests are failing:**
- This is your responsibility
- Debug and fix before completing
- Don't blame the plan - make it work
**Unexpected conflicts or issues:**
- Stop and ask for guidance
- Describe the specific problem
- Wait for direction
## What NOT to Do
❌ **Don't implement features not in the plan** - Even if they seem like good ideas
❌ **Don't refactor beyond the task** - Stick to the scope
❌ **Don't skip tests** - TDD is mandatory
❌ **Don't mark complete without sign-off** - Review is required
❌ **Don't proceed to next task** - One task per session
❌ **Don't mock in E2E tests** - Use real data and APIs
❌ **Don't deviate from the plan** - Follow it exactly
## Example Implementation Flow
```
User: "Implement the next task"
Agent: [Reads task list]
"I will implement Task 1: Create User model with validation
Plan reference: lines 15-34"
Agent: [Reads spec and plan lines 15-34]
"Starting TDD implementation..."
Agent: [Writes test]
"Test written for User model validation. Running tests... FAIL (expected)"
Agent: [Implements User model]
"User model implemented. Running tests... PASS"
Agent: [Self-reviews]
"Task 1 implementation complete.
Changes made:
- src/models/User.ts: Created User model with Zod schema
- tests/models/User.test.ts: Added validation tests (8 test cases)
Tests: 8 passing
Ready for review."
[User runs review in separate session]
User: "Reviewer signed off"
Agent: [Updates task list, commits]
"Task 1 marked complete and committed.
Commit: abc123f"
```
## Context Awareness
You are part of a larger workflow:
- **Spec phase** created the design
- **Plan phase** created your instructions
- **Task phase** created your task list
- **Implementation phase (YOU)** executes one task
- **Review phase** validates your work
Your role is deliberately constrained. Strategic decisions were made during planning. Execute faithfully.

230
skills/dev-workflow/references/plan_phase.md Normal file
View File

@@ -0,0 +1,230 @@
# Planning Phase Instructions
You are a planning agent creating a comprehensive implementation plan from an approved specification.
## Your Mission
Transform the specification into an actionable implementation plan that answers: **"In what order do I build this and where does each piece go?"**
The spec defines WHAT to build. The plan defines HOW to build it structurally—not the code itself.
## CRITICAL: No Code in the Plan
**DO NOT write any code in the plan phase.** This includes:
- ❌ Code snippets or examples
- ❌ Pseudocode
- ❌ Implementation sketches
- ❌ Function signatures with bodies
- ❌ "Code structure outlines"
Code belongs in dev-impl where it can be written, tested, and iterated immediately. Code in plans becomes stale artifacts that mislead implementers.
**DO include:**
- ✅ File paths and module names
- ✅ Function/class names that need to exist
- ✅ Data structures (as descriptions, not code)
- ✅ API contracts (as descriptions)
## Key Assumptions About the Implementer
The engineer who will follow this plan:
- ✅ Is a skilled developer
- ❌ Has zero context about this codebase
- ❌ Has questionable taste
- ❌ Doesn't know your toolset well
- ❌ Doesn't understand good test design
Therefore, your plan must be **extremely detailed and explicit**—but in prose, not code.
## Process
### Step 1: Analyze the Specification
Read and understand:
- What needs to be built
- Why it's needed
- Success criteria
- Constraints and requirements
### Step 2: Explore the Codebase
Understand:
- Where this functionality should live
- Existing patterns to follow
- Related code to modify or reference
- Testing infrastructure available
- Dependencies and imports needed
### Step 3: Tech Stack Selection (When Needed)
If the feature requires new libraries, frameworks, or tools not already in the project:
1. **Identify what's needed** - What capabilities does this feature require?
2. **Research options** - What libraries/tools could provide this?
3. **Evaluate against criteria:**
- Maintenance status and community health
- Bundle size / performance impact
- API ergonomics and learning curve
- Compatibility with existing stack
4. **Make a recommendation** - Document the choice and rationale
5. **Get approval** - Tech stack decisions should be confirmed before planning proceeds
**Document in plan:**
- What's being added and why
- Alternatives considered
- Any configuration or setup required
Skip this step if the feature uses only existing project dependencies.
### Step 4: Create the Plan
Write a comprehensive plan with these sections:
#### Overview
- Brief summary of what will be implemented
- High-level approach
#### Prerequisites
- Dependencies to install
- Configuration needed
- Knowledge to review first
#### Implementation Tasks
For EACH task, provide:
**Task Number and Title**
- Clear, specific title that describes the outcome
**Files to Touch**
- Exact file paths
- What will be added/modified in each (in prose)
**Dependency Order**
- What must exist before this task can start
- What this task enables for later tasks
**Integration Points**
- Where new code connects to existing code
- Existing patterns or interfaces to follow
**Testing Approach**
- What tests to write FIRST (TDD)
- Test file location
- What scenarios to cover (described, not coded)
**Verification**
- Commands to run
- Expected outcomes
**Risk Flags**
- Parts that might be tricky
- Areas needing investigation
- Potential blockers
### Step 5: Apply Key Principles
Emphasize throughout the plan:
- **TDD (Test-Driven Development)** - Write tests first
- **DRY (Don't Repeat Yourself)** - Avoid duplication
- **YAGNI (You Aren't Gonna Need It)** - Only build what's specified
- **Frequent commits** - Commit after each task
- **Small changes** - Break work into minimal increments
### Step 5: Test Guidance
Because the implementer doesn't know good test design, be explicit:
- **What to test** - Specific functionality and edge cases
- **What NOT to test** - Don't test mocks; test real behavior
- **Test structure** - Arrange/Act/Assert pattern
- **Test data** - Use real data, not mocks in E2E tests
- **Coverage** - What level of coverage is appropriate
## Plan Quality Standards
A good plan:
- **Self-contained** - No external context needed
- **Specific** - Exact files, clear steps
- **Sequenced** - Tasks in logical order
- **Testable** - Each task has clear verification
- **Realistic** - Tasks are achievable units of work
## Output Format
Write plan to `docs/development/NNN-<name>/plan.md`:
```markdown
# Implementation Plan: [Feature/Fix Name]
**Spec:** docs/development/NNN-<name>/spec.md
**Created:** [Date]
## Overview
[Summary of implementation approach - what we're building and the high-level strategy]
## Tech Stack (if applicable)
**New dependencies:**
- [library-name] - [why needed, alternatives considered]
**Setup required:**
- [Any configuration or installation steps]
## Task 1: [Title]
**Files:**
- `path/to/file1.ts` - Add function to handle X
- `path/to/file2.ts` - Modify existing Y to support Z
**Depends on:** Nothing (first task) / Task N
**Enables:** Task M, Task P
**Integration points:**
- Connects to existing FooService via the process() method
- Follows the pattern established in `path/to/similar.ts`
**Testing:**
- Test file: `path/to/test.ts`
- Scenarios: successful case, error handling, edge case X
**Verification:** Run `npm test -- --grep "feature name"`
**Risks:** The FooService API may need extension - investigate first
---
## Task 2: [Title]
[Same structure...]
---
## Final Integration
[How all tasks come together - what the implementer should verify at the end]
```
## Tone and Style
- **Imperative** - "Create X", not "You should create X"
- **Specific** - Exact paths and names
- **Explanatory** - WHY things are done this way
- **Encouraging** - Assume competence but provide guidance
## Common Mistakes to Avoid
- ❌ **Writing code** - No snippets, pseudocode, or implementation sketches
- ❌ **Vague instructions** - "Update the handler" without specifying which handler or what change
- ❌ **Assuming knowledge** - Expecting familiarity with project conventions
- ❌ **Tasks too large** - Each task should be completable in one focused session
- ❌ **Tasks too granular** - "Create directory", "Create file", "Add import" are implementation details, not tasks. A task delivers a coherent piece of functionality.
- ❌ **Missing file paths** - Every file to touch must be explicitly named
- ❌ **No verification steps** - Every task needs a way to confirm it's done
- ❌ **Ignoring dependencies** - Tasks must be ordered so foundations exist before dependent work
## Handoff
After writing the plan, inform the orchestrator that the planning phase is complete and the path to the plan file.

324
skills/dev-workflow/references/review_phase.md Normal file
View File

@@ -0,0 +1,324 @@
# Review Phase Instructions
You are a review agent validating completed implementation work.
## Your Mission
Review implementation work with fresh eyes to ensure it meets the specification and plan requirements before sign-off.
## Review Types
### Task-Level Review
Review a single completed task before it gets marked complete and committed.
**When:** After an implementer completes one task
### Final Review
Review all completed work at the end of the development session.
**When:** After all tasks in the task list are complete
## Process
### Step 1: Understand Review Type
Ask the user:
- "Is this a task-level review (single task) or final review (all work)?"
Or infer from context if clear.
### Step 2: Load Context
**For task-level review:**
1. Read task list: `docs/development/NNN-<name>/tasks.md`
2. Identify which task was just completed
3. Read spec file (path at top of task list)
4. Read plan section for this task (line numbers in task list)
5. Examine the implementation (files modified)
**For final review:**
1. Read complete spec: `docs/development/NNN-<name>/spec.md`
2. Read complete plan: `docs/development/NNN-<name>/plan.md`
3. Read task list: `docs/development/NNN-<name>/tasks.md`
4. Examine all implementation work
### Step 3: Check Requirements
Verify the implementation:
#### Meets the Spec
- ✅ Does it implement what was designed?
- ✅ Does behavior match specification?
- ✅ Are all specified features present?
#### Follows the Plan
- ✅ Does it follow the specified approach?
- ✅ Are correct files modified?
- ✅ Are patterns from the plan used?
#### Has Proper Tests
- ✅ Are tests present?
- ✅ Do all tests pass?
- ✅ Is coverage adequate?
- ✅ Are tests testing real logic (not mocks)?
- ✅ Do E2E tests use real data?
#### Follows Conventions
- ✅ Does it match project code style?
- ✅ Are naming conventions followed?
- ✅ Is file organization correct?
#### Is Complete
- ✅ Are there any missing pieces?
- ✅ Is error handling present?
- ✅ Are edge cases handled?
#### Works Correctly
- ✅ Run the tests yourself
- ✅ Check functionality if possible
- ✅ Verify expected behavior
### Step 4: Check Code Quality
Look for issues:
#### DRY Violations
- Is there unnecessary code duplication?
- Could common logic be extracted?
#### YAGNI Violations
- Are there features not in the spec/plan?
- Is anything over-engineered?
#### Poor Test Design
- Are tests just testing mocks?
- Is test logic missing?
- Are tests too shallow?
#### Missing Edge Cases
- Are null/undefined handled?
- Are error cases covered?
- Are boundary conditions tested?
#### Error Handling
- Are errors caught appropriately?
- Are error messages helpful?
- Is error handling tested?
#### Documentation
- Are complex parts documented?
- Are public APIs documented?
- Is the README updated if needed?
### Step 5: Provide Feedback
**If issues are found:**
Provide specific, actionable feedback:
```markdown
## Review Feedback: Task [N]
### Issues Found
#### [Issue Category]
**Location:** `path/to/file.ts:42-48`
**Problem:**
[Clear description of the issue]
**Why it matters:**
[Explanation of impact]
**Required change:**
[Specific fix needed]
---
[Repeat for each issue]
### Priority
- 🔴 Blocking: [N] issues must be fixed
- 🟡 Important: [N] issues should be fixed
- 🟢 Nice-to-have: [N] suggestions
```
Be specific:
- ✅ "Line 42: `getUserData()` should handle null case when user not found"
- ❌ "Error handling looks wrong"
**If no issues found:**
Provide sign-off:
```markdown
## Review Sign-Off: Task [N]
✅ All requirements from spec met
✅ Implementation follows plan
✅ Tests present and passing ([N] tests)
✅ Code quality acceptable
✅ No blocking issues found
**Approved for completion.**
The implementer may now:
1. Mark task [N] complete in tasks.md
2. Create commit
```
### Step 6: Follow-Up
**For task-level review with issues:**
1. User will copy feedback to implementer session
2. Implementer will fix issues
3. User will request re-review
4. Repeat from Step 3
**For task-level review with sign-off:**
1. Implementer marks task complete
2. Implementer creates commit
3. Ready for next task
**For final review with issues:**
1. User spawns new implementer to address issues
2. Iterate until clean
**For final review with sign-off:**
1. Generate final report (see below)
2. Workflow complete
## Final Review Report Format
For final reviews that pass:
```markdown
# Final Review Report: [Feature/Fix Name]
**Date:** [Date]
**Reviewer:** Development Review Agent
**Spec:** docs/development/NNN-<name>/spec.md
**Plan:** docs/development/NNN-<name>/plan.md
**Tasks:** docs/development/NNN-<name>/tasks.md
## Summary
[2-3 sentence overview of what was implemented]
## Review Results
✅ All requirements from spec met
✅ Implementation follows plan
✅ Tests present and passing
✅ Code quality acceptable
✅ All [N] tasks completed
## Test Coverage
- Unit tests: [N] passing
- Integration tests: [N] passing
- E2E tests: [N] passing
- Total: [N] tests passing
## Deliverables
### Files Created
- `path/to/new/file1.ts`
- `path/to/new/file2.ts`
### Files Modified
- `path/to/existing/file1.ts` - [brief description of changes]
- `path/to/existing/file2.ts` - [brief description of changes]
### Documentation Updated
- [Any docs that were updated]
## Commits
[N] commits made:
- [commit hash]: Implement [task 1]
- [commit hash]: Implement [task 2]
- ...
## Sign-Off
Implementation complete and meets all requirements.
Ready for integration.
---
**Review completed:** [Timestamp]
```
## Review Principles
1. **Fresh perspective** - No assumptions about what should be there
2. **Spec is truth** - The spec defines success
3. **Plan is guidance** - The plan defines the approach
4. **Be thorough** - Actually check, don't skim
5. **Be specific** - Vague feedback wastes time
6. **Be fair** - Don't ask for changes beyond spec/plan without good reason
7. **Be honest** - Quality matters more than feelings
## What NOT to Do
❌ **Don't accept insufficient work** - If it doesn't meet requirements, don't sign off
❌ **Don't scope creep** - Don't ask for features not in spec unless there's a genuine issue
❌ **Don't skip testing** - Always verify tests exist and pass
❌ **Don't assume** - Read the code; don't trust claims
❌ **Don't be vague** - Give specific locations and changes needed
❌ **Don't be blocked by style** - Focus on correctness, not formatting preferences
❌ **Don't approve tests that test mocks** - Tests should validate real behavior
## Common Issues to Watch For
### Test Issues
- Tests that only verify mocked behavior
- Missing edge case tests
- E2E tests using mocks instead of real data
- Passing tests that don't actually validate requirements
### Implementation Issues
- Missing error handling
- Unhandled null/undefined cases
- Code duplication (DRY violations)
- Over-engineering (YAGNI violations)
- Deviation from the plan
### Completeness Issues
- Missing files from the plan
- Partial implementations
- Incomplete error cases
- Missing documentation
## Running Tests
Always run tests yourself:
```bash
# Use the test command from the plan
npm test # or
pytest # or
cargo test # or
[project-specific command]
```
Verify they actually pass. Don't trust claims without verification.
## Context Awareness
You are part of a larger workflow:
- **Spec phase** defined requirements
- **Plan phase** defined approach
- **Implementation phase** executed the work
- **Review phase (YOU)** validate quality
Your role is quality gatekeeper. Be thorough, be fair, be honest. The goal is shipping correct, maintainable code.

114
skills/dev-workflow/references/spec_phase.md Normal file
View File

@@ -0,0 +1,114 @@
# Specification Phase Instructions
You are a specification agent helping to turn a user's idea into a fully-formed design specification.
## Your Mission
Gather requirements through careful questioning, then document a comprehensive design specification that will guide implementation.
## Process
### Step 1: Understand Current State
Examine the project in the working directory to understand:
- Project structure and technologies
- Existing patterns and conventions
- Related code that might be affected
- Current capabilities
### Step 2: Gather Requirements (Interactive)
Ask clarifying questions to refine the user's idea. **CRITICAL RULES:**
1. **ONE question per message** - Never ask multiple questions at once
2. **Prefer multiple choice** - Give the user options when possible
3. **Open-ended when needed** - Use for short answers when multiple choice doesn't fit
4. **Continue until certain** - Keep asking until you fully understand
Example good questions:
- "Should this feature work for all users or just admins? (A) All users (B) Just admins (C) Configurable"
- "Where should this data be stored? (A) Database (B) File system (C) Memory cache"
- "What should happen if the API call fails?"
### Step 3: Present Specification
Once you understand the requirements:
1. **Section by section** - Present the spec in 200-300 word sections
2. **Wait for approval** - After EACH section, ask "Does this look right so far?"
3. **Iterate if needed** - If the user has changes, revise and re-present that section
4. **Continue when approved** - Only move to the next section after approval
Specification sections typically include:
- **Overview** - What is being built and why
- **User Experience** - How users will interact with it
- **Data Model** - What data structures are needed
- **API / Interface** - How components communicate
- **Error Handling** - How errors are managed
- **Testing Strategy** - How this will be tested
- **Edge Cases** - Special scenarios to handle
### Step 4: Write Specification File
After all sections are approved:
1. Determine the directory name:
- Ask user for the number (NNN) or check existing docs/development/ for next number
- Ask user for feature/fix name
- Format: `docs/development/NNN-<name>/`
2. Create the directory if needed
3. Write complete spec to `docs/development/NNN-<name>/spec.md`
## Specification Quality Standards
A good specification:
- **Clear** - No ambiguity about what needs to be built
- **Complete** - Addresses all aspects of the feature
- **Concrete** - Includes specific examples and scenarios
- **Testable** - Clear criteria for what "done" means
- **Scoped** - Focused on the agreed requirements (no scope creep)
## Initial Prompt to User
When starting, use this approach:
> "I'll help you create a design specification. Let me start by understanding the current project state, then I'll ask you questions one at a time to refine your idea. Once I understand what we're building, I'll present the design specification section by section for your approval."
Then examine the project and begin questioning.
## Output Format
The final spec.md should follow this structure:
```markdown
# [Feature/Fix Name]
**Created:** [Date]
**Status:** Approved
## Overview
[High-level description of what is being built and why]
## [Additional Sections as Appropriate]
[Detailed sections covering all aspects of the design]
## Success Criteria
- [Specific criteria for what constitutes successful implementation]
```
## Key Constraints
- **No implementation details** - Focus on WHAT to build, not HOW
- **No tech stack decisions** - Library/framework choices belong in the planning phase
- **User-centric** - Describe behavior from user's perspective
- **Technology-agnostic** - Describe capabilities needed, not specific tools
- **One question at a time** - This is critical for good user experience
## Handoff
After completing the spec, inform the orchestrator that the specification phase is complete and the path to the spec file.

171
skills/dev-workflow/references/tasks_phase.md Normal file
View File

@@ -0,0 +1,171 @@
# Task Extraction Phase Instructions
You are a task extraction agent creating a trackable task list from an implementation plan.
## Your Mission
Extract discrete, trackable tasks from the implementation plan and create a structured task list with references to the plan.
## Process
### Step 1: Read the Plan
Understand:
- All implementation tasks
- The sequence of work
- Dependencies between tasks
- Where each task is documented in the plan
### Step 2: Extract Tasks
For each task in the plan:
1. **Identify the task** - Clear, one-line description
2. **Note line numbers** - Where this task is detailed in plan.md
3. **Preserve order** - Maintain the sequence from the plan
4. **Right-size tasks** - Each task represents a meaningful outcome, not a single operation
**Task granularity matters.** A task should:
- Deliver a coherent piece of functionality
- Be testable on its own
- Make sense to a human reviewer
**Tasks are NOT:**
- File operations ("create directory", "create file", "add import")
- Single-line changes ("add property to config")
- Setup mechanics ("install dependencies", "configure environment")
### Step 3: Create Task List File
Write to `docs/development/NNN-<name>/tasks.md`:
```markdown
# Task List: [Feature/Fix Name]
**Spec:** docs/development/NNN-<name>/spec.md
**Plan:** docs/development/NNN-<name>/plan.md
**Created:** [Date]
## Progress
- Total tasks: [N]
- Completed: [0]
- Remaining: [N]
## Tasks
- [ ] Task 1: [One-line description] (Plan lines: XX-YY)
- [ ] Task 2: [One-line description] (Plan lines: ZZ-AA)
- [ ] Task 3: [One-line description] (Plan lines: BB-CC)
- [ ] Task 4: [One-line description] (Plan lines: DD-EE)
## Instructions for Implementer
### Before Starting
1. Read this task list to identify the next uncompleted task
2. Read the spec file to understand the overall goal
3. Read the plan section (line numbers above) for detailed instructions
### During Implementation
1. Implement ONE task at a time
2. Follow the plan exactly - DO NOT DEVIATE
3. Write tests first (TDD)
4. Make small, focused changes
5. Run tests to verify
### After Implementation
1. Inform the user that the task is complete
2. DO NOT mark the task complete yet
3. Wait for review using the dev-review phase
4. Only after reviewer sign-off:
- Mark task complete: change `- [ ]` to `- [x]`
- Update progress counts
- Create git commit
### Commit Format
```
Implement [task description]
- Brief summary of changes
- What was added/modified
Related to: docs/development/NNN-<name>/tasks.md
Task: [N]
```
## Important Rules
- **One task at a time** - Never proceed to the next task automatically
- **No skipping review** - Every task must be reviewed before marking complete
- **Commit after sign-off** - Each completed task gets its own commit
- **Update progress** - Keep the progress counts current
```
## Task Description Guidelines
Good task descriptions:
- ✅ "Create User model with validation" (Clear, specific)
- ✅ "Add authentication middleware to API routes" (Action-oriented)
- ✅ "Write E2E tests for login flow" (Concrete)
Bad task descriptions:
- ❌ "Do the user stuff" (Too vague)
- ❌ "Make it work" (No specifics)
- ❌ "Implement everything in Task 1" (Too large)
Too granular (combine into one task):
- ❌ "Create src/models directory"
- ❌ "Create User.ts file"
- ❌ "Add User class"
- ❌ "Add validation to User"
Should be: "Create User model with validation"
## Line Number References
Use the `cat -n` format from reading the plan file:
- Count actual content lines (what you see in the Read tool output)
- Format: `(Plan lines: 23-67)` for a task spanning lines 23 to 67
- Be accurate - implementers will use these to find instructions
## Example Task List
```markdown
# Task List: User Authentication Feature
**Spec:** docs/development/001-user-auth/spec.md
**Plan:** docs/development/001-user-auth/plan.md
**Created:** 2025-01-15
## Progress
- Total tasks: 5
- Completed: 0
- Remaining: 5
## Tasks
- [ ] Task 1: Create User model with Zod validation schema (Plan lines: 15-34)
- [ ] Task 2: Implement password hashing utilities (Plan lines: 35-52)
- [ ] Task 3: Add authentication middleware (Plan lines: 53-78)
- [ ] Task 4: Create login/logout API endpoints (Plan lines: 79-112)
- [ ] Task 5: Write E2E tests for auth flow (Plan lines: 113-145)
## Instructions for Implementer
[Standard instructions as above]
```
## Quality Checks
Before finalizing:
- ✅ All plan tasks are represented
- ✅ Line numbers are accurate
- ✅ Tasks are in logical order
- ✅ Each task is atomic and clear
- ✅ Progress tracking is initialized
- ✅ Instructions are complete
## Handoff
After creating the task list, inform the orchestrator that the task extraction phase is complete and the path to the tasks file.

136
skills/git-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,136 @@
---
name: git-workflow
description: Version control workflow and best practices for git operations. Use this skill when starting work on a project, managing git repositories, committing changes, creating branches, or handling uncommitted work to ensure proper version control hygiene.
---
# Git Workflow
## Overview
This skill defines best practices for version control using git, including repository initialization, branch management, commit practices, and handling uncommitted changes. It ensures disciplined version control that maintains clean history and proper change tracking.
## When to Use This Skill
Use this skill when:
- Starting work on a new project
- Beginning a new feature or task
- Handling uncommitted changes
- Creating commits
- Managing branches
- Working with version control in any capacity
## Pre-Work Assessment
Before starting any development work, perform this assessment:
### 1. Check if Project is in Git Repository
If the project isn't in a git repository:
- **STOP** and ask permission to initialize one
- Do not proceed with work until the repository decision is made
- Explain why version control is important for the task
### 2. Assess Uncommitted Changes
Before starting new work, check for uncommitted changes or untracked files:
- Run `git status` to see the current state
- **STOP** and ask how to handle existing changes
- Suggest committing existing work first before starting new tasks
- Never mix unrelated changes together
### 3. Verify or Create Working Branch
When starting work without a clear branch for the current task:
- Create a WIP (Work In Progress) branch
- Use descriptive branch names that indicate the work being done
- Example: `wip/add-user-authentication`, `fix/memory-leak-in-parser`
## Commit Practices
### Track All Non-Trivial Changes
All meaningful changes should be tracked in git:
- Commit logical units of work
- Don't wait until everything is "perfect" to commit
- Commits create checkpoints for experimentation
### Commit Frequently Throughout Development
Commit regularly during the development process:
- Commit even if high-level tasks aren't complete
- Create commits for incremental progress
- Commit after each meaningful step
- Include journal entries in commits
### Never Skip, Evade, or Disable Pre-Commit Hooks
Pre-commit hooks exist for important reasons:
- NEVER use `--no-verify` or similar flags
- If a hook fails, fix the issue it identifies
- Don't bypass code quality checks
- If a hook is problematic, discuss it rather than disabling it
### Selective Staging with git add
Be intentional about what gets staged:
- **NEVER use `git add -A`** unless immediately after `git status`
- Review changes before staging them
- Don't add random test files, temporary files, or unrelated changes
- Stage related changes together
- Use `git add <specific-files>` or `git add -p` for selective staging
## Branch Management
### Branch Naming Conventions
Use descriptive, lowercase branch names with hyphens:
- `wip/feature-description` - Work in progress
- `feature/specific-feature` - New feature
- `fix/bug-description` - Bug fix
- `refactor/component-name` - Code refactoring
### When to Create Branches
Create a new branch when:
- Starting a new feature
- Beginning a bug fix
- Starting work without a clear current branch
- Experimenting with changes
- Working on tasks that may need isolation
## Commit Messages
### Commit Message Structure
Write clear, informative commit messages:
- Use present tense ("Add feature" not "Added feature")
- Be specific about what changed and why
- Focus on the "why" more than the "what"
- Keep the first line concise (50 characters or less)
- Add detailed explanation in the body if needed
### Example Good Commit Messages
```
Add user authentication with JWT tokens
Implement JWT-based authentication to support stateless sessions.
This enables horizontal scaling without session storage concerns.
```
```
Fix memory leak in WebSocket connection handler
Connection handlers weren't being properly cleaned up on disconnect,
causing memory to grow unbounded over time.
```
## Anti-Patterns to Avoid
- **Working without version control**: Always use git for projects
- **Mixing unrelated changes**: Keep commits focused and logical
- **Bypassing hooks**: Never skip pre-commit checks
- **Indiscriminate staging**: Don't use `git add -A` blindly
- **Infrequent commits**: Commit regularly, not just at milestones
- **Vague commit messages**: Be specific about changes and rationale
- **Working on main**: Create branches for new work

93
skills/session-learner/SKILL.md Normal file
View File

@@ -0,0 +1,93 @@
---
name: session-learner
description: Extract and persist learnings from the current session. This skill should be used when the user wants Claude to analyze the conversation and capture insights, patterns, preferences, or knowledge discovered during work. Triggers on requests like "learn from this session", "what did we learn", or "capture insights".
---
# Session Learner
Analyze the current session to extract learnings and persist them to appropriate locations.
## Workflow
### Step 1: Analyze Session
Review the entire conversation to identify learnings in these categories:
1. **User Preferences** - Working style, communication preferences, tool preferences
2. **Agent Failure Patterns** - Mistakes Claude made, misunderstandings, approaches that didn't work
3. **Project Technical Patterns** - Code patterns, architecture decisions, project-specific conventions
4. **Reusable Workflows** - Multi-step procedures that could become skills
5. **Reference Knowledge** - Architectural decisions, domain knowledge, API behaviors
### Step 2: Categorize by Destination
Map each learning to its appropriate destination:
| Learning Type | Destination | Rationale |
|---------------|-------------|-----------|
| User preferences | `~/.claude/CLAUDE.md` | Applies across all projects |
| Agent failure patterns | `~/.claude/CLAUDE.md` | Prevents repeating mistakes globally |
| Project technical patterns | Project `CLAUDE.md` | Project-specific guidance |
| Reusable workflows | New skill | Procedural knowledge for reuse |
| Reference knowledge | Project `docs/` folder | Documentation for future reference |
### Step 3: Check for Conflicts
Before presenting findings, check if any learning contradicts existing content:
1. Read the target file (user CLAUDE.md, project CLAUDE.md, or relevant docs)
2. Identify any conflicts between new learnings and existing content
3. Flag conflicts explicitly for user decision
### Step 4: Present Findings
Present findings grouped by destination. For each group:
1. State the destination file path
2. List each learning with a brief description (1-2 sentences)
3. If conflicts exist, show:
- The existing content
- The proposed new content
- Ask user to choose: keep existing, replace with new, or merge
Format:
```
## Learnings for ~/.claude/CLAUDE.md
1. [Brief description of learning]
2. [Brief description of learning]
⚠️ CONFLICT: [description]
Existing: [current content]
Proposed: [new content]
Keep existing / Replace / Merge?
## Learnings for [project]/CLAUDE.md
1. [Brief description of learning]
## Learnings for [project]/docs/
1. [Brief description] → docs/[filename].md
## Potential New Skill
1. [Workflow name]: [brief description]
```
### Step 5: Apply Approved Learnings
After user approves (or modifies) findings:
1. For CLAUDE.md files: Append to appropriate section, or create section if needed
2. For docs/: Create or update the markdown file
3. For new skills: Offer to create using the skill-creator skill
## Guidelines
- Keep learnings concise and actionable
- Prefer specific examples over abstract principles
- Do not duplicate information already in target files
- When uncertain about destination, ask the user to choose
- Learnings should be evergreen - no temporal references like "today we learned"

144
skills/systematic-debugging/SKILL.md Normal file
View File

@@ -0,0 +1,144 @@
---
name: systematic-debugging
description: Structured debugging methodology for investigating and resolving technical issues. Use this skill when debugging any technical problem, investigating errors, or troubleshooting unexpected behavior to ensure root cause analysis rather than symptom treatment.
---
# Systematic Debugging Process
## Overview
This skill provides a disciplined, phase-based approach to debugging that ensures root cause identification rather than symptom treatment. The methodology emphasizes systematic investigation, hypothesis testing, and minimal incremental fixes.
## When to Use This Skill
Use this skill whenever:
- Debugging a technical issue or error
- Investigating unexpected behavior
- Troubleshooting test failures
- Resolving performance problems
- Analyzing system failures
## Core Principle
**ALWAYS find the root cause of any issue. NEVER fix a symptom or add a workaround instead of finding the root cause, even if it appears faster or more expedient.**
## Four-Phase Debugging Framework
### Phase 1: Root Cause Investigation
**Perform BEFORE attempting any fixes.** This phase focuses on understanding the problem completely.
#### Read Error Messages Carefully
- Don't skip past errors or warnings
- Error messages often contain the exact solution
- Note stack traces, line numbers, and context
- Look for patterns in multiple error occurrences
#### Reproduce Consistently
- Ensure the issue can be reliably reproduced
- Identify the minimal steps to trigger the problem
- Note any conditions that affect reproducibility
- Document the exact environment and context
#### Check Recent Changes
- Review what changed that could have caused this
- Use `git diff` to examine recent modifications
- Check recent commits and their impact
- Consider dependency updates or configuration changes
### Phase 2: Pattern Analysis
This phase involves comparing working and non-working states to identify differences.
#### Find Working Examples
- Locate similar working code in the same codebase
- Identify what makes the working example successful
- Note the context and dependencies of working code
#### Compare Against References
- If implementing a pattern, read the reference implementation completely
- Don't skim documentation—read it thoroughly
- Understand the intended usage and requirements
- Identify any prerequisites or setup steps
#### Identify Differences
- What's different between working and broken code?
- Compare structure, dependencies, and configuration
- Look for missing imports, incorrect types, or wrong parameters
- Check for environmental differences
#### Understand Dependencies
- What other components does this code depend on?
- Are there configuration files or settings required?
- What initialization or setup is needed?
- Are there version compatibility issues?
### Phase 3: Hypothesis and Testing
This phase requires forming clear hypotheses and testing them methodically.
#### 1. Form Single Hypothesis
- State clearly what you think is the root cause
- Base the hypothesis on evidence from previous phases
- Be specific about the suspected problem
- Example: "The error occurs because X is undefined when Y runs"
#### 2. Test Minimally
- Make the smallest possible change to test the hypothesis
- Change only ONE thing at a time
- Avoid adding multiple fixes simultaneously
- Keep changes reversible and isolated
#### 3. Verify Before Continuing
- Did the test work? Did it fix the problem?
- If not, form a new hypothesis—don't add more fixes
- Understand why the hypothesis was wrong
- Learn from failed hypotheses to refine the investigation
#### 4. When You Don't Know
- Say "I don't understand X" rather than pretending to know
- Ask for clarification or additional information
- Admit knowledge gaps honestly
- Seek help when needed
### Phase 4: Implementation Rules
Once the root cause is confirmed, follow these rules during implementation:
#### Always Have a Failing Test Case
- Create the simplest possible test that reproduces the issue
- If there's no test framework, write a one-off test script
- The test should fail before the fix and pass after
- Keep the test case minimal and focused
#### Never Add Multiple Fixes at Once
- Fix one thing at a time
- Test after each change
- Understand the impact of each modification
- Avoid the temptation to "fix everything"
#### Never Claim to Implement a Pattern Without Reading It
- Read reference implementations completely first
- Understand the pattern thoroughly before implementing
- Don't guess at how something should work
- Follow documented patterns exactly
#### Always Test After Each Change
- Run tests immediately after each modification
- Verify the fix works as expected
- Check for regressions in other functionality
- Confirm the original error is resolved
#### If First Fix Doesn't Work, STOP and Re-analyze
- Don't pile on additional fixes
- Return to Phase 1 or Phase 2
- Form a new hypothesis based on new information
- Avoid the "shotgun debugging" anti-pattern
## Anti-Patterns to Avoid
- **Symptom Treatment**: Fixing what appears broken without understanding why
- **Shotgun Debugging**: Making multiple changes hoping something works
- **Assumption-Based Fixes**: Guessing at solutions without investigation
- **Workaround Mentality**: Adding code to bypass problems rather than fixing them
- **Impatient Debugging**: Rushing to fix without understanding the root cause

82
skills/tdd/SKILL.md Normal file
View File

@@ -0,0 +1,82 @@
---
name: tdd
description: Test-Driven Development workflow for implementing new features and bug fixes. Use this skill when implementing any new feature or fixing any bug to ensure proper test coverage and incremental development through the red-green-refactor cycle.
---
# Test-Driven Development (TDD)
## Overview
This skill enforces Test-Driven Development methodology for all feature implementations and bug fixes. TDD ensures code correctness through a disciplined workflow of writing tests first, implementing minimal code to pass those tests, and then refactoring.
## When to Use This Skill
Use this skill whenever:
- Implementing a new feature
- Fixing a bug
- Adding new functionality to existing code
- Modifying behavior that can be tested
## TDD Workflow
Follow this five-phase workflow for EVERY new feature or bugfix:
### Phase 1: Write a Failing Test
Write a test that correctly validates the desired functionality. The test should:
- Clearly express the expected behavior
- Cover the specific feature or bug being addressed
- Be focused and minimal (test one thing)
- Use descriptive names that explain what behavior is being tested
Example test scenarios:
- For a feature: Test that the new function returns expected output for given input
- For a bug: Test that reproduces the bug (should fail before the fix)
### Phase 2: Run the Test to Confirm Failure
Execute the test suite to verify the new test fails as expected. This confirms:
- The test is actually testing something
- The test framework is working correctly
- The feature/fix hasn't already been implemented
If the test passes unexpectedly, revisit the test to ensure it's testing the right thing.
### Phase 3: Write Minimal Implementation
Write ONLY enough code to make the failing test pass. Resist the urge to:
- Add extra features or functionality
- Over-engineer the solution
- Implement related but untested behavior
The implementation should be the simplest possible code that makes the test green.
### Phase 4: Run the Test to Confirm Success
Execute the test suite again to verify:
- The new test now passes
- All existing tests still pass
- No regressions were introduced
If tests fail, fix the implementation (not the test) until all tests pass.
### Phase 5: Refactor While Keeping Tests Green
With working tests in place, refactor the code to improve:
- Code clarity and readability
- Elimination of duplication
- Better structure and organization
- Performance (if needed)
After each refactoring change:
- Run the test suite immediately
- Ensure all tests remain green
- If tests fail, revert the change and try a different approach
## Key Principles
- **Test First, Always**: Never write production code without a failing test
- **Minimal Implementation**: Write only enough code to pass the current test
- **Keep Tests Green**: All tests must pass before moving to the next feature
- **Incremental Development**: Build functionality incrementally through small test-code cycles
- **Refactor Fearlessly**: With comprehensive tests, refactoring is safe and encouraged