@baldurpan/create-ai-workflow 0.4.1 → 0.5.1

package/README.md

@@ -7,7 +7,7 @@
 npx @baldurpan/create-ai-workflow      # or: npm create @baldurpan/ai-workflow
 ```
 
-You get a backlog, plan documents with phase ledgers, two verification gates, and seven commands that
+You get a backlog, plan documents with phase ledgers, two verification gates, and eight commands that
 move work between them. Your coding agent runs the commands; you read and hand-edit the files.
 
 ---
@@ -39,6 +39,7 @@ starting point — nothing has to be looked up first.
 | `/feature-status` | read-only. Reconciles the ledger against the repo, then names **exactly one** next action |
 | `/feature-close` | retires a feature: a `history.md` row, a `git mv` into `archive/`, and a reviewed reference sweep |
 | `/orchestrate` | one ad-hoc, commit-sized change through the same gates — no entry, no ledger |
+| `/prototype` | a throwaway HTML/CSS mockup under `prototypes/`, to settle a layout question before a plan commits to it — no gates, no application code |
 | `/onboard` | fills in your own stubs, adopting what the repo already documented and running each verification command before writing it down |
 
 ## What makes it different
@@ -57,6 +58,11 @@ test commands. No skill, agent prompt or role file carries a copy — a hardcode
 project changes shape, and a second copy rots faster. `/onboard` **runs each candidate and writes only the
 ones that exit 0.**
 
+**Nothing commits unless you said it could.** `context/git.md` holds one answer — the user commits, or
+the agent does — and every command that lands code reads it before closing out. It ships saying *the user
+commits*: a tool installed into a repository it knows nothing about does not get to write that
+repository's history unasked. Branches, pushes and pull requests are outside the workflow entirely.
+
 **A finding outlives the session that found it.** A reviewer `FAIL` or a capped gate is written to
 `context/findings.md` *before* the loopback, so it survives the conversation ending. An open `P0`/`P1`
 blocks its phase from being marked `done` and blocks `/feature-close`.
@@ -66,11 +72,11 @@ blocks its phase from being marked `done` and blocks `/feature-close`.
 ```
 context/
   README.md  workflow.md  plan-template.md  plan-template.notes.md  roles/  standards/     tool-owned
-  stack.md  verify.md  executors.md  roadmap.md  history.md  findings.md                   yours
+  stack.md  verify.md  executors.md  git.md  roadmap.md  history.md  findings.md           yours
   drafts/  plans/  archive/                                                                yours
   .state/manifest.json
-.claude/skills/<seven>/SKILL.md   .claude/agents/*.agent.md                                tool-owned
-.agents/skills/<seven>/SKILL.md   the same seven bodies, for hosts that read that tree       tool-owned
+.claude/skills/<eight>/SKILL.md   .claude/agents/*.agent.md                                tool-owned
+.agents/skills/<eight>/SKILL.md   the same eight bodies, for hosts that read that tree       tool-owned
 AGENTS.md   a delimited block, merged into whatever is already there
 CLAUDE.md   a single @AGENTS.md line, and only when the file does not exist
 ```
@@ -79,7 +85,7 @@ Nothing is committed. Review the diff yourself.
 
 **Onto a repository that already documents itself**, the installer only appends — your existing
 `AGENTS.md` prose is left exactly where it is. `/onboard` reconciles the two afterwards: it classifies
-each existing claim into `stack.md`, `verify.md` or `executors.md`, asks wherever a destination is
+each existing claim into `stack.md`, `verify.md`, `git.md` or `executors.md`, asks wherever a destination is
 unclear or the old text contradicts the installed workflow, and prunes the source only once the
 replacement is written and shown.
 
@@ -140,7 +146,7 @@ positive points at the document that is out of step.
 ## Scope
 
 **Both skill trees ship.** Claude Code reads `.claude/skills/`; Codex reads `.agents/skills/` and never
-looks at the other one. They get the same seven bodies — the only difference is one frontmatter line,
+looks at the other one. They get the same eight bodies — the only difference is one frontmatter line,
 `disable-model-invocation: true`, which is Claude Code's key and means nothing elsewhere. The bodies are
 written runtime-neutral, with no runtime primitive named in any of them, and a test enforces it.
 

package/dist/cli.js

@@ -24,8 +24,8 @@ ${bold('Options')}
 ${bold('What it installs')}
   context/            the workflow's documents. Tool-owned files are replaced on update; your
                       roadmap, plans, findings, stack, verify and executors never are.
-  .claude/            seven skills and two subagent definitions, for Claude Code.
-  .agents/            the same seven skills, for Codex and anything else reading that tree.
+  .claude/            eight skills and two subagent definitions, for Claude Code.
+  .agents/            the same eight skills, for Codex and anything else reading that tree.
   AGENTS.md           a delimited block, merged into whatever is already there.
   CLAUDE.md           a single ${cyan('@AGENTS.md')} line, and only if the file does not exist.
 

package/dist/commands/install.js

@@ -34,7 +34,7 @@ export function install(root) {
         manifest.managedFiles[file.dest] = hash(content);
     }
     info(`${green('+')} ${managed.length} tool-owned files ${dim('(replaced on update)')}`);
-    info(dim(`    the seven skills go to ${adapters.map((a) => `${ADAPTER_SKILL_DIRS[a]}/`).join(' and ')} — ` +
+    info(dim(`    the eight skills go to ${adapters.map((a) => `${ADAPTER_SKILL_DIRS[a]}/`).join(' and ')} — ` +
         'one body, one directory per host, neither hand-edited'));
     for (const stub of STUBS) {
         write(root, stub.dest, readTemplate(stub.source));
@@ -70,9 +70,9 @@ export function install(root) {
     info();
     info(bold('Next'));
     info(`  1. Review the diff. ${dim('Nothing was committed — that is deliberate.')}`);
-    info(`  2. Run ${cyan('/onboard')} in your agent to fill in verify.md, executors.md and stack.md.`);
+    info(`  2. Run ${cyan('/onboard')} in your agent to fill in verify.md, executors.md, git.md and stack.md.`);
     if (before !== null) {
-        info(dim('     AGENTS.md already said things of its own — /onboard folds those into the three files\n' +
+        info(dim('     AGENTS.md already said things of its own — /onboard folds those into the four files\n' +
             '     above and prunes what it moved, asking before anything is deleted.'));
     }
     info(`  3. ${cyan('/roadmap "some idea"')} starts the loop.`);

package/dist/commands/update.js

@@ -128,7 +128,7 @@ export function update(root, options) {
     info();
     info(bold('Ownership'));
     info(`  ${green('replaced by update')}  ${dim('the tool-owned files above — every one is in the manifest')}`);
-    info(`  ${cyan('yours, untouched')}    ${dim('context/stack.md, verify.md, executors.md, roadmap.md,')}`);
+    info(`  ${cyan('yours, untouched')}    ${dim('context/stack.md, verify.md, executors.md, git.md, roadmap.md,')}`);
     info(`                      ${dim('history.md, findings.md, drafts/, plans/, archive/, CLAUDE.md,')}`);
     info(`                      ${dim('and anything else you have added under context/')}`);
     info(dim('  A project-owned file is not in the manifest, so no code path here reaches it.'));

package/dist/layout.js

@@ -28,6 +28,7 @@ export const SKILL_NAMES = [
     'feature-status',
     'feature-close',
     'orchestrate',
+    'prototype',
     'onboard',
 ];
 /**
@@ -79,7 +80,7 @@ export function managedFiles(adapters) {
             files.push({ source: `claude/agents/${posix}`, dest: `.claude/agents/${posix}` });
         }
     }
-    // The same seven bodies, verbatim. No transform: `disable-model-invocation` is Claude Code's key and
+    // The same eight bodies, verbatim. No transform: `disable-model-invocation` is Claude Code's key and
     // means nothing here, and there is no subagent tree to go with it — the skills already write
     // delegation as optional.
     if (adapters.includes('agents')) {
@@ -97,6 +98,7 @@ export const STUBS = [
     { source: 'stubs/stack.md', dest: 'context/stack.md' },
     { source: 'stubs/verify.md', dest: 'context/verify.md' },
     { source: 'stubs/executors.md', dest: 'context/executors.md' },
+    { source: 'stubs/git.md', dest: 'context/git.md' },
     { source: 'stubs/roadmap.md', dest: 'context/roadmap.md' },
     { source: 'stubs/history.md', dest: 'context/history.md' },
     { source: 'stubs/findings.md', dest: 'context/findings.md' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baldurpan/create-ai-workflow",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Overlay a tiered planning workflow — roadmap, plans, phase ledgers, verification gates — onto an existing repository, for coding agents.",
   "keywords": [
     "ai",

package/templates/blocks/agents-block.md

@@ -12,17 +12,22 @@ the standing rules, and every command cites it rather than restating it.
 | `/feature-status` | read-only "where do things stand". **Never a prerequisite** for anything |
 | `/feature-close` | retires a finished or abandoned feature into `context/archive/` |
 | `/orchestrate` | one ad-hoc, gated, commit-sized change — no roadmap entry, no ledger |
-| `/onboard` | fills in this project's own stubs — `verify.md`, `executors.md`, `stack.md` — adopting what an existing `AGENTS.md` already said |
+| `/prototype` | a throwaway HTML/CSS mockup under `prototypes/` — no gates, no ledger, no application code |
+| `/onboard` | fills in this project's own stubs — `verify.md`, `executors.md`, `git.md`, `stack.md` — adopting what an existing `AGENTS.md` already said |
 
 | Read | For |
 |---|---|
 | [`context/stack.md`](context/stack.md) | runtime, layout, conventions |
 | [`context/standards/README.md`](context/standards/README.md) | engineering standards — load per its conditional table |
 | [`context/verify.md`](context/verify.md) | the real lint / typecheck / build / test commands — the only file that names one |
+| [`context/git.md`](context/git.md) | who commits, and at what granularity — read it before closing out any change |
 
 **Phase status lives in the active plan's status ledger and nowhere else.** Work the lowest-numbered phase
 that is not `done` and whose `Depends on` are all `done`; state which you picked before starting; update
-the row in the same commit as the work. **If the ledger disagrees with the repo, stop and say so.**
+the row as part of the same change as the work. **If the ledger disagrees with the repo, stop and say so.**
+
+**Nothing commits unless [`context/git.md`](context/git.md) says so.** Absent or silent, the work is left in
+the working tree and the user commits it.
 
 **An open `P0` or `P1` in [`context/findings.md`](context/findings.md) blocks its phase from being `done`.**
 

package/templates/context/README.md

@@ -35,6 +35,7 @@ generated "current state" file — hand-editing a ledger row changes every comma
 | [`stack.md`](stack.md) | this project's runtime, layout, conventions, and an index of your own files | project |
 | [`verify.md`](verify.md) | this project's real lint / typecheck / build / test commands | project |
 | [`executors.md`](executors.md) | how this project dispatches a coder and a reviewer | project |
+| [`git.md`](git.md) | who commits the work an agent produces, and at what granularity | project |
 | [`roadmap.md`](roadmap.md) | Tier 1 — the backlog. `pending` and `active` entries only | project |
 | [`history.md`](history.md) | index of retired features, newest last | project |
 | [`findings.md`](findings.md) | open findings that gate a phase from being marked `done` | project |
@@ -64,7 +65,7 @@ hash, `update` walks that manifest, and a project-owned file is not in it — so
 
 | Tool-owned — replaced on `update` | Project-owned — unreachable by the updater |
 |---|---|
-| `README.md`, `workflow.md`, `plan-template*.md`, `roles/` | `stack.md`, `verify.md`, `executors.md` |
+| `README.md`, `workflow.md`, `plan-template*.md`, `roles/` | `stack.md`, `verify.md`, `executors.md`, `git.md` |
 | the skill and agent trees, the `AGENTS.md` block | `roadmap.md`, `history.md`, `findings.md` |
 | `standards/` while it is ours and unmodified | `drafts/`, `plans/`, `archive/`, `CLAUDE.md` |
 

package/templates/context/plan-template.md

@@ -36,8 +36,11 @@ Written <YYYY-MM-DD>. <One line on what this is.> The `<name>` entry in
 | 1 | <name> | not started | — | |
 | 2 | <name> | not started | 1 | |
 
-Status is one of `not started`, `in progress`, `blocked`, `done`. `done` only when committed and verified,
-and whoever finishes a phase updates the row in the same commit.
+Status is one of `not started`, `in progress`, `blocked`, `done`. A row goes to `in progress` when work on
+the phase starts, before any code, so an interrupted run leaves a ledger that says what was underway. `done`
+only when the scope landed and both gates passed, and whoever finishes a phase updates the row as part of
+the same change as the work — who commits that change is [`../git.md`](../git.md)'s answer, not this
+table's.
 
 **Exactly one table in this document has these columns.** Do not add a second phase table — a
 differently-shaped one nearby is a decoy that gets read by mistake.

package/templates/context/workflow.md

@@ -20,7 +20,7 @@ running something else.
 | Tier 1 → a plan | `/feature-plan` |
 | a plan → being worked, then phase by phase | `/feature-implement` |
 | Tier 2 → retired | `/feature-close` |
-| no tier crossed | `/orchestrate` — one ad-hoc gated change; `/feature-status` — read-only |
+| no tier crossed | `/orchestrate` — one ad-hoc gated change; `/feature-status` — read-only; `/prototype` — a throwaway mockup |
 
 **Every command finds its own starting point.** Nothing has to be looked up first, and `/feature-status` is
 never a prerequisite for anything.
@@ -35,7 +35,8 @@ never a prerequisite for anything.
 | `/feature-status` | nothing — read-only | — |
 | `/feature-close` | Tier 2 → retired | `history.md`, `archive/`, the reference sweep |
 | `/orchestrate` | one ad-hoc gated change | the code, and `findings.md` |
-| `/onboard` | the project-owned stubs | `verify.md`, `executors.md`, `stack.md`, and the pruning of what they replace |
+| `/prototype` | one throwaway HTML/CSS mockup — no gates, no application code | `prototypes/<NAME>/`, and nothing else |
+| `/onboard` | the project-owned stubs | `verify.md`, `executors.md`, `git.md`, `stack.md`, and the pruning of what they replace |
 
 ## One source of truth per fact
 
@@ -85,6 +86,16 @@ features may hold plans at once, and that is what makes planning ahead possible.
 `/orchestrate` is the ad-hoc escape hatch, not the way to skip planning. It refuses anything larger than a
 commit-sized unit and anything an existing roadmap entry already covers.
 
+### Nothing commits unless `git.md` says so
+
+> **Read [`git.md`](git.md) before closing out any command that lands code. If it does not exist, or does
+> not say the agent commits, the work is left in the working tree and the user commits it.**
+
+This workflow has always described phases as commit-sized and `done` as landed — which an agent, given no
+policy, resolves by committing on its own every phase. That is a call about someone else's repository, so
+it is a written answer rather than an inference. Branching and pushing are outside it: nothing here creates
+a branch, pushes, or opens a pull request under either answer.
+
 ### Never transcribe a credential
 
 > **A DSN, token or key is described and pointed at the secret store, never copied into a tracked file.**
@@ -114,10 +125,21 @@ To pick the next phase: take the **lowest-numbered phase that is not `done` and
 are all `done`.** State which one you picked before starting. If it is already `in progress`, read its Note
 and resume — do not restart it.
 
-`done` means committed and verified, and whoever finishes a phase updates its row in the same commit.
+**A phase's row is written twice.** It opens to `in progress` when the work starts, before any code, and
+closes to `done`, `in progress` or `blocked` when the phase ends. The opening write is what makes an
+interruption survivable: a run that dies mid-phase leaves a tree with half the work in it, and the row is
+the only thing that can say so.
+
+`done` means the phase's scope landed and both gates passed — **a verdict about the gates, not about git.**
+Whoever finishes a phase updates its row **as part of the same change as the work**: one commit where the
+agent commits, one working tree handed over where the user does. A closing row updated separately is a row
+that disagrees with the repository in between. The opening write is not a change of its own — it is left in
+the tree and lands with the work it describes.
 
 If the ledger's claim disagrees with the repo — a phase marked `done` whose files do not exist, or the
-reverse — **stop and say so.** Never silently re-do or skip a phase on a stale ledger.
+reverse — **stop and say so.** Never silently re-do or skip a phase on a stale ledger. A `done` row whose
+change is still uncommitted is not that: under the default policy in [`git.md`](git.md) it is the normal
+end state.
 
 ## The gates
 

package/templates/skills/feature-close/SKILL.md

@@ -79,6 +79,11 @@ grep -rn "<old-path>\|<OLD-FILENAME>" --include='*.md' . | grep -v node_modules
 Move every **closed** finding tied to this feature out of `context/findings.md` and into the archived plan's
 own log. `findings.md` must not grow for the life of the project.
 
+Then read [`context/git.md`](../../../context/git.md) before committing anything. `git mv` stages a rename
+and writes no history, so it is safe under either answer — but the commit that carries it is the agent's to
+make only where that file says so. If it does not exist, the answer is *the user commits*: show the whole
+retirement as one reviewable change and hand it over.
+
 ## Mode 2 — `--dropped`
 
 For an entry that will not be built. **There is no ledger check in this mode** — unfinished phases are
@@ -97,6 +102,6 @@ expected.
 - **Never delete a plan document.** Archiving keeps the reasoning; deleting throws away the record of a
   decision someone will otherwise re-litigate.
 - **Never leave `roadmap.md` and `history.md` inconsistent.** An entry is in exactly one of them.
-- **Never commit the sweep unreviewed.**
+- **Never commit the sweep unreviewed** — and never commit it at all unless `git.md` says the agent commits.
 - **Never mark a phase `done` to get past the refusal.** If phases are unfinished, the feature is
   unfinished.

package/templates/skills/feature-implement/SKILL.md

@@ -65,7 +65,22 @@ If the ledger's claim contradicts the repo — a phase marked `done` whose **Fil
 plainly in the tree under a phase marked `not started` — **say so and stop.** Never silently re-do or skip
 a phase on a stale ledger.
 
-## 6. Do the work
+## 6. Open the ledger row
+
+Set the phase's Status to `in progress` and write a Note naming what is underway — **before any code.**
+
+This row is what a *later* session reads. A phase interrupted here — context exhausted, session closed, run
+cancelled — leaves a working tree with half a phase in it. A row still reading `not started` sends the next
+run into step 5's disagreement stop, or into redoing work that is already there.
+
+One token and one Note, in the row that is already there — do not move the entry, restructure the table, or
+write a summary anywhere else. If the row is already `in progress` because you are resuming it, leave it
+alone; step 11 rewrites the Note.
+
+**This write is not a change of its own.** Leave it in the working tree — it lands with the phase's work
+under either answer in [`context/git.md`](../../../context/git.md). Never commit it on its own.
+
+## 7. Do the work
 
 Read the phase's §6.2 sub-section: its scope, its **Files:**, and what `done` means for it.
 
@@ -79,7 +94,7 @@ this repository can open them, and a brief that inlines them is a brief that goe
 
 Describe **what** needs to happen, never **how** to code it. Scope each delegated task to specific files.
 
-## 7. Gate 1 — verification
+## 8. Gate 1 — verification
 
 Per the gate contract in [`context/workflow.md`](../../../context/workflow.md): read
 [`context/verify.md`](../../../context/verify.md) and run its sections in order — Lint → Typecheck → Build →
@@ -89,9 +104,9 @@ Test.
 so, never faked. Exit 0 is the verdict regardless of summary text. If `verify.md` does not exist or has no
 filled-in section, stop and say so. Docs-only changes run Lint plus a read of the diff.
 
-A failure is the verdict — go to step 9 with the failing output verbatim as the feedback.
+A failure is the verdict — go to step 10 with the failing output verbatim as the feedback.
 
-## 8. Gate 2 — review
+## 9. Gate 2 — review
 
 Dispatch per [`context/executors.md`](../../../context/executors.md). With no independent reviewer
 configured, review the diff yourself against the plan's review expectations and the standards — weaker, and
@@ -100,13 +115,13 @@ configured, review the diff yourself against the plan's review expectations and
 Require concrete evidence — file paths, command output — for every verdict, and a `P0`–`P3` severity on
 every blocking finding.
 
-- `PASS` or `PASS WITH NOTES` → the phase's work is done; go to step 10.
-- `FAIL` → **write it to [`context/findings.md`](../../../context/findings.md) first, then** go to step 9.
+- `PASS` or `PASS WITH NOTES` → the phase's work is done; go to step 11.
+- `FAIL` → **write it to [`context/findings.md`](../../../context/findings.md) first, then** go to step 10.
 
 **Write the finding before the loopback, not after it.** A verdict that lives only in this session's
 transcript evaporates when the conversation ends — including a `P0` the cap never got to.
 
-## 9. Loopback
+## 10. Loopback
 
 Cap: **two loops per gate, per phase.**
 
@@ -118,9 +133,9 @@ At the cap: **write a finding** (`P1` for a Gate 1 cap-out — a phase whose ver
 blocked by definition), then escalate to the user with the current state and the last feedback.
 **Escalating is not a substitute for recording.**
 
-## 10. Close out the ledger row
+## 11. Close out the ledger row
 
-In the same commit as the work:
+The row is part of the same change as the work — never a separate step afterwards:
 
 - **All of the phase's scope landed and both gates passed** → `done`.
 - **Some landed** → stays `in progress`, Note rewritten to name exactly what remains.
@@ -129,9 +144,22 @@ In the same commit as the work:
 **Never mark `done` on a coder's self-report** — the gate output is the evidence. **Refuse `done` while an
 open `P0` or `P1` is tied to this phase**; leave it `in progress` and name the finding.
 
-## 11. Report
+`done` is a verdict about the gates, not about git. Whether the change is committed at all is the next step.
+
+## 12. Land it — read [`context/git.md`](../../../context/git.md)
+
+**Do not commit until you have read that file, and do not commit at all unless it says the agent does.**
+It is the only place this project's answer lives, the same way `verify.md` is the only place its commands
+live. If it does not exist — an install from before it shipped — the answer is *the user commits*: say so
+once, and name `/onboard`.
+
+- **The user commits** → leave the change in the working tree, ledger row and all. Report it, hand it over,
+  and stop. Do not stage-and-commit "to be helpful", and do not push or branch under either answer.
+- **The agent commits** → the code and the ledger row in one commit, at the granularity that file names.
+
+## 13. Report
 
-- What changed, and which files.
+- What changed, and which files — and whether it is committed or waiting in the tree.
 - Gate 1 output, and Gate 2's verdict.
 - Loopback counts, if any.
 - Findings written or closed, by id.

package/templates/skills/feature-plan/SKILL.md

@@ -89,6 +89,10 @@ inline. Either way the brief is the same, and the output contract is the templat
 planner's own default shape:
 
 - The roadmap entry verbatim, and the full content of its draft if there was one.
+- **If `prototypes/<NAME>/` exists at the repository root**, its `NOTES.md` and the mockups beside it. A
+  sketch someone has already looked at settles a design question that a paragraph would only argue. Carry
+  what it settled into §4 Design and cite the folder; treat anything it marked invented as a proposal, not
+  a fact. **No folder, no step** — this is a conditional read, not a prerequisite.
 - **The full section list from `context/plan-template.md`, stated as required output**, in order, with the
   ledger's exact column set. A general-purpose planner will otherwise emit implementation-steps-and-
   acceptance-criteria — a per-phase artifact, not a plan — and you will throw it away.

package/templates/skills/feature-status/SKILL.md

@@ -40,8 +40,10 @@ stale. That is the exact failure this workflow exists to prevent.
 
 - Every phase `done` while the entry still reads `active` — that is the normal state before
   `/feature-close`. Next action 5 handles it.
-- A `done` row with its changes still in the working tree — a phase finished but not committed. Name it in
-  the report; do not stop on it.
+- A `done` row with its changes still in the working tree. Under the default policy in
+  [`context/git.md`](../../../context/git.md) that is the normal end state of a phase, not a discrepancy —
+  the user commits. Name it in the report; do not stop on it, and do not commit it: this command writes
+  nothing.
 
 ## 3. Report
 

package/templates/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "Fill in this project's own workflow stubs — context/verify.md, context/executors.md and context/stack.md — by adopting what the repository already documented, asking wherever a claim's destination is unclear, and running each candidate verification command so only the ones that pass are written down. Explicit invocation only — run this when the user types /onboard. Do NOT match on 'set up the project', 'get started', or general setup requests."
+description: "Fill in this project's own workflow stubs — context/verify.md, context/executors.md, context/git.md and context/stack.md — by adopting what the repository already documented, asking wherever a claim's destination is unclear, and running each candidate verification command so only the ones that pass are written down. Explicit invocation only — run this when the user types /onboard. Do NOT match on 'set up the project', 'get started', or general setup requests."
 ---
 
 # /onboard
@@ -21,8 +21,9 @@ Read [`context/workflow.md`](../../../context/workflow.md) for the tier model.
 |---|---|
 | [`context/verify.md`](../../../context/verify.md) | the real Lint / Typecheck / Build / Test commands — **only ones that exited 0** |
 | [`context/executors.md`](../../../context/executors.md) | how this project dispatches a coder and a reviewer |
+| [`context/git.md`](../../../context/git.md) | who commits the work, and at what granularity |
 | [`context/stack.md`](../../../context/stack.md) | runtime, layout, conventions |
-| [`AGENTS.md`](../../../AGENTS.md) | pruned, on confirmation, of what moved into those three. The region between the `ai-workflow` markers is never touched |
+| [`AGENTS.md`](../../../AGENTS.md) | pruned, on confirmation, of what moved into those four. The region between the `ai-workflow` markers is never touched |
 
 Show every proposed edit before writing it, and **do not commit.** The user reviews and commits.
 
@@ -44,8 +45,9 @@ Break what you read into claims — a paragraph, a table row, a bullet — and p
 | A claim about | Goes to |
 |---|---|
 | what the project is, its layout, its conventions | `context/stack.md` |
-| a lint, typecheck, build or test command | a **candidate** for `context/verify.md` — Step 5 still has to run it |
+| a lint, typecheck, build or test command | a **candidate** for `context/verify.md` — Step 6 still has to run it |
 | how a coder or a reviewer is dispatched | `context/executors.md` |
+| a rule about who commits, or when work is committed | `context/git.md` |
 | a rule the bundled standards already state | nowhere — the standards own it. Ask before dropping |
 | planning or review process this workflow now owns | nowhere — superseded. Ask before dropping |
 | anything else — ownership, contacts, external links | stays in `AGENTS.md`, outside the block |
@@ -63,7 +65,7 @@ destination. Two kinds of row are never decided alone:
 An adopted claim is an *input* to the steps below, not a substitute for them. A command lifted out of the
 old file is a candidate like any other and still has to run.
 
-**Nothing is deleted here.** Pruning is Step 7, after the destination files exist.
+**Nothing is deleted here.** Pruning is Step 8, after the destination files exist.
 
 On a re-run, a claim its destination file already states is already adopted. Say so in a line and move on.
 
@@ -87,7 +89,7 @@ on that being true, and it is true of some executors and not others.
 4. If it comes back empty, guessed, or refused, record that **this executor needs content inline** — the
    one case where a brief carries file contents instead of paths.
 
-Never write down an invocation you have not run. This is the same rule as Step 5, for the same reason.
+Never write down an invocation you have not run. This is the same rule as Step 6, for the same reason.
 
 ## Step 3 — Reviewer dispatch
 
@@ -107,7 +109,33 @@ winner: it differs per host and changes underneath you. What ships is the contra
 Whatever is chosen, that contract stands: a review happens, every blocking finding carries a `P0`–`P3`
 severity, and a `FAIL` writes a finding before the loopback.
 
-## Step 4 — Standards source
+## Step 4 — Who commits
+
+**Ask this one. It is the question the workflow used to answer by inference.**
+
+Every command that lands code closes out by updating a ledger row *as part of the same change as the work*,
+and `done` has always meant the scope landed and the gates passed. Given no policy, an agent resolves that
+the only way it can — by committing, every phase, in someone else's repository. That is a call for the
+project to make, so ask it and write the answer to [`context/git.md`](../../../context/git.md).
+
+Ask, using your runtime's question mechanism if it has one:
+
+- **The user commits** — the default, and what the stub ships saying. A phase ends verified, with its
+  ledger row updated, left in the working tree. The agent reports and stops.
+- **The agent commits** — one commit per phase, the code and its ledger row together.
+
+Then confirm the granularity if the agent commits, and **say plainly what is not being decided**: nothing in
+this workflow branches, pushes, or opens a pull request under either answer, and choosing one does not start
+that.
+
+Write the answer as the surviving line under **Who commits**, and delete the other. If `context/git.md` does
+not exist — an install from before it shipped — create it, with a `## Who commits` section holding the
+chosen line, a `## Granularity` section, and a line recording that branches and pushes are out of scope.
+
+If Step 1 turned up an existing rule about committing, quote it here and let it win unless the user says
+otherwise. Prose someone wrote about their own repository beats a default.
+
+## Step 5 — Standards source
 
 `context/standards/` ships with a bundled default. Ask whether that is right for this project.
 
@@ -121,7 +149,7 @@ Say plainly what the default is and that a wrong set is not inert — agents loa
 conditional table unprompted, on every task. If Step 1 turned up house rules that the bundled set already
 covers, this is the moment that matters: keeping both means the project has two answers.
 
-## Step 5 — Verification commands
+## Step 6 — Verification commands
 
 **This is the most valuable step in this command.** Do it properly.
 
@@ -143,7 +171,7 @@ covers, this is the moment that matters: keeping both means the project has two
 Explain what you are doing: this turns `verify.md` from someone's guess into something verified at install
 time, which is the one moment it is cheap to catch.
 
-## Step 6 — Stack
+## Step 7 — Stack
 
 Start from what Step 1 routed here, show it back as a draft, and ask only for the gaps:
 
@@ -158,9 +186,9 @@ Start from what Step 1 routed here, show it back as a draft, and ask only for th
 Point out that anything else added under `context/` should be indexed in `stack.md`, not in
 `context/README.md`, which is tool-owned and replaced on update.
 
-## Step 7 — Prune the sources
+## Step 8 — Prune the sources
 
-Only now, with the three stubs written, remove from `AGENTS.md` and `CLAUDE.md` what has landed elsewhere.
+Only now, with the four stubs written, remove from `AGENTS.md` and `CLAUDE.md` what has landed elsewhere.
 Duplication left standing is the failure this step exists to prevent: two statements of one fact drift, and
 the stale copy is indistinguishable from the live one.
 

package/templates/skills/orchestrate/SKILL.md

@@ -79,10 +79,18 @@ expand no scope.
 At the cap: write a finding (`P1` for a Gate 1 cap-out), then escalate with the current state and the last
 feedback. **Escalating is not a substitute for recording.**
 
-## 6. Report
+## 6. Land it — read [`context/git.md`](../../../context/git.md)
 
-What changed, the Gate 1 output, the Gate 2 verdict, any loopbacks, and any findings written, closed or
-swept — by id.
+**Do not commit unless that file says the agent does.** If it does not exist, the answer is *the user
+commits*: say so once, and name `/onboard`. Nothing branches or pushes under either answer.
+
+- **The user commits** → leave the change in the working tree and hand it over.
+- **The agent commits** → one commit, at the granularity that file names.
+
+## 7. Report
+
+What changed, whether it is committed or waiting in the tree, the Gate 1 output, the Gate 2 verdict, any
+loopbacks, and any findings written, closed or swept — by id.
 
 ## Rules
 

package/templates/skills/prototype/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: prototype
+description: "Mock one screen or interaction as throwaway HTML and CSS under prototypes/, to settle a layout or look-and-feel question before a plan commits to it. Writes no application code and runs no gates. Explicit invocation only — run this when the user types /prototype. Do NOT match on 'mock this up', 'try a layout', 'what should this look like', or any request to build, style or restyle real UI."
+---
+
+# /prototype
+
+A cheap, disposable sketch of something that will be built properly later. **No roadmap entry, no ledger,
+no gates, no tier boundary crossed** — and no application source is touched.
+
+It exists because some questions are only answerable by looking at the thing. Arguing about a layout in a
+plan document is slow and inconclusive; two static files answer it in minutes, and the answer then goes
+into the plan as a decision rather than a paragraph of hedging. **Nothing in the workflow requires this
+command** — skip it and every other command behaves identically.
+
+Read [`context/workflow.md`](../../../context/workflow.md) for the tier model and the feature/task rule.
+
+## Usage
+
+```
+/prototype "<what to mock>"     # a screen, a flow, an interaction
+/prototype "<entry name>"       # mock what a roadmap entry describes
+```
+
+## 0. Refuse, before anything else
+
+1. **Refuse to build the real thing.** This command produces throwaway files outside the application. The
+   moment the request is "now wire it up" or "put this in the app", it belongs to `/orchestrate` if it is
+   commit-sized, or to `/feature-plan` and `/feature-implement` if it is a feature. Name the one that
+   applies and stop.
+2. **Refuse to sketch the whole application.** A screen or two, chosen because something about them is
+   actually in question. If the answer is "all of them", ask which decision is being made and mock the two
+   screens that decide it.
+
+Say which question the mockup exists to answer, in one line, before writing anything.
+
+## 1. Read what this project already looks like
+
+**Borrow before inventing.** This repository exists already, so most of the look is decided — and a mockup
+built from values the project does not have is a picture of an app nobody is going to build.
+
+Read `context/stack.md`, then find the real thing: the stylesheet or token file, the design system or
+component library, and two or three existing screens close to what is being mocked. Copy the actual token
+names, spacing scale, radii and type stack out of them.
+
+Invent only where there is genuinely nothing to borrow — a new surface, or a project with no styling of its
+own yet. **Mark every invented value**, so the plan that reads this knows which parts are proposals and
+which are already true.
+
+## 2. Agree the sketch, then stop
+
+Ask a short set of questions — which screens, which states, and what specifically is undecided. Use your
+runtime's question mechanism if it has one, or a plain numbered question if it does not.
+
+Then propose, and **wait**:
+
+- the screens, one line each on what each one shows,
+- the states each will exercise, and
+- which values are borrowed and which are invented.
+
+**Write nothing until the user approves.** Adjust the proposal if they push back. Generating five files
+before anyone has agreed what is being asked is how a fast tool becomes a slow one.
+
+## 3. Write the mockups
+
+Everything goes under `prototypes/<NAME>/` at the repository root, where `<NAME>` is the kebab-case subject
+— matching the roadmap entry's name when there is one.
+
+| File | Holds |
+|---|---|
+| `theme.css` | every value the mockups use, in one place — the project's real tokens copied in, and invented ones marked with a comment |
+| `<screen>.html` | one self-contained page per screen, linking `theme.css` |
+| `NOTES.md` | the question this exists to answer, what it settled, what is still open, and which values were invented |
+
+- **Plain HTML and CSS. No framework, no build step, no dependencies.** A few lines of inline script for a
+  view toggle is fine; anything more means this stopped being a sketch.
+- **Every colour, font and spacing value comes from a `theme.css` variable**, never hard-coded — that is
+  what makes tweaking one file restyle every screen at once.
+- **Realistic content and the states that matter** — the empty list, the error, the mid-action moment, the
+  name that is too long. An empty shell full of lorem ipsum answers nothing. Desktop-first is enough unless
+  the question is about small screens.
+- Never transcribe a credential. Placeholder content is invented, and a real key is never realistic detail.
+
+`NOTES.md` is the durable part. The HTML is scaffolding for a conversation; the notes are what a plan reads.
+
+## 4. It gets committed
+
+`prototypes/` is yours, not the tool's — nothing installs it, nothing updates it, nothing validates it.
+**It gets committed anyway.** Until a plan absorbs `NOTES.md` its conclusions live nowhere else, and neither
+the notes nor the mockups survive a cleared context or a second machine if they were never tracked.
+
+Who does the committing is [`context/git.md`](../../../context/git.md)'s answer, not this command's. Where
+the user commits, say plainly that these files are worth tracking rather than leaving them to be mistaken
+for scratch output.
+
+## 5. Hand off and stop
+
+Report the folder path, and tell the user to open the files in a browser and iterate on the look — that
+iteration is the point, and it costs nothing.
+
+Then name exactly one next step, and **do not run it**:
+
+- **No roadmap entry yet** → `/roadmap "<idea>"`, citing `prototypes/<NAME>/`.
+- **An entry exists** → `/feature-plan "<NAME>"`, which reads the folder and carries what it settled into
+  the plan's Design section.
+
+## Rules
+
+- **Nothing outside `prototypes/` is written.** Not application source, not `context/`, not `roadmap.md`.
+  This command creates no entry, marks nothing active, and touches no ledger row.
+- **No gates.** Nothing here is verified or reviewed, because there is nothing to verify — no test covers
+  a throwaway file, and review time spent on one is time wasted. Work that needs a gate is not a mockup.
+- **Throwaway means throwaway.** When the feature ships, delete `prototypes/<NAME>/` and the citation that
+  pointed at it. A mockup that no longer matches the app is worse than no mockup, because someone will
+  believe it.

package/templates/stubs/git.md

@@ -0,0 +1,44 @@
+# Git
+
+Who commits the work an agent produces, and at what granularity. **Every command that lands code reads this
+file before it closes out** — the exact parallel to [`verify.md`](verify.md) for commands and
+[`executors.md`](executors.md) for dispatch, and for the same reason: git etiquette differs per repository,
+and a skill that assumes one project's ships one project's habits everywhere.
+
+Two answers, and the file is short on purpose. Run `/onboard` to set them, or edit them here.
+
+## Who commits
+
+<!-- Exactly one of the two answers below is this project's. Keep it, delete the other.
+
+     Shipped as: the user commits. A tool installed into a repository it knows nothing about does not get
+     to write that repository's history unasked. -->
+
+**The user commits.** A phase ends with the work verified and its ledger row updated, left in the working
+tree. The agent reports what changed and stops there — no `git commit`, no `git push`, nothing that
+rewrites history.
+
+<!-- **The agent commits.** A phase ends committed: the code and its ledger row in one commit, so the two
+     cannot disagree. Nothing is pushed either way. -->
+
+## Granularity
+
+**One commit per phase.** A phase is a commit-sized unit with one checkable outcome — that is what a plan's
+ledger is a list of. Where the user commits, this describes the shape the agent leaves the tree in, not
+something it carries out.
+
+## What this file does not decide
+
+**Branches, pushes and pull requests.** Nothing in this workflow creates a branch, pushes, or opens a pull
+request, and neither answer above makes it start. If work here belongs on a branch, make the branch before
+the phase starts.
+
+## The rules that hold either way
+
+- **The ledger row lands with the work.** Whoever makes the commit, the row and the code it describes are
+  one change. A row updated separately is a row that disagrees with the repository in between.
+- **`done` is a verdict about the gates, not about git.** A phase is `done` when its scope landed and both
+  gates passed. Where the user commits, a `done` row whose change is still in the working tree is the
+  normal end state — not a discrepancy, and nothing stops on it.
+- **If this file is missing, the answer is the first one.** An install from before this file existed has
+  no policy written down; treat it as *the user commits*, say so once, and name `/onboard`.

package/templates/stubs/stack.md

@@ -32,4 +32,4 @@ What this project is, and what an agent has to know before touching it. Run `/on
      line lost. -->
 
 Verification commands are in [`verify.md`](verify.md), not here. Executor dispatch is in
-[`executors.md`](executors.md).
+[`executors.md`](executors.md), and who commits is in [`git.md`](git.md).