Abstract
DSPI (Design → Specify → Plan → Implement) is a phased workflow for software development with AI coding agents like Claude Code and Snowflake Cortex Code. Instead of throwing a ticket description at an agent and hoping for the best, you break the work into four gated phases --- each producing a markdown document that becomes the contract for the next phase. The result is a structured paper trail of architecture decisions, behavioral specs, and implementation tasks that the agent follows step by step. This guide walks you through the folder structure, the document templates for each phase, and the custom slash commands that tie it all together.
Table of Contents
1. Project Setup
Before starting any tickets, set up the project-level documentation. These files are written once and updated as the project evolves. They provide context that Cortex Code reads when working on any ticket.
Folder Structure
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
doc/architecture/architecture.md
High-level system architecture. Cortex Code reads this to understand how components fit together.
# 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. -->
doc/architecture/coding_style.md
Coding conventions the team follows. Cortex Code uses this to generate code that matches your style.
# 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. -->
doc/architecture/documentation_style.md
How to write documentation, comments, and commit messages.
# 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. -->
doc/architecture/tech_stack.md
Technologies used and why.
# 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. -->
doc/architecture/project_structure.md
Map of the repository so Cortex Code knows where things live.
# 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. -->
2. Per-Ticket Workflow
Every ticket gets its own folder under doc/issues/. The folder is named after the ticket ID (e.g., doc/issues/42/, doc/issues/AUTH-123/). Each file in the folder corresponds to a DSPI phase.
Create the ticket folder
mkdir -p doc/issues/<ticket-id>
doc/issues/<ticket-id>/requirements.md
Phase: before Design. Captures what needs to be built and why. Written by the developer or product owner. This is the input to the Design phase.
# 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
doc/issues/<ticket-id>/arch.md
Phase: Design. Ticket-level architecture. How this specific feature fits into the system. References doc/architecture/architecture.md for the big picture.
# 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? -->
doc/issues/<ticket-id>/specs.md
Phase: Specify. Detailed, unambiguous specification of behavior. This is the contract -- implementation must match the spec.
# 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. -->
doc/issues/<ticket-id>/*task.md
Phase: Plan. Individual implementation tasks, numbered for ordering. Each task is small enough to complete in one focused session. These are the steps Cortex Code executes.
Name them 01_task.md, 02_task.md, etc.
# 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? -->
3. Cortex Code Skills
These skills automate each DSPI phase. Install them by creating the files under doc/.cortex/skills/ in your repo.
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
doc/.cortex/skills/dspi-design/SKILL.md
---
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.
Top comments (0)