sdd-v

Methodology for AI-assisted feature development: plan what to build, ensure the agent can verify its work, then execute with self-proving loops.

Principles

• Spec-first: Requirements → design → tasks, with human review between each.
• Control audit/build is separate from run: Inventory and repair verification infrastructure before feature execution; don't hide that work inside implementation tasks.
• Control surface as precondition: CLI probes, test harnesses, and health checks are infrastructure — build them before features, maintain over time.
• Every task proves itself: Concrete Verify: command on each task. Not "check it works."
• Task state must be explicit: Plan artifacts must support resumable execution without relying on chat history.
• Behavior changes need behavioral proof: Structural checks are not enough for routing, auth, integration, or user-visible behavior.
• Schema changes require trust gates: Migration parity and live-environment freshness must be proven before claiming runtime success.
• Untested code is dead code: No verification path = not done.
• Preflight fast-fails: Check environment before execution. Don't waste work.

Workflow Selection

| User intent | Reference | |---|---| | Plan / design / spec a feature | references/plan.md | | Audit the control surface | references/control.md | | Build missing verification infrastructure | references/control.md | | Execute / implement approved tasks | references/run.md | | Quick fix (< 3 files, no migrations, reversible) | Fast-track below |

If intent is unclear, ask: "Are you planning, auditing control surface, building verification tooling, or ready to execute approved tasks?"

Artifacts

.specdev/
├── control-surface.md            # Project-wide proof catalog and recipe index
└── specs/<feature-name>/
    ├── requirements.md           # EARS-format requirements
    ├── design.md                 # Architecture and interfaces
    ├── tasks.md                  # Stateful execution plan
    └── verification.md           # Optional proof matrix for runtime-heavy features

Task Format

All tasks.md files use this structure. This is the contract between plan and run.

# Tasks: [Feature Name]

## Preconditions
- [ ] `<check command>` — <what it proves>

## Control Surface
| Action | Command |
|--------|---------|
| <what to observe> | `<command>` |

## Tasks

### 1.1 [Short description]
- **Status**: `todo`
- **Requirements**: R1, R2
- **Proof Class**: `structural` | `automated-behavioral` | `runtime` | `migration`
- **Action**: What to change
- **Context**: Files to read (minimal — only what this task needs)
- **Verify**: `<command>` → <expected result>
- **Evidence**: `_pending_`
- **Handover**: No

Rules:

• Task headings are the canonical task identifiers; do not convert them into checkbox bullets during execution
• Every task MUST have Status, Requirements, Proof Class, Verify, and Evidence
• Status starts as todo; the run workflow may update it to in_progress, completed, or blocked
• Every task MUST have Verify: with a runnable command and expected outcome
• structural proof is only for shape checks such as generated symbols, file presence, or static schema shape
• Tasks that change behavior, auth, routing, or integrations MUST use automated-behavioral, runtime, or migration proof and cannot close on search-based evidence alone
• migration proof MUST include schema-parity and live-environment trust checks when runtime behavior depends on the changed schema
• Preconditions are checked by the run workflow's preflight, not manually
• Control Surface is a per-feature subset of .specdev/control-surface.md, not a place to invent missing probes during run mode
• Tasks are atomic: ~5-15 min of agent work each
• Use verification.md when the feature needs a happy-path, negative-path, and corner-path proof matrix or lengthy runtime recipes

Handover Protocol

When a task requires human intervention (Handover: Yes), stop and output:

HANDOVER REQUIRED

Task: [description]
Prepared: [what's ready]
Risk: [why human needed]
Action: [specific instruction]

Reply "approved" to continue.

Triggers: destructive data ops, external system changes, visual/UX decisions, security changes, irreversible actions.

Fast-Track

All conditions must be true: < 3 files, no migrations, no new dependencies, no runtime proof requirement, reversible.

1. Implement the change
2. Verify via CLI/tests
3. Report pass/fail

If routing, auth, integrations, schema changes, or live-environment trust are involved, do not fast-track; use the full plan → control → run flow.