@crafts69guy/orchestra 0.4.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orch",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0",
+  "version": "0.6.0",
   "description": "Orchestrator workflow: scope, implement, review, ship via specialised subagents and worktrees.",
   "author": {
     "name": "crafts69guy",

package/README.md

@@ -48,6 +48,7 @@ codex plugin marketplace add crafts69guy/orchestra
 | `orch doctor` | checks Node, git, `wt`, the harness CLIs and the installed plugins |
 | `orch claude [--yolo] [args...]` | starts `claude` with `ORCH=1` and `--model opus` (unless you pass `--model`) |
 | `orch codex [--yolo] [args...]` | starts `codex` with `ORCH=1` and the orchestration context (below) |
+| `orch update` | updates the npm CLI, then the plugin for each harness on `PATH` (`claude plugin update orch@orchestra`, `codex plugin marketplace upgrade orchestra`); skips npm from a git checkout |
 | `orch wt new\|merge\|list ...` | worktree helper used by the `dispatch` skill; prints JSON |
 | `orch eval [args...]` | behaviour evals; only from a git checkout (see [AGENTS.md](AGENTS.md)) |
 | `orch --help`, `orch --version` | usage and version |
@@ -59,6 +60,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.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Cross-harness (Claude Code + Codex) orchestration workflow plugin",
   "license": "MIT",

package/rules/orchestrator.md

@@ -13,6 +13,7 @@ Subagents: `scoper`, `implementer`, `reviewer`, `shipper`. On Claude Code call t
 - **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.
 
@@ -20,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.mjs

@@ -13,6 +13,7 @@ commands:
   codex [--yolo] [args]    run codex with the orch workflow
   wt new|merge|list ...    manage task worktrees (prints JSON)
   doctor                   check prerequisites
+  update                   update the npm CLI and the installed Claude/Codex plugins
   eval [args]              run the behaviour evals (git checkout only)
   help, -h, --help         show this help
   -V, --version            print the version
@@ -35,6 +36,26 @@ export function claudeArgs(args) {
   ];
 }
 
+/**
+ * Steps of `orch update` as `[cmd, args]`. The npm step is skipped in a git checkout (update it
+ * with `git pull`); a harness step is skipped when that harness is not on PATH.
+ */
+export function updateSteps(io) {
+  const has = (cmd) => io.hasCommand(cmd, io.env.PATH ?? '');
+  return [
+    ...(io.exists(join(io.root, '.git'))
+      ? []
+      : [['npm', ['install', '-g', '@crafts69guy/orchestra@latest']]]),
+    ...(has('claude')
+      ? [
+          ['claude', ['plugin', 'marketplace', 'update', 'orchestra']],
+          ['claude', ['plugin', 'update', 'orch@orchestra']],
+        ]
+      : []),
+    ...(has('codex') ? [['codex', ['plugin', 'marketplace', 'upgrade', 'orchestra']]] : []),
+  ];
+}
+
 /** Each command takes `(args, io)` and returns the exit code. */
 export const commands = {
   claude: (args, io) =>
@@ -62,6 +83,20 @@ export const commands = {
     io.stdout(`${lines.join('\n')}\n`);
     return code;
   },
+  /** Runs every step even after a failure; returns the first non-zero code. */
+  update(_args, io) {
+    if (io.exists(join(io.root, '.git'))) {
+      io.stderr(`orch: ${io.root} is a git checkout; skipping npm (run git pull there)\n`);
+    }
+    let code = 0;
+    for (const [cmd, args] of updateSteps(io)) {
+      io.stdout(`$ ${cmd} ${args.join(' ')}\n`);
+      const c = spawnExit(io.spawn(cmd, args, { env: io.env }), cmd, io.stderr, 'skipping.');
+      if (c !== 0 && code === 0) code = c;
+    }
+    if (code === 0) io.stdout('orch: updated; restart Claude Code / Codex sessions to apply\n');
+    return code;
+  },
   eval(args, io) {
     const script = join(io.root, 'evals', '_support', 'run.sh');
     if (!io.exists(script)) {