Spec-Driven Development (SDD)

Core Workflow Mandate

You must strictly execute your work following a four-phase model. You are forbidden from progressing to a later phase until the Human-in-the-Loop (HITL) has formally reviewed and signed off on the current phase's artifact.

• Phase 1: Specify (Produce/Update requirements.md)
• Phase 2: Plan (Produce/Update plan.md)
• Phase 3: Task Breakdown (Produce/Update tasks.md)
• Phase 4: Implement & Verify (Code execution and validation)

Phase-by-Phase Instructions

Phase 1: Specify

When given a feature request, your only objective is to define the "what" and "why". Do not touch application code or choose libraries.

1. Read the global workspace documentation (e.g., docs/ARCHITECTURE.md, docs/CONVENTIONS.md).
2. Generate or update a requirements.md file within the feature's directory.
3. Your output must strictly contain:
   • Summary and business/user context.
   • Exact user journeys and scope boundaries (explicitly state what is OUT of scope).
   • Testable, direct, unambiguous Acceptance Criteria using absolute terms (e.g., "must select", "must throw error code X") instead of soft language ("should", "prioritize").
4. Stop and await human validation.

Phase 2: Plan

Once the human approves the requirements, you must translate the "what" into the technical "how".

1. Update or generate the plan.md file.
2. Outline the exact data models, API contracts, schemas, and structural dependencies required.
3. Explicitly state the technology choices, test frameworks, and error handling rules.
4. Stop and await human validation.

Phase 3: Task Breakdown

Once the technical plan is approved, you must decompose it into micro-tasks.

1. Update or generate the tasks.md file.
2. Break the plan down into highly granular, atomic, and independent steps.
3. Every single task must include a checkbox [ ] and a clear, deterministic verification step (e.g., "Run command: npm test path/to/file.test.ts").
4. Stop and await human validation.

Phase 4: Implement and Verify

Once the task list is validated, you may begin modifying the codebase.

1. Execute tasks sequentially, one at a time. Do not multi-task.
2. For each task, write the code, then immediately run the corresponding verification step (compilation check, unit test, or linter).
3. If a test fails, you must debug and iterate within that specific task's scope before moving forward.
4. Once verified, mark the task checkbox as complete [x].

General Behavior & Guardrails

• Code Style: Prioritize looking for existing code patterns and snippets in the codebase over generating generalized boilerplate. Follow naming conventions and formatting rules precisely.
• Commands: Always issue explicit, full executable terminal commands (e.g., vp test, vp run web#dev) instead of suggesting vague actions.
• Context Preservation: Maintain references to exact file paths and line numbers in your spec documentation rather than writing vague component descriptions.
• Zero Guessing: If an implementation detail, edge case, or integration path is ambiguous or undocumented, you must stop and prompt the user for clarification.