kryptonite

Kryptonite — Spec-Driven Development

Turn ideas into structured specs and implementation plans through user-story gathering, party definition, and technical scoping. Produces a branded HTML spec, a story-grouped implementation plan with parallel execution waves, and tracks every story's state from definition through completion.

In this document, <skill-path> resolves to the directory containing this SKILL.md at runtime.

References — load when relevant

Don't read these upfront. Pull each in when its phase or task arrives.

When	File
Starting a workflow / resume detection	references/storage-protocol.md
Writing or validating any story	references/story-schema.json
Phase 8 mocks or cross-repo split	references/mocks-and-cross-repo.md
Phase 9 schema gate; before any phase advance	references/phase-gates.md
Phase 10 spec generation, comments, amendments	references/spec-versioning.md
Phase 12 execution loop	references/execution-protocol.md + agents/orchestrator.md
State transitions or commit rules	references/state-machine.md

When NOT to use

• One-off scripts or throwaway snippets where there are no users or parties.
• Bug fixes inside an existing project that already has a spec.
• Tasks where the user has explicit, line-level instructions and just needs them executed.
• Live infrastructure / production incident response.

If the user is in one of these cases, don't run the workflow — just do the task.

Compressed run

When the user pushes back ("just prototype it", "I'm in a hurry", "skip the phases"), don't silently capitulate and don't refuse — surface the tradeoff and offer a compressed run. The shape:

• Collapse Phases 1–3 into one turn. Ask for description + stories together; do gap analysis inline with best-guesses the user can correct in one pass instead of one-at-a-time probing.
• Skip Phase 5 (spikes) if the user names no unknowns. Note it explicitly so they can override.
• Skip Phase 8 mocks if there's no UI surface, or accept ASCII/sketch-level mocks.
• Keep DOD validation, schema gate, and Phase 12 wave gates intact. These are the parts that make the difference between "a plan" and "a prototype that demonstrably works" — compressing them removes the value of running kryptonite at all.

Tell the user what you're collapsing and why. If they want to also drop the gates, that's their call, but it's a different request — say so and let them confirm before you start.

Why phases run in order

Each phase narrows ambiguity the next one depends on:

• Stories you skip clarifying in Phase 3 become acceptance criteria nobody can verify in Phase 8.
• Spike findings from Phase 5 reshape the story list — writing DODs first means redoing them.
• A spec generated before mocks are approved misrepresents what the user actually wants.
• A plan generated before DODs exist can't tell what "done" looks like.

Skipping ahead to code is the most common way kryptonite projects fail — agents implement the wrong thing because the right thing was never specified.

Phases at a glance

1. General description
2. User-story braindump
3. Gap analysis & clarification
4. Party definition
5. Spikes
6. Re-scope from spike findings
7. Technical guidance + repo registration 7.5. Repo conventions preflight
8. DOD & mocks
9. Schema validation gate
10. Spec generation + Spec Critic
11. Implementation plan + Plan Critic
12. Wave-gate execution

The visual companion is available throughout Phases 1–9 (see "Visual Companion" below).

Agent architecture

Phases 1–11 run in the main session following agents/interviewer.md (multi-turn user interaction can't be delegated). Phase 12 dispatches subagents under the Orchestrator (agents/orchestrator.md). Communication is hub-and-spoke — agents never talk to each other directly.

Agent	Prompt	Dispatched when
Designer	agents/designer.md	Phase 8 visual stories
Researcher	agents/researcher.md	Phase 5 spikes; fix-loop attempt 2
Coder	agents/coder.md	Phase A of every wave
Wave UAT	agents/wave-uat-agent.md	Phase B of every wave
Wave UX	agents/wave-ux-agent.md	Phase B of every wave
Wave Spec Compliance	agents/wave-spec-compliance-agent.md	Phase B of every wave
Wave Code Review	agents/wave-code-review-agent.md	Phase B of every wave
Spec Critic	agents/spec-critic.md	After Phase 10
Plan Critic	agents/plan-critic.md	After Phase 11

---

Phase 1: General Description

"Describe what you want to build — the problem it solves, who it's for, and roughly what it should do. Don't worry about details yet, just the big picture."

Listen. Don't ask follow-ups yet. Acknowledge and transition to stories.

Phase 2: User-Story Braindump

"Now let's capture user stories. Tell me everything you can think of — who needs to do what, and why. Any format works. Say 'done' when finished."

Accumulate silently. Parse each story for actor, action, motivation. After the first 2–3 stories, show the format once ("As a [actor], I want to [action] so that [reason]"). Don't nag.

Phase 3: Gap Analysis & Clarification

Always thorough regardless of project size — better to over-clarify than ship a broken spec.

1. Present understanding. Show stories grouped by actor with your interpretation of how the system works.
2. Identify gaps. Look for missing error/edge cases, incomplete flows, ambiguous scope, missing actors, security/auth boundaries, untracked state transitions, dangling data, missing notification flows, missing deletion/archival, bulk operations implied by single-item stories.
3. Probe gaps one at a time. Propose your best guess; let the user confirm or correct. Don't dump 15 questions.
4. Record each resolution as it happens. Confirmed decisions land in epic.json.decisions[] as ADRs (ADR-001, ADR-002, …); unresolved gaps land in epic.json.open_questions[] as OQs. Don't accumulate them in chat — they're load-bearing inputs to Phase 10 (the spec generator lifts them verbatim into spec.json). Schema in references/epic-schema.json.

If new stories emerge mid-phase, integrate them and re-check for gaps. New scope (entirely new concepts) is not a gap — acknowledge it, update the story list, then re-assess existing stories against the new context.

Phase 4: Party Definition

Extract all unique actors. Present your best guess per party: who they are, what distinguishes them, permission/access boundaries, human vs. system vs. external, how they're authenticated. Don't move on until the user confirms.

Phase 5: Spikes

Spike when a technical choice hasn't been made, a complex domain needs investigation, performance/feasibility is uncertain, or a visual approach needs exploration.

1. Present identified spikes for confirmation.
2. Dispatch Researcher agents in parallel.
3. Surface findings to the user.

Findings live at <skill-path>/data/{PROJECT}/{EPIC}/spikes/<spike-id>-<topic>.md.

Phase 6: Re-scope

After spikes return:

1. Present findings + implications.
2. Scope check: if findings expand scope, ask the user whether to include all of it, trim, or defer.
3. Add/modify/remove stories. Re-check for new gaps. Update parties if new actors emerged.
4. Confirm final story list.
5. Append every scope delta to epic.json.scope_history[] (trigger + added/removed/modified/deferred). The current state always lives in state.json; this is the change log so Phase 10 can show how scope evolved and resume can explain why the story list looks the way it does.

Never let spikes silently explode the story count — the user decides scope.

Phase 7: Technical Guidance

Ask one at a time, skipping anything already known. Each answer lands in a named slot under epic.json.technical_context (full schema in references/epic-schema.json):

1. Repos — if <skill-path>/data/{PROJECT}/repos.json exists, list the registered repos and ask which apply to this epic / whether to add new ones. For adding, updating, or removing repos, hand off to the repos skill (it owns the auto-detection, schema validation, and prompts) rather than gathering fields inline. The on-disk shape is defined by references/repos-schema.json.
2. Architectural patterns → technical_context.patterns.{honor,avoid}.
3. Existing infrastructure to integrate with → technical_context.infrastructure.{integrate_with,do_not_integrate,gating}.
4. Testing approach → technical_context.testing.{backend,frontend,e2e}.
5. Non-functional requirements (performance, concurrency, reliability, observability, security, accessibility, browser support, cost, i18n) → technical_context.non_functional.*.

The Phase 7 gate (on 0.6.0+ epics) requires at least one of testing / non_functional / infrastructure / patterns to be populated — small projects may legitimately not cover all four.

Repos are project-level, shared across all epics. Stories reference them by name. Wave-gate agents resolve ${APP_URL} per-repo from repos.json[].testing.app_url.

Phase 7.5: Repo Conventions Preflight

For each repo this epic uses, populate repos.json[].conventions by reading the repo — not by asking the user. Phase 7.5 exists because pre-0.7.0 epics regularly burned dozens of agent runs on wrong assumptions about app-root, test runner, or directory layout. Verified facts cost minutes here and save days later.

Required slots (full schema in references/repos-schema.json):

Slot	How to populate
app_root	Read WORKDIR from Dockerfile; or the service's working_dir in docker-compose.yml. If neither exists and the app runs locally, set to ".".
test_runner.{backend,frontend,e2e}	For each surface that exists: detect the runner (Gemfile → rspec/minitest, package.json scripts.test → jest/vitest/playwright, pytest.ini / pyproject.toml → pytest, go.mod → go test). Record name, exact invocation (with flags), and config_path. Don't guess — if you can't find it, ask the user once.
directory_layout	Run a directory scan for the artifact types this project uses (resolvers, mutations, models, workers, components, locales, …). Only record keys whose paths actually exist. Don't seed unused keys with null.
assertion_shapes	Optional, but high-value when the project has consistent patterns (e.g. GraphQL auth-failure shape differs between resolvers and mutations). Capture by reading 2–3 existing examples in the repo and recording the verified shape.
schema_introspection_command	The command that dumps a non-empty schema artifact. A naive dump can produce an empty file (some stacks gate field visibility by scope/warden). Verify it emits content before recording it.
compile_gate_command	The dev-server-safe compile/typecheck command. A full production build can fail against a running dev-server container (busy output volume) — record the safe equivalent.
test_db_setup	The command that provisions/migrates the shared test DB to a populated state. Some repos bootstrap via migrations on a prebuilt structure, not schema:load. The orchestrator runs this once per wave.
test_data_gotchas	Project-specific factory/test-data traps (e.g. "create(:owner) twice collapses into one account"). Fed to every Coder so N parallel coders don't each rediscover the same trap.
grep_gotchas	Where a "grep for token X" DOD check would false-match prose/comments — record the precise anchored pattern instead.
verified_at	ISO timestamp of the verification you just performed.

The core principle: DOD validation commands authored in Phase 8 encode environment assumptions, and those assumptions must be verified against the live repo HERE — not discovered at gate time. Every environment-dependent command class belongs in conventions, verified by running it (or reading the repo), so Phase 8 authoring and Phase 12 coders reference a checked fact instead of guessing. The recurring failure: an agent writes a plausible command (pnpm build, a naive schema dump, a bare bundle exec rspec, grep skip_policy!) that's wrong in this repo, and it isn't caught until a wave gate fails on it across many stories at once.

If the repos skill (skills/repos) is involved (add a repo or update repo), it auto-detects defaults and asks you to confirm. If a repo is already registered without conventions, run Phase 7.5 against it now.

The Phase 7.5 gate (scripts/phase-gates/07_5.json on 0.7.0+ epics) requires every repo referenced by stories in this epic to have a populated conventions block — at minimum app_root, one test_runner entry, and a non-empty directory_layout. This gate runs before Phase 8 advances.

The DOD authoring step (Phase 8) and Coder dispatch (Phase 12) both read conventions directly. Don't restate the values in stories — reference them.

Phase 8: DOD & Mocks

Write the Definition of Done per story; produce mocks for visual stories. Every DOD item must be automatable: curl, chrome_mcp, test_suite, or file_exists (per references/story-schema.json). If a proposed DOD item can't be verified by one of those, rewrite it — vague items like "looks good" or "works correctly" do not ship.

Cover the affordance, not just the API. When a story's i_want asks the user to mutate something (assign, add, create, edit, delete, toggle, set, …), the ACs and DODs must cover the user-facing control that performs it — not only that the data persists or renders. A story that ships "the API accepts labels + chips render + a label filter works" but has no control to assign a label is incomplete. For every mutation verb, author (a) an acceptance criterion describing the control (a button/dropdown/picker/field the user interacts with) and (b) a test_suite DOD asserting that control's handler calls the mutating API (e.g. a component test that fires the onChange/onClick and checks the API call + resulting render). A curl-only DOD proves the endpoint, not the affordance. The Phase 9 gate enforces this (it flags a mutation-verb story lacking an affordance AC + a test_suite/chrome_mcp DOD), so authoring it correctly here avoids a gate failure. Read-only verbs (filter, sort, search, view) are exempt — they need no mutation control.

Three things happen in this phase. Load references/mocks-and-cross-repo.md for the full two-phase protocol on the first two:

• Mocks (two-phase: foundational sequential, detail parallel; foundational approval locks design direction and populates epic.json.design_direction.shell_summary — see references/epic-schema.json). For every visual story (has_mock:true), the compare loop is mandatory and gate-enforced (0.15.0+):

  1. Generate 3 option files — mocks/{id}-option-a.html, -option-b.html, -option-c.html (foundational: explore visual DNA across all three; detail: vary the content area only, reuse the locked shell verbatim).
  2. Fire the compare UI — POST the gallery, give the user the /mocks URL, and STOP for their pick. Do not self-select.
  3. Read the selection from /api/selections — never assume it.
  4. Record mock_options: ["a","b","c"], mock_choice, mock_path; copy the chosen option to mocks/{id}.html.
  5. Only then set mock_approved: true.

  A single mock, or mock_approved:true without a compare-driven choice, fails the Phase 8 gate on 0.15.0+ epics (mock_options ≥ 3 + a mock_choice that names a real option whose approved file is on disk). On 0.6.0+ epics the gate also requires shell_summary populated whenever design_direction.locked === true.

• Cross-repo auto-split (if a story touches multiple repos, split into US-005a / US-005b along repo boundaries with explicit dependencies).

• DOD + priority/dependencies/complexity per story.

Phase 9: Schema Validation Gate

Validate every story against references/story-schema.json before generating the spec. Run node <skill-path>/scripts/validate-gate.js (see references/phase-gates.md) — exit code 0 is required to advance.

Phase 10: Spec Generation

Generate the spec once, after all earlier phases are done. Premature generation produces specs that miss spike findings, mock approvals, or DOD details.

1. Initialize epic directory + state.json (see references/storage-protocol.md).
2. Generate branded HTML spec (spec.html); start the comment server on port 3847; tell the user the URL.
3. Dispatch the Spec Critic. If NEEDS_REVISION, fix critical issues and regenerate before showing the user.
4. Versioning, comment resolution, and mid-execution amendments all flow through references/spec-versioning.md.

Phase 11: Implementation Plan

Group stories into waves respecting hard rules (a story's deps must all be in earlier waves) and soft criteria (cohesion, testability, parallelizability, incremental value).

1. Write wave assignments to state.json ({ id, name, stories, parallel_groups, status }).
2. Dispatch the Plan Critic. If NEEDS_REVISION, fix conflicts/ordering/infrastructure gaps and regenerate.
3. Render plan.html, serve at /plan, wait for user approval.

Phase 12: Execution

Drive the loop from references/execution-protocol.md and agents/orchestrator.md — that pair is the authority for preconditions, the per-wave Phase A / Phase B sequence, the adaptive fix-loop strategies, service lifecycle, and the pass/blocked criteria. Don't restate those rules here; they drift.

Dispatch path (opt-in accelerator). If the Workflow tool is available (ultracode / Workflow-enabled sessions), run Phase 12 by invoking the shipped workflow skills/kryptonite/workflows/phase12.js with args = { epicDataDir: <the active epic's data dir> } — it runs the wave-gate loop with deterministic parallel fan-out and hands back (sets wave.status="blocked") if a wave can't complete cleanly, at which point you resume in-session. If the Workflow tool is not available, run the in-session orchestrator exactly as described below — that is the default and the fallback. The rules (references/execution-protocol.md) are identical for both paths; only the dispatch mechanism differs.

In short: each wave first runs a Phase A0 preflight (verify the test harness / infra this wave's gates + DODs need is functional, BEFORE any coder is dispatched — fail fast on a blocked service / DB / Chrome MCP), then runs Coders in parallel worktrees (Phase A), merges, then runs the four wave gates in parallel (Phase B). All four gates must pass for stories to flip to done. A blocked preflight or gate pauses for the user — the fix loop only addresses code defects.

Tools:

• scripts/worktree-manager.js — create/remove worktrees + branches, merge with conflict handling.
• scripts/service-runner.js — start/stop services per repos.json[].testing.
• scripts/validate-wave-gate-report.js — schema-validate every gate report before trusting it.
• scripts/validate-wave-preflight.js — schema-validate the Phase A0 preflight result before trusting it.

---

Visual Companion

Available throughout Phases 1–9. Offer when a question would benefit from showing alternatives visually (architecture, data flows, wireframes, comparisons). Skip for text-answerable questions.

"This might be easier to show than describe — want me to open a visual companion in your browser?"

Mechanics: write HTML fragments, serve at /visual on the comment server. If the server isn't running yet, start in visual-only mode:

node <skill-path>/scripts/comment-server.js --visual-only --port 3847

Phase gates are hard gates

Before incrementing current_phase in epic.json:

node <skill-path>/scripts/validate-gate.js --phase <N> --data-path <epic-dir>

Exit 0 advances. Exit 1: read errors, fix, re-run. Never increment current_phase without a passing gate. Full validator behavior in references/phase-gates.md.

---

Discipline

The pressure to skip phases or fudge gates always sounds reasonable in the moment. The table below pairs the rationalization with what actually happens — read it when you feel the urge to cut a corner.

Rationalization	What's actually true
"User said 'just prototype it' — skip the phases."	Surface the tradeoff and offer a compressed run; let the user choose. Silently capitulating builds the wrong thing faster.
"This DOD says 'works correctly' — close enough."	A DOD that can't be validated by curl / chrome_mcp / test_suite / file_exists is not a DOD. Rewrite it with the user or drop it.
"Chrome MCP is down but I can read the source — UAT passes."	UAT must report blocked, not pass. A single false pass poisons trust in every later gate. See references/execution-protocol.md.
"Just dispatch the coders — I'll find out at the gates if the service/DB/Chrome MCP is broken."	Run the Phase A0 preflight FIRST. Discovering a dead service or unprovisioned DB at Phase B wastes the entire Phase A coding effort. A0 verifies the harness on current main (it does NOT verify the wave's code); a blocker failure is infrastructure-class — pause, don't fix-loop, stories stay pending. See references/execution-protocol.md → "Wave preflight checklist".
"The element's in the DOM, so the feature works."	DOM presence ≠ visible-and-usable. A passing journey needs a final-state screenshot you looked at and an observed claim that matches the pixels; an input must be in the viewport, a link must resolve, a state change must render. A blocking overlay or degraded render is blocked, not pass. See references/wave-gate-report-schema.json preconditions + the gate agents.
"The mock looks polished, the impl looks like a wireframe, but it 'matches'."	match requires a metric fingerprint within tolerance of the mock (color richness, typography, depth, WCAG contrast) AND an independent reviewer that saw ONLY the two screenshots — eyeballing your own render is not a visual gate. And the Coder must be GIVEN the mock: the A1 dispatch ships story.mock_path (HTML + screenshot + tokens) so the build targets the mock, not AC prose. See scripts/visual-fingerprint.js, agents/wave-visual-reviewer.md, and agents/wave-ux-agent.md.
"I'll just show one polished mock and move on — three options is overkill here."	The compare loop is gate-enforced from 0.15.0: a has_mock:true story needs mock_options ≥ 3 AND a recorded mock_choice that names a real option whose approved file is on disk. A single mock — or mock_approved:true without a compare-driven pick — fails the Phase 8 gate. Generate 3 options, fire /mocks, wait for the pick, record it. See references/mocks-and-cross-repo.md.
"Splitting this cross-repo story is annoying."	The orchestrator can't resolve one working directory for a multi-repo story. The split is mechanical, not optional.
"I'll mark stories done as soon as they merge."	A story is merged, not done, until its wave is complete. State machine invariant — see references/state-machine.md.
"Phase gate validator is complaining about a tiny field — I'll just bump current_phase."	The gates exist because LLM perception drifts from actual state. Fix the field, re-run, advance.
"I have enough context to skip Phase 3 / Phase 5 / mocks."	Each phase narrows ambiguity the next one depends on. Skipping moves the cost forward, doesn't remove it.
"User keeps adding stories mid-Phase 3."	New stories ≠ gaps. Integrate them, re-assess existing stories against the new context, continue.
"This decision/scope-delta/NFR doesn't fit the schema — I'll write a gap_analysis.md / rescope.md / technical_guidance.md sidecar."	If it's load-bearing for Phase 10/11, it belongs in epic.json (decisions[], scope_history[], technical_context, design_direction.shell_summary — schema in references/epic-schema.json). Sidecars are invisible to the spec generator and are lost on resume. The recurring urge to add a sidecar means the schema needs a new field — propose it, don't sidestep.
"I'll stash what this wave taught me in state.deferred_findings / a notes field / the handoff prompt."	Phase-12 discoveries belong in epic.json.findings[] (schema in references/epic-schema.json; capture/curation in references/execution-protocol.md). state.json is sliced for dispatch and is the wrong home; a growing handoff prompt is the symptom this field exists to cure. Durable repo facts get promoted into repos.json conventions.

Conversational stance

These are about how the interview feels to the user, not about correctness gates:

• One question at a time. Never batch — it overwhelms and fragments answers.
• Accumulate then analyze. Let the user dump freely in Phase 2; probe in Phase 3.
• Guess then confirm. Always propose your best understanding instead of asking from scratch.
• Comments drive revision. The HTML spec is a living document during review — don't argue, integrate.
• Self-contained. Don't reach for other plugins to do core kryptonite work.