specs-dev

vaayne's avatarfrom vaayne

Plan-first development workflow with review gates. Use when implementing features, refactoring, or any task requiring structured planning, iterative implementation with reviews, and clean commits. Triggers on requests like "implement feature X", "plan and build", "spec-driven development", or when user wants disciplined, reviewed code changes.

⭐20stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026⬇️1downloads

When & Why to Use This Skill

The Specs-Dev Workflow skill provides a rigorous, plan-first framework for software development, ensuring high-quality outcomes through mandatory review gates and structured task management. It solves the problem of disorganized AI coding by enforcing a disciplined state machine—Discovery, Planning, Implementation, and Completion—ensuring that every code change is architecturally sound, reviewed, and validated before being committed.

Use Cases

  • Complex Feature Implementation: Use this skill when building new functionalities that span multiple files and require a clear architectural plan to ensure consistency and maintainability.
  • Large-Scale Refactoring: Ideal for restructuring legacy codebases where a 'plan-first' approach is critical to avoid breaking changes and ensure all modifications are peer-reviewed.
  • Spec-Driven Development: Perfect for projects with strict technical requirements where every implementation step must be validated against a formal specification and approved through quality gates.
  • Disciplined Team Collaboration: Enhances professional workflows by generating structured session logs, task lists, and review histories, making it easier for human developers to audit AI-generated changes.
namespecs-dev
descriptionPlan-first development workflow with review gates. Use when implementing features, refactoring, or any task requiring structured planning, iterative implementation with reviews, and clean commits. Triggers on requests like "implement feature X", "plan and build", "spec-driven development", or when user wants disciplined, reviewed code changes.

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