mandrel 2.83.0 → 2.85.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/.agents/README.md +65 -20
  2. package/.agents/docs/configuration.md +36 -0
  3. package/.agents/docs/runbooks/mods.md +98 -54
  4. package/.agents/docs/workflows.md +14 -0
  5. package/.agents/instructions.md +4 -1
  6. package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
  7. package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
  8. package/.agents/schemas/story-deliver-terminal.schema.json +2 -2
  9. package/.agents/scripts/boot-sweep.js +42 -13
  10. package/.agents/scripts/coverage-capture.js +1 -0
  11. package/.agents/scripts/evidence-gate.js +1 -0
  12. package/.agents/scripts/generate-workflows-doc.js +14 -0
  13. package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
  14. package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
  15. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
  16. package/.agents/scripts/lib/close-lock-events.js +29 -9
  17. package/.agents/scripts/lib/codex/agents-projection.js +284 -0
  18. package/.agents/scripts/lib/codex/skills-projection.js +291 -0
  19. package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
  20. package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
  21. package/.agents/scripts/lib/config-resolver.js +5 -42
  22. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  23. package/.agents/scripts/lib/full-suite-lock.js +2 -0
  24. package/.agents/scripts/lib/full-suite-queue.js +66 -26
  25. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  26. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +242 -0
  27. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +151 -111
  28. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
  29. package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
  30. package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
  31. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +12 -5
  33. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +30 -4
  34. package/.agents/scripts/lib/orchestration/story-handoff.js +84 -10
  35. package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
  36. package/.agents/scripts/single-story-init.js +20 -5
  37. package/.agents/scripts/sync-agentrc.js +5 -3
  38. package/.agents/scripts/sync-claude-agents.js +20 -0
  39. package/.agents/scripts/sync-claude-commands.js +64 -27
  40. package/.agents/scripts/sync-codex-agents.js +36 -0
  41. package/.agents/scripts/sync-codex-skills.js +36 -0
  42. package/.agents/workflows/helpers/deliver-story-reference.md +6 -0
  43. package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
  44. package/.agents/workflows/mandrel-update.md +2 -1
  45. package/docs/CHANGELOG.md +23 -0
  46. package/lib/cli/guarded-sync.js +3 -2
  47. package/lib/cli/registry.js +248 -0
  48. package/lib/cli/sync-agents.js +5 -2
  49. package/lib/cli/sync-commands.js +5 -2
  50. package/lib/cli/sync.js +45 -14
  51. package/lib/cli/uninstall.js +8 -1
  52. package/lib/migrations/index.js +2 -0
  53. package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
  54. package/package.json +3 -2
package/.agents/README.md CHANGED
@@ -111,6 +111,43 @@ The bootstrap pipeline, in order:
111
111
  The bootstrap is idempotent — safe to re-run; an already-configured
112
112
  clone produces zero file mutations.
113
113
 
114
+ ### Running Mandrel from Codex
115
+
116
+ Claude Code and Codex are both supported hosts, and both are covered by the
117
+ **same install** — there is no host setting. `mandrel init`, `mandrel update`
118
+ and the `prepare` script run `mandrel sync-commands` / `mandrel sync-agents`,
119
+ which write the Claude Code projections and the Codex ones side by side, all
120
+ gitignored:
121
+
122
+ | Surface | Claude Code | Codex |
123
+ | --- | --- | --- |
124
+ | Instructions | `AGENTS.md` → `@.agents/instructions.md` | `AGENTS.md` → the read directive in the same block |
125
+ | Workflows | `.claude/commands/<name>.md`, invoked `/<name>` | `.agents/skills/workflows/<name>/SKILL.md`, invoked `$<name>` |
126
+ | Role agents | `.claude/agents/<role>.md` | `.codex/agents/mandrel-<role>.toml` |
127
+
128
+ - **Workflows.** Each Codex skill is a pointer: it tells Codex to read
129
+ `.agents/workflows/<name>.md` (or `.agents/local/workflows/<name>.md`) and
130
+ run it, with the text after `$<name>` as its arguments — e.g.
131
+ `$mandrel-plan add a CSV export`. Loop units are `$loops-<name>`.
132
+ - **Role agents.** A workflow's `subagent_type: <role>` dispatch spawns the
133
+ project custom agent `<role>` (`story-worker`, `acceptance-critic`,
134
+ `plan-critic`, `auditor`) on Codex, per `instructions.md` § 1.A. The
135
+ generated TOML inlines the security baseline and sets no `model`, so the
136
+ Codex session's model applies. Your own `.codex/agents/*.toml` files are
137
+ left alone — only `mandrel-*.toml` files carrying the generated header are
138
+ rewritten or reaped.
139
+ - **Trust the project.** Codex loads the project `.codex/` layer (and so the
140
+ role agents) only for a project it trusts; trust the checkout when Codex
141
+ asks. Skills and `AGENTS.md` load either way.
142
+ - **Instruction size.** Codex reads `AGENTS.md` only up to
143
+ `project_doc_max_bytes` (default 32768). Bootstrap puts the Mandrel block at
144
+ the top for that reason; raise the limit in `.codex/config.toml` if your own
145
+ notes below it are cut.
146
+ - **Doctor.** `mandrel doctor` adds `codex-skills-in-sync`,
147
+ `codex-agents-in-sync` (remedy: re-run `mandrel sync-commands` /
148
+ `mandrel sync-agents`) and `codex-instructions`, which fails when the
149
+ Mandrel block sits beyond the effective `project_doc_max_bytes`.
150
+
114
151
  ---
115
152
 
116
153
  ## Upgrading and local additions
@@ -154,8 +191,8 @@ Run `mandrel --help` for a subcommand list. Each subcommand supports
154
191
  | ---------- | ------- | --------- |
155
192
  | `init` | Install + configure mandrel in the current project (cold-start). | `--assume-yes`, `--skip-github`, `--dry-run` |
156
193
  | `sync` | Re-materialize `.agents/` from the installed package payload. | `--dry-run` |
157
- | `sync-commands` | Regenerate `.claude/commands/` from `.agents/workflows/`. | — |
158
- | `sync-agents` | Regenerate `.claude/agents/` from `.agents/agents/`. | — |
194
+ | `sync-commands` | Regenerate `.claude/commands/` and the Codex skills under `.agents/skills/workflows/` from `.agents/workflows/`. | — |
195
+ | `sync-agents` | Regenerate `.claude/agents/` and `.codex/agents/mandrel-<role>.toml` from `.agents/agents/`. | — |
159
196
  | `doctor` | Run readiness checks and print per-check remedies. | — |
160
197
  | `update` | Upgrade mandrel to the newest published version. | `--dry-run`, `--install-cmd` |
161
198
  | `migrate` | Apply version-keyed migrations for a version range. | `--from`, `--to`, `--dry-run` |
@@ -176,14 +213,16 @@ mandrel explain --json # same report as JSON
176
213
 
177
214
  ### `mandrel sync-commands`
178
215
 
179
- Regenerates the flat `.claude/commands/` projection from `.agents/workflows/`.
180
- Runs automatically at install time (via the `prepare` script) and as part of
216
+ Regenerates the flat `.claude/commands/` projection from `.agents/workflows/`,
217
+ and the Codex skill projection under `.agents/skills/workflows/` from the same
218
+ source set. Runs automatically at install time (via the `prepare` script) and as part of
181
219
  `mandrel sync` / `mandrel update`; doctor's `commands-in-sync` check flags a
182
- hand-edited or stale tree. Refuses to project when the materialized `.agents/`
220
+ hand-edited or stale tree, and `codex-skills-in-sync` does the same for the
221
+ Codex skills. Refuses to project when the materialized `.agents/`
183
222
  tree doesn't match the running CLI's own version — run `mandrel sync` first.
184
223
 
185
224
  ```bash
186
- mandrel sync-commands # rebuild .claude/commands/
225
+ mandrel sync-commands # rebuild .claude/commands/ and .agents/skills/workflows/
187
226
  ```
188
227
 
189
228
  ### `mandrel sync-agents`
@@ -191,11 +230,12 @@ mandrel sync-commands # rebuild .claude/commands/
191
230
  Regenerates the flat `.claude/agents/` projection from `.agents/agents/` —
192
231
  the role-scoped boot contexts (`story-worker`, `acceptance-critic`) that
193
232
  `delivery.routing.roleScopedAgents` (default `true`) dispatches spawns
194
- against. Same delegation shape, wiring, and version-match refusal as
233
+ against — and the Codex custom agents `.codex/agents/mandrel-<role>.toml`
234
+ (checked by `codex-agents-in-sync`). Same delegation shape, wiring, and version-match refusal as
195
235
  `sync-commands` above.
196
236
 
197
237
  ```bash
198
- mandrel sync-agents # rebuild .claude/agents/
238
+ mandrel sync-agents # rebuild .claude/agents/ and .codex/agents/mandrel-*.toml
199
239
  ```
200
240
 
201
241
  ### `mandrel uninstall`
@@ -217,18 +257,23 @@ mandrel uninstall --include-github # acknowledge GitHub-side manual steps
217
257
 
218
258
  ## Automatic system-prompt wiring
219
259
 
220
- The bootstrap wires the framework system prompt into a project-root
221
- `CLAUDE.md` automatically, so there is no manual "load the system prompt"
222
- step. Claude Code hydrates its always-loaded context from `CLAUDE.md`,
223
- and the wiring step (idempotent, keyed off the literal
224
- `@.agents/instructions.md` import path) does one of three things:
225
-
226
- - **No `CLAUDE.md`** → writes a minimal one carrying a `## System Prompt`
227
- heading and the `@.agents/instructions.md` import.
228
- - **`CLAUDE.md` exists but lacks the import** → appends the import block.
229
- - **`CLAUDE.md` already imports it** → no-op (no duplicate import line).
230
-
231
- If your AI tool is not Claude Code, load
260
+ The bootstrap wires the framework system prompt into the project-root
261
+ `AGENTS.md` automatically, so there is no manual "load the system prompt"
262
+ step. The block it writes carries the `@.agents/instructions.md` import that
263
+ Claude Code expands, plus a one-line read directive for hosts that expand no
264
+ `@` imports (Codex), and goes at the **top** of the file — directly after a
265
+ leading H1 heading — because Codex stops reading at `project_doc_max_bytes`.
266
+ The wiring step (idempotent, keyed off the literal import path) does one of
267
+ three things:
268
+
269
+ - **No `AGENTS.md`** → writes a minimal one carrying the `## System Prompt`
270
+ block. A root `CLAUDE.md` is folded into `AGENTS.md` and deleted first.
271
+ - **`AGENTS.md` exists but lacks the import** → inserts the block at the top.
272
+ - **`AGENTS.md` already imports it** → no-op (no duplicate import line). An
273
+ older install whose block was appended at the end is moved to the top, and
274
+ gains the read directive, by `mandrel update` (the 2.84.0 migration).
275
+
276
+ If your AI tool is neither Claude Code nor Codex, load
232
277
  [`instructions.md`](instructions.md) verbatim through that tool's own
233
278
  system-prompt mechanism (`.cursorrules`, Custom Instructions, etc.).
234
279
 
@@ -592,6 +592,42 @@ your real handle, and the guards proceed. By contrast, `github.owner` / `repo`
592
592
  are **shared** repo identifiers (everyone targets the same `dsj1984/mandrel`)
593
593
  and stay committed with real values.
594
594
 
595
+ #### Multi-operator repos
596
+
597
+ When several developers run Mandrel against one repo, keep the committed
598
+ `.agentrc.json` team-shared and put each operator's identity in their own
599
+ `.agentrc.local.json`:
600
+
601
+ | Key | Committed `.agentrc.json` | Per-operator `.agentrc.local.json` |
602
+ | --- | --- | --- |
603
+ | `github.owner` / `github.repo` | Real shared values | — |
604
+ | `github.operatorHandle` | The `@[USERNAME]` placeholder | `"@your-handle"` |
605
+ | `project.baseBranch` | The team's integration branch (omit only when it is `main`) | Your personal base branch, e.g. `"dev-<name>"`, when you do not work off the team branch |
606
+
607
+ ```json
608
+ {
609
+ "project": { "baseBranch": "dev-your-name" },
610
+ "github": { "operatorHandle": "@your-handle" }
611
+ }
612
+ ```
613
+
614
+ Both the runtime resolver and `node .agents/scripts/sync-agentrc.js` (the
615
+ `/mandrel-update` Step 3 check) validate the **merged** config, so a key
616
+ supplied only by the overlay satisfies the schema on your machine.
617
+
618
+ **Keep the placeholder committed.** CI runners and fresh clones have no
619
+ `.agentrc.local.json`. If you drop `github.operatorHandle` from the committed
620
+ file entirely, every overlay-less run, CI included, fails schema validation
621
+ with `/github must have required property 'operatorHandle'`. The error names
622
+ both remedies: set the handle in `.agentrc.local.json`, or keep `@[USERNAME]`
623
+ committed. The placeholder names no real person, so the committed file never
624
+ makes one developer the fallback identity for everyone else.
625
+
626
+ **Commit a non-`main` integration branch.** `project.baseBranch` defaults to
627
+ `main`. If the team integrates elsewhere, commit that branch to `.agentrc.json`.
628
+ Otherwise a developer without an overlay silently seeds Story branches from,
629
+ and opens PRs against, `main`.
630
+
595
631
  ### Adding a new top-level key (framework change)
596
632
 
597
633
  This is a framework-level change, not a project-level one. The path is:
@@ -18,31 +18,58 @@ until a developer loads it. This runbook is listed at the end of every
18
18
  above the prompt while you work in a Mandrel checkout. It follows one
19
19
  Story: the newest one in flight (a `.worktrees/story-<id>/` with no newer
20
20
  terminal envelope), otherwise the newest
21
- `story-deliver-terminal-<id>.json` from the last 2 hours. With neither, or
22
- with no `.agents/` in the checkout, it draws nothing.
21
+ `story-deliver-terminal-<id>.json` on disk. A `landed` result shows for 10
22
+ minutes; any other result shows for 2 hours. With neither, or with no
23
+ `.agents/` in the checkout, it draws nothing.
23
24
 
24
- **Line 1** is an outcome glyph (none, `✓` or `✗`), then
25
- `mandrel · #<id> <title>`, with the PR and its checks on the right when
26
- they are known. **Line 2** is the stage strip, the current step and the
27
- time:
25
+ The band is **one quiet line while the Story is healthy**. A second line
26
+ appears only when the Story needs a look, and it never repeats line 1:
28
27
 
29
28
  ```text
30
- mandrel · #5552 mandrel-status band v2 · PR #5560 checks pending
31
- ✓ start ─ ✓ build ─ ✓ check ─ ✓ handoff ─ ● close ─ ○ merge · gate lint · 1m10s of usual ~1m30s
29
+ ● #5552 mandrel-status band v2 ▰▰▰▰▰▱ close · gate lint 1:10 / ~1:30
30
+ ▲ #5552 mandrel-status band v2 ▰▰▰▰▰▱ close · code-review 6:12 / ~2:00
31
+ ↳ 3.1× usual · gate log quiet 4m · last gate test
32
+ ◆ #5552 mandrel-status band v2 needs you at check · acceptance-unmet
33
+ ↳ /mandrel-deliver 5552 --resume AC-3, AC-5 [Copy]
32
34
  ```
33
35
 
34
- `✓` marks a finished stage, `●` the current one and `○` the ones to come.
35
- Each stage comes from a file delivery already writes, and the latest
36
- evidence wins:
36
+ **Attention.** One value picks the glyph, the color and whether line 2
37
+ shows:
37
38
 
38
- | Stage | Evidence | Detail shown |
39
+ | Attention | When | Glyph | Color | Line 2 |
40
+ | --- | --- | --- | --- | --- |
41
+ | working | in flight, on pace | `●` | dim | none |
42
+ | slow | in flight and past its usual time | `▲` | yellow | the ratio to usual, how long the close-gates log has been quiet, the last gate |
43
+ | needs you | a `blocked` result: the HITL pause | `◆` | magenta | `↳ <nextCommand>`, plus the unmet acceptance ids when it stopped at check; a `Copy` button copies the command |
44
+ | failed | a `failed` or `escalated` result, or a PR whose checks are red | `✗` | red | `↳ <nextCommand>`, or `↳ PR #<n> checks failing` with an `Open PR` link |
45
+ | landed | a `landed` result | `✓` | green | none |
46
+
47
+ **Line 1** is the glyph, `#<id>`, the title cut to 30 columns, then:
48
+
49
+ - **in flight:** a six-cell meter (`▰` per finished or current stage, `▱`
50
+ per stage to come), the current step, and the time in the current phase
51
+ against its usual time (`2:00 / ~1:30`; `/ ~<usual>` is left out until
52
+ there are 3 samples). A pending result shows `pending` in place of the
53
+ time.
54
+ - **stopped:** `needs you at <stage> · <blockClass>` or
55
+ `failed at <stage> · <failure.reason>`.
56
+ - **landed:** `landed in <elapsed> · PR #<n> · <k> follow-ups`, where `k`
57
+ counts the bullets in `follow-ups-rollup-<id>.md`.
58
+
59
+ Times read `m:ss`, or `h:mm:ss` past an hour.
60
+
61
+ **Stages and steps.** Each stage comes from a file delivery already writes,
62
+ and the latest evidence wins. The step names the stage, plus what it is
63
+ doing when that is known:
64
+
65
+ | Stage | Evidence | Step shown |
39
66
  | --- | --- | --- |
40
- | `start` | `<tempRoot>/orchestration/story-init-result-<id>.log` | `initialized`; the Story title on line 1 comes from this log |
41
- | `build` | `commit…` lines in the worktree's reflog (`logs/HEAD` under its gitdir) | commit count and the last subject |
42
- | `check` | the highest `<tempRoot>/scratch/story-<id>/acceptance-verdict-round-<n>.json` | `round <n> · <met>/<total> met` |
43
- | `handoff` | the newest `story-handoff-<id>-<step>.log`; `story-handoff-<id>.json` ends the stage | the step name, or `handed off` |
44
- | `close` | `close-gates-<id>.log` | the gate named by its last line's `[name]` prefix |
45
- | `merge` | a terminal envelope with `status` `pending`, or a progress file in `auto-merge` / `confirm-merge` | the PR number and the phase |
67
+ | `start` | `<tempRoot>/orchestration/story-init-result-<id>.log` | `start`; the Story title on line 1 comes from this log |
68
+ | `build` | `commit…` lines in the worktree's reflog (`logs/HEAD` under its gitdir) | `build · <n> commits` |
69
+ | `check` | the highest `<tempRoot>/scratch/story-<id>/acceptance-verdict-round-<n>.json` | `check · round <n> · <met>/<total> met` |
70
+ | `handoff` | the newest `story-handoff-<id>-<step>.log`; `story-handoff-<id>.json` ends the stage | `handoff · <step>` |
71
+ | `close` | `close-gates-<id>.log` | `close · gate <name>` from its last line's `[name]` prefix, or the close phase |
72
+ | `merge` | a terminal envelope with `status` `pending`, or a progress file in `auto-merge` / `confirm-merge` | `merge · PR #<n> · <phase>` |
46
73
 
47
74
  A commit made after the last verdict round puts the Story back in `build`.
48
75
  When `story-progress-<id>.json` is present and newer than everything else,
@@ -50,41 +77,55 @@ it decides the stage, the step or close phase and the PR number. The band
50
77
  never needs it: without it, every stage still shows, and only the close
51
78
  sub-phase after validation is unknown.
52
79
 
53
- **Learned ETAs.** For each close phase, the band takes the median of
54
- `phaseDurations` over the newest 30 terminal envelopes on disk, and
55
- recomputes it at most every 10 minutes. Once a phase has 3 or more samples,
56
- line 2 reads `<elapsed> of usual ~<median>`. The phase counts as stalled when
57
- its elapsed time passes the larger of twice the median and 2 minutes. With
58
- fewer samples, a close whose gate log has been quiet for 10 minutes is
59
- stalled instead (`stalled? no gate output for <n>m`). Elapsed time runs from
60
- the progress file's `phaseStartedAt` when it is there, else from when the
61
- stage's evidence began.
62
-
63
- **Results.** A `landed` envelope collapses the band to one line:
64
- `✓ mandrel · #<id> <title> · landed in <elapsed> · PR #<n> · <k> follow-ups`,
65
- where `k` counts the bullets in `follow-ups-rollup-<id>.md`. A `blocked`,
66
- `failed` or `escalated` envelope puts its `blocked.blockClass` or
67
- `failure.reason` on line 1 and replaces line 2 with `next: <nextCommand>`,
68
- the command that resumes the work.
69
-
70
- **Run line.** When a `<tempRoot>/run-<id>/ledger.json` was updated in the
71
- last 2 hours and still has a Story without a `landed` envelope, a third line
72
- reads `run <landed>/<total> landed · #<id> <stage> · <queued> queued`.
73
-
74
- **Colors.** Dim by default, yellow when stalled, red for `blocked` /
75
- `failed` / `escalated`, green for `landed`.
76
-
77
- **Width.** Under 80 body columns only line 1 shows. Long text is cut short
78
- with `…`, never wrapped.
79
-
80
- **Buttons.** `Hide` hides the band for this session until the followed
81
- Story changes. `Details` opens the `mandrel-status` pane, which lists each
82
- stage with its start time and duration, the handoff steps, and the close
83
- phases with their recorded and usual durations.
84
-
85
- It also toasts once when a terminal envelope appears with `status` `landed`
86
- or `blocked`. Results already on disk when the session starts are not
87
- toasted, and a hot reload does not repeat one.
80
+ **Usual times.** Close and merge phases use the median of `phaseDurations`
81
+ over the newest 30 terminal envelopes on disk, recomputed at most every 10
82
+ minutes. Start, build, check and handoff have no recorded durations once
83
+ temp is purged, so the band learns them itself. Each time the Story it
84
+ follows moves past one of those stages, it keeps how long the stage took
85
+ (the newest 30 per stage, in the mod's own state). Each median counts once
86
+ it has 3 samples, so these usual times start empty on a new machine and
87
+ fill in as you deliver. A phase or stage is **slow** when its elapsed time
88
+ passes the larger of twice the median and 2 minutes. With fewer samples, a
89
+ close whose gate log has been quiet for 10 minutes is slow instead.
90
+ Elapsed time runs from the progress file's `phaseStartedAt` when it is
91
+ there, else from when the stage's evidence began.
92
+
93
+ **Run chips.** When a `<tempRoot>/run-<id>/ledger.json` was updated in the
94
+ last 2 hours, line 1 ends with `run <landed>/<total>` and one chip per
95
+ ledger Story, in ledger order: `✓` landed, `◆` needs you, `✗` failed, `●`
96
+ the Story the band follows, `◐` another dispatched Story, `○` not
97
+ dispatched yet. The followed Story is always its own chip, so the band
98
+ never names two Stories without showing how they relate.
99
+
100
+ **Run roll-up.** Once every ledger Story has a result, the band shows one
101
+ line for the run instead:
102
+ `◆ run 2/3 landed in 35:00 · #5545 needs you at confirm-merge ✓5543 ✓5544 ◆5545`.
103
+ It leads with the first Story that did not land and takes that Story's
104
+ color. A run that landed whole shows in green for 10 minutes; a run with a
105
+ Story that did not land stays while its ledger is live.
106
+
107
+ **Width.** Under 80 body columns, line 1 drops the title and the run chips.
108
+ An attention state keeps its second line. Long text is cut short with
109
+ `…`, never wrapped.
110
+
111
+ **Buttons.** `Hide` hides the band for this Story and attention state.
112
+ The band comes back when either changes, so hiding a healthy band never
113
+ hides a later slow, needs-you or failed state. `Details` opens the
114
+ `mandrel-status` pane:
115
+
116
+ - a header with the Story, its attention and its total time;
117
+ - a `NEEDS ATTENTION` block when the Story is slow, needs you or failed,
118
+ with the slow phase's time, usual time and ratio, or the problem, the
119
+ unmet acceptance ids and the next command;
120
+ - a `TIMELINE`, one row per stage with its start time, its duration and a
121
+ bar, plus the close phases indented under close. Every bar shares one
122
+ scale, and `▏` marks the usual time;
123
+ - the run chips, when a run is live.
124
+
125
+ **Toasts.** The band toasts once for each result (`landed`, `blocked`,
126
+ `failed`, `escalated`) and once the first time a Story turns slow. Results
127
+ already on disk when the session starts are not toasted, and a hot reload
128
+ does not repeat one.
88
129
 
89
130
  **Where it reads.** Every path is relative to the main checkout. A session
90
131
  running in a linked worktree (for example `.claude/worktrees/<name>`, which
@@ -92,7 +133,10 @@ holds no `temp/` or `.worktrees/`) has a `.git` file reading
92
133
  `gitdir: <main>/.git/worktrees/<name>`, and the band reads from that
93
134
  `<main>`. `tempRoot` is `project.paths.tempRoot` from
94
135
  `.agentrc.local.json`, then `.agentrc.json`, and defaults to `temp`. The
95
- band refreshes on session start, after each turn and every 15 seconds.
136
+ `Open PR` link uses the envelope's `pr.url`, else
137
+ `https://github.com/<github.owner>/<github.repo>/pull/<n>` from the same
138
+ config. The band refreshes on session start, after each turn and every 15
139
+ seconds.
96
140
 
97
141
  ### Turn it on
98
142
 
@@ -20,6 +20,20 @@ up as a bare `/<name>` slash command (e.g. `/mandrel-deliver`). The projection
20
20
  writes only `.claude/commands/<name>.md` — there is no plugin manifest and no
21
21
  marketplace listing. The commands load in every Claude Code environment.
22
22
 
23
+ **Codex.** The same sync also writes one Codex skill per command to
24
+ `.agents/skills/workflows/<name>/SKILL.md`, invoked as `$<name>` (e.g.
25
+ `$mandrel-plan`; loop units as `$loops-<name>`). Each skill points Codex at
26
+ the workflow file and passes the text after `$<name>` as its arguments.
27
+ `npm run sync:agents` likewise writes the role agents a workflow dispatches
28
+ (`subagent_type: <role>`) as Codex custom agents
29
+ `.codex/agents/mandrel-<role>.toml`; Codex loads those only in a trusted
30
+ project. `mandrel doctor` checks both projections
31
+ (`codex-skills-in-sync`, `codex-agents-in-sync`) and that Codex reads the
32
+ Mandrel block of `AGENTS.md` (`codex-instructions`). To refresh only the
33
+ Codex half, run `node .agents/scripts/sync-codex-skills.js` or
34
+ `node .agents/scripts/sync-codex-agents.js`. Setup: the
35
+ [`.agents/README.md`](../README.md#running-mandrel-from-codex) Codex section.
36
+
23
37
  Loop units are the one namespaced exception: files under
24
38
  `.agents/workflows/loops/<name>.md` project to
25
39
  `.claude/commands/loops/<name>.md` and are invoked as the namespaced
@@ -17,7 +17,10 @@ No persona packs, no `persona::*` labels — constraints come from this
17
17
  file, the rules, and skills; "act as [role]" means apply the matching
18
18
  skill or workflow guidance. Role-scoped spawn contexts live under
19
19
  `.agents/agents/` (`delivery.routing.roleScopedAgents`); `qa.personas`
20
- is a separate fixture concept.
20
+ is a separate fixture concept. **Host mapping:** a `subagent_type: <role>`
21
+ dispatch uses the Agent tool on Claude Code and spawns the project custom
22
+ agent named `<role>` on Codex; `general-purpose` means the host's default
23
+ agent.
21
24
 
22
25
  ### B. Skill Activation
23
26