Skip to content

Commit 69878b2

Browse files
AlexAlexandreAlvesAlexAlexandreAlves
committed
feat: applying ai-sdd
1 parent c50f044 commit 69878b2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+6273
-2
lines changed

‎.claude/commands/sdd/spec-design.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
description: Create comprehensive technical design for a specification
3+
allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
4+
argument-hint: <feature-name> [-y]
5+
---
6+
7+
# Technical Design Generator
8+
9+
<background_information>
10+
- **Mission**: Generate comprehensive technical design document that translates requirements (WHAT) into architectural design (HOW)
11+
- **Success Criteria**:
12+
- All requirements mapped to technical components with clear interfaces
13+
- Appropriate architecture discovery and research completed
14+
- Design aligns with steering context and existing patterns
15+
- Visual diagrams included for complex architectures
16+
</background_information>
17+
18+
<instructions>
19+
## Core Task
20+
Generate technical design document for feature **$1** based on approved requirements.
21+
22+
## Execution Steps
23+
24+
### Step 1: Load Context
25+
26+
**Read all necessary context**:
27+
- `.sdd/specs/$1/spec.json`, `requirements.md`, `design.md` (if exists)
28+
- **Entire `.sdd/steering/` directory** for complete project memory
29+
- `.sdd/settings/templates/specs/design.md` for document structure
30+
- `.sdd/settings/rules/design-principles.md` for design principles
31+
- `.sdd/settings/templates/specs/research.md` for discovery log structure
32+
33+
**Validate requirements approval**:
34+
- If `-y` flag provided ($2 == "-y"): Auto-approve requirements in spec.json
35+
- Otherwise: Verify approval status (stop if unapproved, see Safety & Fallback)
36+
37+
### Step 2: Discovery & Analysis
38+
39+
**Critical: This phase ensures design is based on complete, accurate information.**
40+
41+
1. **Classify Feature Type**:
42+
- **New Feature** (greenfield) → Full discovery required
43+
- **Extension** (existing system) → Integration-focused discovery
44+
- **Simple Addition** (CRUD/UI) → Minimal or no discovery
45+
- **Complex Integration** → Comprehensive analysis required
46+
47+
2. **Execute Appropriate Discovery Process**:
48+
49+
**For Complex/New Features**:
50+
- Read and execute `.sdd/settings/rules/design-discovery-full.md`
51+
- Conduct thorough research using WebSearch/WebFetch:
52+
- Latest architectural patterns and best practices
53+
- External dependency verification (APIs, libraries, versions, compatibility)
54+
- Official documentation, migration guides, known issues
55+
- Performance benchmarks and security considerations
56+
57+
**For Extensions**:
58+
- Read and execute `.sdd/settings/rules/design-discovery-light.md`
59+
- Focus on integration points, existing patterns, compatibility
60+
- Use Grep to analyze existing codebase patterns
61+
62+
**For Simple Additions**:
63+
- Skip formal discovery, quick pattern check only
64+
65+
3. **Retain Discovery Findings for Step 3**:
66+
- External API contracts and constraints
67+
- Technology decisions with rationale
68+
- Existing patterns to follow or extend
69+
- Integration points and dependencies
70+
- Identified risks and mitigation strategies
71+
- Potential architecture patterns and boundary options (note details in `research.md`)
72+
- Parallelization considerations for future tasks (capture dependencies in `research.md`)
73+
74+
4. **Persist Findings to Research Log**:
75+
- Create or update `.sdd/specs/$1/research.md` using the shared template
76+
- Summarize discovery scope and key findings (Summary section)
77+
- Record investigations in Research Log topics with sources and implications
78+
- Document architecture pattern evaluation, design decisions, and risks using the template sections
79+
- Use the language specified in spec.json when writing or updating `research.md`
80+
81+
### Step 3: Generate Design Document
82+
83+
1. **Load Design Template and Rules**:
84+
- Read `.sdd/settings/templates/specs/design.md` for structure
85+
- Read `.sdd/settings/rules/design-principles.md` for principles
86+
87+
2. **Generate Design Document**:
88+
- **Follow specs/design.md template structure and generation instructions strictly**
89+
- **Integrate all discovery findings**: Use researched information (APIs, patterns, technologies) throughout component definitions, architecture decisions, and integration points
90+
- If existing design.md found in Step 1, use it as reference context (merge mode)
91+
- Apply design rules: Type Safety, Visual Communication, Formal Tone
92+
- Use language specified in spec.json
93+
- Ensure sections reflect updated headings ("Architecture Pattern & Boundary Map", "Technology Stack & Alignment", "Components & Interface Contracts") and reference supporting details from `research.md`
94+
95+
3. **Update Metadata** in spec.json:
96+
- Set `phase: "design-generated"`
97+
- Set `approvals.design.generated: true, approved: false`
98+
- Set `approvals.requirements.approved: true`
99+
- Update `updated_at` timestamp
100+
101+
## Critical Constraints
102+
- **Type Safety**:
103+
- Enforce strong typing aligned with the project's technology stack.
104+
- For statically typed languages, define explicit types/interfaces and avoid unsafe casts.
105+
- For TypeScript, never use `any`; prefer precise types and generics.
106+
- For dynamically typed languages, provide type hints/annotations where available (e.g., Python type hints) and validate inputs at boundaries.
107+
- Document public interfaces and contracts clearly to ensure cross-component type safety.
108+
- **Latest Information**: Use WebSearch/WebFetch for external dependencies and best practices
109+
- **Steering Alignment**: Respect existing architecture patterns from steering context
110+
- **Template Adherence**: Follow specs/design.md template structure and generation instructions strictly
111+
- **Design Focus**: Architecture and interfaces ONLY, no implementation code
112+
- **Requirements Traceability IDs**: Use numeric requirement IDs only (e.g. "1.1", "1.2", "3.1", "3.3") exactly as defined in requirements.md. Do not invent new IDs or use alphabetic labels.
113+
</instructions>
114+
115+
## Tool Guidance
116+
- **Read first**: Load all context before taking action (specs, steering, templates, rules)
117+
- **Research when uncertain**: Use WebSearch/WebFetch for external dependencies, APIs, and latest best practices
118+
- **Analyze existing code**: Use Grep to find patterns and integration points in codebase
119+
- **Write last**: Generate design.md only after all research and analysis complete
120+
121+
## Output Description
122+
123+
**Command execution output** (separate from design.md content):
124+
125+
Provide brief summary in the language specified in spec.json:
126+
127+
1. **Status**: Confirm design document generated at `.sdd/specs/$1/design.md`
128+
2. **Discovery Type**: Which discovery process was executed (full/light/minimal)
129+
3. **Key Findings**: 2-3 critical insights from `research.md` that shaped the design
130+
4. **Next Action**: Approval workflow guidance (see Safety & Fallback)
131+
5. **Research Log**: Confirm `research.md` updated with latest decisions
132+
133+
**Format**: Concise Markdown (under 200 words) - this is the command output, NOT the design document itself
134+
135+
**Note**: The actual design document follows `.sdd/settings/templates/specs/design.md` structure.
136+
137+
## Safety & Fallback
138+
139+
### Error Scenarios
140+
141+
**Requirements Not Approved**:
142+
- **Stop Execution**: Cannot proceed without approved requirements
143+
- **User Message**: "Requirements not yet approved. Approval required before design generation."
144+
- **Suggested Action**: "Run `/sdd:spec-design $1 -y` to auto-approve requirements and proceed"
145+
146+
**Missing Requirements**:
147+
- **Stop Execution**: Requirements document must exist
148+
- **User Message**: "No requirements.md found at `.sdd/specs/$1/requirements.md`"
149+
- **Suggested Action**: "Run `/sdd:spec-requirements $1` to generate requirements first"
150+
151+
**Template Missing**:
152+
- **User Message**: "Template file missing at `.sdd/settings/templates/specs/design.md`"
153+
- **Suggested Action**: "Check repository setup or restore template file"
154+
- **Fallback**: Use inline basic structure with warning
155+
156+
**Steering Context Missing**:
157+
- **Warning**: "Steering directory empty or missing - design may not align with project standards"
158+
- **Proceed**: Continue with generation but note limitation in output
159+
160+
**Discovery Complexity Unclear**:
161+
- **Default**: Use full discovery process (`.sdd/settings/rules/design-discovery-full.md`)
162+
- **Rationale**: Better to over-research than miss critical context
163+
- **Invalid Requirement IDs**:
164+
- **Stop Execution**: If requirements.md is missing numeric IDs or uses non-numeric headings (for example, "Requirement A"), stop and instruct the user to fix requirements.md before continuing.
165+
166+
### Next Phase: Task Generation
167+
168+
**If Design Approved**:
169+
- Review generated design at `.sdd/specs/$1/design.md`
170+
- **Optional**: Run `/sdd:validate-design $1` for interactive quality review
171+
- Then `/sdd:spec-tasks $1 -y` to generate implementation tasks
172+
173+
**If Modifications Needed**:
174+
- Provide feedback and re-run `/sdd:spec-design $1`
175+
- Existing design used as reference (merge mode)
176+
177+
**Note**: Design approval is mandatory before proceeding to task generation.
178+
179+
think hard

‎.claude/commands/sdd/spec-impl.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
description: Execute spec tasks using TDD methodology
3+
allowed-tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS, WebFetch, WebSearch
4+
argument-hint: <feature-name> [task-numbers]
5+
---
6+
7+
# Implementation Task Executor
8+
9+
<background_information>
10+
- **Mission**: Execute implementation tasks using Test-Driven Development methodology based on approved specifications
11+
- **Success Criteria**:
12+
- All tests written before implementation code
13+
- Code passes all tests with no regressions
14+
- Tasks marked as completed in tasks.md
15+
- Implementation aligns with design and requirements
16+
</background_information>
17+
18+
<instructions>
19+
## Core Task
20+
Execute implementation tasks for feature **$1** using Test-Driven Development.
21+
22+
## Execution Steps
23+
24+
### Step 1: Load Context
25+
26+
**Read all necessary context**:
27+
- `.sdd/specs/$1/spec.json`, `requirements.md`, `design.md`, `tasks.md`
28+
- **Entire `.sdd/steering/` directory** for complete project memory
29+
30+
**Validate approvals**:
31+
- Verify tasks are approved in spec.json (stop if not, see Safety & Fallback)
32+
33+
### Step 2: Select Tasks
34+
35+
**Determine which tasks to execute**:
36+
- If `$2` provided: Execute specified task numbers (e.g., "1.1" or "1,2,3")
37+
- Otherwise: Execute all pending tasks (unchecked `- [ ]` in tasks.md)
38+
39+
### Step 3: Execute with TDD
40+
41+
For each selected task, follow Kent Beck's TDD cycle:
42+
43+
1. **RED - Write Failing Test**:
44+
- Write test for the next small piece of functionality
45+
- Test should fail (code doesn't exist yet)
46+
- Use descriptive test names
47+
48+
2. **GREEN - Write Minimal Code**:
49+
- Implement simplest solution to make test pass
50+
- Focus only on making THIS test pass
51+
- Avoid over-engineering
52+
53+
3. **REFACTOR - Clean Up**:
54+
- Improve code structure and readability
55+
- Remove duplication
56+
- Apply design patterns where appropriate
57+
- Ensure all tests still pass after refactoring
58+
59+
4. **VERIFY - Validate Quality**:
60+
- All tests pass (new and existing)
61+
- No regressions in existing functionality
62+
- Code coverage maintained or improved
63+
64+
5. **MARK COMPLETE**:
65+
- Update checkbox from `- [ ]` to `- [x]` in tasks.md
66+
67+
## Critical Constraints
68+
- **TDD Mandatory**: Tests MUST be written before implementation code
69+
- **Task Scope**: Implement only what the specific task requires
70+
- **Test Coverage**: All new code must have tests
71+
- **No Regressions**: Existing tests must continue to pass
72+
- **Design Alignment**: Implementation must follow design.md specifications
73+
</instructions>
74+
75+
## Tool Guidance
76+
- **Read first**: Load all context before implementation
77+
- **Test first**: Write tests before code
78+
- Use **WebSearch/WebFetch** for library documentation when needed
79+
80+
## Output Description
81+
82+
Provide brief summary in the language specified in spec.json:
83+
84+
1. **Tasks Executed**: Task numbers and test results
85+
2. **Status**: Completed tasks marked in tasks.md, remaining tasks count
86+
87+
**Format**: Concise (under 150 words)
88+
89+
## Safety & Fallback
90+
91+
### Error Scenarios
92+
93+
**Tasks Not Approved or Missing Spec Files**:
94+
- **Stop Execution**: All spec files must exist and tasks must be approved
95+
- **Suggested Action**: "Complete previous phases: `/sdd:spec-requirements`, `/sdd:spec-design`, `/sdd:spec-tasks`"
96+
97+
**Test Failures**:
98+
- **Stop Implementation**: Fix failing tests before continuing
99+
- **Action**: Debug and fix, then re-run
100+
101+
### Task Execution
102+
103+
**Execute specific task(s)**:
104+
- `/sdd:spec-impl $1 1.1` - Single task
105+
- `/sdd:spec-impl $1 1,2,3` - Multiple tasks
106+
107+
**Execute all pending**:
108+
- `/sdd:spec-impl $1` - All unchecked tasks
109+
110+
think

‎.claude/commands/sdd/spec-init.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
description: Initialize a new specification with detailed project description
3+
allowed-tools: Bash, Read, Write, Glob
4+
argument-hint: <project-description>
5+
---
6+
7+
# Spec Initialization
8+
9+
<background_information>
10+
- **Mission**: Initialize the first phase of spec-driven development by creating directory structure and metadata for a new specification
11+
- **Success Criteria**:
12+
- Generate appropriate feature name from project description
13+
- Create unique spec structure without conflicts
14+
- Provide clear path to next phase (requirements generation)
15+
</background_information>
16+
17+
<instructions>
18+
## Core Task
19+
Generate a unique feature name from the project description ($ARGUMENTS) and initialize the specification structure.
20+
21+
## Execution Steps
22+
1. **Check Uniqueness**: Verify `.sdd/specs/` for naming conflicts (append number suffix if needed)
23+
2. **Create Directory**: `.sdd/specs/[feature-name]/`
24+
3. **Initialize Files Using Templates**:
25+
- Read `.sdd/settings/templates/specs/init.json`
26+
- Read `.sdd/settings/templates/specs/requirements-init.md`
27+
- Replace placeholders:
28+
- `{{FEATURE_NAME}}` → generated feature name
29+
- `{{TIMESTAMP}}` → current ISO 8601 timestamp
30+
- `{{PROJECT_DESCRIPTION}}` → $ARGUMENTS
31+
- Write `spec.json` and `requirements.md` to spec directory
32+
33+
## Important Constraints
34+
- DO NOT generate requirements/design/tasks at this stage
35+
- Follow stage-by-stage development principles
36+
- Maintain strict phase separation
37+
- Only initialization is performed in this phase
38+
</instructions>
39+
40+
## Tool Guidance
41+
- Use **Glob** to check existing spec directories for name uniqueness
42+
- Use **Read** to fetch templates: `init.json` and `requirements-init.md`
43+
- Use **Write** to create spec.json and requirements.md after placeholder replacement
44+
- Perform validation before any file write operation
45+
46+
## Output Description
47+
Provide output in the language specified in `spec.json` with the following structure:
48+
49+
1. **Generated Feature Name**: `feature-name` format with 1-2 sentence rationale
50+
2. **Project Summary**: Brief summary (1 sentence)
51+
3. **Created Files**: Bullet list with full paths
52+
4. **Next Step**: Command block showing `/sdd:spec-requirements <feature-name>`
53+
5. **Notes**: Explain why only initialization was performed (2-3 sentences on phase separation)
54+
55+
**Format Requirements**:
56+
- Use Markdown headings (##, ###)
57+
- Wrap commands in code blocks
58+
- Keep total output concise (under 250 words)
59+
- Use clear, professional language per `spec.json.language`
60+
61+
## Safety & Fallback
62+
- **Ambiguous Feature Name**: If feature name generation is unclear, propose 2-3 options and ask user to select
63+
- **Template Missing**: If template files don't exist in `.sdd/settings/templates/specs/`, report error with specific missing file path and suggest checking repository setup
64+
- **Directory Conflict**: If feature name already exists, append numeric suffix (e.g., `feature-name-2`) and notify user of automatic conflict resolution
65+
- **Write Failure**: Report error with specific path and suggest checking permissions or disk space

0 commit comments

Comments
 (0)