spec-driven-workflow-v1

name	spec-driven-workflow-v1
description	Structured six-phase software development workflow with requirements, design, tasks, and documentation artifacts. Use when starting any significant feature or refactor to ensure requirements are clearly defined, designs are planned, and implementations are validated. Phases are ANALYZE, DESIGN, IMPLEMENT, VALIDATE, REFLECT, HANDOFF. Maintains requirements.md, design.md, and tasks.md artifacts.
argument-hint	[feature or change to develop using spec-driven workflow]

Spec Driven Workflow v1

Bridge the gap between requirements and implementation using a structured six-phase loop.

Maintain these artifacts at all times:

• requirements.md — User stories and acceptance criteria in EARS notation
• design.md — Technical architecture, sequence diagrams, implementation considerations
• tasks.md — Detailed, trackable implementation plan

Execution Workflow (6-Phase Loop)

Never skip any phase. Use consistent terminology. Reduce ambiguity.

Phase 1: ANALYZE

Objective: Understand the problem, analyse the existing system, produce clear testable requirements.

• Read all provided code, documentation, tests, and logs
• Define requirements in EARS Notation: WHEN [condition], THE SYSTEM SHALL [behavior]
• Identify dependencies and constraints
• Map data flows and interactions
• Catalog edge cases and failures
• Assess confidence (0–100%) — document score and rationale

Critical Constraint: Do not proceed until all requirements are clear and documented.

Phase 2: DESIGN

Objective: Create comprehensive technical design and detailed implementation plan.

Confidence-adaptive strategy:

• >85% — Draft comprehensive plan, skip PoC, proceed with full implementation

• 66–85% — Build MVP/PoC first, validate, then expand incrementally

• <66% — Research phase first, re-run ANALYZE after, escalate if still low

• Document technical design in design.md (architecture, data flow, interfaces, data models)

• Document error handling matrix

• Define unit testing strategy

• Create implementation plan in tasks.md with description, expected outcome, and dependencies per task

Critical Constraint: Do not proceed to implementation until design and plan are complete.

Phase 3: IMPLEMENT

Objective: Write production-quality code according to the design and plan.

• Code in small, testable increments
• Implement from dependencies upward
• Follow conventions; document deviations with a Decision Record
• Add meaningful comments focused on intent ("why"), not mechanics ("what")
• Update task status in real time

Critical Constraint: Do not merge or deploy until all implementation steps are documented and tested.

Phase 4: VALIDATE

Objective: Verify implementation meets all requirements and quality standards.

• Execute automated tests; document outputs, coverage, and failure root causes
• Perform manual verification if necessary
• Test edge cases and errors
• Verify performance; profile critical sections
• Log execution traces

Critical Constraint: Do not proceed until all validation is complete and all issues resolved.

Phase 5: REFLECT

Objective: Improve codebase, update documentation, analyse performance.

• Refactor for maintainability; document before/after comparisons
• Update all project documentation (READMEs, diagrams, comments)
• Identify potential improvements and add to backlog with prioritisation
• Validate success criteria; document final verification matrix
• Auto-create technical debt issues with remediation plans

Critical Constraint: Do not close phase until all documentation and improvement actions are logged.

Phase 6: HANDOFF

Objective: Package work for review and deployment.

• Generate executive summary using Compressed Decision Record format
• Prepare pull request with: summary, changelog, validation artifact links, artifact links
• Finalise workspace; archive temporary files to .agent_work/
• Continue to next task; document transition or completion

Critical Constraint: Task is not complete until all handoff steps are finished and documented.

Documentation Templates

Action Documentation (all steps)

### [TYPE] - [ACTION] - [TIMESTAMP]
**Objective**: [Goal]
**Context**: [Current state and requirements]
**Decision**: [Approach and rationale]
**Execution**: [Steps taken with file paths]
**Output**: [Complete results and metrics]
**Validation**: [Success verification or remediation plan]
**Next**: [Automatic continuation plan]

Decision Record

### Decision - [TIMESTAMP]
**Decision**: [What was decided]
**Context**: [Situation and data]
**Options**: [Alternatives with pros/cons]
**Rationale**: [Why chosen option is superior]
**Impact**: [Consequences for implementation and maintainability]
**Review**: [Conditions or schedule for reassessment]

EARS Notation Reference

• Ubiquitous: THE SYSTEM SHALL [behavior]
• Event-driven: WHEN [trigger] THE SYSTEM SHALL [behavior]
• State-driven: WHILE [state] THE SYSTEM SHALL [behavior]
• Unwanted behavior: IF [condition] THEN THE SYSTEM SHALL [response]
• Optional feature: WHERE [feature included] THE SYSTEM SHALL [behavior]

Each requirement must be: testable, unambiguous, necessary, feasible, traceable.