Spec-Driven Development Based on DSPI: Design-Specify-Plan-Implement

doc/                                # Everything lives here
  DSPI_GUIDE.md                     # This guide
  architecture/                     # Project-level documentation
    architecture.md
    coding_style.md
    documentation_style.md
    tech_stack.md
    project_structure.md
  issues/                           # Per-ticket folders
    <ticket-id>/
      requirements.md
      specs.md
      arch.md
      01_task.md
      02_task.md
      ...
  .cortex/                          # Cortex Code skills
    skills/
      dspi-design/SKILL.md
      dspi-spec/SKILL.md
      dspi-plan/SKILL.md
      dspi-implement/SKILL.md

# Architecture

## Overview
<!-- One paragraph describing the system at a high level. -->

## Components
<!-- List each major component/service with a short description. -->

## Data Flow
<!-- Describe how data moves through the system. ASCII diagrams are fine. -->

## Key Decisions
<!-- Document architectural decisions and why they were made. -->

# Coding Style

## Language Conventions
<!-- Language-specific rules: naming, formatting, imports. -->

## Patterns
<!-- Preferred patterns: error handling, logging, dependency injection, etc. -->

## Anti-Patterns
<!-- Things to avoid. Be specific. -->

## Examples
<!-- Short before/after examples showing preferred style. -->

# Documentation Style

## Code Comments
<!-- When to comment, when not to. Inline vs block. -->

## Commit Messages
<!-- Format, conventions, examples. -->

## File/Module Documentation
<!-- What goes at the top of each file or module. -->

# Tech Stack

## Languages
<!-- Languages and versions. -->

## Frameworks & Libraries
<!-- Key dependencies and their purpose. -->

## Infrastructure
<!-- Databases, message queues, cloud services, CI/CD. -->

## Development Tools
<!-- Linters, formatters, test frameworks. -->

# Project Structure

## Directory Layout
<!-- Tree view of the repo with descriptions for each directory. -->

## Entry Points
<!-- Main entry points for the application. -->

## Configuration
<!-- Where config files live, how environments are managed. -->

## Tests
<!-- Test directory structure, how to run tests. -->

mkdir -p doc/issues/<ticket-id>

# Requirements: <ticket-id>

## Problem
<!-- What problem does this solve? Why does it matter? -->

## Desired Outcome
<!-- What should the system do when this is complete? -->

## Constraints
<!-- Performance, security, compatibility, scope limits. -->

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

# Architecture: <ticket-id>

## Approach
<!-- How will this be built? Which components are involved? -->

## Changes to Existing Components
<!-- What existing code/services need to change? -->

## New Components
<!-- What new code/services are introduced? -->

## Data Model Changes
<!-- Schema changes, new tables, migrations. -->

## Tradeoffs
<!-- What alternatives were considered? Why was this approach chosen? -->

# Specification: <ticket-id>

## API Contract
<!-- Endpoints, request/response schemas, status codes. -->
<!-- Or: function signatures, input/output types. -->

## Business Rules
<!-- Validation logic, conditional behavior, calculations. -->

## Edge Cases
<!-- Boundary conditions, empty states, concurrent access. -->

## Error Handling
<!-- What errors can occur? How is each handled? -->

## Security
<!-- Authentication, authorization, input sanitization. -->

# Task 01: <short description>

## Objective
<!-- What does this task accomplish? -->

## Files to Change
<!-- List specific files that need modification or creation. -->

## Steps
1. Step one
2. Step two
3. Step three

## Verification
<!-- How to confirm this task is done correctly. -->
<!-- Commands to run, tests to pass, behavior to check. -->

## Dependencies
<!-- Which other tasks must be complete before this one? -->

mkdir -p doc/.cortex/skills/dspi-design
mkdir -p doc/.cortex/skills/dspi-spec
mkdir -p doc/.cortex/skills/dspi-plan
mkdir -p doc/.cortex/skills/dspi-implement

---
name: dspi-design
description: "Design phase: read requirements, produce architecture. Triggers: design, architecture, design phase."
tools: ["bash", "read", "write", "edit", "glob", "grep"]
---

# DSPI Design Phase

## Input
- `doc/issues/<ticket-id>/requirements.md`
- `doc/architecture/architecture.md` (system context)
- `doc/architecture/tech_stack.md` (technology constraints)

## Workflow
1. Read the requirements file for the given ticket
2. Read `doc/architecture/architecture.md` and `doc/architecture/tech_stack.md` for system context
3. Explore the codebase to understand existing patterns and components involved
4. Write `doc/issues/<ticket-id>/arch.md` covering:
   - Approach and rationale
   - Changes to existing components
   - New components introduced
   - Data model changes
   - Tradeoffs considered

## Stopping Points
- After reading requirements: confirm understanding with user
- After drafting arch.md: get approval before finalizing

## Rules
- Do not write any application code in this phase
- Reference specific files and line numbers in the codebase when describing changes
- Keep the architecture document concise -- one page maximum
```

`

### doc/.cortex/skills/dspi-spec/SKILL.md

`

```markdown
---
name: dspi-spec
description: "Spec phase: read architecture, produce detailed specification. Triggers: spec, specify, specification."
tools: ["bash", "read", "write", "edit", "glob", "grep"]
---

# DSPI Spec Phase

## Input
- `doc/issues/<ticket-id>/requirements.md`
- `doc/issues/<ticket-id>/arch.md`
- `doc/architecture/coding_style.md` (style constraints)

## Workflow
1. Read the requirements and architecture for the given ticket
2. Read `doc/architecture/coding_style.md` for conventions
3. Explore the codebase for existing interfaces, types, and patterns to follow
4. Write `doc/issues/<ticket-id>/specs.md` covering:
   - API contracts or function signatures with exact types
   - Business rules and validation logic
   - Edge cases and boundary conditions
   - Error handling behavior
   - Security considerations
5. Map each acceptance criterion from requirements.md to a specific spec section

## Stopping Points
- After reading arch.md: confirm scope with user
- After drafting specs.md: review for completeness before finalizing

## Rules
- Do not write any application code in this phase
- Every acceptance criterion must be traceable to a spec section
- Be precise -- specs are the contract that implementation is verified against
- Include concrete examples for complex business rules
```

`

### doc/.cortex/skills/dspi-plan/SKILL.md

`

```markdown
---
name: dspi-plan
description: "Plan phase: read spec, produce ordered task files. Triggers: plan, tasks, break down, task breakdown."
tools: ["bash", "read", "write", "edit", "glob", "grep"]
---

# DSPI Plan Phase

## Input
- `doc/issues/<ticket-id>/specs.md`
- `doc/issues/<ticket-id>/arch.md`
- `doc/architecture/project_structure.md` (where files live)

## Workflow
1. Read the spec and architecture for the given ticket
2. Read `doc/architecture/project_structure.md` to understand repo layout
3. Explore the codebase to identify exact files and functions to change
4. Break the spec into ordered implementation tasks
5. Write task files as `doc/issues/<ticket-id>/01_task.md`, `02_task.md`, etc.
   Each task file contains:
   - Clear objective
   - Specific files to change
   - Step-by-step instructions
   - Verification criteria
   - Dependencies on other tasks

## Stopping Points
- After reading spec: confirm task granularity with user (fewer large tasks vs many small ones)
- After writing all task files: review the full plan before implementation

## Rules
- Do not write any application code in this phase
- Each task should be completable in one focused session
- Tasks must be ordered so dependencies are respected
- Every spec requirement must be covered by at least one task
- Include a verification step in every task
```

`

### doc/.cortex/skills/dspi-implement/SKILL.md

`

```markdown
---
name: dspi-implement
description: "Implement phase: execute tasks in order, verify against spec. Triggers: implement, build, code, execute tasks."
tools: ["bash", "read", "write", "edit", "glob", "grep"]
---

# DSPI Implement Phase

## Input
- `doc/issues/<ticket-id>/specs.md` (the contract)
- `doc/issues/<ticket-id>/arch.md` (the design)
- `doc/issues/<ticket-id>/*task.md` (ordered tasks)
- `doc/architecture/coding_style.md` (style rules)

## Workflow
1. Read the spec, architecture, and all task files for the given ticket
2. Read `doc/architecture/coding_style.md` for conventions
3. Create a todo list from the task files
4. For each task, in order:
   a. Read the task file
   b. Implement the changes described
   c. Run the verification steps from the task file
   d. Mark the task as complete
5. After all tasks are done:
   a. Run the full test suite
   b. Verify every acceptance criterion from requirements.md
   c. Verify implementation matches specs.md

## Stopping Points
- Before starting: confirm the task list with user
- After each task: report what was done and verification results
- After all tasks: final review against spec

## Rules
- Follow `doc/architecture/coding_style.md` strictly
- Do not deviate from the spec without explicit approval
- If a task reveals a gap in the spec, stop and flag it rather than guessing
- Run verification after every task, not just at the end
```

`

---

## 4. Workflow Walkthrough

Here is the complete flow for a single ticket.

### Step 1: Write Requirements

Create the ticket folder and write what needs to be built.

```bash
mkdir -p doc/issues/42
```

Write `doc/issues/42/requirements.md` with the problem, desired outcome, constraints, and acceptance criteria.

### Step 2: Design

Use the design skill to generate the architecture.

```shell
$dspi-design Ticket 42 -- @doc/issues/42/requirements.md
```

Cortex Code will:
- Read your requirements
- Explore the codebase
- Write `doc/issues/42/arch.md`
- Ask for your approval

Review the architecture. Edit if needed. Move on when satisfied.

### Step 3: Specify

Use the spec skill to generate the detailed specification.

```shell
$dspi-spec Ticket 42 -- @doc/issues/42/requirements.md @doc/issues/42/arch.md
```

Cortex Code will:
- Read the requirements and architecture
- Explore existing code for patterns
- Write `doc/issues/42/specs.md`
- Ask for your review

Review the spec carefully. This is the contract -- implementation will be verified against it.

### Step 4: Plan

Use the plan skill to break the spec into tasks.

```shell
$dspi-plan Ticket 42 -- @doc/issues/42/specs.md @doc/issues/42/arch.md
```

Cortex Code will:
- Read the spec and architecture
- Identify files to change
- Write `doc/issues/42/01_task.md`, `02_task.md`, etc.
- Present the full task list for approval

Review the tasks. Adjust granularity if needed.

### Step 5: Implement

Use the implement skill to execute the plan.

```shell
$dspi-implement Ticket 42 -- @doc/issues/42/specs.md @doc/issues/42/arch.md
```

Cortex Code will:
- Read all specs and task files
- Create a tracked todo list
- Implement each task in order
- Run verification after each task
- Do a final check against the spec

### Step 6: Review

After implementation, review the changes against the spec.

```plaintext
Review the changes in this session against @doc/issues/42/specs.md -- flag any deviations.
```

---

## 5. Quick Reference

### Commands

| Phase | Command |
|---|---|
| Setup ticket | `mkdir -p doc/issues/<id>` then write `requirements.md` |
| Design | `$dspi-design Ticket <id> -- @doc/issues/<id>/requirements.md` |
| Specify | `$dspi-spec Ticket <id> -- @doc/issues/<id>/requirements.md @doc/issues/<id>/arch.md` |
| Plan | `$dspi-plan Ticket <id> -- @doc/issues/<id>/specs.md @doc/issues/<id>/arch.md` |
| Implement | `$dspi-implement Ticket <id> -- @doc/issues/<id>/specs.md @doc/issues/<id>/arch.md` |

### Phase Gates

| Phase | Produces | Gate |
|---|---|---|
| Requirements | `requirements.md` | Developer/PO writes and reviews |
| Design | `arch.md` | Review architecture before proceeding |
| Specify | `specs.md` | Review spec -- this is the contract |
| Plan | `*task.md` files | Review task breakdown and ordering |
| Implement | Code changes | Verify against spec and acceptance criteria |

### File Reference for @ Context

When prompting Cortex Code, use `@` to inject relevant files:

```plaintext
@doc/architecture/architecture.md      # System-level context
@doc/architecture/coding_style.md      # Style rules
@doc/architecture/tech_stack.md        # Technology constraints
@doc/architecture/project_structure.md # Repo layout
@doc/issues/42/requirements.md         # What to build
@doc/issues/42/arch.md                 # How to build it
@doc/issues/42/specs.md                # Detailed behavior contract
@doc/issues/42/01_task.md              # Current task
```

### Key Principle

**Each phase is a gate.** Do not skip phases. Do not move forward until the current phase is reviewed and approved. The documents are the contract -- Cortex Code implements what the documents say, not what it assumes.