@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/skills/do-flow/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: do-flow
+description: "Auto-chain the doflow spec-driven flow (brainstorm → design → plan → implement → test → review), pausing only at defined approval gates. Use when the user wants the lifecycle run end-to-end, says 'build this feature end-to-end', 'run the doflow chain' or 'take this from idea to implementation', or /do classified the request as a feature. A plain change request that names no /do-* skill goes to /do first, which decides whether it needs this flow. Skip it for single-file fixes, questions and reviews."
+argument-hint: "[feature description] [--from brainstorm|design|plan|implement|test|review]"
+effort: high
+---
+
+# do-flow
+
+Runs a DoFlow workflow end-to-end without a manual `/do-X` at every stage. The task's **class**
+selects the workflow; the resolved workflow's stages name which existing skills run, in what order,
+and where the run stops. `do-flow` does not replace or modify those skills — it invokes their own
+Behavioral Flows in sequence. `do-constitution` belongs to no class; invoke it directly when you
+need to set or amend repo-level rules.
+
+**You propose the class; the runtime validates it.** Never the reverse. A class you assumed, or one
+the runtime rejected and you replaced with the familiar default, runs a confident workflow for the
+wrong task.
+
+## Invocation
+```text
+/do-flow [feature description] [--from brainstorm|design|plan|implement|test|review]
+```
+
+## Behavioral Flow
+
+1. **Resolve state** — run the resolver. Every DoFlow runtime call in this skill goes through the
+   runtime seam. Resolve it **once** here and reuse `$DOFLOW` for every later call in this skill:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+```bash
+"$DOFLOW" paths --json
+```
+`feature_slug` `null` with a non-empty `candidate_slugs` is an unresolved choice, not "no active feature": ask one option per entry, re-resolve with `"$DOFLOW" paths --json --slug="<chosen>"`, and use that slug for the rest of this flow. `/do-flow` passing `--slug` already resolves it — no prompt then.
+
+2. **Propose one class** — read the request and name exactly one class id, using the cues and the
+   confusable pairs in this skill's own `references/task_classes.md`. State the class and the
+   signal it rests on in one line. If two classes fit equally, do **not** take the longer one: show
+   what each would run —
+   `"$DOFLOW" workflow --task-class "<candidate>" --json`, quote its `stageIds` — and ask via
+   `AskUserQuestion`, one option per candidate.
+
+3. **Validate the class through the runtime** — a proposal is not a selection until this returns:
+
+```bash
+"$DOFLOW" classify --task-class "<proposed>" --calling-skill do-flow --json
+```
+Branch on the returned `outcome` field, not the exit code.
+- **`ACCEPTED`** — the returned `workflow` is this run's plan of record; read `stages`, `gates` and `handoff` off it rather than from memory.
+- **`REJECTED`** — **stop.** Print `message` verbatim (it already names `validClasses` and any `suggestions`), ask the user to choose from `validClasses`, then re-validate. Never substitute `feature`.
+  A rejection may be about **you** rather than the class (`reason: caller-not-a-stage`). Then the fix is to propose one of the classes in `fit.hostingClasses`, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
+- **Exit 2** — surface the message verbatim and stop.
+
+Every stage this run enters comes from the accepted `workflow`'s `stages`; a phase the workflow does
+not declare is not run here, however familiar it is from the `feature` chain.
+
+4. **Announce the selection** — one line before anything runs:
+   `<taskClass> → <workflow.name>: <stageIds joined by →>`, plus the gate ids if `gates` is
+   non-empty. This is the user's chance to correct a misclassification cheaply.
+
+5. **Pick the starting stage.**
+   - `feature`: resume from the first missing chain artifact — `!has_requirement` → the discovery
+     stage; `has_requirement && !has_design` → design; `has_design && !has_plan` → planning; all
+     three present → go straight to the pre-implementation gate in step 7.
+   - Every other class: start at the first entry in `stages`.
+   - `--from <phase>` overrides the above to deliberately re-run a stage. Match the phase to the
+     stage whose `skill` is that phase's skill (`brainstorm` → `do-brainstorm`, `design` →
+     `do-design`, `plan` → `do-plan`, `implement` → the stage with `mutatesSource: true`, `test` →
+     `do-test`, `review` → `do-code-review`). No stage matches in this workflow → stop and list the
+     stage ids it does have. Two stages match — `bug` and `refactor` each run `do-test` twice — →
+     ask which one.
+
+6. **Run the stages in order**, invoking each stage's `skill` Behavioral Flow directly.
+   - `optional: true` — decide from that stage's own `purpose`, then say which way you went and
+     why. Never drop an optional stage silently.
+   - `readinessTemplate` is non-null — consult readiness before entering the stage:
+     `"$DOFLOW" readiness --task-class "<taskClass>" --task-id "<task id>" --mode workflow --json`.
+     Both `--task-class` and `--task-id` are required; omitting either exits 2 and names the valid
+     set. Act on the returned `stageEntry.decision` — the entry policy is the runtime's, not this
+     page's: `ENTER` → enter the stage; `GATHER_FIRST` → report the missing items and gather them
+     first, do not enter; `ASK_USER` → ask the owed decision and wait; `STOP` → stop and surface
+     the conflicted claim.
+   - `readinessTemplate` is `null` — enter the stage. Do not consult readiness "to be safe": a
+     workflow whose `requiresImplementationReadiness` is `false` has no implementation to be ready
+     for and declares no template by design (`references/task_classes.md`). Calling it anyway
+     invents a gate the registry does not declare.
+   - After each stage, report one line: stage id, skill, and the artifact path or result it
+     produced — so the user can follow without intervening.
+
+7. **Stop at the gates the resolved workflow declares** — read them from `workflow.gates`, each
+   attached to a stage by `afterStage`. `trigger: always` stops every time; any other trigger stops
+   only when that named condition actually holds. Ask with the gate's own `prompt` via
+   `AskUserQuestion`. For the `feature` workflow's three, which behave as they always have:
+   - **`gate-0`** (after discovery, trigger `unresolved-clarifications`) — a safety net, not the
+     normal path: `do-brainstorm` resolves ambiguities to zero via its own loop, so this fires only
+     if a `[NEEDS CLARIFICATION]` marker survived an aborted session. Ask one question per marker
+     (grouped if closely related), patch the answers into `requirement.md` directly, and do not
+     re-run `do-brainstorm`. Then follow steps 1-4 of the decision step in the guidance
+     tree's `references/WORKFLOW_HANDOFF.md` (stage `discovery`, channel `question`) so the answers
+     are registered and cited; do-brainstorm already recorded discovery's handoff, so record none.
+   - **`gate-a`** (after planning) — the conversational checkpoint on top of the already-existing
+     hard hook (`pre-implement-gate.sh`, which blocks source edits until `requirement.md`,
+     `design.md` and `plan.md` exist and remains the real enforcement regardless of what happens
+     here). Options: `Proceed` / `Let me review the artifacts first` / `Stop here`.
+   - **`gate-b`** (after review) — no enforcement hook exists for this today; `/do-git` is a
+     separate, always-manually-invoked skill. Frame the question by the review's own approval
+     status: on `CHANGES REQUESTED`, foreground addressing the findings rather than offering a bare
+     proceed.
+   A workflow with an empty `gates` array stops at none of these. It still stops on a readiness
+   block, on an ambiguous answer, and on any stage skill's own stopping rule.
+
+   **Record every answer that is a decision.** Asking is not recording: a gate this skill asked but
+   never wrote back stays open in the run, so the stage skill that owns it asks the same question
+   again — the user answers twice for one decision. Immediately after the user answers, write it:
+   ```bash
+   "$DOFLOW" orchestrate --action decide-gate --task-id "<slug>" --gate "<gate id>" --decision approve|reject --note "<the user's own answer, one line>" --json
+   ```
+   Map each gate's own option set onto the two decisions the runtime accepts, and never onto a third:
+   - **`gate-a`** — `Proceed` is `approve`; `Stop here` is `reject`. `Let me review the artifacts
+     first` is **neither**: it is a pause, not a decision, so call nothing and actually pause — hold
+     the run at this gate and re-ask once the user comes back, exactly as step 8's ambiguous-answer
+     rule already requires.
+   - **`gate-b`** — an actual "proceed to commit/merge" answer is `approve`; an explicit stop is
+     `reject`. Anything that is not a real decision — "let me address the findings first" on a
+     `CHANGES REQUESTED` review, most often — is neither, and gets no `decide-gate` call. `reject`
+     terminates the run outright, which is a different answer from "not now".
+   - **`gate-0`** — only in the aborted-session branch above, where this skill patched
+     `requirement.md` itself: once every surviving marker is resolved, `approve`. If any marker is
+     still open, leave the gate alone.
+   This call is advisory to the trail, not to the chain: if it fails for a reason outside this flow's
+   control (an unwritable local state directory, say), report the failure plainly and carry the
+   user's answer forward anyway — the answer is what governs whether the next stage runs, and the
+   record of it is what keeps the next stage from asking again.
+
+   When the answer also carries a choice beyond approve or reject and `paths --json` reports
+   `has_decisions: true`, register it too, once `decision --action list`
+   shows no live decision with that statement; the receiving stage's batch then leaves it out:
+   ```bash
+   "$DOFLOW" decision --action add --topic "<key>" --statement "<text>" --channel gate --stage "<stage the gate follows>" --rationale "<text>" --json
+   ```
+
+8. **Never skip a gate on an ambiguous answer** — an unanswered or unclear response to any
+   `AskUserQuestion` means stop and ask again, per this repo's `RULE_04_QUESTIONS`. When the
+   terminal stage completes, state `workflow.handoff` as the next step rather than continuing into
+   it.
+
+## Conditional research within a feature
+
+Before a feature stage relies on an external fact that local or user evidence cannot establish, or when the developer explicitly asks a research question, let that stage follow `../do-document/references/embedded-research.md`. The stage opens a same-task `research-request`, records a source-linked finding or gap, then resumes itself without adding a seventh workflow stage. On resume, read request status and context pack. A blocking unanswered question prevents stage completion; neither research nor a retrieved page approves any existing gate. Do not trigger external search merely because a feature began.
+
+## Boundaries
+**Will:**
+- Propose a task class, validate it through the runtime, and run the resolved workflow's stages in
+  order without a manual re-invocation at each boundary.
+- Stop only where the resolved workflow says to: its declared gates, a readiness block, or an
+  ambiguous answer.
+- Record each gate answer it collects through `orchestrate --action decide-gate`, so the stage skill
+  that owns that gate finds it already resolved instead of asking the user the same question twice.
+- Compose with the existing `pre-implement-gate.sh` hard gate rather than bypass or duplicate it.
+  That hook keys on branch and artifact state, not on class, so it can deny a `bug` or
+  `trivial-edit` workflow's edits on a branch that already holds an incomplete feature dir —
+  surface its message as written.
+
+**Will Not:**
+- Run any workflow for a class the runtime rejected, or replace a rejected class with `feature`.
+- Infer a class silently when two fit, or read a class the user stated as a suggestion.
+- Consult implementation readiness for a stage that declares no readiness template, or invent a
+  readiness template for a class that has none.
+- Modify any stage skill, or invoke `do-constitution` — it is standalone and in no class.
+- Add a hook-level enforcement gate for commit/merge — `gate-b` is conversational only. A
+  hook-level version would be a separate, future proposal.
+- Silently proceed past a gate on an ambiguous or missing answer.
+- Record a pause or a deferral as a gate decision — `Let me review the artifacts first` and "let me
+  address the findings first" are neither `approve` nor `reject`, and forcing them into one writes a
+  decision the user did not make.
+
+**Next Step:** whatever the resolved `workflow.handoff` names — for every class that ends in a
+change, `/do-git` to commit/merge once the last gate is cleared.

package/core/shared/skills/do-flow/references/task_classes.md

@@ -0,0 +1,134 @@
+# Task classes — proposal guide
+
+The runtime's workflow registry is authoritative for **what runs**; this file is authoritative for
+**which class to propose**. Never quote a stage list from here: get stages from `classify` or
+`workflow`, so a registry edit reaches the run without a prose edit.
+
+## Propose exactly one
+
+- Read the request, name one class id, and hand it to `classify` as `taskClass`. That key name is
+  literal — the runtime detects `class`, `type`, `taskType`, `workflow` and friends as near-misses
+  and rejects the proposal rather than reading them.
+- A proposal is a hypothesis, not a decision. Say what you propose and the one or two signals it
+  rests on, so a wrong read is visible before the workflow runs.
+- Two classes fit equally well → **ask**, do not pick the larger one. "Feature" is not the safe
+  default; it is the longest workflow and the only one that demands three artifacts before an edit.
+- The user naming a class outright settles it. Propose what they said, and let `classify` reject it
+  if it is not a declared id.
+
+## Cues
+
+| Class | Propose when the request is about… |
+|---|---|
+| `feature` | A capability that does not exist yet and needs to be specified before it is built. |
+| `bug` | Behavior that is wrong *now*, with a symptom the user can point at. |
+| `refactor` | Changing structure while holding behavior fixed — extract, rename, split, de-duplicate. |
+| `review` | Judging code or a diff that already exists. The deliverable is findings. |
+| `research` | Answering a question. The deliverable is a written report, not a change. |
+| `documentation` | Writing or updating docs that ship with the repo — a reference page, a guide, a README section, an architecture note. |
+| `dependency-change` | Adding, removing, or moving the version of something the project depends on. |
+| `operations` | Repository lifecycle — branch, release, merge, hotfix, backport, tag. |
+| `trivial-edit` | One file, no cascade: a typo, a constant, a string, a comment. |
+
+## Confusable pairs
+
+- **bug vs refactor** — a bug has an observed wrong behavior; a refactor has none, and the suite is
+  green before and after. If the suite is red, it is a bug.
+- **bug vs trivial-edit** — a one-line change is still `bug` when the reason it is wrong has to be
+  established. `trivial-edit` is for when the target and the correct value are both already known.
+- **review vs bug** — reviewing produces findings; acting on a finding is a separate task with its
+  own class. Do not propose `review` for work that ends in an edit.
+- **research vs review** — `review` judges this repository's code, `research` answers a question
+  that may have no code answer at all.
+- **dependency-change vs feature** — an upgrade is `dependency-change` even when it unlocks a
+  feature. The feature is the next task.
+- **operations vs trivial-edit** — changing a version *string* in a manifest as part of cutting a
+  release is `operations`; changing it because it is wrong is `trivial-edit` or `bug`.
+- **documentation vs trivial-edit** — a one-line doc fix with a known target and a known correct
+  value is `trivial-edit`; anything that has to be written, or that spans the files a doc set
+  cross-references, is `documentation`.
+- **documentation vs research** — `research` answers a question and files a report; `documentation`
+  writes prose that ships in the tree. If the deliverable is committed alongside the code, it is
+  `documentation`.
+
+## Properties each class guarantees
+
+These are structural facts about the resolved workflow, not advice — read them off the returned
+object rather than assuming them.
+
+- **`review`** — `hasImplementationStage: false`. There is no stage that edits source, so a review
+  run never enters implementation and never consults implementation readiness. A finding leaves the
+  workflow as its own task under its own class.
+- **`research`** — terminates at synthesis. `requiresImplementationReadiness: false`: do not run a
+  readiness check, do not report one as skipped, and do not ask for the evidence a readiness
+  template would want. If the synthesis motivates a change, that change is a new task.
+- **`documentation`** — no readiness template, by the same rule as `review` and `research`: the
+  workflow authors no source, so implementation readiness has nothing to gate. Every claim the prose
+  makes carries a locator — a figure nobody measured is the failure this class actually has. The
+  verification stage is optional, and a skip must be stated with the reason the repository has no
+  check the documentation can break.
+- **`bug`** — starts from reproduction and root cause. Do not propose or apply a fix before the
+  reproduction stage has recorded the failure and the analysis stage has supported a cause. A fix
+  proposed at intake is the thing this ordering exists to prevent.
+- **`refactor`** — needs a recorded green baseline before the first edit, so a later failure is
+  attributable to the restructuring rather than argued about.
+- **`dependency-change`** — starts from the upstream release evidence for the exact version range,
+  not from the version number. Its verification stage runs the full suite: the blast radius is not
+  bounded by the diff.
+- **`operations`** — **ungated, deliberately.** The readiness registry holds no `operations`
+  template, and the class claims none: the workflow authors no source, so
+  implementation readiness has nothing to gate. Its equivalent safeguard is the preflight
+  verification stage. Do not invent a template, and do not call `readiness --task-class operations`
+  — the verb rejects it, and rightly.
+- **`trivial-edit`** — deliberately the shortest workflow. Do not add checks to it; if it needs
+  them, it was the wrong class.
+- **`feature`** — unchanged from what `do-flow` has always run: the six-stage chain, resumed from
+  the first missing artifact, stopping at unresolved clarifications, before implementation, and
+  before commit or merge.
+
+## Reading the decision
+
+`classify` returns one object. The fields this skill acts on:
+
+- `outcome` — `ACCEPTED` or `REJECTED`. Branch on this, never on the exit code.
+- `message` — the sentence to show the user. On a rejection it already names the valid set and any
+  near-match suggestions, so surface it verbatim rather than paraphrasing it.
+- `validClasses`, `suggestions` — present on a rejection; the option set for the follow-up question.
+- `fit` — whether the class's workflow has a stage for the skill that called `classify`. See below.
+- `callerSuggestions` — present only on an `unknown-calling-skill` rejection. Skill ids, never class
+  ids: do not offer them as an answer to "which class?".
+- `workflow` — present only on `ACCEPTED`; `null` on a rejection. The run's plan of record.
+
+Within `workflow`: `stages[]` (each with `id`, `skill`, `kind`, `purpose`, `optional`,
+`readinessTemplate`, `mutatesSource`, `gatesAfter`), `stageIds`, `gates[]` (`id`, `name`,
+`afterStage`, `trigger`, `prompt`), `hasImplementationStage`,
+`requiresImplementationReadiness`, and `handoff`.
+
+## Fit: does this class have a stage for the skill asking?
+
+Pass `--calling-skill <this skill's own id>` with every `classify` call. Membership — "is this a
+real class?" — is not the same question as fit — "does this class's workflow have a stage I can
+occupy?" — and a class can pass the first while having nowhere to put your work.
+
+`fit.state` is one of four:
+
+- `HOSTED` — the class names your skill at `fit.hostedStageIds`. Proceed.
+- `NOT_APPLICABLE` — you are a router (`do`, `do-flow`): you select stages rather than occupying
+  one, so fit is judged one hop later by the skill you hand the work to.
+- `NOT_HOSTED` — a rejection. See below.
+- `NOT_EVALUATED` — **nothing was checked.** Either no calling skill was named, or it was named
+  under the wrong key. This is not a pass: the decision establishes that the class exists and
+  nothing more. Re-run with `--calling-skill`.
+
+A `caller-not-a-stage` rejection is about **you**, not about the class. Answer it from
+`fit.hostingClasses`, which lists every class that does have a stage for your skill and names the
+stage — propose one of those, or hand the work to the skill this class names for the stage you
+meant. Re-proposing the same class will be rejected the same way.
+
+## The hard hook does not know about classes
+
+`pre-implement-gate.sh` keys on branch and artifact state: if the current branch already carries a
+feature directory missing `requirement.md`, `design.md` or `plan.md`, it denies source edits
+regardless of the class in play — so a `bug` or `trivial-edit` workflow started on that branch will
+be blocked at its implementation stage. Surface the hook's message as written. Do not route around
+it, and do not create placeholder artifacts to satisfy it.

package/core/shared/skills/do-git/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: do-git
+description: "Git operations with lifecycle-aware intents and safety checks — start, save, sync, ship, release, hotfix, backport, and status, plus raw git passthrough for anything else. Use whenever the user requests git actions, branch management, committing changes, syncing with remotes, or release rituals (e.g., 'commit these files', 'ship this feature', 'create a feature branch', 'cut a hotfix', 'sync repo', 'what is git status'). Always activate this skill for safe, confirmed git operations rather than running bare mutating git commands."
+argument-hint: "[intent] [args...] [--confirm]"
+effort: medium
+---
+
+# do-git
+
+Cycle-aware git operations via named lifecycle intents. Reads policy from the repository's
+constitution or falls back to opinionated defaults. All mutating operations require explicit
+confirmation.
+
+## Invocation
+```text
+/do-git <intent> [args...] [--confirm]
+```
+
+### Intents
+
+| Intent | Description |
+|---|---|
+| `start` | Start a new task on the appropriate branch type |
+| `save` | Stage and commit current changes with intelligent message |
+| `sync` | Sync local branches with remote state |
+| `ship` | Ship the current feature/fix (merge to integration) |
+| `release` | Run the release ritual as one previewed sequence |
+| `hotfix` | Create and propagate a hotfix across all live lines |
+| `backport` | Cherry-pick a commit to another branch |
+| `status` | Report repository state and lifecycle position |
+
+### Raw Operation Passthrough
+
+Any unrecognized first token falls through to today's raw git operation behavior:
+```text
+/do-git status      # Today's raw git status (no prompt)  
+/do-git log --oneline
+/do-git diff HEAD~10
+```
+
+Existing `/do-git [operation]` invocations keep working.
+
+## Behavioral Flow
+
+Every DoFlow runtime call in this skill goes through the runtime seam. Resolve it **once** here and
+reuse `$DOFLOW` for every later call in this skill:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+### Per Intent Processing
+
+1. **Read repository state** → `"$DOFLOW" paths --json`, `"$DOFLOW" git-state` as needed
+2. **Dry-run fingerprint** (for mutable intents) → `"$DOFLOW" git-state --fingerprint`, record it, so a later step can tell whether the working tree moved underneath the plan
+3. **Compose preview sequence** → exact commands with concrete values, no placeholders. **The preview is the contract for this intent**: it is the complete set of commands that will run, in order, against the fingerprint from step 2. A command that is not in it does not run, and a step you cannot spell concretely is a step to stop on rather than to improvise at execution time
+4. **User confirmation** → explicit go/no-go before execution
+5. **Re-fingerprint** → `"$DOFLOW" git-state --fingerprint`; if changed since step 2, abort and re-preview
+6. **Execute, then report against the preview** → every command in the previewed sequence gets a reported result; one the sequence listed and the run did not reach is reported as not run, never dropped from the report
+
+### Raw Operation Passthrough Flow
+
+1. **Check state first** (`git status`) for any operation that could discard work
+2. **Gate on reversibility**: stash or confirm before destructive operations
+3. **Execute** the raw git command
+4. **Report** result, next-Step suggestion if applicable
+
+## Safety Gates
+
+The following behaviors from today's skill are carried over unchanged:
+
+- **State checks** → `git status` before anything that could discard uncommitted work
+- **Confirm before irreversible actions**:
+  - Force-pushes to any branch
+  - Pushes to production (`master`/`main`)
+  - History rewrites (rebase, reset, tag force-overwrite)
+- **No implicit approvals** → confirmation is per-command sequence, not broad permission
+
+## Boundaries
+
+**Will:**
+- Run named lifecycle intents with full preview and confirmation
+- Fall through to raw git operations for unrecognized first tokens
+- Generate commit messages from actual diff content, never from the request's wording
+- Derive branch names purely from policy plus `"$DOFLOW" git-state` — never invent one
+
+**Will Not:**
+- Forge API calls (PR/MR creation, pipeline watching) - excluded per scope boundary
+- CI/CD setup or branch protection scaffolding - excluded per scope boundary
+- Confirm multiple commands at once - each requires explicit go/no-go
+
+## Reference Files
+
+This skill loads the following reference files on demand (not parsed at runtime):
+
+- `references/lifecycle-policy.md` - default policy + override shape + forge mapping
+- `references/release-ritual.md` - release sequence, manifest rewrite, CHANGELOG drafting
+- `references/hotfix-ritual.md` - hotfix propagation rules and halt-on-conflict behavior
+
+## Examples
+
+```
+/do-git status                    # Report current lifecycle position
+/do-git start                     # Prepare for a new task (feature/fix branch)
+/do-git save                      # Stage and commit with intelligent message
+/do-git ship                      # Merge feature to integration
+/do-git release                   # Run full release ritual
+/do-git hotfix 12345              # Create hotfix from fix #12345
+/do-git log --oneline             # Raw git passthrough
+```

package/core/shared/skills/do-git/references/hotfix-ritual.md

@@ -0,0 +1,44 @@
+# Hotfix Procedure: /do-git
+
+This procedure is executed when `/do-git hotfix` is invoked. It patches production and
+propagates to every live line.
+
+## Sequence
+
+Runs inside `SKILL.md`'s Per Intent Processing sequence. This file supplies only the
+intent-specific preview content (its steps 2–3).
+
+1. **Propagation targets** → `"$DOFLOW" git-state --propagation-targets`
+2. **Preview full command sequence**:
+   - Create hotfix branch from production: `git checkout -b hotfix/<slug> production-branch`
+   - Cherry-pick or merge the fix commit(s)
+   - Tag with patch version: `git tag v<major>.<minor>.<patch>` (annotated)
+   - Merge to production without fast-forward
+   - For each target in propagation targets:
+     - If target is integration: merge hotfix branch into it
+     - If target is active release branch: cherry-pick the fix commit
+
+## Propagation Rules
+
+### Target Order
+1. Production branch (merge hotfix)
+2. Integration branch (merge hotfix)
+3. Active release branches in order of creation (cherry-pick)
+
+### Outstanding Target Definition
+A target is "outstanding" if:
+- It cannot receive the fix automatically (conflicting cherry-pick)
+- It requires manual intervention
+
+### Halt-and-Report Behavior
+On a conflicting cherry-pick:
+1. Stop propagation immediately
+2. Report all outstanding targets with conflict details
+3. Do NOT report hotfix as complete
+4. Report exact chain of commits that could not be applied
+
+## Constraints
+
+- **Hotfix merges directly to production first** before any other targets
+- **Each target's propagation status is tracked** - no silent omissions
+- **Conflict detection is required** - no forced cherry-picks without user intervention

package/core/shared/skills/do-git/references/lifecycle-policy.md

@@ -0,0 +1,54 @@
+# Lifecycle Policy: /do-git default branching policy
+
+## Default Policy Table
+
+| Field | Value |
+|---|---|
+| `trunk_names` | `main`, `develop` |
+| `feature_prefixes` | `feat`, `feature` |
+| `fix_prefixes` | `fix`, `bugfix` |
+| `integration_branch` | `develop` |
+| `production_branch` | `master` |
+| `tag_format` | `vX.Y.Z` (semver) |
+
+These are transcribed defaults, not the live ones. `"$DOFLOW" git-state` computes the branch class
+and lifecycle position from the values it actually holds — when the two disagree, the verb is right
+and this table is stale.
+
+## Tier-2 Constitution Override Shape
+
+A repo may override the default policy by adding a block under `agent-docs/constitution.md`:
+
+```markdown
+## /do-git Policy Overrides
+
+| Field | Value |
+|---|---|
+| trunk_names | Comma-separated list of trunk branch names |
+| feature_prefixes | Comma-separated list of feature branch prefixes |
+| fix_prefixes | Comma-separated list of fix branch prefixes |
+| integration_branch | The integration branch name |
+| production_branch | The production branch name |
+| tag_format | The tagging format (semver or custom) |
+```
+
+Where absent, defaults apply.
+
+## Forge Adaptation
+
+Nothing in this repo runs forge detection today, so this file describes no mechanism for it. Read
+the forge off the remote's host when the vocabulary matters (`Pull Request` on GitHub, `Merge
+Request` on GitLab); detection failure or an unknown remote degrades to plain git with the ambiguity
+stated rather than guessed.
+
+## Deviation Catalogue
+
+What counts as a policy deviation and how it's reported:
+
+| Observation | Classification | Action |
+|---|---|---|
+| Branch name doesn't match any defined pattern | Unclassifiable branch | Report deviation, continue |
+| Release branch without corresponding tag | Missing tag | Report deviation |
+| Hotfix not propagated to all active release branches | Incomplete propagation | Report outstanding targets |
+
+Deviations are **reported**, never silently corrected.

package/core/shared/skills/do-git/references/release-ritual.md

@@ -0,0 +1,64 @@
+# Release Procedure: /do-git
+
+This procedure is executed when `/do-git release` is invoked. It runs as one previewed,
+confirmed sequence.
+
+## Sequence
+
+Runs inside `SKILL.md`'s Per Intent Processing sequence. This file supplies only the
+intent-specific preview content (its steps 2–3).
+
+1. **Next version** → `"$DOFLOW" git-state --next-version`
+   - When `is_prerelease` is true the verb returns **two** candidates and picks neither:
+     `next_version` promotes the line (`1.0.0-beta.7` → `1.0.0`, because semver orders a
+     pre-release *before* its own version, so promoting it is the bump) and `next_prerelease`
+     continues it (`1.0.0-beta.8`). Put both to the user rather than assuming one — which of the
+     two is right is a product decision, not a computation.
+2. **Preview full command sequence** with the proposed version:
+   - `git checkout -b release/v<version> <integration-branch>`
+   - Update all version manifests (per policy: package.json, etc.)
+   - Draft CHANGELOG entry from commits since last tag
+   - Commit version bump
+   - `git checkout <production-branch>`, then `git merge --no-ff release/v<version>`
+   - `git tag v<version>` (annotated)
+   - `git push origin release/v<version> v<version>`
+   - Back-merge: merge the release branch back to the integration branch
+
+   Also preview the shipped features with `"$DOFLOW" lifecycle --action release --tag v<version>`
+   (it writes nothing). After the tag is created, rerun it with `--confirm`. The record is local;
+   DoFlow never stages, commits or pushes it.
+
+## Version Manifest Rewrite
+
+For each manifest file declared in policy:
+- Extract current version string using appropriate format (version, versionCode, etc.)
+- Replace with the next version `"$DOFLOW" git-state --next-version` derived
+- Leave format intact; only change the value
+
+## CHANGELOG Drafting Instruction
+
+Generate a Keep-a-Changelog style entry for `[Unreleased]`:
+- Group commits by type (feat, fix, BREAKING CHANGE)
+- For each group, list commits as bullet items
+- Include scope where inferable from changed paths
+- Use conventional commit message format as-is
+
+Example:
+```markdown
+## [v1.0.0] - YYYY-MM-DD
+### Added
+- Feature X by user
+
+### Fixed
+- Bug Y reported by user
+
+### Breaking Changes
+- Changed API Z
+```
+
+## Constraints
+
+- **Never write the version manifests until after user confirmation** (the preview above shows the
+  proposed content only)
+- **Fingerprint mismatch aborts execution** - state must be exactly as when previewed
+- **All push operations require confirmation** — see `SKILL.md`'s Safety Gates