xpec-flow

Scaffold a spec-driven development harness into any project, for use with Claude Code.

xpec-flow init drops in a complete, auditable, resumable workflow — a one-time /kickoff setup, then /plan → /analyze → /tasks → /implement → /review — plus a /bugfix cycle, all driven by Claude Code slash commands and skills. Every feature is born from a spec and moves through gated steps whose state lives on disk, so you can stop and resume, and every decision is recorded without re-reading conversations.

Quick start

# scaffold into the current directory
npx xpec-flow init

# or into a new folder, with a project name
npx xpec-flow init my-app --name "My App"

Then, inside Claude Code:

/kickoff               # configure the project (once) — unlocks every other command
/new-spec  <title>     # create your first numbered spec
/plan      <spec>      # start the cycle (creates the feature branch)
/xpec-status           # see where every spec stands

What gets scaffolded

.claude/
  commands/            /kickoff /plan /analyze /tasks /implement /review
                       /new-spec /xpec-status /bugfix
  skills/
    spec-branch/       deterministic spec ↔ git-branch resolution
    triage-instrucao/  triage a new product rule before it becomes code
.xpec/
  config.json          harness config + the kickoff gate flag
  docs/
    workflow.md        the canonical spec-driven flow (the harness itself)
    constitution.md    the Constitution — inviolable rules (authored by /kickoff)
    project.md         the charter — identity, architecture, stack, quality bar (authored by /kickoff)
  specs/               numbered specs + SPEC-TEMPLATE.md (source of truth for the product)
  bugs/                one file per bug (report → triage A/B/C → fix)
  progress/            per-spec state: plan/analyze/tasks/implement/review + state.json
  debts.md             conscious technical debt
CLAUDE.md              project entrypoint (created fresh, or the xpec-flow section is appended
                       if you already have one)

The flow

/kickoff ──► /plan ──► /analyze ──► /tasks ──► /implement ──► /review ──► spec CLOSED
 (once)        ▲                                                 │
               └──────── review changes-requested loops back ────┘

• Kickoff gate: nothing runs until /kickoff has configured the project (.xpec/config.json → kickoff.done). /xpec-status still runs, showing a "kickoff pending" banner.
• Step gates: each step runs only if the previous one is done in the spec's state.json.
• Branch per spec: /plan <spec> opens feature/<spec-id>; the other steps discover the spec from the current branch.
• Commit gate: steps ask to commit a clean checkpoint before doing work.
• Closure by delivery commit: an approved /review closes the spec; a rejected one hands a TODO-LIST back to /implement.

The full, canonical description lives in the generated .xpec/docs/workflow.md.

After scaffolding

The harness ships generic and locked. To make it yours, run /kickoff inside Claude Code: it interviews you (language, architecture shape, stack, quality bar, git hooks, which inviolable rules apply…) and from your answers it authors .xpec/docs/project.md, tunes .xpec/docs/constitution.md, fills the vision in CLAUDE.md, and flips the gate in .xpec/config.json. You can hand-edit any of those files afterwards — the markdown is the source of truth.

The commands read these docs to keep generated code faithful to your project's premises. If a project chooses not to use constitution.md/project.md, the commands simply skip the missing file.

CLI

npx xpec-flow init [dir] [options]

  --name <name>   Project name for CLAUDE.md and doc headers (default: dir name)
  --force         Overwrite files that already exist (default: skip them)
  --no-git        Do not run 'git init' when the target has no git repo
  --dry-run       Print what would be written without touching the disk

init never overwrites existing files unless you pass --force; it reports what it kept.

License

MIT