Quickstart

The lightest path through the method: a hotfix-class item, from install to the handoff card. Feature-class ceremony comes later, when you want it; below trivial size, the honest answer is printed in METHOD.md — don't use the workflow.

1. Install and scaffold

npm install -D provegate
npx gate init

gate init creates the artifact tree (_prds/, _readiness/, _tasks/, _docs/ with wip/completed/deferred states), the state and locks directories, and two starter configs (workflow.config.json, gates.manifest.json). It never overwrites anything — re-run it any time.

Check the result:

npx gate status

2. Write the spec (Phase 1)

Create the item — id allocation, template, dates all handled:

npx gate new fix-login-timeout --class=hotfix

That writes _prds/wip/prd-001-fix-login-timeout.md from the shipped template. Fill the hotfix skeleton: the repro in §1, one or two FRs with **Targets:** paths, the smallest §11 table that proves the fix — the failing command that now passes, plus your test command. Replace the example ## Conflict Surface globs with the paths you will actually touch, then claim them:

npx gate open PRD-001

Overlap with another active claim refuses here — at claim time, not merge time. Keep Autonomous Close: operator-gated until you trust the gates. Then lint it:

npx gate check PRD-001

Fix what it reports. This is the same lint the runner trusts — a PRD that passes here is executable by an agent.

3. Score and plan (Phases 2–3)

Paste node_modules/provegate/prompts/phase-2-readiness-scorer.md into your agent with the PRD. Hotfix class: Migration is waived, the deny-path hard cap still bites if you touched anything guarded. You want PASS (≥ 8, no caps tripped) — the verdict is binary; don't negotiate tenths.

Then prompts/phase-3-task-generator.md → the task file (repro → fix → verify → doc → quality gate skeleton), saved to _tasks/wip/tasks-001-fix-login-timeout.md. You approve the plan. That's the last human gate before the machines take over.

4. Implement and prove (Phases 4–7)

Your agent follows prompts/phase-4-implementation.md on a feature branch: fix, inline gates after every step, the regression test written next to the fix. Phase 5 is prompts/phase-5-testing.md: run every §11 command for real — a listed-but-not-run command is never passed. Phase 6: an agent that did not write the code reviews the diff (prompts/phase-6-final-auditing.md) and saves the verdict artifact from templates/review-template.md. Phase 7: update the docs your PRD declared.

5. Close (the runner)

npx gate run --dry-run PRD-001   # see the whole plan first
npx gate run PRD-001

The runner executes the gate chain — floor gates, your §11 commands (safety-checked), the review-artifact schema, the durable-docs diff check, the operator gate — then archives the artifacts and merges the branch into your local base with post-merge verification and auto-revert. It ends with a handoff card whose last line is the whole philosophy:

→ READY TO PUSH — run `git push` yourself (the runner never pushes)

The practices layer (optional, recommended)

npx gate init --practices

--practices is the recommended install. It adds the agent bootstrap and artifact templates plus scripts/verify/ — the checks that hold the artifacts to what they claim. Without them you get the lifecycle and no one auditing it. Plain gate init remains available for a repository that wants only the tree.

What the pack wires, and what it leaves to you: --practices writes a gates.manifest.json with the Phase 7 memory validator already in it, and that is the only thing it wires. Everything else is a printed manual step — the package.json scripts to add, the CI job to run them in, and the agent-entry shims to paste. That list is NEXT_STEPS.md, printed at the end of the install and kept in the package. Editing your package.json and your CI config is not something a scaffold should do without you.

Single-package repos

gate is repo-layout-agnostic — a monorepo is not required. "Workspace" means your git repo root, and gate init scaffolds only the workflow tree (_prds/, _tasks/, …); it never creates apps//packages/ or a pnpm-workspace.yaml. The one thing to configure is which gate commands run — and nothing assumes pnpm or turbo.

What gate init leaves you depends on which mode you ran, and the two differ in a way worth knowing: --practices writes { "phases": { "7": [ … ] } } — phases."4" is absent, and an absent key inherits the built-in floor (pnpm check-types, lint, build, test), so Phase 4 already runs. Plain gate init writes { "phases": { "4": [] }, "postMerge": [] }, and an empty array erases rather than inherits, so no floor command runs at all.

Either way, write your own commands in once your script names are known — phases."4" is the floor the run executes, postMerge runs after the local merge:

{
  "phases": {
    "4": ["npm run check-types", "npm run lint", "npm run test", "npm run build"]
  },
  "postMerge": ["npm run check-types", "npm run build"]
}

The commands are plain strings, so any allowlisted invocation works — npm, npx, yarn, bun, node, tsx, vitest. A direct toolchain via npx is fine (npx tsc --noEmit, npx eslint ., npx vitest run); bare tsc/eslint are not allowlisted by default — use npx … or add the prefix to commands.allowedPrefixes. gate check --wiring confirms every gate is wired or excepted.

Where to go next

• METHOD.md — the method spec (classes, gates, locks, deferral governance)
• prompts/PLACEHOLDERS.md — adapt the prompts to your project
• gates.manifest.json — add your own gates (examples/ shows two patterns)
• gate check --wiring — keeps every gate you add wired or honestly excepted