@crafts69guy/orchestra 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orch",
-  "version": "0.4.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.4.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.4.0",
+  "version": "0.5.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 }),