zhongwei/gh-codethread-claude-code-plugins-plugins-spec-dev
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 18:15:01 +08:00
commit 2fbdb7fc3d
23 changed files with 2851 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
skills/spec-architect/SKILL.md Normal file
View File

@@ -0,0 +1,123 @@
---
name: spec-architect
description: Coordinate multi-agent software development from requirements through verified implementation using spec-driven workflows. Use when planning features, creating technical specifications, implementing complex tasks through specialized agents, or managing spec-dev workflows (PLAN/BUILD/ITERATE).
---
# Spec Architect
## Principles
When coordinating development, prioritize:
- **Pattern consistency** - Find and reuse existing patterns before creating new ones
- **Type safety** - Push logic into the type system; use discriminated unions over optional fields
- **Test quality** - Never remove or weaken tests without justification
- **Message passing over shared state** - Prefer immutable data and event-driven architectures
- **Simplicity** - Everything should be as simple as possible, but not simpler (Einstein)
- **Code review before QA** - Always review code for patterns, types, and test quality before specification testing
## Available Agents
Coordinate specialized agents using the Task tool—invoked explicitly, not autonomously. Agents can be resumed once (see COMMUNICATION_PROTOCOL).
### Core Spec-Driven Development Agents
Follow [`COMMUNICATION_PROTOCOL`](./references/COMMUNICATION_PROTOCOL.md) for structured handoffs:
- **spec-developer**: Implements code following specifications
- **code-reviewer**: Static code analysis during BUILD phase (patterns, types, tests, architecture)
- **spec-signoff**: Reviews specifications during PLAN phase before implementation
- **spec-tester**: Functional verification from user perspective (loads testing skills as needed)
### Supporting Agents
Flexible delegation without COMMUNICATION_PROTOCOL:
- **Explore**: Find files by patterns, search code, answer codebase questions
- **researcher**: External documentation, best practices, API docs, architectural patterns
### Repository-Specific Agents
Check for custom agents in this repository—leverage domain-specific expertise when relevant.
## Agent Communication Standards
### For core spec-dev agents
Follow [`COMMUNICATION_PROTOCOL`](./references/COMMUNICATION_PROTOCOL.md):
- Agent resumption limited to once (use `cc-logs--extract-agents <session-id>`)
- Use structured briefings (Context, Inputs, Responsibilities, Deliverables)
- Reference files: `/full/path/file.ext:line:col`
### For other agents
Standard Task tool delegation. Adapt briefing format to agent's purpose.
## Specification Structure
All specifications follow the directory-based pattern:
```
specs/
├── PROJECT.md # Project-wide configuration and agent instructions (optional)
└── <numerical-id>-<kebab-cased-feature>/
├── feature.md # WHAT needs to be built (FR-X, NFR-X)
├── notes.md # Technical discoveries from spike work (optional)
└── tech.md # HOW to build it (implementation tasks like AUTH-1, COMP-1, etc.)
```
## State Transfer Between Phases
Each phase operates independently but follows these conventions:
1. **Explicit Arguments**: Each command receives a spec directory path
2. **Deterministic Structure**: All related files live in the same directory with standard names
3. **Self-Contained Documents**: Each document contains all necessary context
4. **Progressive Enhancement**: Each phase adds detail without modifying previous outputs
### Project Configuration (PROJECT.md)
Optional project-wide agent instructions. Template: [`PROJECT_TEMPLATE.md`](./references/PROJECT_TEMPLATE.md).
### Requirement Numbering
Feature: FR-1/NFR-1. Tech: Component-prefixed (AUTH-1, COMP-1) linked to FR/NFR.
### Templates Available
The following **MUST** be read during the PLAN workflow
- [`PROJECT_TEMPLATE.md`](./references/PROJECT_TEMPLATE.md) - Project configuration template (create at `specs/PROJECT.md`)
- [`SPEC_TEMPLATE.md`](./references/SPEC_TEMPLATE.md) - Feature specification template
- [`TECH_SPEC_TEMPLATE.md`](./references/TECH_SPEC_TEMPLATE.md) - Technical specification template
## Workflow Selection
**New feature?** → PLAN then BUILD
**Continuing work?** → ITERATE (routes to PLAN or BUILD)
Available workflows:
- [`PLAN_WORKFLOW`](./references/PLAN_WORKFLOW.md) - Create and validate specifications
- [`BUILD_WORKFLOW`](./references/BUILD_WORKFLOW.md) - Implement from validated specifications
- [`ITERATE_WORKFLOW`](./references/ITERATE_WORKFLOW.md) - Assess work and route appropriately
## Common Pitfalls to Avoid
- ❌ Over-specifying tech.md with implementation details instead of guidance
- ❌ Implementing without checking existing code first (use Explore agent)
- ❌ Not documenting discoveries from Explore/researcher agents in tech.md
- ❌ Ignoring repository-specific agents that provide domain expertise
- ❌ Skipping code review to save time (prevents technical debt)
- ❌ Skipping QA verification to save time
- ❌ Batching multiple tasks together (implement one at a time)
- ❌ Wasting the single resumption opportunity on trivial fixes
- ❌ Allowing agents to communicate directly (route through architect)
- ❌ Proceeding without clear specifications
---
## Role Summary
Orchestrate specialized agents rather than implementing directly—maintain oversight while trusting agent expertise.

188
skills/spec-architect/references/BUILD_WORKFLOW.md Normal file
View File

@@ -0,0 +1,188 @@
# BUILD Workflow - Feature Implementation
Use this workflow to implement a feature from an existing, validated technical specification.
**Prerequisites**: Specifications must exist and be validated (see `PLAN_WORKFLOW.md`):
- `specs/<id>-<feature>/feature.md` with numbered FR-X and NFR-X requirements
- `specs/<id>-<feature>/tech.md` with numbered implementation tasks
## Phase 1: Implementation Coordination
**Objective**: Build the feature by coordinating specialized agents
**FIRST STEP: Load Project Configuration**
Check if `specs/PROJECT.md` exists. If it does:
1. Read the entire file
2. Check the version metadata at the bottom:
- Extract `template_version` and compare with current PROJECT_TEMPLATE.md version
- If PROJECT_TEMPLATE.md has a newer version, offer to show the user what's new:
"Your PROJECT.md was created from template version X.X.X, but version Y.Y.Y is now available. Would you like me to show you the changes so you can decide if you want to adopt any new features?"
- If user wants to see changes, read PROJECT_TEMPLATE.md and explain the differences
3. Extract the "General Instructions" and "Architect Instructions" sections for your own use
4. Keep the agent-specific sections ready to inject into briefings:
- "Developer Agent Instructions" → inject into spec-developer briefings
- "Reviewer Agent Instructions" → inject into code-reviewer briefings
- "Tester Agent Instructions" → inject into spec-tester briefings
When briefing agents, inject PROJECT.md sections into `Your_Responsibilities` as defined in COMMUNICATION_PROTOCOL.
**CRITICAL RULE: Implement and verify ONE task at a time. Never batch tasks.**
**For each task in `tech.md`, follow this exact sequence**:
### Step 1: Select One Task
Open `tech.md` and choose a single uncompleted task. For example:
- [ ] **LINK-1**: Create get-project-dirs-to-link function (delivers FR-2)
This is your target. Work ONLY on this task until completely done.
### Step 2: Implement the Single Task
Delegate to **spec-developer agent** with explicit boundaries and skill suggestions:
> "Implement ONLY task LINK-1 from the tech spec. Do not implement LINK-2 or any other tasks. Focus solely on creating the get-project-dirs-to-link function that delivers FR-2."
Provide full context per `COMMUNICATION_PROTOCOL`, including:
- **Relevant_Skills**: Suggest appropriate skills based on the tech stack
- Language skills: typescript, python, go, ruby, etc.
- Framework skills: react, vue, django, rails, etc.
- Check what skills are available in the current repository
- The agent will load these skills before implementing to ensure proper conventions
### Step 3: Code Review (Static Analysis)
**CRITICAL**: Before functional testing, perform static code analysis for quality and consistency.
Delegate to **code-reviewer agent** for STATIC analysis (code review WITHOUT running code) per `COMMUNICATION_PROTOCOL`.
Example briefing:
> "Review the implementation of task LINK-1 through STATIC code analysis. Check for:
> - Similar patterns in the codebase (are we duplicating existing solutions?)
> - Type safety (should we use discriminated unions instead of optional fields?)
> - Test quality (are tests clear, comprehensive, and maintainable?)
> - Architectural consistency (does this follow project conventions?)
> - PROJECT REQUIREMENTS: [inject Reviewer Agent Instructions here if PROJECT.md exists]
> Focus ONLY on code quality for LINK-1. Do NOT test functionality - that's spec-tester's job."
**If code-reviewer finds blocking issues**:
- Use `cc-logs--extract-agents <session-id>` to find developer agent ID
- Resume developer agent once to fix: `Task({ resume: "<dev-agent-id>", prompt: "Code review found issues: [specific issues]. Please fix these." })`
- If further issues remain after resumption, spawn a new developer agent (resumption only works once)
- Only proceed to QA once code review passes
**If the reviewer suggests improvements (non-blocking)**:
- Note them for future refactoring
- Proceed to QA testing
### Step 4: Specification Testing (Functional Verification)
Delegate to **spec-tester agent** for FUNCTIONAL testing from user perspective:
Provide full context per `COMMUNICATION_PROTOCOL`, including:
- **User Perspective**: Identify who the "user" is (web UI user, API consumer, module user)
- **Testing Setup**: Direct them to the "Testing Setup" section in `feature.md`
- **Relevant_Skills**: Suggest testing skills based on what's being tested:
- Web UI → `playwright-skill` (if available)
- REST APIs → curl or API testing tools
- Documents → `pdf`, `xlsx`, `docx`, `pptx` skills
- CLI tools → bash testing skills
- **What to verify**: Which FR-X/NFR-X requirements this task delivers
> "Verify task LINK-1 from the user's perspective as a web UI user.
>
> **Setup**: Follow the 'Testing Setup' section in feature.md to start the necessary systems.
>
> **Testing**: If playwright-skill is available, load it and test the actual feature in the browser. Does it work as specified in FR-2? Test happy path and error cases.
>
> **Cleanup**: Use the cleanup procedures from the Testing Setup section when done."
Check the `tech.md` for testing timing:
**If task is marked [TESTABLE]** or has no special marking:
- Test immediately after code review passes
- Test only this specific task
**If component is marked [TEST AFTER COMPONENT]**:
- Complete all tasks in that component first (with code review for each)
- Then test the entire component as a unit
**IMPORTANT**: Tester performs FUNCTIONAL verification (actually runs/uses the feature), NOT static code analysis.
### Step 5: Fix Any Issues
If QA finds problems:
- Use `cc-logs--extract-agents <session-id>` to find developer agent ID
- Resume developer agent once: `Task({ resume: "<dev-agent-id>", prompt: "QA testing found failures: [specific failures]. Please fix." })`
- Code review the fixes (spawn new reviewer agent - each agent only resumes once)
- Re-test with QA (spawn new tester agent)
- If more fixes needed after first resumption, spawn new developer agent
- Do not proceed until this task fully passes
### Step 6: Architect Review
Once code review and QA both pass, perform final architectural review:
- Check follows project conventions from CLAUDE.md
- Verify matches patterns established in `tech.md`
- Ensure integration points are correct
- Confirm implementation delivers what the task promised
### Step 7: Mark Task Complete in tech.md
**THIS IS MANDATORY**: Update the `tech.md` immediately:
- Use Edit tool to change checkbox from [ ] to [x]
- Example: `- [ ] **LINK-1**:` to `- [x] **LINK-1**:`
- This provides clear audit trail of progress
- Never proceed to next task without updating checkbox
### Step 8: Optional Commit
If this represents a logical checkpoint, create a commit. Otherwise, continue to next task.
### Step 9: Repeat for Next Task
Only NOW select the next task and repeat this entire process.
**ENFORCEMENT RULES**:
- If you find yourself saying "implement tasks LINK-1 through LINK-3", STOP. Implement only one at a time.
- Mandatory sequence: Implement → Code Review → Fix Review Issues → QA Test → Fix QA Issues → Architect Review → Mark Complete
- **Use `resume` strategically** - Each agent can only be resumed once, best used after initial review/testing to fix issues
- For [TESTABLE] tasks: Code review and test immediately. Do not proceed without both passing.
- For [TEST AFTER COMPONENT] groups: Complete all tasks (with code review for each), then QA test as unit
- **code-reviewer** is NEVER optional - it catches pattern duplication, type safety issues, and test problems before QA
- Always update `tech.md` checkbox after a task passes all gates
- The `tech.md` is your progress tracker - it should show exactly which tasks are done at any point
## Phase 2: Quality Gates
Before marking any feature complete:
- ✅ Code review passed (no blocking issues from code-reviewer)
- ✅ No duplicate patterns without justification
- ✅ Type safety maximized (discriminated unions over optional fields)
- ✅ Test quality maintained (no test regressions)
- ✅ All acceptance criteria verified by spec-tester
- ✅ Code follows project conventions (check CLAUDE.md)
- ✅ Error handling implemented and tested
- ✅ Performance requirements met
- ✅ Security considerations addressed
- ✅ Tests pass (if test suite exists)
- ✅ Linting/type checking passes
## Implementation Patterns
### Sequential Tasks (dependent)
```
Implementation → Code Review → QA Testing → Refinement
```
### Parallel Tasks (independent)
```
Auth Module (spec-developer) + Payment Module (spec-developer) → Integration Testing (qa)
```
### Iterative Refinement
```
Implement → Code Review → Fix → QA Test → Fix → Re-test → Complete
```

237
skills/spec-architect/references/COMMUNICATION_PROTOCOL.md Normal file
View File

@@ -0,0 +1,237 @@
# Agent Communication Protocol for Claude Code Workflows
This protocol defines the communication standards for multi-agent workflows in Claude Code, optimized for resumable agent interactions.
## Protocol Goals
Resumable agents, clear boundaries, architect distributes PROJECT.md content.
## Agent Resumption Protocol
**IMPORTANT: Agent resumption is limited - each agent can only be resumed ONCE. Use strategically.**
### Resumption Limitations
Agents can be resumed only one time after their initial execution. This means:
- First execution: Agent does initial work
- First resumption: Agent can fix issues or continue work
- After that: Must spawn new agents for additional work
### Best Use Case for Resumption
Resume the developer agent after initial review/testing to fix issues. This is the most valuable use of the single resumption opportunity.
Typical flow:
1. Developer implements feature
2. Reviewer/tester finds issues
3. **Resume developer to fix** (using the one allowed resumption)
4. After that, spawn new agents if further work is needed
### Finding Previous Agent IDs
Use `cc-logs--extract-agents <session-id>` to get agent IDs from the current session when you need to resume.
Example:
```bash
# Get session ID (shown at session start)
# "Initialized agent context session: 9e3db88b-75cb-416b-a0a7-73e4bd0e5a2b"
cc-logs--extract-agents 9e3db88b-75cb-416b-a0a7-73e4bd0e5a2b
# Output shows agent IDs and details for resumption
```
Resume using the Task tool:
```
Task({
resume: "<agent-id>",
prompt: "Based on the code review feedback, please fix issues X, Y, and Z"
})
```
## File Reference Standard
All file references MUST use the vimgrep format:
```
/full/path/from/cwd/file.ext:line:column
```
Examples:
- `/path/to/project/src/auth.ts:45:12`
- `/path/to/project/config/settings.json:102:3`
When referencing ranges, use:
```
/path/to/file.ext:startLine:startCol-endLine:endCol
```
## Project Configuration
If `specs/PROJECT.md` exists, architect loads it once at workflow start and injects relevant sections into `Your_Responsibilities`:
- **General Instructions** → All agents
- **Architect Instructions** → Architect only (not passed to agents)
- **Developer Agent Instructions** → spec-developer
- **Reviewer Agent Instructions** → code-reviewer and spec-signoff
- **Tester Agent Instructions** → spec-tester
Agents never read PROJECT.md directly.
## Agent Briefing Protocol
When delegating to any agent, provide this structured context:
```yaml
Context:
Workflow: [PLAN|BUILD|ITERATE]
Phase: [exploration|specification|technical-design|implementation|code-review|testing]
Role: "You are working on [phase] of [feature]"
Workflow_Position: "Previous phase: [x] | Your phase: [y] | Next phase: [z]"
Inputs:
Spec_Directory: specs/XXX-feature-name/
Primary_Spec: specs/XXX-feature-name/feature.md
Technical_Spec: specs/XXX-feature-name/tech.md # if exists
Technical_Notes: specs/XXX-feature-name/notes.md # if exists
Related_Docs:
- /full/path/to/related.md
Relevant_Skills: # Suggested skills for this work (load as needed)
- [skill-name] # Language: typescript, python, go, ruby, etc.
- [skill-name] # Framework: react, vue, django, rails, etc.
- [skill-name] # Testing: playwright-skill, pdf, xlsx, etc.
# These are EXAMPLES - adapt to skills available in the current repository
# Agents may load additional skills at their discretion beyond suggestions
Your_Responsibilities:
- [Specific task 1]
- [Specific task 2]
- [
Project-specific instructions from PROJECT.md if applicable,
injected by architect,
]
NOT_Your_Responsibilities:
- [Explicitly excluded task 1]
- [Explicitly excluded task 2]
Deliverables:
Format: [Description of expected output format]
References: "Use pattern: file:line:col for all code references"
Checklist_Items:
[List specific items to complete, e.g., "AUTH-1, AUTH-2, AUTH-3"]
```
## Handover Requirements
### PLAN Workflow Outputs
**After Specification Creation (Phase 2)**:
- Complete feature specification with numbered requirements (FR-X, NFR-X)
- `interview.md` capturing user's original request and Q&A
- Technical notes (`notes.md`) if spike work was performed
- Clear success criteria for each requirement
- Testing setup instructions
**After Technical Design (Phase 3)**:
- Technical specification with numbered tasks (e.g., AUTH-1, COMP-1, API-1)
- Each task explicitly linked to feature requirements
- File paths for similar patterns and integration points (file:line:col references)
- Guidance on approach (not detailed implementation)
- Spec-signoff validation passed
### BUILD Workflow Inputs and Outputs
**Required Inputs**:
- Validated `feature.md` with FR-X and NFR-X requirements
- Validated `tech.md` with numbered implementation tasks
**During Implementation (Phase 1)**:
- Completed checklist items with file:line:col references to changes
- List of any deviations from technical specification
- Known limitations or incomplete items
**Code Review Deliverables**:
- Pattern consistency analysis (duplication check)
- Type safety review (discriminated unions vs optional fields)
- Test quality assessment
- Architectural consistency validation
- PASS/FAIL with specific file:line:col references for issues
**Testing Deliverables**:
- Status for each numbered requirement (FR-X, NFR-X)
- Status for each implementation task (e.g., AUTH-1, COMP-1, API-1)
- Specific file:line:col references for any issues found
- Clear PASS/FAIL status with evidence from user perspective
## Example Agent Invocation
```markdown
Context:
Workflow: BUILD
Phase: implementation
Role: "You are implementing the authentication service for a user management feature"
Workflow_Position: "Previous phase: technical-design | Your phase: implementation | Next phase: code-review"
Inputs:
Spec_Directory: specs/001-user-auth/
Primary_Spec: specs/001-user-auth/feature.md
Technical_Spec: specs/001-user-auth/tech.md
Technical_Notes: specs/001-user-auth/notes.md
Relevant_Skills:
- typescript # Example: Project uses TypeScript
- react # Example: Building React components
# Check available skills in repository and load as needed
Your_Responsibilities:
- Implement tasks AUTH-1, AUTH-2, and AUTH-3 from the technical spec
- Ensure all code follows project conventions in CLAUDE.md
- Create unit tests for each component
- PROJECT REQUIREMENTS (from specs/PROJECT.md):
- Always run tests after completing work: `yarn test <files-changed>`
- Use the project's logger (don't use console.log): `import { logger } from '@/lib/logger'`
- All error messages should be actionable and include next steps
NOT_Your_Responsibilities:
- Do not implement tasks AUTH-4 through AUTH-6 (assigned to parallel stream)
- Do not modify database schema (completed in previous sprint)
- Do not deploy or configure production environment
Deliverables:
Format: Working code with all specified tasks completed
References: "Use pattern: /full/path/file.ts:line:col for all code references"
Checklist_Items: "Complete and mark done: AUTH-1, AUTH-2, AUTH-3"
```
## Validation Rules
1. **Never use relative paths** - Always use full paths from project root
2. **Always include line numbers** - Even for new files (use :1:1)
3. **Reference specific items** - Use requirement IDs (FR-1) not descriptions
4. **Maintain checklist state** - Mark items complete immediately upon finishing
5. **Document deviations** - Any variance from spec must be explicitly noted with rationale
## Protocol Versioning
Protocol Version: 2.0.0
Last Updated: 2025-01-19
Compatibility: Claude Code with resumable agents (Task tool with `resume` parameter)
Changes to this protocol require updating all prime-\* commands that reference it.
### Version History
- **2.0.0** (2025-01-19): Added agent resumption protocol, folder-based spec structure
- **1.0.0** (2025-01-19): Initial protocol for multi-agent workflows

58
skills/spec-architect/references/ITERATE_WORKFLOW.md Normal file
View File

@@ -0,0 +1,58 @@
# ITERATE Workflow - Continuing Existing Work
Use this workflow when continuing work on an existing specification.
## Phase 1: Load and Assess
**Actions**:
1. **Load Project Configuration**: Check for `specs/PROJECT.md`. If exists:
- Read the entire file
- Check version metadata and offer template updates if available (see version checking in PLAN_WORKFLOW.md or BUILD_WORKFLOW.md)
- Extract sections per COMMUNICATION_PROTOCOL
2. **Load Specification**:
- Read `feature.md` from provided spec directory
- Read `tech.md` if it exists
- Read `notes.md` if it exists
3. **Assess Current State**:
- Review what's been completed (marked checkboxes in `tech.md`)
- Identify incomplete tasks
- Check for any new requirements or changes needed
- Follow PROJECT.md guidelines if loaded earlier
4. **Determine Next Action**:
- Continue incomplete implementation → Use BUILD workflow
- Expand/refine specifications → Use PLAN workflow
- Create initial specifications → Use PLAN workflow
## Phase 2: Execute Appropriate Workflow
Based on your assessment, choose the appropriate workflow:
### If continuing implementation
**Use `BUILD_WORKFLOW.md`**
- Specifications already exist and are validated
- Continue with task-by-task implementation
- Use existing `tech.md` checklist to track progress
- Follow Phase 1 (Implementation Coordination) through Phase 2 (Quality Gates)
### If expanding or refining specifications
**Use `PLAN_WORKFLOW.md`**
- Start at appropriate phase based on what needs updating:
- **Phase 2** (Specification Creation) - Adding new FR-X/NFR-X requirements to existing `feature.md`
- **Phase 3** (Technical Design) - Updating `tech.md` with revised implementation approach
- Get user approval for changes
- Ensure spec review (Phase 3, Step 8) validates updated specs
- Then proceed to `BUILD_WORKFLOW.md` for implementation
### If no specifications exist yet
**Use `PLAN_WORKFLOW.md` from Phase 1**
- Create complete specifications from scratch
- Validate before implementation
- Then proceed to `BUILD_WORKFLOW.md`
## Key Principle
**The ITERATE workflow doesn't duplicate content** - it's simply an assessment entry point that routes to the appropriate workflow (PLAN or BUILD) based on the current state of the specification.

247
skills/spec-architect/references/PLAN_WORKFLOW.md Normal file
View File

@@ -0,0 +1,247 @@
# PLAN Workflow - Feature Specification and Design
Use this workflow to create specifications for a new feature from a user briefing.
**Outcome**: Complete, reviewed specifications (`feature.md` and `tech.md`) ready for implementation.
## Phase 1: Exploration and Discovery
**Objective**: Understand the problem space before proposing solutions
**FIRST STEP: Load Project Configuration**
Check if `specs/PROJECT.md` exists. If it does:
1. Read the entire file
2. Check the version metadata at the bottom:
- Extract `template_version` and compare with current PROJECT_TEMPLATE.md version
- If PROJECT_TEMPLATE.md has a newer version, offer to show the user what's new:
"Your PROJECT.md was created from template version X.X.X, but version Y.Y.Y is now available. Would you like me to show you the changes so you can decide if you want to adopt any new features?"
- If user wants to see changes, read PROJECT_TEMPLATE.md and explain the differences
3. Extract the "General Instructions" and "Architect Instructions" sections for your own use
4. Keep the agent-specific sections (Developer, Reviewer, Tester) ready to inject into agent briefings later
**Actions**:
1. **Problem Understanding**:
- What specific problem are we solving?
- Who are the users and their pain points?
- What does success look like?
- What are edge cases and failure modes?
- What is the migration strategy for PUBLIC API breaking changes?
2. **Technical Discovery**:
- Use **Explore agent** to find similar implementations in the codebase
- Use **researcher agent** to investigate industry best practices
- Resume agents as needed for follow-up research
3. **Spike Work** (Small POCs):
- Create minimal proof-of-concepts to validate feasibility
- Test critical assumptions about external dependencies
- Verify API behaviors and integration points
- Document findings in `notes.md`
**Outputs**: Understanding of problem domain, existing patterns, technical constraints
## Phase 2: Specification Creation
**Objective**: Document WHAT needs to be built with measurable acceptance criteria
**IMPORTANT**: This is DISCOVERY and SPECIFICATION only - no implementation yet. It is your responsibility to identify any breaking changes to PUBLIC APIs and ask for clarification on migration strategy unless explicitly stated. Internal APIs can be refactored freely.
**Actions**:
1. **Create Spec Directory**:
- The next spec ID is provided in the command Context
- Create `specs/<id>-<feature>/` directory
- Create `feature.md` from `references/SPEC_TEMPLATE.md`
2. **Create `interview.md` in spec directory**:
- Document the user's original prompt verbatim in "Original Brief" section
- Record ALL Q&A exchanges, clarifications, and decisions
- Format:
```markdown
# Feature Interview
## Original Brief
[User's exact prompt]
## Discovery Q&A
### Q: [Question]
A: [Answer]
## Key Decisions
- [Decision with rationale]
```
3. **Document Requirements**:
- Problem statement and value proposition
- Functional requirements (FR-1, FR-2, ...) with testable ACs
- Non-functional requirements (NFR-1, NFR-2, ...)
- Interface definitions and data models
- **Testing Setup** - CRITICAL: Document how to start systems, environment setup, test data, access points, and cleanup
- This enables the spec-tester agent to successfully verify the feature
- Include exact bash commands to start servers, clients, databases, etc.
- Specify URLs, ports, credentials for accessing the system
- Note any testing tools available (playwright-skill, API scripts, etc.)
- Clear acceptance criteria for each requirement
- External dependency validation (pre-flight checks)
- Follow PROJECT.md guidelines if loaded earlier
4. **User Review and Approval**:
- Present draft specification for review
- Highlight assumptions and technical discoveries
- Ask structured review questions:
- "Does this capture your intended user workflow?"
- "Are these acceptance criteria measurable enough?"
- "Have I missed any critical edge cases?"
- "Is the migration strategy appropriate for PUBLIC API changes?"
- Iterate based on feedback
- Get explicit user approval
5. **Final Architectural Review**:
- Think deeply about edge cases
- Identify implicit assumptions
- Verify specification completeness
**Outputs**:
- `specs/<id>-<feature>/feature.md` with numbered requirements
- `specs/<id>-<feature>/interview.md` with user's original prompt and Q&A
- `specs/<id>-<feature>/notes.md` if spike work was performed
## Phase 3: Technical Design
**Objective**: Document HOW to build what was specified
**IMPORTANT**: This is TECHNICAL DESIGN - defining implementation approach but not building yet. Tasks must be broken down to enable tight build-test cycles during implementation.
**Actions**:
1. **Load Context**:
- Read `feature.md` and `notes.md` from spec directory
- Review related specifications and technical docs
- Use **Explore agent** to analyze existing system patterns
- Use **researcher agent** for technology stack research
2. **Architecture Review**:
- Component breakdown and responsibilities
- Service boundaries and interfaces
- Data flow and state management
- Integration patterns and protocols
3. **Technology Stack Decisions**:
- Use researcher for framework comparisons
- Use Explore for existing patterns analysis
- Document rationale for all technology choices
4. **Implementation Strategy**:
- Development sequence and dependencies
- Migration strategy (backwards compatibility vs in-place updates)
- Testing strategy (unit, integration, e2e)
5. **Create Technical Specification**:
- Use `references/TECH_SPEC_TEMPLATE.md` as starting point
- Create `tech.md` in spec directory
**CRITICAL: Focus on GUIDANCE, not IMPLEMENTATION**
The tech spec should be a MAP that enables the developer to implement effectively, NOT a BLUEPRINT that prescribes exact implementation.
**Think:**
- "Where should they look?" (file references to similar code)
- "What patterns should they follow?" (existing implementations)
- "What decisions have been made?" (technology choices with rationale)
- "What constraints exist?" (NFRs, gotchas discovered)
**Don't:**
- Write exact function signatures
- Design complete API schemas with all fields
- Specify detailed algorithms or step-by-step logic
- Write pseudo-code implementations
**Use discoveries from Explore/researcher agents:**
- Document similar implementations found (file:line:col references)
- Reference existing patterns to follow
- Note integration points discovered
- Capture gotchas and constraints learned
**Quality check:**
If a developer could copy-paste from tech.md to create the implementation, you've over-specified.
The developer should still need to make design decisions, just informed ones.
- Structure tasks for testability:
**CRITICAL: Task Decomposition for Testability**
When creating the `tech.md`, structure tasks to enable tight build-test cycles:
**Pattern A: Task-Level Testing (Preferred)**
```markdown
### Component: User Validation
- [ ] **VAL-1**: Create email validation function (delivers FR-1) [TESTABLE]
- [ ] **VAL-2**: Add password strength checker (delivers FR-2) [TESTABLE]
- [ ] **VAL-3**: Create validation error messages (delivers NFR-1) [TESTABLE]
```
**Pattern B: Component-Level Testing (When Tasks are Interdependent)**
```markdown
### Component: OAuth Integration [TEST AFTER COMPONENT]
- [ ] **OAUTH-1**: Setup OAuth client configuration (delivers FR-3)
- [ ] **OAUTH-2**: Implement token exchange (delivers FR-3)
- [ ] **OAUTH-3**: Add refresh token logic (delivers FR-3)
Note: These tasks are interdependent. QA should test after all three are complete.
```
**Task Sizing Guidelines**:
- Task completable in 1-2 hours
- Clear deliverable (function, endpoint, component)
- If larger, break down further
- Each task references FR-X or NFR-X it delivers
**Avoid These Anti-Patterns**:
- ❌ "Implement entire authentication system" (too large)
- ❌ "Add a comment" (too trivial)
- ❌ Tasks with no clear testable outcome
- ❌ Tasks requiring extensive mocking to test
6. **Technical Review and Refinement**:
- Validate with user for technical feasibility
- Discuss trade-offs and alternatives
- Confirm resource availability
- Get final technical approval
7. **Final Architectural Review**:
- Ensure comprehensive coverage of `feature.md`
- Verify work is broken down into manageable chunks
- Identify concurrent work streams where appropriate
8. **Specification Review (Pre-Implementation Quality Gate)**:
Delegate to **spec-signoff agent**:
> "Review the specifications in specs/<id>-<feature>/ for design quality before implementation begins"
**If spec-signoff finds issues**:
- Address all gaps and ambiguities
- Re-review until specifications are complete
- Do NOT proceed to implementation with incomplete specs
This review ensures implementation can proceed smoothly without constant backtracking to clarify requirements.
**Outputs**: Validated `specs/<id>-<feature>/tech.md` with numbered implementation tasks, ready for BUILD workflow
## Next Step
Once specifications are complete and reviewed, proceed to `BUILD_WORKFLOW.md` for implementation.

70
skills/spec-architect/references/PROJECT_TEMPLATE.md Normal file
View File

@@ -0,0 +1,70 @@
# Project Configuration
## General Instructions
**Example:**
- This is a developer tool - breaking changes are acceptable as users always use the latest version
- Code should prioritize clarity over clever optimizations
- All error messages should be actionable and include next steps
- Dependencies should be kept minimal
## Architect Instructions
**Example:**
- Focus on incremental delivery - each spec should be independently deployable
- Breaking changes to PUBLIC APIs require explicit migration strategy documentation
- Internal APIs can be refactored freely without migration guides
- Prefer composition over inheritance when designing component relationships
## Developer Agent Instructions
**Example:**
- Always run tests after completing work: `yarn test <files-changed>`
- Use the project's logger (don't use console.log directly): `import { logger } from '@/lib/logger'`
- Follow the project's error handling pattern (see `src/lib/errors.ts`)
- New API endpoints must include OpenAPI documentation comments
## Reviewer Agent Instructions
**Example:**
- Check for proper error handling - all async operations must have error boundaries
- Verify type safety - no `any` types without explicit justification comments
- Ensure test coverage for edge cases, not just happy paths
- Look for security issues: SQL injection, XSS, CSRF vulnerabilities
## Tester Agent Instructions
**Example:**
- Test with realistic data volumes (at least 1000 items for list operations)
- Verify mobile responsive design on viewport widths: 320px, 768px, 1024px
- Test error scenarios explicitly (network failures, invalid inputs, timeouts)
- Check browser console for errors during testing
---
## Version Metadata
**DO NOT EDIT THIS SECTION - It is used for template version tracking**
- **template_version**: 1.0.0
- **owner_version**: 1.0.0
### Version Field Descriptions
- **template_version**: The version of PROJECT_TEMPLATE.md that was used to generate this file. Updated only when you regenerate from a newer template or manually adopt changes from a newer template.
- **owner_version**: Your customization version. Increment this when you make significant changes to your PROJECT.md (e.g., 1.0.0 → 1.1.0 for additions, 2.0.0 for major restructuring). This helps track your project's configuration evolution separately from template updates.
### How Versioning Works
When you create a new PROJECT.md from this template:
1. Both `template_version` and `owner_version` start at the same value (the current template version)
2. When you customize PROJECT.md for your project, increment `owner_version`
3. When a new PROJECT_TEMPLATE.md is released, the architect can compare versions and offer to show you what's new
4. You can then decide which new features to adopt and update `template_version` accordingly
### Template Version History
**1.0.0** (2025-01-13)
- Initial versioned template
- Sections: General Instructions, Architect Instructions, Developer Agent Instructions, Reviewer Agent Instructions, Tester Agent Instructions
- Establishes version tracking system for template evolution

174
skills/spec-architect/references/SPEC_TEMPLATE.md Normal file
View File

@@ -0,0 +1,174 @@
# <Feature Name>
<!-- This is a **living document**, it can and should be updated as implementation reveals insights requiring spec updates. These should be validated with the architect and user -->
User Sign off: [REQUIRED - DO NOT BUILD WITHOUT THIS]
[where appropriate, diagrams, flowcharts, and visual aids significantly improve specification comprehension**. System context diagrams showing how new components fit within existing architecture prove especially valuable. Data flow illustrations clarify complex processes better than verbose descriptions. Visual elements should complement, not replace, textual specifications - they provide the high-level understanding that makes detailed requirements meaningful]
## Context and Problem Statement
[Clear description of the business problem and why this feature is needed]
## Value Statement
[Expected outcomes and success metrics]
## Stakeholders
- **Users**: [Who will use this]
- **Maintainers**: [Who will maintain this]
- **Dependencies**: [Other systems/teams affected]
## Technical Architecture
[High-level design decisions, component boundaries, integration points]
## Functional Requirements
### FR-1: [Feature Name]
[Description of what the system SHALL do]
### FR-2: [Feature Name]
[Description of what the system SHALL do]
### FR-3: [Feature Name]
[Description of what the system SHALL do]
## Non-Functional Requirements
### NFR-1: Performance
[Specific performance requirement, e.g., "Response time SHALL be < 200ms for 95% of requests"]
### NFR-2: Scalability
[Specific scalability requirement, e.g., "System SHALL support 10K concurrent users"]
### NFR-3: Security
[Specific security requirement, e.g., "Authentication SHALL use JWT tokens with 1-hour expiry"]
### NFR-4: Reliability
[Specific reliability requirement, e.g., "System SHALL maintain 99.9% uptime"]
## External Dependencies
[Validated through spike work - actual behaviors documented]
## Interface Definitions
[API endpoints, data models, integration contracts]
## Testing Setup
**CRITICAL: This section enables the spec-tester agent to successfully verify this feature.**
### System Startup
[Provide exact commands to start required systems. The spec-tester agent has full Bash capabilities.]
**Example for web application:**
```bash
# Start development server
cd /path/to/project
npm run dev
# Server will be available at http://localhost:3000
# Wait for "Server ready" message before testing
```
**Example for full-stack application:**
```bash
# Terminal 1: Start backend API
cd /path/to/backend
npm run dev
# API available at http://localhost:8080
# Terminal 2: Start frontend
cd /path/to/frontend
npm start
# UI available at http://localhost:3000
```
**Example for CLI tool:**
```bash
# Build the tool
cd /path/to/project
npm run build
# Run the CLI
./bin/my-tool --help
```
### Environment Requirements
[Any environment setup needed before testing]
**Example:**
- Environment variables: Copy `.env.example` to `.env` and configure
- Database: Run `npm run db:migrate` to set up test database
- API keys: Requires `API_KEY` environment variable (use test key: `test-key-123`)
### Test Data Setup
[How to create/load test data if needed]
**Example:**
```bash
# Seed test database
npm run db:seed:test
# Or manually create test user
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"test123"}'
```
### Access Points
[Where to access the system for testing]
**Example:**
- **Web UI**: http://localhost:3000
- **API**: http://localhost:8080/api
- **Admin Panel**: http://localhost:3000/admin (login: admin@test.com / admin123)
- **API Docs**: http://localhost:8080/docs
### Cleanup / Shutdown
[How to properly stop systems and clean up]
**Example:**
```bash
# Stop all servers (Ctrl+C in each terminal)
# Or if using background processes:
npm run stop
# Clean up test data (optional)
npm run db:reset
```
### Testing Tools Available
[List any testing tools, scripts, or helpers]
**Example:**
- **playwright-skill**: Available for browser-based UI testing
- **API testing**: Use `curl` or built-in test scripts (`npm run test:api`)
- **Test utilities**: Helper scripts in `/scripts/test-helpers.sh`
## Acceptance Criteria
[Clear conditions that determine feature completion]
## Implementation Notes
[Technical constraints, dependencies, risks discovered during spikes]
## Technical Debt Tracking
[Document any shortcuts or future improvements needed]

244
skills/spec-architect/references/TECH_SPEC_TEMPLATE.md Normal file
View File

@@ -0,0 +1,244 @@
# [Feature Name] - Implementation Guide
User Sign off: [REQUIRED - DO NOT BUILD WITHOUT THIS]
## Implementation Context
### What We're Building
[1-2 sentence summary linking to feature.md requirements]
### Why This Approach
[High-level rationale for technical direction taken]
## Discovery Findings
### Similar Implementations
[Reference existing features that solve similar problems - use Explore agent findings]
**Pattern: [Pattern Name]**
- Implementation: `relative-to-cwd/path/to/existing.ext:startLine:endLine`
- Follow this pattern for: [what aspects]
- Note: [Key observations about the pattern]
**Pattern: [Another Pattern]**
- Example: `relative-to-cwd/path/to/another.ext:line:col`
- Key learning: [What to replicate or avoid]
### Key Integration Points
[Where this feature connects to existing code - from Explore agent discoveries]
- **[System/Service]**: Uses `ServiceName` from `relative-to-cwd/path/to/service.ext:line:col`
- Purpose: [Why we integrate here]
- **[Another Integration]**: Add to `relative-to-cwd/path/to/file.ext:line:col`
- Purpose: [Why we integrate here]
### Constraints & Gotchas
[Technical constraints, edge cases, and discoveries from exploration]
- [Constraint or gotcha discovered]
- [Performance limitation or consideration]
- [Security requirement or compliance need]
## Technology Decisions
### [Decision Area]
**Options Considered:**
- **Option A**: [Brief description]
- Pros: [Key benefits]
- Cons: [Key drawbacks]
- **Option B**: [Brief description]
- Pros: [Key benefits]
- Cons: [Key drawbacks]
**Selected: Option [X]**
- Rationale: [Why this choice best serves requirements]
- Documentation: [Link to official docs if helpful]
- Example usage: `relative-to-cwd/path/to/similar-usage.ext:line:col`
## File Map
### Files to Create
- `relative-to-cwd/path/to/new/file.ext:1:1` - [Component purpose and responsibility]
- `relative-to-cwd/path/to/another/new.ext:1:1` - [Component purpose]
### Files to Modify
- `relative-to-cwd/path/to/existing.ext:line:col` - [What needs to change and why]
- `relative-to-cwd/path/to/another.ext:line:col` - [What needs to change]
### Files to Reference
[Files that provide patterns, types, or examples to follow]
- `relative-to-cwd/path/to/pattern.ext` - [What pattern/approach to follow]
- `relative-to-cwd/path/to/types.ext` - [Type patterns to replicate]
## Component Architecture
### Component: [Component Name]
**Responsibility**: [What this component does - high level, not implementation details]
**Interfaces With:**
- Uses: `relative-to-cwd/path/to/dependency.ext:line:col` - [Why and how it's used]
- Provides: [What other components will consume from this]
**Key Constraints:**
- [Performance requirements from NFRs]
- [Security requirements from NFRs]
- [Other constraints discovered during planning]
**Testing Approach:**
- Follow pattern: `relative-to-cwd/path/to/similar/test.ext:line:col`
- Use: [Testing tools/skills - playwright-skill, API helpers, etc.]
- Focus: [What aspects are critical to test]
### Component: [Another Component]
[Repeat structure above for each major component]
## Implementation Tasks
### Component: [Component Name]
Location: `relative-to-cwd/path/to/component/directory`
- [ ] **COMP-1**: [Task description] (delivers FR-X, NFR-Y) [TESTABLE]
- Create: `relative-to-cwd/path/to/new/file.ext:1:1`
- Reference pattern: `relative-to-cwd/path/to/existing/similar.ext:line:col`
- Integration: Uses [ServiceName] from `relative-to-cwd/path/to/service.ext:line:col`
- [ ] **COMP-2**: [Task description] (delivers FR-X) [TESTABLE]
- Modify: `relative-to-cwd/path/to/existing/file.ext:line:col`
- Follow pattern from COMP-1
- Dependencies: COMP-1 must be complete
### Component: [Another Component] [TEST AFTER COMPONENT]
Location: `relative-to-cwd/to/another/component`
- [ ] **AUTH-1**: [Task description] (delivers FR-1, NFR-3)
- Create: `relative-to-cwd/to/auth/service.ts:1:1`
- Reference: `relative-to-cwd/to/existing/auth-pattern.ts:23:67`
- [ ] **AUTH-2**: [Task description] (delivers FR-2)
- Update: `relative-to-cwd/to/session/manager.ts:45:12`
- Dependencies: AUTH-1 must be complete before AUTH-2
Note: Test AUTH-1 and AUTH-2 together after both are implemented
## Testing Guidance
### Testing Setup
[Reference to Testing Setup section in feature.md - spec-tester will use this]
See feature.md "Testing Setup" section for system startup, environment requirements, test data, access points, and cleanup procedures.
### Testing Patterns to Follow
**Unit tests:**
- Pattern: `relative-to-cwd/path/to/unit.test.ext:line:col`
- Focus: [What to test at unit level]
**Integration tests:**
- Pattern: `relative-to-cwd/path/to/integration.test.ext:line:col`
- Focus: [What to test at integration level]
**E2E tests:**
- Tools: [playwright-skill / API helpers / etc.]
- Pattern: `relative-to-cwd/path/to/e2e.test.ext:line:col`
### Testing Tools Available
[List testing tools, scripts, or helpers available for this feature]
- Jest/Vitest for unit and integration tests
- playwright-skill for UI testing (spec-tester can load this)
- API test helpers: `scripts/test-api.sh`
- [Other tools discovered during exploration]
## Implementation Notes
### Discovered During Planning
[Technical discoveries, constraints, gotchas from Explore/researcher agents]
- [Finding from exploration that affects implementation]
- [Constraint discovered that wasn't obvious initially]
- [Best practice from similar implementations]
### Migration Strategy
[If this involves breaking changes to PUBLIC APIs]
- [How existing consumers will be supported]
- [Deprecation timeline if applicable]
- [Communication plan for breaking changes]
Note: Internal APIs can be refactored freely without migration strategy.
### Performance Considerations
[Specific NFRs and validation approach]
- NFR-X requires: [Specific performance target]
- Validate with: [How to measure/verify]
### Security Considerations
[Authentication, authorization, data protection, compliance]
- [Specific security requirements from NFRs]
- [Compliance requirements if applicable]
- [Security patterns to follow from similar features]
## References
### Codebase Documentation
[Links to relevant documentation within the repository]
- [Internal docs about patterns/architecture]
- [ADRs (Architecture Decision Records) if applicable]
### External Documentation
[Links to API docs, library docs, frameworks]
- [Library/framework documentation]
- [API documentation for external services]
### Related Specifications
[Links to related feature.md files in specs/]
- `specs/XXX-related-feature/feature.md` - [How it relates]
## Technical Debt Considerations
[Known compromises and future refactoring needs identified during planning]
- [Known shortcut or compromise with rationale]
- [Future improvement opportunity]
## Dependencies and Prerequisites
[External services, libraries, infrastructure requirements]
- [External service dependencies]
- [Library/framework versions required]
- [Infrastructure or environment requirements]
## Regressions or Missed Requirements
None found
<!-- Section for documenting missed requirements discovered during implementation and their resolution, with the intention being to prevent future mistakes -->

162
skills/spec-architect/references/writing-specs.md Normal file
View File

@@ -0,0 +1,162 @@
# Core principles for technical specifications
## Problem definition establishes shared understanding
Technical specifications must begin with **clear problem articulation before proposing solutions**. Research from Google Engineering, Carnegie Mellon's Software Engineering Institute, and IEEE standards consistently shows that specifications fail when they jump directly to implementation details without establishing context. The most effective specifications dedicate substantial effort to documenting why something needs to be built, what business problem it solves, and what constraints exist. This problem-first approach reduces costly rework - studies indicate that **49% of digital transformation projects fail due to requirements issues**, primarily from misunderstood objectives.
## Requirements must be measurable and testable
Every requirement needs **quantifiable acceptance criteria** that enable objective verification. The principle appears across IEEE 29148:2018, ISTQB guidelines, and developer surveys as fundamental to specification success. Instead of stating "the system should be fast," specify "the system must respond within 200ms for 95% of requests under normal load conditions." This precision serves both developers implementing features and QA teams designing test cases. Requirements using structured formats like "Given X, when Y, then Z" naturally translate into executable tests, creating what the testing community calls **inherently testable specifications**.
## Structured documentation enables effective navigation
Successful specifications follow **consistent organizational patterns** that all stakeholders can navigate efficiently. Industry standards converge on essential sections: context and scope, functional requirements, non-functional requirements, interface definitions, and acceptance criteria. Google's engineering practices show that specifications between 10-20 pages hit the sweet spot for substantial projects - comprehensive enough for clarity, concise enough for busy stakeholders. Each section should serve a specific audience need while maintaining coherence across the whole document. The structure itself becomes a **communication framework** that ensures nothing critical is overlooked.
**Use the specification template**: A ready-to-use template is available at `.claude/agent-docs/specification-template.md` that implements these structural patterns and can be copied when creating new specifications.
## Visual communication enhances understanding
Research across Stack Overflow developer surveys and academic studies confirms that **diagrams, flowcharts, and visual aids significantly improve specification comprehension**. System context diagrams showing how new components fit within existing architecture prove especially valuable. Data flow illustrations clarify complex processes better than verbose descriptions. Visual elements should complement, not replace, textual specifications - they provide the high-level understanding that makes detailed requirements meaningful. Effective specifications use visuals strategically to reduce ambiguity and accelerate stakeholder alignment.
## Living documentation evolves with implementation
The most successful specifications are **maintained throughout the development lifecycle**, not frozen at project initiation. This "living documentation" approach, validated by Agile research and industry case studies, recognizes that implementation reveals insights requiring specification updates. Version control and change tracking become essential - not for bureaucratic compliance, but for maintaining shared understanding as projects evolve. Organizations reporting highest project success rates treat specifications as **collaborative working documents** updated within the same sprint as code changes.
# Practical checklist for technical specifications
**Note**: When creating a new specification, start by copying `.claude/agent-docs/specification-template.md` which provides a structured format implementing these principles.
## Foundation phase
☐ **Define the problem clearly** - State what business problem needs solving before describing any solution
☐ **Establish scope boundaries** - Document what is included and explicitly what is NOT included
☐ **Identify all stakeholders** - List who will use, implement, test, and maintain the system
☐ **Document assumptions and dependencies** - Make implicit knowledge explicit
☐ **Create a glossary** - Define domain-specific terms to eliminate ambiguity
## Requirements definition phase
☐ **Write testable functional requirements** - Each requirement must have clear pass/fail criteria
☐ **Specify measurable non-functional requirements** - Include specific metrics for performance, security, reliability
☐ **Use consistent requirement format** - Apply structured patterns like "The system SHALL [capability] WHEN [condition]"
☐ **Assign unique identifiers** - Every requirement needs a traceable ID for lifecycle management
☐ **Define priority levels** - Clearly distinguish must-have from nice-to-have features
## External dependency validation phase (Pre-flight checklist)
**Critical**: Execute this phase for any specification involving external tools, APIs, or libraries to prevent regressions from incorrect assumptions.
### Dependency discovery
☐ **Inventory all external dependencies** - List tools, APIs, libraries with specific version requirements
☐ **Document platform differences** - Note macOS/Linux/Windows variations
☐ **Classify criticality** - Distinguish required vs optional dependencies
### API research and validation
☐ **Test actual commands** - Run real commands and capture exact output, don't rely on documentation alone
☐ **Document flag behaviors** - Note differences between similar flags (e.g., `--match` vs `--match-tab`)
☐ **Capture real responses** - Use actual API calls to get true schemas, not documented ones
☐ **Identify nullable fields** - Test which fields can be null vs required vs state-dependent
☐ **Record error outputs** - Document actual error messages and failure modes
### Assumption validation
☐ **Create validation scripts** - Test each API assumption against the real tool
☐ **Document deviations** - Note any differences from expected behavior
☐ **Design accurate mocks** - Base mock implementations on captured real data, not documentation
☐ **Plan integration tests** - Create tests that validate core assumptions against real tools
### Documentation requirements
For each external dependency, document:
- Exact command syntax with all flags
- Sample input and actual captured output
- Error conditions with real error messages
- Version-specific behaviors and quirks
- Response schemas from actual API calls
- Field-level notes on nullable/state-dependent values
## Design documentation phase
☐ **Include system context diagram** - Show how the solution fits within existing architecture
☐ **Document interfaces precisely** - Use validated API information from pre-flight phase
☐ **Address error scenarios** - Include real error cases discovered during validation
☐ **Specify data structures** - Use actual schemas captured from external tools
☐ **Document security requirements** - Authentication, authorization, data protection specifics
## Quality and validation phase
☐ **Define acceptance criteria** - Specific conditions that determine feature completion
☐ **Include positive and negative test scenarios** - What the system should and shouldn't do
☐ **Specify performance benchmarks** - Response times, throughput, resource usage limits
☐ **Document compliance requirements** - Regulatory, legal, or organizational standards
☐ **Create traceability matrix** - Link requirements to implementation tasks and test cases
## Stakeholder collaboration phase
☐ **Conduct multi-perspective reviews** - Include developers, testers, business analysts, users
☐ **Document trade-off decisions** - Explain why certain approaches were chosen over alternatives
☐ **Include visual aids** - Diagrams, mockups, flowcharts to enhance understanding
☐ **Provide concrete examples** - Illustrate abstract requirements with specific scenarios
☐ **Obtain formal sign-offs** - Stakeholder agreement on requirement completeness
## Maintenance and evolution phase
☐ **Establish version control** - Track all changes with clear revision history
☐ **Update specifications with implementation insights** - Maintain as living documents
☐ **Document lessons learned** - Capture what worked and what didn't for future projects
☐ **Review specification effectiveness** - Measure if specs helped achieve project goals
☐ **Refine templates and processes** - Continuously improve based on team feedback
## Critical success factors
**Avoid these proven specification failures:**
- Ambiguous language without measurable criteria
- Missing error handling and edge cases
- Technical implementation details before establishing requirements
- Single-author specifications without stakeholder input
- Static documents that become outdated during development
- **Assuming API behaviors without testing** - Always validate with real tools
- **Creating mocks from documentation** - Use captured real behavior instead
- **Ignoring platform differences** - Test on target platforms
- **Skipping external dependency validation** - Major cause of regressions
**Implement these proven practices:**
- Three Amigos sessions bringing together business, development, and testing perspectives
- Specification by example using concrete scenarios
- Regular specification reviews throughout development
- Automated quality checks for requirement consistency
- Clear change management process for requirement updates
- **Pre-flight validation** - Test all external dependencies before finalizing specs
- **Capture real outputs** - Document actual API responses and command outputs
- **Validation scripts** - Automate assumption testing against real tools
- **Mock-reality alignment** - Ensure mocks match actual tool behavior
## Common pitfalls with external dependencies
Based on real regression analysis, avoid these specific mistakes:
1. **Assuming similar flags behave identically** - Always test each flag's actual behavior
2. **Guessing JSON field names or types** - Capture real responses to verify
3. **Creating mocks from documentation alone** - Documentation often diverges from implementation
4. **Ignoring version-specific behaviors** - Different versions may have different outputs
5. **Not testing error conditions** - Error handling design requires real error outputs
6. **Skipping platform testing** - Tools behave differently across operating systems
7. **Complex command compositions** - Test pipes and command chains thoroughly
## Red flags requiring extra validation
Pay special attention when specifications involve:
- Commands with multiple filtering options
- APIs returning different schemas based on state
- Tools with poor or outdated documentation
- Platform-specific implementations
- Undocumented features or behaviors
- Complex data transformations or parsing
This checklist synthesizes decades of industry experience, formal standards from IEEE and ISO, empirical research from leading software organizations, and hard-learned lessons from production regressions. Teams that follow these principles—especially the external dependency validation phase—consistently report **reduced rework, faster development cycles, and higher stakeholder satisfaction**. The key is adapting these universal principles to your specific context while maintaining the rigor that makes specifications truly useful for both implementation and verification. The pre-flight validation phase has proven critical in preventing costly regressions caused by incorrect assumptions about external tools and APIs.