project-spine-kickoff

name	project-spine-kickoff
description	Use when the user wants to set up Project Spine for a new project — phrases like "new client project", "kickoff", "create AGENTS.md from scratch", "generate agent instructions for this repo", "set up project context". Runs `spine init` → edits brief → `spine compile` → reviews outputs. For stale files use project-spine-drift.

Kickoff flow for a new project

Goal: produce the 21 canonical Project Spine files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/project-spine.mdc, plus scaffold/QA/rationale docs) from a real brief + the current repo.

Prerequisites — check before proceeding

1. CLI installed: spine --version returns 0.9.2-beta.0 or later
2. Current directory is the project root (has package.json or equivalent)
3. No .project-spine/ directory yet (if there is, this is probably a drift scenario — switch to project-spine-drift)

Step 1 — pick a template (optional but strongly recommended)

List available starter templates:

spine template list

Bundled templates cover these project types:

• saas-marketing — marketing site (hero, pricing, customer pages, compliance)
• app-dashboard — authenticated product with data tables, settings, role gating
• design-system — component library, tokens, Storybook
• docs-portal — technical documentation site
• api-service — Node / TypeScript API service with health and readiness probes
• monorepo — pnpm / Turborepo / Nx workspace guidance

If the user mentions one of these project types, pick the matching template. If they describe something unusual (extension, CLI tool, data pipeline), skip the template and compile without it — the brief carries the intent.

Step 2 — scaffold

spine init --template <template-name>
# or, without a template:
spine init

This creates:

• brief.md at the repo root, with prompts for each section (Goals, Audience, Constraints, Assumptions, Risks, Success criteria)
• .project-spine/ directory for outputs

Step 3 — ask the user for brief content

Do not fill the brief yourself from general knowledge. Ask the user directly:

I scaffolded a brief at brief.md. To generate useful agent instructions I need your help filling a few sections. Could you tell me:

1. What are the 3–5 core goals for this project? (measurable, not aspirational)
2. Who is the audience? (role, scale, prior tools)
3. Any hard constraints? (stack, compliance, budget)
4. What's out of scope that you want agents to not touch?

I'll fill the rest from the repo analysis.

Edit brief.md with their answers. Preserve the YAML frontmatter including projectType.

Step 4 — compile

spine compile --brief ./brief.md --repo . --template <template-name>

(Omit --template if you skipped Step 1.)

If the user has a design-tokens export from Figma or Tokens Studio, pass it in too — tokens are merged into the design rules so agents know the brand palette and spacing scale:

spine compile --brief ./brief.md --repo . --tokens ./tokens.json

The parser auto-detects DTCG ($value/$type) and Tokens Studio (value/type) formats. Aliases like {color.primary} resolve across the file. See spine compile --help for all input flags.

Step 5 — read the output summary

The compile prints a summary. The three things that matter:

• hash: ... — content-addressable signature of the inputs. Useful later for drift.
• project type: ... — should match what the user said.
• warnings: N (E error, W warn, I info) — always surface these to the user.

If there are warnings, show them and offer to resolve. Call spine explain <warning-id> to get the fix for each.

Step 6 — review key outputs with the user

Show these files to the user and summarise (don't dump):

• AGENTS.md at the repo root — "this is what other coding agents will see. Key rules it derived from your brief + repo: [3–5 bullets]"
• .project-spine/exports/scaffold-plan.md — "here's the proposed route/component plan for sprint 1"
• .project-spine/exports/sprint-1-backlog.md — "starter backlog items with acceptance criteria traced back to your goals"

Ask: "Does this match what you had in mind? Anything worth editing in brief.md and recompiling?"

Common follow-ups

• "The stack is wrong" → spine inspect --repo . to see what was detected; edit repo state (add framework dep) or pass explicit --template, then recompile.
• "I want to commit these files" → The repo-root AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and .cursor/rules/project-spine.mdc are the canonical tool-discovery locations. Commit them. Gitignore .project-spine/ internals if desired.
• "How do I share this with my team?" → Save a project-local template with spine template save --location project, or use your normal VCS flow.
• "How do I send a client-facing version?" → Switch to project-spine-rationale skill to review the generated .project-spine/exports/rationale.md locally.

What NOT to do

• Do NOT edit the generated AGENTS.md / CLAUDE.md by hand. Edit brief.md and recompile. Hand-edits trigger drift warnings and defeat the source-of-truth model.
• Do NOT compile without a brief that actually describes the project. Generic briefs produce generic AGENTS.md which is exactly what Project Spine exists to prevent.
• Do NOT run spine compile twice without a reason. It's idempotent, but needless recompiles churn the timestamps in the export manifest.