alexsoyes · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026 · Sep 25, 2026
@@ -4,37 +4,64 @@ The contract every generated skill satisfies. `skill-generate` obeys it too.
 
 ## The skill
 
-- **R1.** One skill, one domain. Named per `naming.md`.
-- **R2.** `name` is not the invocation token: a colon or prefix breaks loading. In prose call a skill `plugin:folder`.
-- **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to <intents>` and an optional `Not for <X>`. No colon or dash, no other skill or `/command` named.
-- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`). One or two words per case, never the action slugs. Present unless no action declares an `## Input`, which means the skill takes nothing.
+- **R1.** One skill, one domain.
+  Named per `naming.md`.
+- **R2.** `name` is not the invocation token: a colon or prefix breaks loading.
+  In prose call a skill `plugin:folder`.
+- **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to <intents>` and an optional `Not for <X>`.
+  No colon or dash, no other skill or `/command` named.
+- **R4.** `argument-hint` names what the user brings: the cases they can ask for (`setup | refresh | rewire`) or the artifact the skill consumes (`request | epic`).
+  One or two words per case, never the action slugs.
+  Present unless no action declares an `## Input`, which means the skill takes nothing.
 - **R5.** English only, one idea per sentence.
+  In any bullet, start each complete sentence on a new source line.
 
 ## The router
 
-- **R6.** The router holds the flow, the action table, and the transversal rules. Nothing else.
-- **R7.** The mermaid flow shows every path a run can take: the nominal chain, one entry node per case, a back-edge per loop, a terminal node per outcome. A branch stated in prose is a branch missing from the flow.
-- **R8.** The action table is `| Action | Does |`, one row per action file, in run order. `Action` is the bare slug, no backticks and no number. `Does` is a lowercase imperative half-line with no final period. Above the table, one sentence: what to read next, nothing more.
-- **R9.** `## Transversal rules` holds the rules no single action or reference owns. A rule stated there is stated nowhere else.
+- **R6.** The router holds the flow, the action table, and the transversal rules.
+  Nothing else.
+- **R7.** The mermaid flow shows every path a run can take: the nominal chain, one entry node per case, a back-edge per loop, a terminal node per outcome.
+  A branch stated in prose is a branch missing from the flow.
+- **R8.** The action table is `| Action | Does |`, one row per action file, in run order.
+  `Action` is the bare slug, no backticks and no number.
+  `Does` is a lowercase imperative half-line with no final period.
+  Above the table, one sentence: what to read next, nothing more.
+- **R9.** `## Transversal rules` holds the rules no single action or reference owns.
+  A rule stated there is stated nowhere else.
 - **R10.** The router is loaded on every call, an action only when its turn comes: the router carries nothing an action or a reference could carry.
 
 ## An action
 
-- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, `## Test`. A section earns its content or is omitted, never invented or reordered.
-- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence. A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number. A fenced block is content the action emits, not structure: leave it as its consumer needs it.
+- **R11.** Sections in this order: `## Input` when the action consumes something, then `## Output`, `## Process`, `## Test`.
+  A section earns its content or is omitted, never invented or reordered.
+- **R12.** A `## Process` step opens with `**Label.**`, then one imperative sentence.
+  A number is always a step run in order; a case, a branch, a loop back, or a constraint is a dash sub-item of the step it belongs to, never a number.
+  A fenced block is content the action emits, not structure: leave it as its consumer needs it.
 - **R13.** `## Test` is a `| Case | Pass |` table, each row observable by real execution, never a mock.
 
 ## A reference
 
-- **R14.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. It names a sibling in backticks and never links it.
-- **R15.** A reference carries one fact per row: a table, a mermaid, or a list. Prose is what is left when neither fits.
+- **R14.** References stay flat, nesting one directory deep only as a load boundary.
+  Each stands alone, never pulling in another.
+  It names a sibling in backticks and never links it.
+- **R15.** A reference carries one fact per row: a table, a mermaid, or a list.
+  Prose is what is left when neither fits.
 
 ## An asset
 
-- **R16.** An asset states how it is filled and what is removed. Nothing of its scaffold survives in the artifact produced from it.
+- **R16.** An asset states how it is filled and what is removed.
+  Generated prose gives general guidance without boilerplate such as "per template".
+  An action still links to an asset template it must read.
+  Trust the model's judgment for routine choices.
+  Remove the asset's scaffold from the produced artifact.
 
 ## Across all of them
 
-- **R17.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either.
-- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those. It sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Test` line to conform to it. Never a block or a line of its own.
-- **R19.** One file, one artifact. Split two apart only when a path needs one without the other.
+- **R17.** One fact, one home.
+  An action follows its already loaded `SKILL.md` router without linking back to it.
+  It cites only distinct files it needs, without restating their rules.
+- **R18.** A citation is a relative markdown link, `[name](path)`, never an `@` include: nothing resolves those.
+  It sits in the sentence that uses it, a `## Process` step to read the file, an `## Output` or `## Test` line to conform to it.
+  Never a block or a line of its own.
+- **R19.** One file, one artifact.
+  Split two apart only when a path needs one without the other.
@@ -21,8 +21,22 @@ Before running an action, read its file in `actions/`, not only the table or ass
 
 ## Transversal rules
 
-- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit.
-- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against.
+- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`.
+  Never commit an `in-progress` marker alone.
+- Commit timing: follow the user's explicit instruction, else `AI should auto commit` in VCS memory.
+  `never` or absent means no automatic commits.
+  `after task done` commits a verified `###` category; defer an unverifiable or final category until the phase assertion.
+  `after phase` waits for that assertion; `after feature` and `post-tests` wait for final validation.
+  An explicit commit request without timing also waits for final validation.
+- Commit unit: one coherent `###` category under `## Tasks to do`, including all numbered steps, per commit; never commit per step or checkbox.
+  Keep category changes separable even in shared files; if impossible, report `replan needed`.
+  The last category commit includes phase `done`; commit plan `implemented` separately after final validation.
+  Commit only implementation-owned changes due at the checkpoint; leave unrelated pre-existing edits untouched.
+  Without authorization, leave changes uncommitted.
+- Commit handoff: at a due checkpoint, discover an installed atomic local commit capability by purpose.
+  Delegate staging, message, commit, and hook handling for each due unit.
+  Stop and report if the provider is absent or rejects a commit.
+  Automatic commits require a non-default branch; never request a push.
 
 ## References
 

@@ -12,9 +12,14 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress`
 
 ## Process
 
-1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at <path>`. Never fabricate a plan.
-2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it.
-3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code.
+1. **Resolve.** Resolve the plan from the arguments.
+   A path must exist and be readable.
+   With neither a readable file nor inline content, stop with `plan not found at <path>`.
+   Never fabricate a plan.
+2. **Branch.** On the default branch, create a feature branch and announce it.
+   On a non-default branch, keep it.
+3. **Mark.** Set plan frontmatter `status: in-progress`.
+   Include it at the first authorized commit checkpoint, or with `implemented` when there is no phase.
 
 ## Test
 

@@ -8,19 +8,29 @@ The prepared plan on its feature branch, from `01-prepare`.
 
 ## Output
 
-Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan.
+Each phase asserted and marked `status: done`, or a stop at `status: blocked` or `replan needed`.
 
 ## Process
 
-1. **Open.** Walk the phases in order. In a feature folder each is a `phase-<n>.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet.
-2. **Code.** Build the phase scope against its acceptance criteria.
-3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together.
+1. **Open.** Walk the phases in order.
+   In a feature folder each is a `phase-<n>.md` next to `plan.md`.
+   Set its `status: in-progress` as a runtime marker; no commit yet.
+2. **Code by category.** Complete the numbered steps under each `###` heading in `## Tasks to do`; check relevant behavior and retain separable changes.
+   For legacy phases without headings, treat the phase as one category.
+   Hand off only categories due at the current checkpoint.
+3. **Assert the phase.** Assert all acceptance criteria; repair the owning category and repeat on failure.
+   Keep corrections to an earlier committed category separate until an authorized checkpoint.
+   On success, set `status: done`; hand off categories due now and retain the others for finalization.
 4. **Guard.** Stop the loop on either condition:
-   - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop.
-   - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: <reason>`. Never rewrite the plan; replanning is the caller's job.
+   - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked` and stop; do not automatically commit an unverified unit.
+   - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: <reason>`.
+     Never rewrite the plan; replanning is the caller's job.
 
 ## Test
 
-- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits).
-- The branch holds one commit per phase; there are no separate `in-progress` status commits.
+- Each due category has one scoped commit, including all its steps.
+  Any correction to an earlier commit stays scoped to that category.
+- The full assertion passes before `status: done`; when committed, that status rides in the last category's commit.
+- Without authorization, no commits are made.
+  Unrelated pre-existing edits remain untouched.
 - A blocker leaves the plan `status: blocked` with no later phase run.
@@ -12,10 +12,13 @@ The feature validated green with the plan frontmatter `status: implemented`.
 
 ## Process
 
-1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode.
-2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it.
+1. **Verify.** Run the plan's validation commands and tests.
+   Never format code, never run dev mode.
+2. **Mark.** When every phase is done and validation passes, set plan `status: implemented`.
+   Hand off retained categories separately in phase order, then the plan status, at their authorized checkpoints.
+   Without authorization, leave changes uncommitted.
 
 ## Test
 
 - The validation commands exit zero.
-- The plan reads `status: implemented`, committed (`git status --short` shows it clean).
+- The plan reads `status: implemented`; authorized commits include only due implementation changes and status.