spec-driven-auto

Prerequisites

.spec-driven/

ls .spec-driven/

/spec-driven-init

Steps

1. Assess complexity — before doing anything, evaluate the change using a three-tier model:
   • Read

     .spec-driven/config.yaml

     for project context
   • Read

     .spec-driven/specs/INDEX.md

     and relevant spec files to understand the current system
   • Read the codebase files that the change will likely touch — estimate the number of files, modules, and cross-cutting concerns involved
   • Classify the change into one of three tiers:
     • Green (proceed): touches ≤ 6 modules or packages, modifies ≤ 20 files, clear scope, straightforward schema migrations (add column, create table, simple backfill), additive auth/authz/payment changes (e.g., adding a new role or permission) — proceed without additional confirmation beyond the standard proposal checkpoint
     • Yellow (warn and ask): touches 7-15 modules or packages, modifies 21-50 files, schema migrations involving data transformation, auth/authz/payment changes that modify existing logic, cross-cutting changes touching multiple subsystems — show the user the specific risk factors and require explicit confirmation before proceeding
     • Red (suggest brainstorm): requires coordinating across multiple services or repositories, scope is vague or open-ended (e.g. "refactor the codebase", "improve performance"), no clear definition of done — explain why and suggest running

       /spec-driven-brainstorm

       first to converge the idea, then entering

       /spec-driven-auto

       to execute the resulting proposal
   • If the change spans multiple tiers (e.g., module count is Green but file count is Yellow), use the highest applicable tier
   • If Red, stop and suggest brainstorm
   • If Yellow, list the risk factors and wait for the user to confirm before proceeding
   • If Green, proceed
2. Propose — run

   /spec-driven-propose

   :
   • Run

     node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>

   • Fill all artifacts: proposal.md (with Unchanged Behavior), specs/ delta files, design.md, tasks.md (with ## Testing), questions.md (open questions)
   • Show the user a summary: scope, key decisions, task count, unchanged behaviors, and any open questions
   • Wait for explicit confirmation before proceeding — this is the only mandatory checkpoint
   • If questions.md has open questions, list them and ask the user to resolve them before confirming
   • If the user requests changes, apply them and re-confirm
3. Apply — implement all tasks:
   • Run

     node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>

     to show task summary
   • Check questions.md for open

     - [ ] Q:

     entries — if any, ask the user and resolve before continuing
   • Work through each

     - [ ]

     task in order: read code, implement, verify Unchanged Behavior, mark

     - [x]

   • For

     ## Testing

     tasks: actually run the tests and confirm they pass
   • Run

     node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>

     to confirm

     remaining === 0

4. Verify — check completeness:
   • Run

     node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>

   • Then perform the rest of the

     /spec-driven-verify

     checks: task completion, open questions, implementation evidence, and spec alignment
   • Treat script

     errors

     plus any CRITICAL findings from those checks as blockers
   • If there are blockers you can safely fix, fix them automatically, then rerun both the script check and the verification pass
   • If any blocker cannot be auto-fixed: stop and ask the user
   • Re-read delta spec files and update them to match what was actually implemented
5. Review — check code quality:
   • Read every file changed by this change
   • Check: readability, security, error handling, performance, best practices, test quality
   • MUST FIX issues: fix them automatically, then re-review
   • If MUST FIX issues cannot be auto-fixed: stop and ask the user
   • SHOULD FIX and NITS: fix if straightforward, otherwise note in the final report
6. Archive — close out the change:
   • Confirm there are no incomplete tasks before archiving
   • List all delta files in

     specs/

     and merge each into the corresponding main spec file
   • If

     changes/<name>/specs/

     is empty, ask the user to confirm this change has no observable spec impact before continuing
   • Update

     .spec-driven/specs/INDEX.md

     if new spec files were created
   • Run

     node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>

   • Report the final result: what was built, files changed, tests passing

Rules

• The complexity check in Step 1 is mandatory — never skip it
• The user confirmation in Step 2 is mandatory — never skip it
• Additional confirmations are required whenever the workflow is blocked by unresolved questions or an empty delta-spec archive decision
• All other steps run automatically unless blocked by an unresolvable issue
• Follow all config.yaml rules (specs, change, code, test) throughout
• If anything goes wrong mid-flow, stop and explain — do not silently continue
• Mark tasks complete one at a time, not in bulk