mandrel 1.58.0 → 1.60.0

package/.agents/README.md

@@ -1,58 +1,62 @@
-# Mandrel — `.agents/`
-
-This is the framework payload (`.agents/`) consumed by host repos. It ships
-inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
-npm package and is materialized into a consumer's `./.agents/` directory by
-`mandrel sync`. It carries a system prompt, a baseline rule pack, a
-two-tier skill library, a slash-command workflow set, and the
-orchestration engine that runs Epic → Feature → Story plans on
-GitHub. The framework version is the version of the installed
-[`mandrel`](https://www.npmjs.com/package/mandrel) npm
-package — run `npm ls mandrel` (or read `package.json`), not a
-count here.
+# Mandrel Framework
+
+An opinionated workflow framework for AI coding assistants built on
+Epic-centric GitHub orchestration. Planning, execution, and state all live natively in GitHub Issues, Labels, and Projects V2.
+
+This is the consumer README inside the distributed `.agents/` bundle. It explains what each part of the bundle is for and captures the cross-directory authoring conventions. The process narrative for
+`/plan` and `/deliver` stays in [`docs/SDLC.md`](docs/SDLC.md).
 
-> **Ticket hierarchy.** Mandrel uses a **3-tier hierarchy**
-> (Epic → Feature → Story) with inline `acceptance[]` / `verify[]` on
-> Story bodies. See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the
-> diagram and execution-model implications.
+The framework payload (`.agents/`) is consumed by host repos. It ships inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
+npm package and is materialized into a consumer's `./.agents/` directory by `mandrel sync`. It carries a system prompt, a baseline rule pack, a two-tier skill library, a slash-command workflow set, and the orchestration engine that runs Epic → Story plans on GitHub.
 
-This is the only README inside the distributed `.agents/` bundle. It
-explains what each part of the bundle is for and captures the
-cross-directory authoring conventions. The process narrative for
-`/epic-plan` and `/epic-deliver` stays in [`docs/SDLC.md`](docs/SDLC.md).
+The framework version is the version of the installed [`mandrel`](https://www.npmjs.com/package/mandrel) npm package — run `npm ls mandrel` (or read `package.json`), not a
+count here.
 
 ---
 
 ## Activation
 
-### Cold start — `npx create-mandrel`
+### All-in-one Install
 
-The canonical cold-start path is a single launcher command, run from the
-root of your project (the folder does **not** need to be a git repo yet):
+From an **empty or existing** local directory, run:
 
 ```bash
-npx create-mandrel        # install mandrel → mandrel sync → bootstrap.js
+npx mandrel init        # install (if absent) → prompt: configure now, or just the files
 ```
 
-`create-mandrel` installs `mandrel`, materializes `./.agents/` via
-`mandrel sync` (skipping the install when `.agents/` already exists), and
-finishes by running `node .agents/scripts/bootstrap.js`, forwarding any flags
-you pass. After it completes, run **`/onboard`** inside Claude Code for the
-guided first run — stack detection, docs scaffolding, a `mandrel doctor`
-readiness gate, and a started `/epic-plan` handoff.
+`mandrel init` first **installs the framework if `./.agents/` is absent** —
+`npm install mandrel --ignore-scripts` followed by an explicit `mandrel sync`,
+so the materialization is a single deterministic step rather than a
+postinstall-then-init double sync. When `./.agents/` already exists from a prior install, it skips straight to the prompt — the one subcommand is idempotent across both entry points.
+
+It then shows a **two-option prompt**:
+
+1. **Configure now** — runs `node .agents/scripts/bootstrap.js`, forwarding any
+   passthrough flags unchanged, to wire the project and GitHub side (creates the
+   GitHub repo + Projects board).
+2. **Just the files** — stops after materialization and prints a re-run hint
+   (`mandrel init`) so you can configure later.
 
-The remainder of this section documents the manual steps `create-mandrel`
-wraps, for operators who prefer to drive them by hand.
+`--assume-yes` skips the prompt and configures non-interactively (the flag is
+also forwarded to `bootstrap.js`); a non-TTY run without `--assume-yes` defaults
+to **files-only**, so the side-effecting GitHub provisioning never runs
+unattended.
 
-### Manual cold start — install the npm package
+After it completes, run **`/onboard`** inside Claude Code for the guided first
+run — stack detection, docs scaffolding, a `mandrel doctor` readiness gate, and
+a started `/plan` handoff.
+
+### Manual Install
+
+This section documents the manual steps `mandrel init` wraps, for operators who prefer to drive them by hand.
+
+#### Mandrel Package
 
 From an **empty or existing** project that does not yet have `.agents/`,
 install the package and materialize the framework payload:
 
 ```bash
 npm install mandrel
-# pnpm add mandrel
-# yarn add mandrel
 ```
 
 Installing `mandrel` pins an exact, provenance-signed version in
@@ -69,13 +73,43 @@ npx mandrel sync --dry-run # preview the planned copies, write nothing
 npx mandrel doctor         # confirm the install is healthy
 ```
 
-Then run the bootstrap to wire the project and GitHub side:
+#### Bootstrap Config
 
-```bash
-node .agents/scripts/bootstrap.js
-```
+To wire the local directory and GitHub, run `npx mandrel init` again or use the bootstrapper directly: `node .agents/scripts/bootstrap.js`
+
+The bootstrap pipeline, in order:
+
+1. **Preflight gate (runs first, before any mutation).** A single
+   fail-before-mutate check confirms Node is at the required major
+   version, `git` is on `PATH`, the command is running inside a git work
+   tree, and — unless `--skip-github` is set — that the `gh` CLI is
+   installed and authenticated. If any check fails the bootstrap prints
+   each failing check's remedy and halts with exit 1 **before** touching
+   a single file or making a GitHub call, so a half-configured repo is
+   never left behind.
+2. **Resolve answers (owner / repo / base branch / operator handle /
+   project number).** Defaults are inferred from the local `git remote`
+   and config (no network calls). Each value is resolved through a
+   priority chain: CLI flag → environment variable
+   (`GH_OWNER`, `GH_REPO`, …) → silently-accepted inferred default →
+   interactive picker → free-text prompt → `--assume-yes` default.
+3. **Project-side mutations.** Seeds `.agentrc.json` from
+   [`starter-agentrc.json`](starter-agentrc.json), merges the framework's
+   runtime dependencies into `package.json`, runs the install, wires the
+   command-sync hook (the UserPromptSubmit hook that regenerates the flat
+   `.claude/commands/` tree so every `/<command>` loads), wires the system
+   prompt (see below), gitignores derived artefacts, and runs the
+   quality-gates installer.
+4. **GitHub-side mutations.** Creates the label taxonomy, Project V2
+   fields, branch protection, and merge-method settings. Skipped with
+   `--skip-github`.
 
-### Upgrading and local additions
+The bootstrap is idempotent — safe to re-run; an already-configured
+clone produces zero file mutations.
+
+---
+
+## Upgrading and local additions
 
 Once installed, the ongoing upgrade path is **`mandrel update`** — it bumps
 `mandrel` to the newest non-major version, re-runs `mandrel sync`,
@@ -107,53 +141,9 @@ the consumer-owned space `mandrel sync` never copies into nor prunes and the
 drift check treats as sanctioned, so keep project-specific skills and local
 workflow fragments there rather than editing synced files in place.
 
-### Run the unified bootstrap directly
-
-When `.agents/` is already materialized, run the bootstrap straight from the
-host repo root:
-
-```bash
-node .agents/scripts/bootstrap.js
-# bootstrap also seeds a discoverable npm alias, so after the first run:
-npm run bootstrap
-```
-
-The bootstrap adds an `npm run bootstrap` script to the consumer's
-`package.json` (pointing at `node .agents/scripts/bootstrap.js`) the
-first time it runs — an operator-defined `bootstrap` script always wins,
-so the seed is skipped when the key already exists.
-
-The bootstrap pipeline, in order:
-
-1. **Preflight gate (runs first, before any mutation).** A single
-   fail-before-mutate check confirms Node is at the required major
-   version, `git` is on `PATH`, the command is running inside a git work
-   tree, and — unless `--skip-github` is set — that the `gh` CLI is
-   installed and authenticated. If any check fails the bootstrap prints
-   each failing check's remedy and halts with exit 1 **before** touching
-   a single file or making a GitHub call, so a half-configured repo is
-   never left behind.
-2. **Resolve answers (owner / repo / base branch / operator handle /
-   project number).** Defaults are inferred from the local `git remote`
-   and config (no network calls). Each value is resolved through a
-   priority chain: CLI flag → environment variable
-   (`GH_OWNER`, `GH_REPO`, …) → silently-accepted inferred default →
-   interactive picker → free-text prompt → `--assume-yes` default.
-3. **Project-side mutations.** Seeds `.agentrc.json` from
-   [`starter-agentrc.json`](starter-agentrc.json), merges the framework's
-   runtime dependencies into `package.json`, runs the install, wires the
-   command-sync hook (the UserPromptSubmit hook that regenerates the flat
-   `.claude/commands/` tree so every `/<command>` loads), wires the system
-   prompt (see below), gitignores derived artefacts, and runs the
-   quality-gates installer.
-4. **GitHub-side mutations.** Creates the label taxonomy, Project V2
-   fields, branch protection, and merge-method settings. Skipped with
-   `--skip-github`.
-
-The bootstrap is idempotent — safe to re-run; an already-configured
-clone produces zero file mutations.
+---
 
-### Automatic system-prompt wiring
+## Automatic system-prompt wiring
 
 The bootstrap wires the framework system prompt into a project-root
 `CLAUDE.md` automatically, so there is no manual "load the system prompt"
@@ -170,7 +160,9 @@ If your AI tool is not Claude Code, load
 [`instructions.md`](instructions.md) verbatim through that tool's own
 system-prompt mechanism (`.cursorrules`, Custom Instructions, etc.).
 
-### Interactive repo / project pickers
+---
+
+## Interactive repo / project pickers
 
 When the bootstrap runs interactively (a TTY, and `--assume-yes` is not
 set), the **repo** and **project-number** questions render a live,
@@ -195,14 +187,16 @@ For non-interactive (CI) installs, pass `--owner`, `--repo`, and
 After bootstrap, every Mandrel command is generated into a flat
 `.claude/commands/` tree by `npm run sync:commands` (the UserPromptSubmit hook
 keeps it current) and loads as a bare `/<command>` slash command — e.g.
-`/epic-plan`, `/story-plan`, `/story-deliver`, `/audit-security`. The
+`/plan`, `/plan`, `/deliver`, `/audit-security`. The
 commands load in every Claude Code environment. The [SDLC guide](docs/SDLC.md) walks
 an end-to-end Epic; standalone Stories pair
-[`/story-plan`](workflows/story-plan.md) (idea → drafted Story
-Issue) with [`/story-deliver`](workflows/story-deliver.md) (Story Issue → merged
+[`/plan`](workflows/helpers/plan-story.md) (idea → drafted Story
+Issue) with [`/deliver`](workflows/helpers/deliver-stories.md) (Story Issue → merged
 PR).
 
-### Runtime dependencies
+---
+
+## Runtime dependencies
 
 The framework scripts under `.agents/scripts/` import a small set of
 third-party npm packages at runtime. The materialized `./.agents/` tree
@@ -237,12 +231,20 @@ in `runtime-deps.json`.
 
 ---
 
+## Ticket Hierarchy
+
+Mandrel uses a **2-tier hierarchy** (Epic → Story) with inline `acceptance[]` / `verify[]` on story bodies.
+
+See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execution-model implications.
+
+---
+
 ## Contents
 
 | Path | Purpose |
 | ---- | ------- |
 | [`instructions.md`](instructions.md) | Primary system prompt loaded by the host AI tool. |
-| [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/epic-plan` and `/epic-deliver`. |
+| [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/plan` and `/deliver`. |
 | [`starter-agentrc.json`](starter-agentrc.json) | Bootstrap delta-seed copied to the consumer repo root as `.agentrc.json`. |
 | [`agentrc-reference.json`](docs/agentrc-reference.json) | Exhaustive editor reference enumerating every schema key with its framework default. |
 | [`personas/`](personas/) | Role-specific behavior packs selected by task persona or explicit user instruction. |
@@ -443,7 +445,7 @@ sessions, `gh auth login` is sufficient.
 ## Self-Healing Checks
 
 `scripts/lib/checks/` is the discovery-based registry of named checks
-consumed by preflight guards (`/epic-deliver`, `/story-close`, `npm test`),
+consumed by preflight guards (`/deliver`, `/story-close`, `npm test`),
 the `diagnose.js` ad-hoc viewer, and the retro surface. Use one check per
 file. The runner (`index.js`) loads checks at process start and filters by
 scope at each call site.
@@ -567,7 +569,7 @@ Schema conventions:
 ## Code review providers (pluggable chain)
 
 `runCodeReview()` (invoked at the end of `helpers/epic-deliver-story`,
-`helpers/single-story-deliver`, and `/epic-deliver`'s `delivery.code-review`
+`helpers/single-story-deliver`, and `/deliver`'s `delivery.code-review`
 state) loads its review backend through a pluggable registry. Two configuration shapes are supported:
 
 - **Legacy single provider** — `delivery.codeReview.provider: "native"`
@@ -719,7 +721,7 @@ falls from minutes to under a second.
 ## Multi-developer coordination
 
 Two operators can drive the same repository at once — one running
-`/epic-deliver <id>`, another running `/single-story-deliver <id>`, or two
+`/deliver <id>`, another running `/single-story-deliver <id>`, or two
 operators on the same Epic from separate clones. The framework keeps those
 runs from clobbering one another with **two distinct coordination layers**.
 They solve different problems and must not be confused:
@@ -761,7 +763,7 @@ yanks the claim back from whoever legitimately took over.
 
 **Where it's wired:**
 
-- **`/epic-deliver`** acquires the lease on the **Epic** ticket during its
+- **`/deliver`** acquires the lease on the **Epic** ticket during its
   prepare phase, before any mutating git work
   ([`epic-deliver-lease-guard.js`](scripts/lib/orchestration/epic-deliver-lease-guard.js)).
   A live foreign claim refuses the run; pass `--steal` to override and
@@ -774,7 +776,7 @@ yanks the claim back from whoever legitimately took over.
   ([`single-story-lease-guard.js`](scripts/lib/orchestration/single-story-lease-guard.js)).
   The standalone path requires `github.operatorHandle` to be set — without
   an operator identity the lease has no owner to record.
-- **`/epic-plan`** acquires the lease on the **Epic** ticket before Phase 7
+- **`/plan`** acquires the lease on the **Epic** ticket before Phase 7
   (spec) and releases it after Phase 8 (decompose)
   ([`epic-plan-lease-guard.js`](scripts/lib/orchestration/epic-plan-lease-guard.js)).
   Because planning emits no `story.heartbeat` (heartbeats are a
@@ -793,7 +795,7 @@ confuse:
 
 | File                              | Audience                          | Role                                                                                                                              |
 | --------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `.agentrc.json` (repo root)       | The framework dogfooding itself   | Live config used when running `/epic-*`, `/story-deliver` against this repo. Exercises the framework end-to-end. |
+| `.agentrc.json` (repo root)       | The framework dogfooding itself   | Live config used when running `/epic-*`, `/deliver` against this repo. Exercises the framework end-to-end. |
 | `.agents/starter-agentrc.json`    | Downstream consumer repos         | Bootstrap delta-seed a consumer copies via `cp .agents/starter-agentrc.json .agentrc.json`. Minimum schema-required keys.        |
 | `.agents/docs/agentrc-reference.json`       | Operators and reviewers           | Exhaustive editor reference enumerating every schema key with its framework default. Not a copy target.                          |