@orkestrel/scaffold 0.0.122 → 0.0.124
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/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
- package/dist/bin/main.js +21 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +13 -7
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -3
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -2
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +16 -3
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
- package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +14 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/claude-code.md +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +2 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +18 -1
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/builder.md +1 -1
- package/dist/host/claude/agents/distiller.md +2 -1
- package/dist/host/claude/agents/grok.md +2 -2
- package/dist/host/claude/agents/opus.md +2 -2
- package/dist/host/claude/agents/orkestrel.md +30 -30
- package/dist/host/claude/agents/reviewer.md +2 -2
- package/dist/host/claude/agents/scout.md +2 -1
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +12 -11
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/patterns.md +14 -0
- package/dist/host/claude/rules/quality.md +4 -1
- package/dist/host/claude/rules/tests.md +4 -0
- package/dist/host/claude/rules/writing.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +4 -1
- package/dist/host/codex/agents/astra.toml +1 -1
- package/dist/host/codex/agents/builder.toml +1 -1
- package/dist/host/codex/agents/distiller.toml +4 -2
- package/dist/host/codex/agents/grok.toml +5 -2
- package/dist/host/codex/agents/opus.toml +3 -3
- package/dist/host/codex/agents/reviewer.toml +6 -2
- package/dist/host/codex/agents/scout.toml +5 -1
- package/dist/host/codex/agents/verifier.toml +6 -1
- package/dist/host/guides/agent.md +1119 -457
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/ndjson.md +94 -21
- package/dist/host/guides/ollama.md +22 -18
- package/dist/host/guides/probe.md +29 -27
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +43 -21
- package/dist/host/guides/study.md +538 -450
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/manifest.json +70 -52
- package/dist/src/core/index.cjs +21 -20
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -4
- package/dist/src/core/index.d.ts +1 -4
- package/dist/src/core/index.js +21 -20
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +87 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -6
- package/dist/src/server/index.d.ts +50 -6
- package/dist/src/server/index.js +87 -10
- package/dist/src/server/index.js.map +1 -1
- package/package.json +15 -15
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: orkestrel-parallel
|
|
3
3
|
description: >-
|
|
4
|
-
Run parallel work: lanes inside one session (subagents, child tasks, background commands) and peer sessions that share a checkout, a machine, or an execution lane. Use when units can progress in parallel, when another session works on the same machine or checkout, or before the first lane on a harness. Bound the host, keep lanes visible, coordinate writers through messages with one runner for checks, and
|
|
4
|
+
Run parallel work: lanes inside one session (subagents, child tasks, background commands) and peer sessions that share a checkout, a machine, or an execution lane. Use when units can progress in parallel, when another session works on the same machine or checkout, or before the first lane on a harness. Bound the host, keep lanes visible, coordinate writers through messages with one runner for checks, and serialize a shared execution lane through one queue per host. Each harness page records its mechanics and quirks; a harness with no page carries no writer or runner lane until its bring-up questions are answered on one.
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Parallel lanes
|
|
@@ -21,12 +21,13 @@ description: >-
|
|
|
21
21
|
Run from the checkout root. The script's opening comment owns its behavior.
|
|
22
22
|
|
|
23
23
|
- `scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]` reads a Vitest `--reporter=json` report and requires every case a `--passed` name matches to have passed and every case a `--failed` name matches to have failed. A name matches a case's full name or its own title exactly; both flags repeat. A name that matches no case is missing, and a failed case no name matches is refused, as is a test file that failed with no failed case (it did not collect, or a hook threw) and a report whose `success` is false while nothing in it failed. It prints one summary line, each difference, and `ok` or `differences=N`. Exit 0 when the report matches, 3 when it does not, 2 when the report cannot be read as a Vitest report, 64 usage.
|
|
24
|
+
- `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...]` runs one process-running command at a time on this host, in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label and `live`, `dead`, or `unread`, and names the holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 70, or 75 reads like the lane's own code. The opening comment owns the limits and the migration stop.
|
|
24
25
|
|
|
25
26
|
## Bound the host
|
|
26
27
|
|
|
27
28
|
The host budget counts every lane on the machine: this session's, each peer session's, and the Orchestrator's own commands.
|
|
28
29
|
|
|
29
|
-
- Set the lane bound in the plan before the first dispatch. Run one process-running
|
|
30
|
+
- Set the lane bound in the plan before the first dispatch. Run one process-running command at a time on the host: a test, a build, a browser, or a capture, the Orchestrator's included, each launched through the serializer § Share an execution lane between sessions names; a bench exec, an owned-file format check, lint, type check, or `policy` run that reads only its owned paths' violations runs beside it. The bound counts commands, never a lane's whole life: while another lane's command runs, a writer keeps drafting, changes no file a live command reads, and batches its tests into one command, and a unit that needs no later unit starts at once. Report to the user before a launch that would start a process-running command outside that serializer.
|
|
30
31
|
- Count running lanes and owned test processes at each launch.
|
|
31
32
|
- Limit terminal launches: chain commands that do not gate each other into one launch (as a plan for `.agents/skills/orkestrel-dispatch/scripts/chain.ts`), write long output to a file and read it once, never poll with repeated short calls, never retry a run in a loop, and check once for owned leftovers before a launch.
|
|
32
33
|
- Find the cause of an interrupted run before relaunching it.
|
|
@@ -40,12 +41,12 @@ The host budget counts every lane on the machine: this session's, each peer sess
|
|
|
40
41
|
|
|
41
42
|
## Assign lanes
|
|
42
43
|
|
|
43
|
-
| Lane | Responsibility | Write boundary
|
|
44
|
-
| ------------ | -------------------------------------------------------- |
|
|
45
|
-
| Orchestrator | Own the roster, scope, rulings, holds, and acceptance. | Assigned coordination records and serial integration.
|
|
46
|
-
| Runner | Run requested tests, checks, and builds as the verifier. | Assigned evidence and declared command outputs; never source repairs.
|
|
47
|
-
| Writer | Implement its bounded unit under its assigned role. | Owned files and regions.
|
|
48
|
-
| Reviewer | Independently assess the subject the size gate names. | None; return the verdict to the Orchestrator.
|
|
44
|
+
| Lane | Responsibility | Write boundary |
|
|
45
|
+
| ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| Orchestrator | Own the roster, scope, rulings, holds, and acceptance. | Assigned coordination records and serial integration. |
|
|
47
|
+
| Runner | Run requested tests, checks, and builds as the verifier. | Assigned evidence and declared command outputs; never source repairs. |
|
|
48
|
+
| Writer | Implement its bounded unit under its assigned role. | Owned files and regions. |
|
|
49
|
+
| Reviewer | Independently assess the subject the size gate names. | None on source; a named probe folder when its tools hold a shell; return the verdict to the Orchestrator. |
|
|
49
50
|
|
|
50
51
|
- Keep active lanes within the harness limit and § Bound the host. Reserve capacity for the runner; queue work that does not fit.
|
|
51
52
|
- Assign every editable region to one writer. Name shared regions by their declarations or sections. Serialize units that rewrite the same region.
|
|
@@ -95,9 +96,9 @@ expect: <red or green, named cases, required artifact>
|
|
|
95
96
|
|
|
96
97
|
- Before a command, verify its input holds and exclusive resources. Hold all writers when the command reads the whole tree; otherwise hold every owner in its input closure. Do not infer that closure from the requesting writer's files alone.
|
|
97
98
|
- When a conflicting process occupies a declared resource, record its owner, process id, command, and a bounded wait based on the expected work. If it remains after that wait, suspend the request for an Orchestrator ruling. Never terminate another lane's or repository's process.
|
|
98
|
-
- Launch through `
|
|
99
|
+
- Launch through `scripts/lane.ts`, which runs `.agents/skills/orkestrel-dispatch/scripts/launch.ts` under the host lane, or through the serializer § Share an execution lane between sessions keeps, with a cap grounded in prior runs, journal and error paths under `coord/runs/` carrying the request identity in each filename. Follow the `orkestrel-dispatch` skill's reference Long-running commands for ownership, process tracking, and cleanup.
|
|
99
100
|
- State in each long command's request which line is its terminal record; that line ends the wait.
|
|
100
|
-
- When the shell yields before the command exits, keep its output in the assigned file and resume its tracked session per the harness page until the terminal record arrives. Start
|
|
101
|
+
- When the shell yields before the command exits, keep its output in the assigned file and resume its tracked session per the harness page until the terminal record arrives. Start no other process-running command meanwhile, and never replace the command with a second launch. Confirm owned descendants have exited before publishing completion. Escalate incomplete cleanup before releasing files or starting another command.
|
|
101
102
|
- Run the commands the accepted unit and the size gate require, narrowest first, and add no standing root, guide, or entry check beyond the request. Preserve receipts and rerun checks per `.agents/orchestration.md` § Pace.
|
|
102
103
|
- For a release run, follow the `orkestrel-publish` skill's reference The release wave § Prepare a layer. For other runs, stop on the first unexpected failure. Return the complete diagnostic and the owning file, and classify the failure as an assertion failure, an invocation error, a reporting failure, a cap, or an interruption. Preserve every receipt obtained before the stop. Check an `expect:` that names cases against the command's `--reporter=json` report with `scripts/cases.ts`.
|
|
103
104
|
- Record the command's input identity and expected outputs before launch. When an input changes during the run, report that result as invalid and retain each result whose input set stayed stable.
|
|
@@ -116,9 +117,9 @@ expect: <red or green, named cases, required artifact>
|
|
|
116
117
|
|
|
117
118
|
Apply this section when two sessions on one machine share the tests, checks, builds, and captures the host can run at once.
|
|
118
119
|
|
|
119
|
-
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
120
|
+
- Run each process-running command through `scripts/lane.ts`, which orders the commands across sessions, and send no handover message. On its exit 75 or 70, report its standard error line to the user and start no process-running command.
|
|
121
|
+
- When a host's sessions run another serializer, keep using it until a scaffold release carries `scripts/lane.ts` and no command runs on the host, then move every caller in one step, because a second queue does not see the first.
|
|
122
|
+
- While another session holds the lane, edit your own files, read, and queue your commands. Set no clock windows and send no per-command acknowledgments.
|
|
122
123
|
- Class contention from another session per `.agents/skills/orkestrel-dispatch/SKILL.md` § Write the brief. Rerun the interrupted unit alone after the window clears.
|
|
123
124
|
- When the user stops work, send the stop to every affected session. Withdraw queued work by its id and preserve finished evidence.
|
|
124
125
|
- When no message channel reaches a peer session, coordinate through one tracked record holding owned paths and a dated log. Read its latest entry before each unit, log each landing, and delete the record when the shared work closes.
|
|
@@ -4,19 +4,19 @@ Lanes that Claude Code starts in its own session. `.claude/AGENTS.md` owns loadi
|
|
|
4
4
|
|
|
5
5
|
## Mechanics
|
|
6
6
|
|
|
7
|
-
| Question | Claude Code
|
|
8
|
-
| ------------------- |
|
|
9
|
-
| Start | The Agent tool for one unit or when the next step depends on the result, with a role from `.claude/agents/` as `subagent_type`; never `general-purpose`, `Plan`, `claude`, `fork`, or `Explore`. A Workflow for a fan-out of small units, a staged pipeline, or a loop, its nodes configured per `.claude/AGENTS.md` § Dispatch. `scout` for an exact bounded lookup, per `.agents/orchestration.md` § Routing.
|
|
10
|
-
| Continue | Resume a custom subagent by its agent id through the installed tool's resume or message interface; a team teammate is not a custom subagent, so verify which one the installed version resumes. Recover an interrupted Workflow with `resumeFromRunId`; its journal replays the finished agents. A surviving transcript file is no continuation route, and a one-shot `Explore` or `Plan` agent cannot continue.
|
|
11
|
-
| Wake versus deliver | A finished subagent, Workflow, or background command wakes the session with a notification.
|
|
12
|
-
| Track | The agent id, not its display name, and the parent session that can recover it. A Workflow's `scriptPath` and `runId`, recorded at launch; its journal writes only at agent start and result, so read its liveness from the newest subagent transcript. A background command's task id and output file.
|
|
13
|
-
| Background | A foreground shell call is capped at 10 minutes. A background command runs to its own timeout, at most 2 hours, then stops. Run anything longer under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership.
|
|
14
|
-
| Isolation | Agents share the session's checkout; `isolation: worktree` gives one agent its own worktree.
|
|
15
|
-
| Tools | A role's frontmatter lists its tools, and the host can still withhold one: in-process roles in the desktop host ran with no shell although their charter listed one (2026-10-03), and the harness can refuse an in-process agent's file write.
|
|
16
|
-
| Limits | At the account's usage limit, running agents and Workflow agents stop mid-run and keep the edits they made.
|
|
17
|
-
| Host effects | Agents and Workflow nodes run inside the session's process and open no window (2026-10-21). An agent's shell can restart in the session root between calls (2026-10-17).
|
|
18
|
-
| Visibility | Agent tool calls, Workflow runs, and background commands appear in the session the user watches, where the user can stop them; a CLI started from a shell shows only its command line, so run it as a capped command inside such a lane.
|
|
19
|
-
| Capability map | `.agents/orchestration.md` § Roles, Claude column; `.claude/AGENTS.md` § Models owns the aliases.
|
|
7
|
+
| Question | Claude Code |
|
|
8
|
+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| Start | The Agent tool for one unit or when the next step depends on the result, with a role from `.claude/agents/` as `subagent_type`; never `general-purpose`, `Plan`, `claude`, `fork`, or `Explore`. A Workflow for a fan-out of small units, a staged pipeline, or a loop, its nodes configured per `.claude/AGENTS.md` § Dispatch. `scout` for an exact bounded lookup, per `.agents/orchestration.md` § Routing. In a target, whose `.claude/agents/` holds `orkestrel.md` alone, start a `general-purpose` agent with `model` set, and inline the role's Do, Refuse, and Return lines from `node_modules/@orkestrel/scaffold/dist/host/claude/agents/<role>.md` in its brief. Under T3, the Start row of `references/t3.md` names when a child task replaces this channel. |
|
|
10
|
+
| Continue | Resume a custom subagent by its agent id through the installed tool's resume or message interface; a team teammate is not a custom subagent, so verify which one the installed version resumes. Recover an interrupted Workflow with `resumeFromRunId`; its journal replays the finished agents. A surviving transcript file is no continuation route, and a one-shot `Explore` or `Plan` agent cannot continue. |
|
|
11
|
+
| Wake versus deliver | A finished subagent, Workflow, or background command wakes the session with a notification. |
|
|
12
|
+
| Track | The agent id, not its display name, and the parent session that can recover it. A Workflow's `scriptPath` and `runId`, recorded at launch; its journal writes only at agent start and result, so read its liveness from the newest subagent transcript. A background command's task id and output file. |
|
|
13
|
+
| Background | A foreground shell call is capped at 10 minutes. A background command runs to its own timeout, at most 2 hours, then stops. Run anything longer under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership. |
|
|
14
|
+
| Isolation | Agents share the session's checkout; `isolation: worktree` gives one agent its own worktree. |
|
|
15
|
+
| Tools | A role's frontmatter lists its tools, and the host can still withhold one: in-process roles in the desktop host ran with no shell although their charter listed one (2026-10-03), and the harness can refuse an in-process agent's file write. |
|
|
16
|
+
| Limits | At the account's usage limit, running agents and Workflow agents stop mid-run and keep the edits they made. |
|
|
17
|
+
| Host effects | Agents and Workflow nodes run inside the session's process and open no window (2026-10-21). An agent's shell can restart in the session root between calls (2026-10-17). |
|
|
18
|
+
| Visibility | Agent tool calls, Workflow runs, and background commands appear in the session the user watches, where the user can stop them; a CLI started from a shell shows only its command line, so run it as a capped command inside such a lane. |
|
|
19
|
+
| Capability map | `.agents/orchestration.md` § Roles, Claude column; `.claude/AGENTS.md` § Models owns the aliases. |
|
|
20
20
|
|
|
21
21
|
## Quirks
|
|
22
22
|
|
|
@@ -25,6 +25,7 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
|
|
|
25
25
|
- When a queued turn's result is needed and no notice came, read the durable result file or `task_status` with the full task id once.
|
|
26
26
|
- When a launch's reply is missing or ambiguous, inspect the recorded task before retrying. A timeout on a parent wait cancels no child work.
|
|
27
27
|
- When a lane must be interrupted and restarted, use `restart`; never use it as a resume. Create no ordinary top-level thread as a delegated lane.
|
|
28
|
+
- When a child task starts, carry its charter's limits in the brief, the refusals to commit and install included: a child's tools are unrestricted whatever its charter's frontmatter lists, so a charter binds only through its brief (2026-11-04).
|
|
28
29
|
- When a child would launch processes beside another, get the user's go-ahead until a quiet single-lane trial passes on that host.
|
|
29
30
|
- When a run must outlive the idle window, start it under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership, or keep the session in its turn.
|
|
30
31
|
- When delegation is refused, record the refusal and whether a child was created, then use the permitted fallback with its actual model disclosed.
|