specs-dev_skill

Overview

This skill implements a plan-first, review-gated development workflow for disciplined TypeScript projects. It guides discovery, produces a reviewed implementation plan, executes iterative task loops with mandatory review gates, and finalizes with tests and documentation. Use it to ensure clean commits, traceable sessions, and predictable quality outcomes.

How this skill works

The skill drives four phases: Discovery (requirements and clarifying questions), Planning (produce plan.md and tasks.md and run reviewer loops), Implementation (task-by-task state machine with mandatory loop rules), and Completion (tests, docs, and final summary). It enforces explicit approval gates before moving between phases and requires following the implementation loop exactly as specified. Sessions are stored in a dated folder structure so work is reproducible and auditable.

When to use it

• Implementing a new feature that needs structured design and reviews
• Complex refactors that must be planned and validated incrementally
• Any task where you want a ‘plan first’ or spec-driven approach
• Multi-file or cross-module changes that benefit from gated reviews
• When you need clear session artifacts (plan.md, tasks.md) for handoff or audit

Best practices

• Start with a focused Discovery: ask goals, constraints, success criteria, and out-of-scope items
• Keep planning review loops short (max 3 rounds) and record feedback in the plan
• Always read and follow the implementation loop before coding to avoid state machine violations
• Limit per-task iterations to three before escalating to the user
• Run the full test suite and update plan.md and tasks.md before closing the session

Example use cases

• Add a new API endpoint with schema changes and client updates — plan, review, implement, test, document
• Refactor a core module across multiple files with incremental reviewed commits
• Implement a cross-cutting performance improvement that requires coordinated changes
• Onboard a second developer: use session artifacts to transfer context and task ownership