xantham-spec-kit-bridge - SKILL.md Agent Skill

name: xantham-spec-kit-bridge description: Use BEFORE dispatching @kai on a greenfield build (no existing code) with estimated budget >4 hours. Walks GitHub spec-kit's constitution -> spec -> plan -> tasks -> analyze pipeline first, so kai gets file-based artifacts with cross-artifact consistency checks rather than a fuzzy brief. Skip for bug fixes, ops work, refactors, brownfield modifications, or any task under 4 hours of estimated work. Pinned to spec-kit v0.8.8.dev0. compatibility: "Claude Code only" metadata: pattern: 1 pattern_name: "Sequential workflow orchestration" last_updated: 2026-05-10

Spec-kit bridge

This skill turns a Xantham brief into spec-kit artifacts before kai dispatch.

When this fires

Trigger conditions (all three must be true):

Greenfield: no existing code in the target repo. Empty repo, new Xcode project, fresh Next.js app, etc. NOT a feature on an existing codebase.
Budget >4 hours estimated total. Below 4h the spec-kit overhead (25 to 45 min) is more than the savings.
Xantham-orchestrated: triggered by ship <project> for a greenfield, OR explicit spec-kit init <project>, OR Xantham decides during brainstorming.

Skip conditions (any one is enough):

Bug fix, hotfix, or ops work
Refactor of existing code
Brownfield modification (existing codebase, new feature)
Quick (<4h) build
Task where the spec is expected to change mid-build (the pipeline is rigid)
Followup work to an already-spec-kit'd project (work continues from existing artifacts; do not re-run the chain)

Prerequisites

Spec-kit must be installed once on this machine:

uv tool install specify-cli==0.8.8.dev0 --from git+https://github.com/github/spec-kit.git
specify --version  # confirm 0.8.8.dev0
specify check      # confirm Claude Code, git, python 3.11+ all present

Pin to v0.8.8.dev0 to avoid silent breaking changes from upstream. Re-pin only when a new version has been pilot-tested through this same skill.

Pipeline

For each greenfield build the skill walks 6 ordered phases. Xantham drives this in foreground (sub-agents do not have access to the speckit-* skills).

Phase 1 - Init (~2 min)

Decide the project directory. For confirmed-name projects, this is the project repo root. For naming-still-open projects (like quit-vape was), pilot in Library/projects/<slug>-spec-kit/ until the name is picked, then move artifacts into the real repo.
From the chosen dir: specify init --here --integration claude --skip-tls. This creates .specify/ (templates + memory + scripts), .claude/skills/speckit-*/ (14 skills), and CLAUDE.md stub. Do NOT run specify init --here from the Xantham root - it will create a CLAUDE.md in the wrong place. Confirm cwd before running.
Add .specify/ and .claude/skills/speckit-*/ to the project's .gitignore if they should not ship; alternatively commit them so they survive across sessions.

Phase 2 - Constitution (~5 min)

Distill the brief's non-negotiables into 3 to 5 named principles. Each principle gets:

A name
A 1 to 2 paragraph statement
Whether it is NON-NEGOTIABLE or guideline-strength
A worked example of what compliance looks like

Write to .specify/memory/constitution.md. Examples in the quit-vape pilot at Library/projects/quit-vape-spec-kit/constitution.md:

I. Honest Vocabulary (NON-NEGOTIABLE) - never claim cessation cures, distinguish active drug from metabolite
II. Tracker, Not Therapy
III. Single Surface = Lock Screen
IV. Streak Is The Sunk-Cost Asset
V. Privacy By Storage Locality

Phase 3 - Spec (~10 min)

Read .specify/templates/spec-template.md to understand required sections. Then write specs/001-<slug>/spec.md containing:

User scenarios as priority-ordered MVP slices. Each story (P1 / P2 / P3 etc) must be independently testable - if you ship only that one, you have a viable MVP.
Acceptance scenarios in Given/When/Then form, 2 to 3 per user story.
Edge cases named explicitly. Pull from the brief but also from analogous shipped products and known failure modes.
Functional requirements numbered FR-001 through FR-NNN with MUST or MUST be able to verb discipline. Each FR must be testable.
Key entities if the feature involves persisted data.
Success criteria SC-001 through SC-NNN. Each MUST be measurable, technology-agnostic, and verifiable. Examples: "users complete onboarding in under 90s" (good); "API responds in 200ms" (bad - too technical, use "users see results instantly").
Assumptions section listing reasonable defaults for anything underspecified.
NEEDS CLARIFICATION markers capped at 3 maximum, prioritised scope > security > UX > tech.

Phase 4 - Plan (~5 min)

Read .specify/templates/plan-template.md. Write specs/001-<slug>/plan.md containing:

Summary: one-paragraph technical approach
Technical Context: language version, primary deps, storage, testing framework, target platform, project type, performance goals, constraints, scale
Constitution Check: a table mapping each constitution principle to plan compliance. Verdict: PASS / FAIL / PARTIAL with notes.
Project Structure: documentation tree + source tree as concrete file paths (no placeholder names)
Cross-cutting decisions: math model, persistence, notifications, etc. - whatever the project needs.
Phase plan: Phase 0 research, Phase 1 design, Phase 2 tasks (deferred to next phase), Phase 3 implementation.
Complexity tracking: only fill if there are constitution violations that must be justified.

Phase 5 - Tasks (~10 min)

Break the plan into atomic tasks. Each task:

Has a T-XYZ-NN identifier
Names which user story and acceptance scenarios it serves
Names which functional requirements it satisfies
Names dependencies on other tasks
Has a "Done when" exit criterion
Has an estimate

Group by phase (Research, Design, Implementation P1, Implementation P2+, App Store / deploy readiness). Sum estimates and surface any mismatch with the brief budget.

Phase 6 - Analyze (~5 min)

Cross-artifact consistency check. Walk:

Constitution alignment: every principle traces through spec, plan, tasks. Table of PASS / FAIL.
FR coverage: every FR-XXX has at least one task. Orphans are blockers.
User story coverage: every story has tasks satisfying every acceptance scenario.
SC verifiability: every SC is verifiable. Post-launch metrics are fine; un-verifiable claims are not.
Issues: list every gap, with HIGH / MEDIUM / LOW severity and a resolution proposal.
Verdict: READY FOR IMPLEMENTATION pending issue resolutions, OR BLOCKED with named blockers.

Write to specs/001-<slug>/analyze.md.

After /analyze passes

Once the analyze pass returns READY FOR IMPLEMENTATION (or all blockers resolved):

Promote the artifacts to the project repo's source-of-truth location (move out of Library/projects/<slug>-spec-kit/ into <project-repo>/specs/).
Xantham dispatches @kai with the artifacts as context. Brief becomes historical input; artifacts are authoritative.
Track which user stories @kai has implemented vs which remain open in tasks.md.

Failure modes to avoid

Running specify init --here from the Xantham root. This creates a CLAUDE.md stub at <orchestrator-repo-root>/CLAUDE.md and overwrites Xantham's actual CLAUDE.md. Always cd into the target dir first and confirm cwd.
Walking the chain on a brownfield task. Spec-kit's constitution-first model assumes the project's rules can be written from scratch. On an existing codebase the constitution is already encoded in the code; spec-kit will produce a clean-room constitution that contradicts the actual code conventions.
Skipping /analyze. The cross-artifact consistency gate is the single biggest value-add. Skipping it puts you in the same position as ad-hoc planning.
Mid-build spec changes. Spec-kit is rigid. If the spec changes after /analyze, re-run /clarify -> /plan -> /tasks -> /analyze rather than ad-hoc patching artifacts.

Pilot evidence

The quit-vape v1 pilot ran 2026-05-10 and surfaced 5 real issues the council-derived brief had missed: budget mismatch (24.5h vs 16-20h promised), naming as a hard blocker not a soft note, SC-008 non-verifiability under the privacy constitution, tip-jar with no acceptance scenario, brain-recovery citation hand-waving. Two of those (budget + naming) are blockers that would have hit mid-build. Full pilot report: data/research/2026-05-10-spec-kit-pilot-evaluation.md.

Out of scope for this skill

Bug fixes (use systematic-debugging skill).
Brownfield feature work (use writing-plans + xantham-orchestration habit 1).
Trivial builds <4h (use brainstorming + plan-first inline).
Mid-build spec changes (re-run the chain rather than patching).