agentic-team 6.1.0 → 6.3.0

package/README.md

@@ -24,6 +24,11 @@ That copies `.orchestra/` and `.claude/` in and adds the Orchestra section to
 blueprints, your own roles, skills and rules are preserved, and `config.yml`
 is merged rather than overwritten.
 
+Only the project's platforms are installed — `web`, `expo`, `ios`, `android`,
+`backend` — from `project.platforms` in `config.yml`, detected from the repo
+when it is empty, or `--platforms ios,backend`. See
+[Getting started](docs/getting-started.md#only-your-platforms).
+
 ## How it works
 
 Once, in a freshly cloned empty repo:
@@ -105,10 +110,10 @@ With `tracker.provider: none` there is no board. The markdown under
 ├── stacks/             how each kind of app is scaffolded and built afterwards
 ├── trackers/           the GitHub adapter; ClickUp goes through its MCP connector
 ├── blueprints/         milestone templates
-└── milestones/         your work — prd, milestone, phases, tracker.yml, context.md
+└── milestones/         your work — prd, milestone, phases, tracker.yml, context/decisions/journal
 
 .claude/
-├── agents/             architect, scaffolder, lead, reviewer, tracker
+├── agents/             architect, scaffolder, lead, reviewer, re-reviewer, tracker
 ├── rules/*.orchestra.md   discipline, loaded into every session
 ├── skills/*/SKILL.md   depth on one topic, loaded per phase
 └── commands/orchestra/ the commands above
@@ -125,7 +130,7 @@ is enforced by `scripts/policy-check.mjs` in the gate; the rest is a review
 item, and the reviewer is told which is which.
 
 **Roles** write only inside their ownership. PM writes milestones. Lead
-writes `context.md`. Sub-agents write what a phase's scope names. A
+writes the milestone record — `context.md`, `decisions.md`, `journal.md`. Sub-agents write what a phase's scope names. A
 `PreToolUse` hook blocks everything else.
 
 ## Principles

package/bin/build-template.js

@@ -36,7 +36,7 @@ const PLUGIN_MANIFEST = {
     "AI Team Orchestration — multi-role coordination with milestones, phases, and quality gates for Claude Code",
   version: require("../package.json").version,
   author: { name: "Sulhadin Öney" },
-  repository: "https://github.com/sulhadin/orchestrator",
+  repository: "https://github.com/sulhadin/agentic-team",
   license: "MIT",
 };
 
@@ -79,7 +79,7 @@ const SYSTEM_PATHS = [
 
 // The repo's CLAUDE.md carries a "## Development" section about THIS package.
 // Copying it wholesale means every scaffolded project tells its own agents it
-// is the orchestrator npm package. Ship only what is between the markers.
+// is the agentic-team npm package. Ship only what is between the markers.
 function packClaudeMd() {
   const src = fs.readFileSync(path.join(rootDir, "CLAUDE.md"), "utf-8");
   const start = src.indexOf("<!-- orchestra -->");

package/bin/index.js

@@ -3,6 +3,7 @@
 const { execFileSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
+const platformsLib = require("./platforms");
 
 const targetDir = process.cwd();
 const templateDir = path.join(__dirname, "..", "template");
@@ -71,9 +72,11 @@ const ALLOW_PERMISSIONS = [
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const flags = { skipPermissions: false, help: false };
+  const platforms = platformsLib.takePlatformsArg(args);
+  const flags = { skipPermissions: false, help: false, platforms: platforms?.list ?? null };
 
-  for (const arg of args) {
+  for (const [i, arg] of args.entries()) {
+    if (platforms?.used.has(i)) continue;
     switch (arg) {
       case "--dangerously-skip-permissions":
         flags.skipPermissions = true;
@@ -101,11 +104,16 @@ function showHelp() {
   console.log("");
   console.log("  Options:");
   console.log("    --public                         new: create a public repository");
+  console.log(
+    "    --platforms <list>               web,expo,ios,android,backend — install only these",
+  );
+  console.log("                                     (default: project.platforms, else detected)");
   console.log("    --dangerously-skip-permissions   Auto-allow all tool permissions");
   console.log("    --help, -h                       Show this help");
   console.log("");
   console.log("  Examples:");
   console.log("    npx agentic-team");
+  console.log("    npx agentic-team --platforms ios,backend");
   console.log("    npx agentic-team new daily-intake");
   console.log("");
 }
@@ -441,22 +449,72 @@ function smartMergeDir(backupPath, restorePath, templateDirPath) {
 // The manifest is that marker, for everything, in one place both sides read.
 const MANIFEST_PATH = ".orchestra/.installed.json";
 
-/** Every destination path the template installs, repo-relative and POSIX. */
-function templateFileList() {
+/**
+ * Every file the template installs for these platforms: its repo-relative
+ * POSIX destination and its source in the package. An empty platform list is
+ * everything.
+ */
+function templateEntries(platforms, keepSkills) {
   const out = [];
   const walk = (dir, prefix) => {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const rel = `${prefix}/${entry.name}`;
-      if (entry.isDirectory()) walk(path.join(dir, entry.name), rel);
-      else out.push(rel);
+      const src = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(src, rel);
+      else if (platformsLib.selected(rel, platforms, keepSkills)) out.push({ rel, src });
     }
   };
   walk(path.join(templateDir, ".orchestra"), ".orchestra");
   for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
     walk(path.join(templateDir, pluginDir), claudeSubdir);
   }
-  return out.sort();
+  return out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}
+
+/**
+ * Copy the template's files for these platforms into the project. A rule
+ * loses the sections marked for other platforms; every file keeps its name,
+ * so the manifest and the system-file hook see the same paths either way.
+ */
+function installTemplate(entries, platforms) {
+  for (const { rel, src } of entries) {
+    const dest = path.join(targetDir, ...rel.split("/"));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // Dereference rather than recreate: a relative link that resolved in the
+    // package will not resolve in the user's tree.
+    const real = fs.realpathSync(src);
+    try {
+      if (fs.lstatSync(dest).isSymbolicLink()) fs.unlinkSync(dest);
+    } catch {
+      // Optional: on a fresh install there is nothing at dest yet.
+    }
+    if (rel.startsWith(".claude/rules/") && rel.endsWith(".md")) {
+      const text = fs.readFileSync(real, "utf-8");
+      fs.writeFileSync(dest, platformsLib.filterSections(text, platforms));
+    } else {
+      fs.copyFileSync(real, dest);
+    }
+  }
+}
+
+/** Names in a platform list that are not platforms. */
+const unknownPlatforms = (list) => list.filter((p) => !platformsLib.PLATFORMS.includes(p));
+
+/**
+ * Which platforms this run installs for, and where that answer came from:
+ * the flag (already validated), then the config, then detection. A config
+ * naming something that is not a platform is refused, not narrowed around —
+ * dropping the name once retired a platform's files and rewrote the user's
+ * list without it.
+ */
+function resolvePlatforms(flagValue, configText, detect) {
+  if (flagValue) return { list: flagValue, source: "--platforms" };
+  const configured = platformsLib.readConfigPlatforms(configText || "");
+  const bad = unknownPlatforms(configured);
+  if (bad.length) return { error: `project.platforms in config.yml names ${bad.join(", ")}` };
+  if (configured.length) return { list: configured, source: "config.yml" };
+  return { list: detect(), source: "detected" };
 }
 
 function readManifest() {
@@ -464,7 +522,9 @@ function readManifest() {
   if (!fs.existsSync(p)) return null;
   try {
     const m = JSON.parse(fs.readFileSync(p, "utf-8"));
-    return Array.isArray(m.files) ? m : null;
+    if (Array.isArray(m?.files)) return m;
+    console.log("  [!] .orchestra/.installed.json has no files list — nothing retired this run");
+    return null;
   } catch {
     // A corrupt manifest means retirement cannot run this time. Reported, and
     // not fatal: the install itself is still correct without it.
@@ -481,18 +541,22 @@ function writeManifest(files) {
 }
 
 /**
- * Delete what a previous version installed and this one no longer ships.
+ * Delete what a previous install put down and this one does not: a file this
+ * version no longer ships, or one for a platform the project no longer lists.
+ * `alsoRetire` adds paths no manifest records, for an install older than it.
  *
  * Without it a retired skill is indistinguishable from one the user wrote, so
  * it survives every future upgrade and keeps teaching whatever it taught.
  */
-function retireRemoved(previous, current) {
-  if (!previous) return 0;
+function retireRemoved(previous, current, alsoRetire = []) {
   const keep = new Set(current);
   let removed = 0;
-  for (const rel of previous.files) {
+  for (const rel of new Set([...(previous?.files || []), ...alsoRetire])) {
     if (keep.has(rel)) continue;
     const full = path.join(targetDir, rel);
+    // The manifest is a committed file anyone can edit. An entry that leaves
+    // the project is never deleted.
+    if (!full.startsWith(targetDir + path.sep)) continue;
     if (!fs.existsSync(full)) continue;
     fs.unlinkSync(full);
     // The directory it lived in is ours too when nothing is left in it.
@@ -711,11 +775,12 @@ function setupPermissions() {
  * Deliberately stops before `/orchestra:setup`. Setup is a conversation — it
  * asks what you are building — and that conversation has to happen inside the
  * new project, where the project's own CLAUDE.md and role boundaries are
- * loaded. Run from the orchestrator repo instead, an agent would be wearing
+ * loaded. Run from the agentic-team repo instead, an agent would be wearing
  * the system maintainer's contract at the moment it starts building an app.
  */
 function newProject(argv) {
-  const name = argv.find((a) => !a.startsWith("-"));
+  const platforms = platformsLib.takePlatformsArg(argv);
+  const name = argv.find((a, i) => !a.startsWith("-") && !platforms?.used.has(i));
   const isPublic = argv.includes("--public");
 
   if (!name) {
@@ -731,6 +796,15 @@ function newProject(argv) {
     return;
   }
 
+  // Checked before the repository exists: the installer would refuse a typo
+  // only after GitHub already has an empty repository by that name.
+  if (platforms && (!platforms.list.length || unknownPlatforms(platforms.list).length)) {
+    console.log(`  [x] --platforms takes a comma list of: ${platformsLib.PLATFORMS.join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+  const forward = platforms ? ["--platforms", platforms.list.join(",")] : [];
+
   const dir = path.resolve(targetDir, name);
   if (fs.existsSync(dir)) {
     console.log(`  [x] ${name}/ already exists here. Refusing to write into it.`);
@@ -771,7 +845,7 @@ function newProject(argv) {
   // The installer runs unchanged, in the new directory. Copying its logic here
   // would give the manifest, the upgrade path and the hook registration a
   // second implementation to drift from.
-  execFileSync(process.execPath, [__filename], { cwd: dir, stdio: "inherit" });
+  execFileSync(process.execPath, [__filename, ...forward], { cwd: dir, stdio: "inherit" });
 }
 
 function run() {
@@ -781,6 +855,20 @@ function run() {
     return;
   }
 
+  // Refused before anything is touched: a typo in the flag would otherwise
+  // install for the wrong platforms and retire the right ones. An empty list
+  // means "everything", which is never what a flag asking for platforms meant.
+  if (flags.platforms && (!flags.platforms.length || unknownPlatforms(flags.platforms).length)) {
+    console.log("");
+    console.log(
+      `  [x] Unknown platform: ${unknownPlatforms(flags.platforms).join(", ") || "(none given)"}`,
+    );
+    console.log(`      Expected any of: ${platformsLib.PLATFORMS.join(", ")}`);
+    console.log("");
+    process.exitCode = 1;
+    return;
+  }
+
   console.log("");
   console.log("  Orchestra — AI Team Orchestration");
   console.log(`  Installing into: ${targetDir}`);
@@ -793,6 +881,38 @@ function run() {
   // Read before anything is copied: after the install the manifest describes
   // this version, and what a previous one left behind is no longer knowable.
   const previousManifest = readManifest();
+  // Asked separately: a manifest that exists but does not parse is not an old
+  // install, and treating it as one sweeps user files the manifest would have
+  // told apart. Read now, because the upgrade removes .orchestra/ below.
+  const manifestExisted = fs.existsSync(path.join(targetDir, MANIFEST_PATH));
+
+  // Also before the copy: the upgrade's config merge cannot keep a block-form
+  // list over the template's flow-form `platforms: []`, so the answer is
+  // taken from the user's file as it stands and written back afterwards.
+  const configBefore = path.join(orchestraDest, "config.yml");
+  let detected = null;
+  const detect = () => {
+    detected ??= platformsLib.detectPlatforms(targetDir);
+    return detected;
+  };
+  const profile = resolvePlatforms(
+    flags.platforms,
+    fs.existsSync(configBefore) ? fs.readFileSync(configBefore, "utf-8") : "",
+    detect,
+  );
+  if (profile.error) {
+    console.log(`  [x] ${profile.error}.`);
+    console.log(
+      `      Expected any of: ${platformsLib.PLATFORMS.join(", ")}. Nothing was changed.`,
+    );
+    console.log("");
+    process.exitCode = 1;
+    return;
+  }
+  // Read before the upgrade moves milestones/ aside.
+  const phaseSkills = platformsLib.phaseSkills(targetDir);
+  const entries = templateEntries(profile.list, phaseSkills);
+  const allEntries = templateEntries([]);
 
   if (isUpgrade) {
     // A backup nobody finished restoring holds the only copy of the user's
@@ -923,17 +1043,8 @@ function run() {
         }
       }
 
-      copyDirRecursive(orchestraSrc, orchestraDest);
+      installTemplate(entries, profile.list);
       console.log("  [+] .orchestra/ installed");
-
-      // Copy plugin dirs → .claude/ (plugin-to-standalone mapping)
-      for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
-        const src = path.join(templateDir, pluginDir);
-        if (fs.existsSync(src)) {
-          const dest = path.join(targetDir, claudeSubdir);
-          copyDirRecursive(src, dest);
-        }
-      }
       console.log("  [+] .claude/ orchestra files installed");
 
       // ── Restore user data ──
@@ -988,30 +1099,111 @@ function run() {
         console.log("");
       }
     }
-  } else {
-    // ── Fresh install ──
-    copyDirRecursive(orchestraSrc, orchestraDest);
-    console.log("  [+] .orchestra/ installed");
 
-    // Copy plugin dirs → .claude/ (plugin-to-standalone mapping)
-    for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
-      const src = path.join(templateDir, pluginDir);
-      if (fs.existsSync(src)) {
-        const dest = path.join(targetDir, claudeSubdir);
-        copyDirRecursive(src, dest);
+    // A milestone written before the split keeps decisions and the journal
+    // inside context.md. The script moves them out losslessly, new files
+    // first, so a failure here leaves context.md whole.
+    const contextScript = path.join(orchestraDest, "scripts", "context.mjs");
+    if (fs.existsSync(contextScript)) {
+      try {
+        const out = execFileSync(process.execPath, [contextScript, "migrate"], {
+          cwd: targetDir,
+          encoding: "utf8",
+        });
+        for (const line of out.split("\n").filter(Boolean)) console.log(`  [~] ${line}`);
+      } catch (e) {
+        // Not fatal: the install itself is complete and context.md is whole,
+        // because the split writes the new files before it touches it. What
+        // is left is one command, and the message names it.
+        console.log(`  [!] context.md not split (${e.message.split("\n")[0]}); run it again with`);
+        console.log("      node .orchestra/scripts/context.mjs migrate");
       }
     }
+  } else {
+    // ── Fresh install ──
+    installTemplate(entries, profile.list);
+    console.log("  [+] .orchestra/ installed");
     console.log("  [+] .claude/ installed");
   }
 
   // ── Record what was installed ──
-  const installed = templateFileList();
-  const retired = retireRemoved(previousManifest, installed);
+  const installed = entries.map((e) => e.rel);
+  // The manifest retires what this project no longer lists. An install from
+  // before the manifest has none, so its files for other platforms would look
+  // like the user's own; only then is every such template path retired. With
+  // a manifest, a path it does not list is the user's — somebody who writes
+  // their own skill under a name a dropped platform freed keeps it.
+  const unselected =
+    isUpgrade && !manifestExisted
+      ? allEntries.map((e) => e.rel).filter((rel) => !installed.includes(rel))
+      : [];
+  const retired = retireRemoved(previousManifest, installed, unselected);
   if (retired > 0) {
-    console.log(`  [~] Removed ${retired} system file(s) this version no longer ships`);
+    console.log(`  [~] Removed ${retired} system file(s) this install no longer ships`);
   }
   writeManifest(installed);
 
+  // ── Record the platforms ──
+  const cfgPath = path.join(orchestraDest, "config.yml");
+  if (fs.existsSync(cfgPath)) {
+    const text = fs.readFileSync(cfgPath, "utf-8");
+    const next = platformsLib.writeConfigPlatforms(text, profile.list);
+    if (next === null) {
+      console.log("  [!] project: in config.yml is an inline map — platforms not written back.");
+      console.log("      Write it as a block, with platforms: [ios] indented under project:");
+    } else {
+      fs.writeFileSync(cfgPath, next);
+    }
+  }
+  if (profile.list.length) {
+    const skipped = allEntries.length - entries.length;
+    console.log(
+      `  [~] Platforms: ${profile.list.join(", ")} (${profile.source})` +
+        (skipped ? ` — ${skipped} file(s) for other platforms not installed` : ""),
+    );
+    if (profile.source === "detected") {
+      console.log(
+        "      Wrong? Edit project.platforms in .orchestra/config.yml, or pass --platforms.",
+      );
+    } else {
+      // The list is trusted once written, so an app added later is said out
+      // loud on every run rather than silently left out.
+      const unlisted = detect().filter((p) => !profile.list.includes(p));
+      if (unlisted.length) {
+        console.log(
+          `  [!] The repository also looks like ${unlisted.join(", ")}, which project.platforms does not list.`,
+        );
+        console.log("      Add it to project.platforms if this project builds for it.");
+      }
+    }
+  } else {
+    console.log(
+      "  [~] Platforms: none set — everything installed. Set project.platforms or pass --platforms to narrow it.",
+    );
+  }
+
+  // A skill kept only because a phase names it is said, so it is not mistaken
+  // for one the profile chose; a name that exists nowhere is a broken plan.
+  const keptOnlyByPhase = [...phaseSkills].filter(
+    (n) =>
+      platformsLib.SKILLS[n] !== undefined &&
+      !allEntries.some(
+        (e) =>
+          e.rel.startsWith(`.claude/skills/${n}/`) && platformsLib.selected(e.rel, profile.list),
+      ),
+  );
+  if (keptOnlyByPhase.length) {
+    console.log(
+      `  [~] Kept for other platforms because a phase names them: ${keptOnlyByPhase.join(", ")}`,
+    );
+  }
+  const missing = [...phaseSkills].filter(
+    (n) => !fs.existsSync(path.join(targetDir, ".claude", "skills", n, "SKILL.md")),
+  );
+  if (missing.length) {
+    console.log(`  [!] A phase names a skill that does not exist: ${missing.join(", ")}`);
+  }
+
   // ── Handle CLAUDE.md ──
   const templateClaudeMd = fs.readFileSync(path.join(templateDir, "CLAUDE.md"), "utf-8");
   const targetClaudeMdPath = path.join(targetDir, "CLAUDE.md");
@@ -1092,9 +1284,12 @@ function run() {
   // The previous message sent a fresh repo straight to the PM, while the
   // CLAUDE.md it had just written says to point at setup before anything else.
   // The first screen a new user reads contradicted the system it installed.
+  // A native app at the root has neither apps/ nor a package.json, so
+  // detection counts too.
   const scaffolded =
     fs.existsSync(path.join(targetDir, "apps")) ||
-    fs.existsSync(path.join(targetDir, "package.json"));
+    fs.existsSync(path.join(targetDir, "package.json")) ||
+    detect().length > 0;
 
   // Preserved, and said out loud. Silently keeping a key nothing reads is how
   // somebody spends an afternoon wondering why their setting has no effect.