Specs-Dev Workflow

A disciplined, review-gated development workflow ensuring quality through structured planning and iterative implementation.

When to Use

• Implementing new features
• Complex refactoring
• Any task requiring planning before coding
• When user requests "plan first" or "spec-driven" approach
• Multi-file changes that benefit from review gates

Workflow Overview

| Phase | Purpose | Exit Criteria | | ----------------- | ----------------------------- | ---------------------------- | | 1. Discovery | Understand requirements | User approves summary | | 2. Planning | Create reviewed plan | Plan reviewed and approved | | 3. Implementation | Iterative coding with reviews | All tasks complete, reviewed | | 4. Completion | Final validation | Tests pass, docs updated |

Phase 1: Discovery

Goal: Reach shared understanding before planning.

1. Interpret the request — state initial understanding
2. Ask clarifying questions (goals, constraints, success criteria, out-of-scope)
3. Iterate — reflect answers, tighten understanding
4. Summarize — present final requirements

Gate A: "Do I understand correctly? Should I proceed to create the plan?" — Wait for approval.

Phase 2: Planning

Goal: Create a comprehensive, reviewed implementation plan.

1. Draft plan using references/templates/plan.md
2. Review loop with reviewer (max 3 rounds) — see references/agents/reviewer.md
3. Integrate feedback, iterate until approved
4. Gate B: Present to user, wait for approval
5. Create session: .agents/sessions/{YYYY-MM-DD}-{feature-name}/
6. Save plan.md and tasks.md (use references/templates/)

Quality gates: see references/gates.md

Phase 3: Implementation

Goal: Implement tasks iteratively with approval-gated review loops.

> ⚠️ MANDATORY: You MUST follow references/loop.md — Read and execute the implementation loop exactly as specified. Do not skip or deviate from the defined state machine.

Summary: For each task:

IMPLEMENTING → VALIDATING → REVIEWING → loop until approved → COMMITTING → DOCUMENTING → NEXT TASK

Required Steps:

1. Read references/loop.md before starting any implementation
2. Follow the state machine transitions exactly
3. Complete each state's requirements before transitioning
4. Max 3 iterations per task before escalating to user
5. Subagents: references/agents/worker.md, references/agents/reviewer.md

Quality gates: see references/gates.md

Phase 4: Completion

Goal: Final validation and wrap-up.

1. Run full test suite
2. Update plan.md with results, final status, known issues
3. Verify all tasks complete in tasks.md
4. Summarize completed work, risks, outcomes
5. Confirm with user — session ready for merge/release

Quality gates: see references/gates.md

Subagent Delegation

Reviewer — Plan reviews, code reviews:

Context: references/agents/reviewer.md
Task: Review [plan/code] for completeness, security, performance, patterns

Worker — Focused implementation:

Context: references/agents/worker.md
Task: Implement [objective] in [files] with [acceptance criteria]

Session Structure

.agents/sessions/{YYYY-MM-DD}-{feature-name}/
├── plan.md      # Strategic plan
└── tasks.md     # Tactical tasks

References

references/
├── loop.md          # Phase 3 state machine, steps, fix routing
├── gates.md         # Quality gates for all phases
├── help.md          # Common issues, best practices
├── agents/
│   ├── reviewer.md  # Reviewer subagent context
│   └── worker.md    # Worker subagent context
└── templates/
    ├── plan.md      # Plan document template
    └── tasks.md     # Tasks document template

| File | When to Read | | -------------------- | --------------------------------- | | loop.md | Phase 3 (MANDATORY — must follow) | | agents/reviewer.md | Plan/code reviews | | agents/worker.md | Task implementation | | templates/plan.md | Phase 2 | | templates/tasks.md | Phase 2 | | gates.md | Each phase exit | | help.md | When stuck |