@crafts69guy/orchestra 0.3.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orch",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Orchestrator workflow: scope, implement, review, ship via specialised subagents and worktrees.",
   "author": {
     "name": "crafts69guy"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orch",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Orchestrator workflow: scope, implement, review, ship via specialised subagents and worktrees.",
   "author": {
     "name": "crafts69guy",

package/README.md

@@ -59,6 +59,9 @@ permission model. Other arguments pass through to the harness, and so does its e
 `orch claude` only sets `ORCH=1`; `ORCH=1 claude` works too. Without `ORCH=1` the hooks exit
 silently and the session is untouched.
 
+The handoff brief to `implementer` includes a Docs/JSDoc acceptance criterion (new or changed exports
+carry JSDoc, touched docs are updated). `ORCH_DOCS=0` turns it off; any other value keeps it on.
+
 ## Codex
 
 Codex does not trust project agents or plugin hooks by default, so `orch codex` runs `codex`

package/agents/implementer.md

@@ -20,3 +20,4 @@ Report with these sections:
 - Changes: files touched and what changed.
 - Validation: each command you ran and its result, as evidence.
 - Notes: deviations, open questions, anything unverified.
+- Docs: if the brief includes Docs/JSDoc, list the JSDoc and docs you added.

package/codex/agents/implementer.toml

@@ -18,4 +18,5 @@ Report with these sections:
 - Changes: files touched and what changed.
 - Validation: each command you ran and its result, as evidence.
 - Notes: deviations, open questions, anything unverified.
+- Docs: if the brief includes Docs/JSDoc, list the JSDoc and docs you added.
 '''

package/hooks/session-start.mjs

@@ -30,9 +30,18 @@ export function which(name, pathEnv = '') {
   });
 }
 
+/** Lines ending in `<!-- orch:docs -->` are the Docs/JSDoc criterion: dropped when off, marker stripped when on. */
+export function applyDocs(rules, docs) {
+  return rules
+    .split('\n')
+    .filter((l) => docs || !l.includes('<!-- orch:docs -->'))
+    .map((l) => l.replace(/ *<!-- orch:docs -->$/, ''))
+    .join('\n');
+}
+
 /** `orchPath` is the absolute `bin/orch`; plugin bin/ is not on PATH under Codex, so name it. */
-export function buildContext(rules, hasWt, orchPath) {
-  const withCli = `${rules.trimEnd()}\n\norch CLI: ${orchPath} (use \`${orchPath} wt new|merge|list\`)\n`;
+export function buildContext(rules, hasWt, orchPath, docs = true) {
+  const withCli = `${applyDocs(rules, docs).trimEnd()}\n\norch CLI: ${orchPath} (use \`${orchPath} wt new|merge|list\`)\n`;
   return hasWt ? withCli : `${withCli}\n${WT_WARNING}\n`;
 }
 
@@ -50,7 +59,16 @@ export function run({ env, root, read, hasCommand, stdout, stderr }) {
     stderr(`orch: rules/orchestrator.md not found under ${root}; skipping injection\n`);
     return 0;
   }
-  stdout(formatOutput(buildContext(rules, hasCommand('wt', env.PATH), join(root, 'bin', 'orch'))));
+  stdout(
+    formatOutput(
+      buildContext(
+        rules,
+        hasCommand('wt', env.PATH),
+        join(root, 'bin', 'orch'),
+        env.ORCH_DOCS !== '0',
+      ),
+    ),
+  );
   return 0;
 }
 

package/hooks/subagent-stop.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { readStdin, roleOf } from './guard.mjs';
 import { isEntry } from './session-start.mjs';
 
@@ -13,8 +14,36 @@ export function hasEvidence(message) {
   return typeof message === 'string' && STATUS.test(message) && VALIDATION.test(message);
 }
 
+/**
+ * The `message` of the last `SubagentHandback` tool call in a subagent transcript (JSONL), or
+ * undefined when the path is missing, unreadable or holds no handback. Never throws.
+ */
+export function handbackReport(path, readFile = (p) => readFileSync(p, 'utf8')) {
+  if (typeof path !== 'string' || path === '') return undefined;
+  let report;
+  try {
+    for (const line of readFile(path).split('\n')) {
+      let content;
+      try {
+        content = JSON.parse(line)?.message?.content;
+      } catch {
+        continue;
+      }
+      if (!Array.isArray(content)) continue;
+      for (const part of content) {
+        if (part?.type === 'tool_use' && part.name === 'SubagentHandback') {
+          report = part.input?.message;
+        }
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return report;
+}
+
 /** Returns the exit code; never throws, bad stdin JSON is a silent allow. */
-export function run({ env, input, stdout }) {
+export function run({ env, input, stdout, readFile }) {
   if (env.ORCH !== '1') return 0;
   let payload;
   try {
@@ -23,7 +52,10 @@ export function run({ env, input, stdout }) {
     return 0;
   }
   if (roleOf(payload?.agent_type) !== 'implementer' || payload?.stop_hook_active === true) return 0;
-  if (!hasEvidence(payload?.last_assistant_message)) {
+  if (
+    !hasEvidence(payload?.last_assistant_message) &&
+    !hasEvidence(handbackReport(payload?.agent_transcript_path, readFile))
+  ) {
     stdout(JSON.stringify({ decision: 'block', reason: BLOCK_REASON }));
   }
   return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crafts69guy/orchestra",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Cross-harness (Claude Code + Codex) orchestration workflow plugin",
   "license": "MIT",
@@ -46,7 +46,8 @@
     "gen:codex": "node scripts/gen-codex-agents.mjs",
     "check": "npm run lint && npm run gen:codex -- --check && npm test",
     "validate": "claude plugin validate .",
-    "eval": "sh evals/_support/run.sh"
+    "eval": "sh evals/_support/run.sh",
+    "eval:bench": "sh evals/_support/bench.sh"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",

package/rules/orchestrator.md

@@ -10,8 +10,10 @@ Subagents: `scoper`, `implementer`, `reviewer`, `shipper`. On Claude Code call t
 - **Scoping:** run `scoper` first on non-trivial work in unfamiliar code, unless you expect to read 3 or fewer new files. Spot-check its brief.
 - **Implementation:** delegate to `implementer` when the change spans 2+ files, adds or fixes tests, or needs more than one edit-and-test cycle.
 - **Planning:** for work with 2+ separable parts, use the `plan` skill to write `.scratch/<feature>/plan.md` before implementing.
-- **Parallel:** when a plan has 2+ tasks with no `depends_on` between them and disjoint `files`, use the `dispatch` skill without asking, even when each task is small. Never run two writers on the same checkout.
+- **Parallel:** use the `dispatch` skill without asking when a plan has 2+ independent tasks (no `depends_on` path, disjoint `files`) that are each substantial: its own module or feature needing several edit-and-test cycles, roughly 100+ changed lines. Independent small tasks go to one `implementer` as a single batched task, done in order, not to dispatch. Never run two writers on the same checkout.
+  Measured: dispatch was no faster on 4 tiny modules (115 s vs 118 s, +45% cost) and 21% faster on 3 large ones (+22% cost).
 - **Review:** review every implementer diff yourself and rerun its validation. Use `reviewer` (fresh context: diff, brief, acceptance criteria) for risky changes (security, concurrency, migrations, public APIs) or on request. At most 2 fix rounds.
+  Also check the Docs/JSDoc criterion. <!-- orch:docs -->
 - **Shipping:** delegate commit, push and PR to `shipper` only after review passes and the user asked to ship.
 - **Stays with you:** scope, architecture, cross-cutting decisions, root-cause analysis, merge conflicts, escalations.
 
@@ -19,6 +21,7 @@ Subagents: `scoper`, `implementer`, `reviewer`, `shipper`. On Claude Code call t
 
 Subagents do not see this conversation. Decide interfaces, names and libraries before delegating, then send:
 objective · decisions already made · files in scope and out of scope · constraints · validation command · stop conditions.
+Docs/JSDoc: new or changed exported types, functions and their fields carry JSDoc in the repo's doc style, and docs the change touches (ADRs, glossary, guides) are updated; the orchestrator checks this when reviewing the diff. <!-- orch:docs -->
 Point to the plan/brief file and section instead of restating it. Pass paths and commit SHAs, not "what we discussed".
 
 ## Results

package/scripts/orch-codex.mjs

@@ -63,7 +63,12 @@ export function run({ argv, env, root, cwd, read, readdir, hasCommand, gitDir, s
     stderr(`orch codex: rules/orchestrator.md not found under ${root}\n`);
     return 1;
   }
-  const context = buildContext(rules, hasCommand('wt', env.PATH), join(root, 'bin', 'orch'));
+  const context = buildContext(
+    rules,
+    hasCommand('wt', env.PATH),
+    join(root, 'bin', 'orch'),
+    env.ORCH_DOCS !== '0',
+  );
   const prefix = buildArgs({
     context,
     agents: agentArgs(root, { read, readdir }),

package/scripts/orch-wt.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, rmdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
@@ -122,9 +122,12 @@ export function merge(deps, cwd, feature, task, message, yes) {
   }
   if (tree.status !== 0) return fail(task, tree.stderr);
 
+  const yesArg = yes ? ['--yes'] : [];
+  // --no-remove: wt's own cleanup runs in the background and returns before the directory is
+  // gone (or never finishes when the caller's sandbox kills it), so remove in the foreground below.
   const r = deps.exec(
     'wt',
-    ['-C', path, 'merge', feature, '--no-commit', ...(yes ? ['--yes'] : [])],
+    ['-C', path, 'merge', feature, '--no-commit', '--no-remove', ...yesArg],
     cwd,
   );
   if (r.status !== 0) {
@@ -135,6 +138,17 @@ export function merge(deps, cwd, feature, task, message, yes) {
     return { code: 2, result: { status: 'conflict', task, files } };
   }
   const commit = git(deps, cwd, 'rev-parse', feature).stdout.trim();
+  const left = `merged as ${commit}, but ${path} is left`;
+  // -D: wt judges "merged" against the default branch, but the branch is now in `feature`.
+  const rm = deps.exec('wt', ['remove', branch, '--foreground', '-D', ...yesArg], cwd);
+  if (rm.status !== 0) return fail(task, `${left}: ${rm.stderr}`);
+  if (deps.exists(path)) {
+    try {
+      deps.rmdir(path); // only an empty leftover: rmdir refuses a non-empty directory
+    } catch (e) {
+      return fail(task, `${left}: ${e.message}`);
+    }
+  }
   return { code: 0, result: { status: 'merged', task, commit } };
 }
 
@@ -164,5 +178,6 @@ export const realDeps = {
   exec,
   exists: existsSync,
   mkdir: (p) => mkdirSync(p, { recursive: true }),
+  rmdir: rmdirSync,
   append: appendFileSync,
 };

package/skills/dispatch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatch
-description: "orch workflow: run independent tasks from .scratch/<feature>/plan.md in parallel, one implementer per git worktree (worktrunk), then merge them into the feature branch one at a time."
+description: "orch workflow: run independent substantial tasks from .scratch/<feature>/plan.md in parallel, one implementer per git worktree (worktrunk), then merge them into the feature branch one at a time."
 ---
 
 # Dispatch
@@ -21,8 +21,10 @@ absolute path. Use that path where the plugin's `bin/` is not on `PATH` (Codex).
 
 ## Each wave
 
-1. **Pick** the ready tasks: all `depends_on` merged, `files` disjoint. At most
-   4 per wave; queue the rest.
+1. **Pick** the ready `substantial` tasks: all `depends_on` merged, `files`
+   disjoint. At most 4 per wave; queue the rest. `small` tasks are never
+   dispatched: run them as one batched implementer task on `F`, before any wave
+   that depends on them.
 2. **Create** worktrees: `orch wt new <F> <T1> <T2> …` → JSON list of
    `{task, branch, path}`.
 3. **Spawn** one implementer per task, all in the **same message** so they run

package/skills/plan/SKILL.md

@@ -32,6 +32,7 @@ Base branch: <F>   # the branch the tasks merge into
   goal: <one sentence, observable outcome>
   files: [<paths this task owns>]
   depends_on: []
+  size: small        # or substantial (rule below)
   validate: <command that proves this task works>
   decisions: [<task-specific choices>]
 ```
@@ -43,14 +44,20 @@ Base branch: <F>   # the branch the tasks merge into
   share a file. If they must, add a `depends_on` edge or merge the tasks.
 - Shared files that everyone touches (lockfiles, barrel exports, registries) go
   to one task that the others depend on.
-- Each task is 1 implementer-sized unit: one edit-and-test loop, not a project.
+- Each task is 1 implementer-sized unit (one module or feature), not a project.
+- `size` is `substantial` when the task is its own module or feature needing
+  several edit-and-test cycles, roughly 100+ changed lines; otherwise `small`.
 - `validate` runs inside the task's own worktree and must not need other
   unmerged tasks.
 - Don't split one feature into many tiny tasks. Separate features stay separate
-  tasks, even when each one is small.
+  tasks (each can land as its own commit), but small ones are batched, not
+  dispatched (below).
 
 ## After writing
 
-Show the user the task table (id, goal, depends_on) in a few lines. If 2+ tasks
-are independent, continue with the `dispatch` skill; otherwise run implementers
-one at a time.
+Show the user the task table (id, goal, size, depends_on) in a few lines. If 2+
+independent tasks are `substantial`, continue with the `dispatch` skill for
+them. Batch the `small` tasks into one implementer task (all of them, in order,
+on the feature branch); run the rest (a lone or dependent substantial task) with
+its own implementer, one at a time. Parallel worktrees only pay off when each
+task is substantial.