agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/scripts/context.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+// Lead's record of a milestone, in three files with one writer:
+//
+//   context.md    state: Status, Phases, Codebase Map — read at every phase
+//   decisions.md  decisions, each open until a later line closes it
+//   journal.md    what was tried and why it lost — append-only, rarely read
+//
+// The split follows who reads what. One run kept all of it in a single
+// context.md: 72 KB, of which the 43 KB journal was dead weight to anyone
+// reading for the current state. It also had lead edit that file with an
+// ad-hoc script per change — ~555k characters of edit code that stayed in
+// lead's own context — so every write goes through a command here instead.
+//
+// A decision is never edited. It closes when a later line names it, and only
+// open decisions reach a phase prompt (`live`), so a resolved blocker or a
+// superseded choice stops costing anything without being lost.
+//
+// Lead is the only writer, so ids are assigned by read-then-append without a
+// lock. Metrics are not stored: `metrics` computes them from git and the
+// review-round count when asked, because hand-kept numbers went unmaintained.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const TYPES = ["binding", "tech_debt", "blocker", "question"];
+const VERDICTS = ["done", "superseded", "dropped", "answered"];
+const STATUSES = ["pending", "in-progress", "done", "failed", "blocked"];
+// One line a reader can take in at a glance. One run's decision lines reached
+// 728 characters because nothing stopped them; the detail belongs in journal.
+const MAX_DECISION = 200;
+
+const DECISION =
+  /^- (D\d+) (binding|tech_debt|blocker|question|legacy) ?(\S*) ?(\d{4}-\d{2}-\d{2})?: (.*)$/;
+const CLOSE = /^- (D\d+) closed (\S+) (\d{4}-\d{2}-\d{2}): (.*)$/;
+
+const root = process.cwd();
+const dir = (m) => path.join(root, ".orchestra", "milestones", m);
+const file = (m, name) => path.join(dir(m), name);
+const today = () => new Date().toISOString().slice(0, 10);
+// CRLF is normalised on read: a section matcher that expects "\n" would
+// otherwise miss a heading and append a second copy of the section.
+const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\r\n/g, "\n") : "");
+const PHASE_ID = /^[A-Za-z0-9._-]+$/;
+
+function die(msg) {
+  process.stderr.write(`context: ${msg}\n`);
+  process.exit(1);
+}
+
+function writeAtomic(p, text) {
+  const tmp = `${p}.${process.pid}`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, p);
+}
+
+function need(m) {
+  if (!m) die("name the milestone directory, e.g. M2-design-system");
+  if (!fs.existsSync(dir(m))) die(`no milestone directory .orchestra/milestones/${m}`);
+}
+
+function oneLine(text, what) {
+  const t = String(text || "").trim();
+  if (!t) die(`${what} is empty`);
+  if (/[\r\n]/.test(t)) die(`${what} must be one line`);
+  return t;
+}
+
+const STATE_HEADER = (m) =>
+  `## Status\nmilestone: ${m}\nstarted: ${today()}\n\n## Phases\n\n## Codebase Map\n`;
+
+function init(m) {
+  need(m);
+  if (!fs.existsSync(file(m, "context.md"))) writeAtomic(file(m, "context.md"), STATE_HEADER(m));
+  if (!fs.existsSync(file(m, "decisions.md")))
+    writeAtomic(file(m, "decisions.md"), "# Decisions\n\n");
+  if (!fs.existsSync(file(m, "journal.md"))) writeAtomic(file(m, "journal.md"), "# Journal\n\n");
+}
+
+/** Replace the body of a `## name` section, or add the section at the end. */
+function setSection(text, name, body) {
+  const re = new RegExp(`(^|\\n)## ${name}\\n[\\s\\S]*?(?=\\n## |$)`);
+  const block = `## ${name}\n${body}${body.endsWith("\n") ? "" : "\n"}`;
+  if (re.test(text)) return text.replace(re, (_, lead) => `${lead}${block}`);
+  return `${text.replace(/\n*$/, "\n\n")}${block}`;
+}
+
+function section(text, name) {
+  const m = new RegExp(`(?:^|\\n)## ${name}\\n([\\s\\S]*?)(?=\\n## |$)`).exec(text);
+  return m ? m[1] : "";
+}
+
+function phase(m, id, status, note) {
+  need(m);
+  init(m);
+  if (!id || !PHASE_ID.test(id)) die("name the phase as its file is named, e.g. phase-3");
+  if (!STATUSES.includes(status)) die(`status is one of ${STATUSES.join(", ")}`);
+  if (status === "done" && !/commits?:\s*\S+/.test(note || "")) {
+    die("a done phase carries its commit: pass a note like 'commit: abc123 | files: 4'");
+  }
+  const p = file(m, "context.md");
+  const text = read(p);
+  const lines = section(text, "Phases")
+    .split("\n")
+    .filter((l) => l.trim());
+  const entry = `- ${id}: ${status}${note ? ` | ${oneLine(note, "note")}` : ""}`;
+  const at = lines.findIndex((l) => l.startsWith(`- ${id}:`));
+  if (at === -1) lines.push(entry);
+  else lines[at] = entry;
+  writeAtomic(p, setSection(text, "Phases", `${lines.join("\n")}\n`));
+}
+
+function map(m) {
+  need(m);
+  init(m);
+  const body = fs.readFileSync(0, "utf8").trim();
+  // An empty stdin is a forgotten heredoc, not a request to erase the map.
+  if (!body) die("pipe the map in on stdin; nothing came, so the map is unchanged");
+  if (body.split("\n").length > 30) die("the codebase map is at most 30 lines");
+  const p = file(m, "context.md");
+  writeAtomic(p, setSection(read(p), "Codebase Map", `${body}\n`));
+}
+
+function parseDecisions(m) {
+  const decisions = new Map();
+  const closes = new Map();
+  for (const line of read(file(m, "decisions.md")).split("\n")) {
+    const c = CLOSE.exec(line);
+    if (c) {
+      closes.set(c[1], { verdict: c[2], date: c[3], text: c[4] });
+      continue;
+    }
+    const d = DECISION.exec(line);
+    if (d) decisions.set(d[1], { id: d[1], type: d[2], phase: d[3], line });
+  }
+  return { decisions, closes };
+}
+
+function nextId(m) {
+  let max = 0;
+  for (const id of parseDecisions(m).decisions.keys()) max = Math.max(max, Number(id.slice(1)));
+  return `D${max + 1}`;
+}
+
+function decide(m, type, phaseId, text) {
+  need(m);
+  init(m);
+  if (!TYPES.includes(type)) die(`type is one of ${TYPES.join(", ")}`);
+  if (!phaseId || !PHASE_ID.test(phaseId)) {
+    die("name the phase the decision came from as its file is named, e.g. phase-3, or milestone");
+  }
+  const t = oneLine(text, "decision");
+  if (t.length > MAX_DECISION) {
+    die(
+      `a decision is at most ${MAX_DECISION} characters (this is ${t.length}); put the detail in the journal`,
+    );
+  }
+  const id = nextId(m);
+  fs.appendFileSync(file(m, "decisions.md"), `- ${id} ${type} ${phaseId} ${today()}: ${t}\n`);
+  process.stdout.write(`${id}\n`);
+}
+
+function close(m, id, verdict, text) {
+  need(m);
+  const { decisions, closes } = parseDecisions(m);
+  if (!decisions.has(id)) die(`no decision ${id} in ${m}`);
+  if (closes.has(id)) die(`${id} is already closed`);
+  if (!VERDICTS.includes(verdict)) die(`verdict is one of ${VERDICTS.join(", ")}`);
+  const t = oneLine(text, "reason");
+  if (t.length > MAX_DECISION) die(`a reason is at most ${MAX_DECISION} characters`);
+  fs.appendFileSync(file(m, "decisions.md"), `- ${id} closed ${verdict} ${today()}: ${t}\n`);
+}
+
+function journal(m, phaseId, text) {
+  need(m);
+  init(m);
+  if (!phaseId || !PHASE_ID.test(phaseId)) die("name the phase, e.g. phase-3, or milestone");
+  fs.appendFileSync(file(m, "journal.md"), `- ${today()} ${phaseId}: ${oneLine(text, "entry")}\n`);
+}
+
+/**
+ * `live`: the open binding decisions — what a phase must follow, so what a
+ * phase prompt carries. `open`: every open decision, blockers, questions and
+ * tech debt included — lead's to act on, not an engineer's to read.
+ */
+function live(m, all) {
+  need(m);
+  const { decisions, closes } = parseDecisions(m);
+  for (const d of decisions.values()) {
+    if (closes.has(d.id)) continue;
+    if (all || d.type === "binding") process.stdout.write(`${d.line}\n`);
+  }
+}
+
+function check(m) {
+  const found = [];
+  const { decisions, closes } = parseDecisions(m);
+  const seen = new Set();
+  for (const line of read(file(m, "decisions.md")).split("\n")) {
+    if (!line.startsWith("- ")) continue;
+    if (CLOSE.test(line)) continue;
+    const d = DECISION.exec(line);
+    if (!d) {
+      found.push(`${m}/decisions.md: not a decision or a close: ${line.slice(0, 60)}`);
+      continue;
+    }
+    if (seen.has(d[1])) found.push(`${m}/decisions.md: ${d[1]} is used twice`);
+    seen.add(d[1]);
+    const migrated = d[2] === "legacy" || d[3] === "legacy";
+    if (!migrated && d[5].length > MAX_DECISION) {
+      found.push(`${m}/decisions.md: ${d[1]} is ${d[5].length} characters, over ${MAX_DECISION}`);
+    }
+  }
+  for (const id of closes.keys()) {
+    if (!decisions.has(id))
+      found.push(`${m}/decisions.md: a close names ${id}, which does not exist`);
+  }
+  return found;
+}
+
+function milestones() {
+  const base = path.join(root, ".orchestra", "milestones");
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+}
+
+/**
+ * Split an older single-file context.md. Lossless: Decisions, Tech debt and
+ * Blocked bullets become open `legacy` decisions with their text unchanged;
+ * Journal and Metrics move to journal.md verbatim; any other section stays.
+ */
+function migrate(m) {
+  const p = file(m, "context.md");
+  const text = read(p);
+  const moves = { Decisions: "legacy", "Tech debt": "legacy", Blocked: "legacy" };
+  const toJournal = ["Journal", "Metrics"];
+  const present = [...Object.keys(moves), ...toJournal].filter((s) =>
+    new RegExp(`(^|\\n)## ${s}\\n`).test(text),
+  );
+  if (!present.length) return false;
+
+  let decisionsText = read(file(m, "decisions.md")) || "# Decisions\n\n";
+  let n = Number(nextId(m).slice(1));
+  for (const s of Object.keys(moves)) {
+    // A bullet starts an entry and an indented line continues it. Anything
+    // else — prose, a numbered item, a sub-heading — becomes its own entry,
+    // so nothing in the section is dropped when the section is removed.
+    const entries = [];
+    for (const raw of section(text, s).split("\n")) {
+      if (!raw.trim()) continue;
+      if (raw.startsWith("- ")) entries.push(raw.slice(2).trim());
+      else if (/^\s/.test(raw) && entries.length) entries[entries.length - 1] += ` ${raw.trim()}`;
+      else entries.push(raw.trim());
+    }
+    const label = s === "Decisions" ? "" : `[${s}] `;
+    for (const e of entries) {
+      // An older line that says it is binding still binds the phases left;
+      // the rest is history lead can close as it reads them.
+      const kind = s === "Decisions" && /^binding\b/i.test(e) ? "binding legacy" : "legacy";
+      decisionsText += `- D${n++} ${kind}: ${label}${e}\n`;
+    }
+  }
+
+  let journalText = read(file(m, "journal.md")) || "# Journal\n\n";
+  for (const s of toJournal) {
+    const body = section(text, s).trim();
+    if (body) journalText += `${s === "Journal" ? "" : `\n## Migrated from ${s}\n`}${body}\n`;
+  }
+
+  // New files first: if this stops halfway, context.md still holds everything.
+  writeAtomic(file(m, "decisions.md"), decisionsText);
+  writeAtomic(file(m, "journal.md"), journalText);
+  let rest = text;
+  for (const s of present)
+    rest = rest.replace(new RegExp(`(^|\\n)## ${s}\\n[\\s\\S]*?(?=\\n## |$)`), "");
+  writeAtomic(p, `${rest.trim()}\n`);
+  return true;
+}
+
+function metrics(m) {
+  need(m);
+  let rounds = {};
+  try {
+    rounds = JSON.parse(
+      read(path.join(root, ".orchestra", ".sessions", "review-rounds.json")) || "{}",
+    );
+  } catch {
+    // An unreadable count reads as no rounds recorded, which is what it says.
+    rounds = {};
+  }
+  const commitTime = (hash) => {
+    try {
+      return execFileSync("git", ["show", "-s", "--format=%cI", hash], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      return "unknown";
+    }
+  };
+  const lines = section(read(file(m, "context.md")), "Phases")
+    .split("\n")
+    .filter((l) => l.startsWith("- "));
+  for (const l of lines) {
+    const [, id, status] = /^- (\S+): ([a-z-]+)/.exec(l) || [];
+    if (!id) continue;
+    const hashes = [];
+    for (const field of l.matchAll(/commits?:\s*([^|]+)/g)) {
+      for (const h of field[1].matchAll(/\b[0-9a-f]{7,40}\b/g)) hashes.push(h[0]);
+    }
+    const when = hashes.length ? commitTime(hashes[hashes.length - 1]) : "no commit";
+    process.stdout.write(
+      `${id}\t${status}\treview rounds: ${rounds[`${m}/${id}`] || 0}\tlast commit: ${when}\n`,
+    );
+  }
+}
+
+// An agent pipes output into `head`; a closed pipe ends the read, not the script.
+process.stdout.on("error", (e) => {
+  if (e.code === "EPIPE") process.exit(0);
+  throw e;
+});
+
+const [cmd, ...args] = process.argv.slice(2);
+switch (cmd) {
+  case "init":
+    init(args[0]);
+    break;
+  case "phase":
+    phase(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "map":
+    map(args[0]);
+    break;
+  case "decide":
+    decide(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "close":
+    close(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "journal":
+    journal(args[0], args[1], args.slice(2).join(" "));
+    break;
+  case "live":
+    live(args[0], false);
+    break;
+  case "open":
+    live(args[0], true);
+    break;
+  case "metrics":
+    metrics(args[0]);
+    break;
+  case "check": {
+    const found = (args[0] ? [args[0]] : milestones()).flatMap(check);
+    for (const f of found) process.stdout.write(`${f}\n`);
+    process.exit(found.length ? 1 : 0);
+    break;
+  }
+  case "migrate": {
+    const moved = (args[0] ? [args[0]] : milestones()).filter(migrate);
+    for (const m of moved)
+      process.stdout.write(`split ${m}/context.md into decisions.md and journal.md\n`);
+    break;
+  }
+  default:
+    die(
+      "usage: context.mjs init|phase|map|decide|close|journal|live|open|check|migrate|metrics <milestone> …",
+    );
+}

package/template/.orchestra/stacks/README.md

@@ -0,0 +1,81 @@
+# Stacks
+
+A **stack** is one kind of app: how it is scaffolded, and how it is built.
+`/orchestra:setup` runs the stack's script, then copies its conventions in.
+
+```
+.orchestra/stacks/
+├── _lib/common.sh        # shared helpers, sourced by every setup.sh
+├── _repo/setup.sh        # repo-level config — CI, dependabot, PR template,
+│                         # commit hook. Runs once, after the apps.
+└── <stack-id>/
+    ├── setup.sh          # scaffolds the app — deterministic, reviewable
+    ├── stack.md          # → apps/<name>/CLAUDE.md   (architecture + conventions)
+    └── claude/           # → apps/<name>/.claude/
+        ├── commands/     # workflows, e.g. /web:component
+        └── skills/       # depth, loaded on demand
+```
+
+## Why scripts
+
+Scaffolding is deterministic work. An agent improvising `npm create` flags
+produces a different repo every run and leaves nothing to review. The script
+is the contract: it runs the same way every time, and it shows up in a diff.
+
+The agent asks the questions and runs the script. It does not scaffold by hand.
+
+## setup.sh contract
+
+- Takes one argument: the target directory
+- Sources `../_lib/common.sh`
+- Resolves every version from the registry — **never hardcodes one**
+- Installs with `--save-exact` and commits the lockfile
+- Ends with `assert_verification_scripts` so the Orchestra gate cannot
+  point at commands that do not exist
+- Is idempotent enough to fail loudly rather than half-apply
+
+## Namespacing
+
+None needed. Claude Code namespaces by directory: a command at
+`apps/web/.claude/commands/build.md` is invoked as `/web:build`, and skills
+under `apps/web/.claude/skills/` are directory-scoped. `apps/web/CLAUDE.md`
+loads automatically when work happens in that folder.
+
+Never prefix filenames. The folder is the namespace.
+
+## Where a convention goes
+
+| Kind | Home |
+|---|---|
+| Always applies in this app | `stack.md` → `apps/<name>/CLAUDE.md` |
+| Detailed how-to, loaded when relevant | `claude/skills/` |
+| A workflow the user invokes | `claude/commands/` |
+| True for *every* app | root `.claude/rules/` — not here |
+
+App-level `CLAUDE.md` loads automatically when work happens in that folder.
+That is the reliable always-on mechanism; do not invent another one.
+
+## stack.md contract
+
+- Describes **how this app is built** — structure, conventions, testing
+  rules, and the engineer identity an agent adopts when working here
+- Contains no product or business logic. That lives in milestones.
+- Anything true for *every* app belongs in root `.claude/rules/`, not here
+
+## Stack IDs
+
+| ID | App |
+|---|---|
+| `web-vite-react` | React SPA on Vite |
+| `web-nextjs` | Next.js App Router |
+| `mobile-expo` | Expo / React Native |
+| `mobile-ios-native` | Native iOS (Swift) |
+| `mobile-android-native` | Native Android (Kotlin) |
+| `backend-hono` | Hono API |
+
+Deliberately not authored: desktop and game. Both are too varied to guess
+at (Tauri vs Electron; Godot vs Unity vs Unreal), and a guessed convention
+reads as a decided one. Author the pack when a real project needs it.
+
+Packs are authored with the user, not generated. A missing pack means
+`setup` writes a `CLAUDE.md` stub and reports it as unauthored.