mandrel 2.82.0 → 2.84.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.
- package/.agents/README.md +65 -20
- package/.agents/docs/configuration.md +40 -3
- package/.agents/docs/runbooks/mods.md +98 -54
- package/.agents/docs/workflows.md +14 -0
- package/.agents/instructions.md +4 -1
- package/.agents/mods/mandrel-status/hooks/register.tsx +579 -204
- package/.agents/mods/mandrel-status/types/index.d.ts +58 -13
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/boot-sweep.js +42 -13
- package/.agents/scripts/coverage-capture.js +55 -24
- package/.agents/scripts/evidence-gate.js +7 -1
- package/.agents/scripts/generate-workflows-doc.js +14 -0
- package/.agents/scripts/lib/baselines/duplication-scanner.js +26 -2
- package/.agents/scripts/lib/bootstrap/agents-md-fold.js +99 -16
- package/.agents/scripts/lib/bootstrap/manifest.js +4 -4
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +16 -1
- package/.agents/scripts/lib/close-lock-events.js +109 -0
- package/.agents/scripts/lib/close-validation/commands.js +12 -0
- package/.agents/scripts/lib/close-validation/gates.js +6 -0
- package/.agents/scripts/lib/close-validation/process.js +5 -2
- package/.agents/scripts/lib/close-validation/runner.js +14 -4
- package/.agents/scripts/lib/codex/agents-projection.js +284 -0
- package/.agents/scripts/lib/codex/skills-projection.js +291 -0
- package/.agents/scripts/lib/config/agentrc-overlay.js +91 -0
- package/.agents/scripts/lib/config/sync-agentrc.js +39 -19
- package/.agents/scripts/lib/config-resolver.js +5 -42
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/config-settings-schema.js +1 -1
- package/.agents/scripts/lib/full-suite-lock.js +20 -0
- package/.agents/scripts/lib/full-suite-queue.js +24 -56
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/observability/source-classifier.js +2 -0
- package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +152 -0
- package/.agents/scripts/lib/orchestration/review-providers/codex.js +33 -105
- package/.agents/scripts/lib/orchestration/review-providers/provider-severity.js +30 -0
- package/.agents/scripts/lib/orchestration/review-providers/security-review.js +3 -17
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +73 -63
- package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +70 -0
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +3 -0
- package/.agents/scripts/lib/single-story-sweep/reconcile-closing.js +89 -0
- package/.agents/scripts/lib/supervised-suite.js +8 -28
- package/.agents/scripts/single-story-init.js +20 -5
- package/.agents/scripts/sync-agentrc.js +5 -3
- package/.agents/scripts/sync-claude-agents.js +20 -0
- package/.agents/scripts/sync-claude-commands.js +64 -27
- package/.agents/scripts/sync-codex-agents.js +36 -0
- package/.agents/scripts/sync-codex-skills.js +36 -0
- package/.agents/workflows/helpers/mandrel-sync-config.md +16 -9
- package/.agents/workflows/mandrel-update.md +2 -1
- package/README.md +167 -216
- package/docs/CHANGELOG.md +25 -0
- package/lib/cli/guarded-sync.js +3 -2
- package/lib/cli/registry.js +248 -0
- package/lib/cli/sync-agents.js +5 -2
- package/lib/cli/sync-commands.js +5 -2
- package/lib/cli/sync.js +45 -14
- package/lib/cli/uninstall.js +8 -1
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.84.0-hoist-system-prompt-block.js +64 -0
- 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
|
-
|
|
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
|
|
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
|
|
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
|
|
221
|
-
`
|
|
222
|
-
step.
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
|
|
@@ -86,7 +86,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
87
|
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
|
|
88
88
|
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution). |
|
|
89
|
-
| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer
|
|
89
|
+
| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command run as a close-validation gate. Left unset (the `null` default), it falls back to `npm run typecheck`. An explicit `null` disables the gate for projects with no type layer: close reports it as skipped (`typecheck-disabled`) and runs nothing. The empty string is rejected so a typo cannot silently disable it. |
|
|
90
90
|
| `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
|
|
91
91
|
| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
|
|
92
92
|
| `commands.formatWrite` | No | `string` | `"npx biome format --write ."` | Mutating format command the close-time format-autofix step spawns. |
|
|
@@ -294,8 +294,9 @@ names or defaults.
|
|
|
294
294
|
and the audit-suite prompt artifacts). Override `tempRoot` to relocate it.
|
|
295
295
|
- **`commands`.** Each string must be non-empty and pass the shell-injection
|
|
296
296
|
guard (`safeString` — disallows `;`, `&`, `|`, backtick, `$`, `<`, `>`).
|
|
297
|
-
`typecheck` is nullable; `null` is the canonical "not
|
|
298
|
-
repo" value
|
|
297
|
+
`typecheck` is nullable; an explicit `null` is the canonical "not
|
|
298
|
+
applicable for this repo" value and makes close report the gate as skipped,
|
|
299
|
+
while leaving the key unset keeps the `npm run typecheck` fallback. Read the block via `getCommands(config)`
|
|
299
300
|
([`config-resolver.js`](../scripts/lib/config-resolver.js)).
|
|
300
301
|
- **`docsContextFiles`.** Entries are **plain filenames, not globs** — each
|
|
301
302
|
resolves to a single file under `paths.docsRoot`. For the decisions log this
|
|
@@ -591,6 +592,42 @@ your real handle, and the guards proceed. By contrast, `github.owner` / `repo`
|
|
|
591
592
|
are **shared** repo identifiers (everyone targets the same `dsj1984/mandrel`)
|
|
592
593
|
and stay committed with real values.
|
|
593
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
|
+
|
|
594
631
|
### Adding a new top-level key (framework change)
|
|
595
632
|
|
|
596
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`
|
|
22
|
-
|
|
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
|
-
|
|
25
|
-
|
|
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
|
-
|
|
31
|
-
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
evidence wins:
|
|
36
|
+
**Attention.** One value picks the glyph, the color and whether line 2
|
|
37
|
+
shows:
|
|
37
38
|
|
|
38
|
-
|
|
|
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` | `
|
|
41
|
-
| `build` | `commit…` lines in the worktree's reflog (`logs/HEAD` under its gitdir) |
|
|
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 |
|
|
44
|
-
| `close` | `close-gates-<id>.log` |
|
|
45
|
-
| `merge` | a terminal envelope with `status` `pending`, or a progress file in `auto-merge` / `confirm-merge` |
|
|
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
|
-
**
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
**
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
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
|
package/.agents/instructions.md
CHANGED
|
@@ -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
|
|