requirement-workflow（需求工作流程）

Requirement Workflow (SDD)

Structured development orchestrator based on Spec-Driven Development: define specs first, decompose into tasks, execute with quality gates, verify against acceptance criteria.

Core principle: Spec is the single source of truth. Code follows spec, not the other way around.

Prerequisites

• Node.js >= 18
• Writable project directory for workflow state files (.trae/workflow/)

Quick Start

User says anything about building/implementing/fixing →
  1. AI classifies the request (type + size + risk)
  2. AI runs: node init.cjs -r <root> -n <name> -t <type> -s <size> -k <risk>
  3. AI fills spec.md with structured requirements (EARS format)
  4. AI decomposes spec.md into tasks.md
  5. AI implements task by task, advancing stages
  6. AI verifies against checklist.md

Working Modes

This skill supports two modes, selected based on classification:

Agent Mode (Default)

For small/tiny scope or bugfix type: skip spec phase, go straight to implementation.

INIT → IMPLEMENTING → TESTING → DONE

Spec Mode (SDD)

For medium/large scope or elevated/critical risk: full SDD lifecycle.

INIT → DEFINING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE

Classification Matrix

Size Heuristics

SDD Lifecycle

Stage 1: INIT

Classify request, initialize workflow, create artifact directory.

node init.cjs -r <project_root> -n "<name>" -t <type> -s <size> -k <risk>

Output: workflow.yaml, empty spec.md, tasks.md, checklist.md

Stage 2: DEFINING (Spec Mode only)

Fill spec.md with structured requirements using EARS format:

# Feature Name

## Background
{Why this is needed — problem statement}

## Scope
- In: {what IS included}
- Out: {what is NOT included}

## Acceptance Criteria (EARS format)
- [ ] When <condition>, the system shall <response>
- [ ] While <state>, the system shall <behavior>
- [ ] Where <constraint>, the system shall <limit>

## Constraints
- {Performance, security, compatibility requirements}

## Out of Scope
- {Explicitly deferred items}

Checkpoint: If risk is elevated/critical, pause for user review of spec.md.

Hooks: pre_stage_DEFINING → iron-audit-pm, problem-definer, risk-auditor

Stage 3: PLANNING (Spec Mode only)

Decompose spec.md into tasks.md — every acceptance criterion maps to ≥1 task:

# Tasks

## Phase 1: Foundation
- [ ] Task 1.1: {description} [files: x, y]
- [ ] Task 1.2: {description} [files: z]

## Phase 2: Core Logic
- [ ] Task 2.1: {description} [files: a, b]

## Phase 3: Integration & Polish
- [ ] Task 3.1: {description} [files: c]

## Verification
- [ ] All acceptance criteria pass
- [ ] Lint clean
- [ ] Type check pass

Rule: Each task must be atomic (completable independently) and traceable to a spec item.

Hooks: pre_stage_PLANNING → story-mapper, mvp-freeze-architect

Stage 4: DESIGNING (Spec Mode only)

Create design.md (only for medium+ size) with architecture decisions:

• Component structure
• Data flow
• API contracts
• Key trade-offs

Checkpoint: If risk is elevated/critical, pause for user review.

Hooks: pre_stage_DESIGNING → domain-modeler, architecture-advisor, responsibility-modeler

Stage 5: IMPLEMENTING

Execute tasks from tasks.md sequentially. For each task:

1. Read the task description
2. Implement the change
3. Mark task as [x] in tasks.md
4. Run relevant tests if available

Hooks: pre_stage_IMPLEMENTING → tdd-coach

Stage 6: TESTING

Run full test suite. Update checklist.md:

# Checklist

## Code Quality
- [ ] Implementation complete
- [ ] Lint clean (run lint command)
- [ ] Type check pass (run typecheck command)

## Tests
- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)

## Acceptance Criteria
- [ ] AC 1: {criterion from spec} — verified
- [ ] AC 2: {criterion from spec} — verified

## Review
- [ ] Self-review complete
- [ ] No TODO/FIXME left unresolved

Hooks: pre_stage_TESTING → test-strategy-advisor, test-strategist, code-reviewer

Stage 7: DELIVERING (Spec Mode only)

Final verification against spec.md. Ensure every acceptance criterion has been met.

Hooks: post_stage_DELIVERING → code-reviewer, tech-design-reviewer

Stage 8: DONE

Workflow complete. Summary output:

• What was delivered
• Files changed
• Tests passed
• Time elapsed

Stage Advancement

# Check current status
node status.cjs -r <project_root>

# Advance to next stage
node advance.cjs -r <project_root>

# Force advance (skip checkpoint)
node advance.cjs -r <project_root> --force

Hooks System

Hooks are agents/skills that run at stage transitions. Three scopes:

Hook Points

# List hooks
node hooks.cjs -r <project_root> list

# Add a hook
node hooks.cjs -r <project_root> add pre_stage_TESTING -n my-validator --type skill

Quality Gates

Checkpoint Rules

At checkpoints, AI pauses and asks user for confirmation before advancing.

SDD Traceability Rule

Every line of code must trace back to:

1. A task in tasks.md
2. Which traces to an acceptance criterion in spec.md

If you find yourself writing code not covered by any task — stop and update tasks.md first.

Error Handling

Scripts

Agents

See AGENTS.md for the full registry. Key agents by phase:

References

• Quick Reference - Condensed decision tables