spec-workflow

name	spec-workflow
description	SDD specification protocol: risk-based spec_mode classification, required sections per mode, plan approval gate, and artifact directory conventions.

Spec Workflow — SDD Specification Protocol

Rules governing when a Software Design Document (SDD) spec is required, what sections it must contain, and how it gates the transition from Plan to Build.

Risk-Based spec_mode Classification

Every planned feature is assigned a spec_mode based on change risk. The Plan agent determines this value and records it in specs/<feature-id>/plan.md YAML frontmatter.

spec_mode	When to use
full	Security changes, schema changes, integration work, features touching more than 2 files
lightweight	Features touching 1–2 files, non-critical changes
none	Bug fixes (non-security), docs-only changes, trivial or cosmetic changes

When in doubt, escalate to the next higher mode. Under-speccing a risky change costs more than over-speccing a safe one.

Required Spec Sections per Mode

full

All sections from spec-template.md are required, plus a tasks.md task breakdown:

• User Scenarios
• Requirements
• Constraints / What NOT to Build
• Key Entities
• Success Criteria
• tasks.md — discrete, bounded build tasks derived from the spec

lightweight

Only two sections are required in spec.md:

• Requirements
• Constraints

none

No spec.md is required. The Plan agent writes only plan.md.

Plan Approval Gate Protocol

What the Plan Agent Writes

The Plan agent always writes specs/<feature-id>/plan.md regardless of spec_mode. The file must include YAML frontmatter with at minimum:

---
feature_id: <feature-id>
spec_mode: full | lightweight | none
status: draft | approved
origin:
  # at least one of: issue, urls, transcripts — OR the explicit
  # internal/unrecoverable exemption. See origin-confirmation skill.
  issue: <repo>#<number>
  urls:
    - <external-reference-url>
  transcripts:
    - specs/<feature-id>/origin/<date>-<slug>.md
  origin_claim: |
    One paragraph in the user's words quoting their original ask.
---

The origin: block is required by scripts/validate-spec.sh and the origin-confirmation gate. See shared/skills/origin-confirmation/SKILL.md for the full convention, the three escape hatches (type: internal, type: unrecoverable), and the alignment-check protocol.

Approval Flow by spec_mode

full or lightweight:

1. Plan agent writes plan.md and spec.md (with required sections populated).
2. All [NEEDS CLARIFICATION] markers in spec.md are resolved via user questions before writing.
3. User reviews and approves both plan.md and spec.md.
4. Build may not start until both are approved.

none:

1. Plan agent writes plan.md only.
2. User reviews and approves plan.md directly.
3. Build proceeds without a spec gate.

Build Agent Behavior

• The Build agent reads specs/<id>/plan.md frontmatter to determine spec_mode.
• For full or lightweight: Build agent checks that spec.md exists and contains no unresolved [NEEDS CLARIFICATION] markers before proceeding.
• If unresolved markers are found, Build agent stops and surfaces them to the user. It does not proceed.

[NEEDS CLARIFICATION] Resolution Rules

• All [NEEDS CLARIFICATION] markers in spec.md must be resolved before Build starts.
• The Plan agent is responsible for resolving these via clarifying questions with the user during the Plan phase.
• Markers may not be carried forward into Build as "TBD" items — they represent missing information that will block implementation.
• The Build agent refuses to proceed if any [NEEDS CLARIFICATION] markers remain in spec.md.

Example marker (must not appear in an approved spec):

[NEEDS CLARIFICATION]: Should this endpoint require authentication?

Spec Artifacts Directory Convention

All SDD artifacts for a feature live under specs/<feature-id>/.

Artifact	Written for	Description
plan.md	all modes	Plan with spec_mode frontmatter and high-level approach
spec.md	full and lightweight	Software design document with required sections
tasks.md	full only	Discrete, bounded build tasks for delegation
collaboration/plan-consult.md	when CCT_PEER_REVIEW_ENABLED=true	Advisory plan review artifact (see review-loop.md)
collaboration/build-review.md	when CCT_PEER_REVIEW_ENABLED=true	Build review artifact — PASS or approved bypass required (see review-loop.md)

The specs/ directory should be committed to the repository so the Plan and Build phases can operate across session boundaries.