running-spec-dev

running-spec-dev — Spec-driven development

Replicates, in Claude Code, the claude-quickstarts/autonomous-coding flow: the spec.xml (rich contract) feeds a trackable tasks.json, which is the durable source of truth of the development loop. The harness task tools (TaskCreate/TaskUpdate/TaskList) are the live mirror of the session; the tasks.json is the persistent state across sessions.

Role split: spec.xml = the what (rich, stable). tasks.json = the state of doing (mutable, trackable). Never edit spec.xml during the loop.

Phase 1 — Init (idempotent)

1. Locate the spec. Use the path given by the user or search under specs/. If there are several, ask which one.
2. Validate first:

   python "${CLAUDE_PLUGIN_ROOT}/skills/writing-specs/scripts/validate_spec.py" specs/<slug>/spec.xml
   

   Don't proceed until it exits with code 0.
3. Derive / resume tasks.json (in specs/<slug>/tasks.json):
   • Missing → derive it from <implementation_steps>: one task per item in <tasks> (or per <step> for coarser granularity). blockedBy default = the previous step's tasks. Fill files/acceptance from <context> and <success_criteria>. Schema and example in references/tasks_schema.json.
   • Present → resume from it; it's the source of truth. Don't recreate or renumber existing tasks.
4. Git branch. Make sure you're on a feat/<slug> or fix/<slug> branch (per the spec's type). Create it if needed. Don't commit unless the user asks.
5. Mirror into the harness. For each task not yet completed, create the task (TaskCreate) and reproduce dependencies with addBlockedBy per the blockedBy in tasks.json.

Phase 2 — Development loop

On resume (anti-regression). If the session starts with tasks already completed, before picking up new work re-validate the acceptance of 1–2 of the most recently completed ones (the most central to functionality). If any fails, move it back to in_progress and fix it before advancing — the previous session may have introduced a regression.

Repeat until there's no pending/in_progress task:

1. Select. TaskList → lowest unblocked id (all blockedBy are completed). TaskGet for the full context.
2. Mark start. TaskUpdate status=in_progress.
3. Implement. Make the task's edits. Keep to the task's scope.
4. Validate (feedback loop). Run the applicable check — project tests, python main_nova.py (smoke), or checking the task's acceptance. If it fails, stay on the task (don't mark completed); fix and re-validate.
5. Complete. Only when it passes: TaskUpdate status=completed and update the corresponding status in tasks.json. Keep both sides in sync.
6. Next. Go back to step 1.

When the queue is empty, summarize: completed tasks, validations run, and what's still open (<open_questions> from the spec that are still relevant).

Rules

• Never mark completed with a failing test, partial implementation, or unresolved error.
• If a task turns out larger than expected, create subtasks (TaskCreate + addBlockedBy) and record them in tasks.json too.
• Parallelization (optional): for independent tasks, you may delegate to subagents via the Agent tool, using owner to claim the task. Use it only when the user asks or the gain is clear — the default is the sequential loop.
• Commits/push only when the user requests.