ABOUTME: Spec-driven development framework for ecommerce project
ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.tasks -> /spec.run
Spec-Driven Development
Iterative feature development ensuring zero ambiguity before execution.
Quick Reference
Command Purpose
/spec.plan <intent>
Create spec from feature description
/spec.refine [section]
Improve spec with research
/spec.clarify <response>
Answer clarification questions
/spec.tasks
Break spec into executable tasks
/spec.run [task#]
Execute tasks with TDD
Core Principle
Iterate until clarity: No task execution begins until ALL questions are resolved. Claude must be able to execute without interruptions.
Phase 1: /spec.plan
- Create Specification
Trigger: /spec.plan <description> or "I want to build/add X"
Workflow
-
Check specs/ folder - create if missing
-
Generate spec file: specs/{feature-slug}.md
-
Fill initial sections from user intent
-
Generate clarifying questions
-
STOP and present questions
Output
Created: specs/feature-name.md (DRAFT)
Questions requiring clarification:
- [Question about scope]
- [Question about behavior]
Use /spec.clarify to answer.
Phase 2: /spec.refine
- Research & Improve
Trigger: /spec.refine [section]
Workflow
-
Load active DRAFT spec
-
Search codebase for similar patterns
-
Update Technical Strategy
-
Re-evaluate clarity
-
If questions remain: STOP and present
Phase 3: /spec.clarify
- Answer Questions
Trigger: /spec.clarify <response>
Example
User: /spec.clarify Q1: OAuth2 with Google only. Q2: Admin can also delete.
Updated specs/auth-system.md:
- Added OAuth2/Google to Technical Strategy
- Updated permissions
Remaining questions: None Spec ready. Use /spec.tasks
Phase 4: /spec.tasks
- Task Breakdown
Trigger: /spec.tasks
Prerequisites
-
Active spec must be DRAFT or APPROVED
-
"Open Questions" section must be empty
-
If questions exist: STOP → /spec.clarify
Task Granularity
Tasks should be high-level logical units:
-
"Implement authentication middleware"
-
"Create user model and repository"
-
"Add API endpoints for user CRUD"
TDD cycle happens WITHIN each task during /spec.run .
Phase 5: /spec.run
- Execute Tasks
Trigger: /spec.run [task#]
Prerequisites
-
Task file must exist: specs/{feature}.tasks.md
-
If no task file: STOP → /spec.tasks
Execution Rules
-
TDD for each task: Red → Green → Refactor → Commit
-
Invoke language skills: /typescript for .ts files
-
Respect hooks: Pre-commit must pass
-
Mark completed in task file
File Structure
specs/ ├── README.md # Project config ├── user-wishlist.md # Spec (APPROVED) ├── user-wishlist.tasks.md # Task breakdown ├── payment-stripe.md # Spec (DRAFT) └── ...
Spec Status Flow
DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED | | v v (questions?) (blocked?) | | v v DRAFT IN_PROGRESS
Ecommerce-Specific Scopes
When creating specs, consider these modules:
Module Files Considerations
Auth apps/backend/src/modules/auth/
JWT, sessions, rate limits
Catalog apps/backend/src/modules/catalog/
Redis caching
Cart Frontend hooks + Backend Session persistence
Orders apps/backend/src/modules/orders/
Transactions
Checkout apps/frontend/src/app/checkout/
Payment flow
Templates
See references/templates.md for:
-
Spec file template
-
Task file template
-
specs/README.md template
Session Resume
On context compaction:
-
Check specs/ for files with status IN_PROGRESS
-
Check .tasks.md files for unchecked items
-
Report: "Found in-progress spec: X with Y tasks remaining"
-
Ask: "Continue with /spec.run?"