@pilotspace/add 1.17.0 → 2.0.0

package/agents/add.md

@@ -0,0 +1,68 @@
+---
+name: add
+description: The ADD specialist — ONE execution shell for every beat of the loop. The spawn prompt names the beat (direction · build · verify) or a service mode (advise · persona); the agent loads that beat's phase guide plus the best-fit persona and becomes the specialist. Personas carry the expertise; this agent carries the discipline. Recommended tier — top for direction/verify/advise, mid for build.
+model: inherit
+color: cyan
+---
+
+You are the **ADD specialist** — the one execution shell of the roster. Your spawn
+prompt names a MODE; everything else about who you are comes from the persona you
+load. Personas are the method's core value: they carry the domain expertise, the
+critical rules, and the measurable done-bar. You carry the loop discipline that
+never changes.
+
+## 1 · Resolve your mode (from the spawn prompt)
+- **direction** — draft the whole direction bundle (setup on a fresh project ·
+  ground · rules · scenarios · contract · scope · red-suite intent) up to, never
+  past, the ONE human freeze. Guide: `phases/direction.md`.
+- **build** — turn the frozen contract + scenarios into a red suite, then drive
+  it green honestly. Guide: `phases/build.md`.
+- **verify** — evidence · 3 lenses (security → concurrency → architecture) ·
+  earned-green refute-read · one outcome · observe/delta drafting. Guide:
+  `phases/verify.md`.
+- **advise** — a consultative second opinion on a named decision: recommendation
+  + tradeoffs weighed + confidence. No guide; you advise, never decide.
+- **persona** — select the best-fit existing persona for a described piece of
+  work, or DRAFT a new one from the seed templates when none fits (never
+  overwrite an existing persona file).
+
+Read YOUR mode's guide from the project's skill tree (`.claude/skills/add/phases/`)
+at spawn — the orchestrator reads only SKILL.md and does not pre-read it for you.
+
+## 2 · Become the persona (FIRST — before any task-specific instruction)
+Select from `.add/personas/` by frontmatter alone (name · vibe · flow ·
+task-kinds): prefer a persona whose `flow:` names your mode's surface
+(direction→design · build→build · verify→verify · advise→advisor) AND whose
+`task-kinds:` covers the task's declared `kind:`. In verify mode select a
+`flow: verify` persona first, falling back to `flow: advisor` when none
+declares verify. Read the body of the ONE you become. Its `## Critical Rules` are your constraints; its `## Success Metrics`
+are your done-bar; tag findings with its severity convention (🔴 blocker ·
+🟡 concern · 💭 note). No persona matched? Use the generic fallback — a
+15-year specialist in the task's domain, correctness over speed; the fallback
+never blocks and never lowers a gate.
+
+## 3 · Boundary (the irreducible floor — binds every mode, above any persona)
+- MAY: read real code, run the suite, draft sections, propose scope/strategy/verdicts.
+- MUST NOT: mark a freeze, gate, or lock on your own authority (human seams) ·
+  edit a frozen contract or locked scope · weaken, delete, or skip a test ·
+  touch files outside the declared Scope · add a dependency off the allow-list ·
+  invent a file or symbol you have not opened · resolve genuine ambiguity by guessing.
+- STOP-and-escalate (return findings; never decide): any SECURITY finding is
+  always HARD-STOP · a needed test/contract change (a change request back to
+  Specify, never a silent edit) · residue the evidence cannot clear · an
+  ambiguity only the human can resolve.
+
+## 4 · Self-improve before you return
+Any Strategy you received is a PREFERRED plan — improve on it and report what
+you ACTUALLY did. Self-score the six confidence dimensions (Completeness ·
+Clarity · Practicality · Optimization · Edge cases · Self-evaluation); below
+0.9 anywhere → refine before returning.
+
+## 5 · Return (disclose progress — the orchestrator parses this)
+`{ mode, persona, kind, result, evidence|bundle|verdict, residue, deltas,
+confidence: {per-dimension 0–1}, open_questions }`
+You PROPOSE; the orchestrator RECORDS — never run the engine or write shared
+state. A lesson about HOW an agent should behave → recommend tagging it
+`persona:<slug>` so the fold grows that persona, not the shared pile.
+
+Method depth: the AIDD book — read only when a decision is genuinely unclear.

package/bin/cli.js

@@ -6,10 +6,9 @@
  *
  *   npx @pilotspace/add init [targetDir] [--force] [--stage <stage>] [--name <name>] [--yes|--non-interactive]
  *
- * Installs the ADD skill + tooling + book into a target project:
+ * Installs the ADD skill + tooling into a target project:
  *   <target>/.claude/skills/add/   (the skill Claude loads)
  *   <target>/.add/tooling/         (add.py scaffolder + state tracker)
- *   <target>/.add/docs/            (the AIDD book — the trust layer)
  * It DROPS FILES ONLY — it does NOT run `add.py init`. Initialisation is deferred to
  * the AI (via `/add`, which runs `init --await-lock` to arm the v12 lock-down gate) or
  * to a CLI user. A pre-run plain init would grandfather-lock the gate before `/add` runs
@@ -58,9 +57,9 @@ function parseArgs(argv) {
     // non-interactive selector the interactive() gate honors (CI/pipes do this too).
     else if (a === "--yes" || a === "-y") args.yes = true;
     else if (a === "--non-interactive") args.nonInteractive = true;
-    // --no-skill: drop the engine + book ONLY, not the skill. The Claude Code plugin
+    // --no-skill: drop the engine ONLY, not the skill. The Claude Code plugin
     // already provides the `add` skill, so a plugin bootstrap uses this to materialize
-    // .add/tooling/ + .add/docs/ into the project without a duplicate .claude/skills/add.
+    // .add/tooling/ into the project without a duplicate .claude/skills/add.
     else if (a === "--no-skill") args.noSkill = true;
     // --rule-file: write the ADD block to .claude/rules/add-workflows.md + reference it from
     // CLAUDE.md instead of inlining (auto-on for ccsk projects with a .ccsk/ dir).
@@ -217,7 +216,7 @@ function agentPointerBlock(profile) {
     GUIDE_BEGIN + "\n" +
     "## ADD — how to work in this repo\n" +
     "\n" +
-    "This project uses **ADD (AI-Driven Development)**. The engine + book are installed.\n" +
+    "This project uses **ADD (AI-Driven Development)**. The engine is installed.\n" +
     "To begin: run `python3 .add/tooling/add.py status` (the resume point), read\n" +
     "`.add/PROJECT.md`, then `python3 .add/tooling/add.py guide` for the current phase.\n" +
     "\n" +
@@ -410,10 +409,11 @@ async function loadClack() {
 // --- brand + feature showcase (interactive path only; fail-soft) -------------
 // Wordmark + value line + the 7-step Specify->Observe loop, rendered BEFORE the first
 // prompt on the interactive path only — so the non-interactive byte stream is unchanged.
-// The 7 labels are the real ADD phases (grounded in the method, never invented). Fail-soft:
-// any draw error is swallowed so a banner can never abort the install. No color is emitted
-// (default accent: none); the glyphs / tagline / accent are a SWAPPABLE content slot.
-const BRAND_LOOP = ["Specify", "Scenarios", "Contract", "Tests", "Build", "Verify", "Observe"];
+// The 7 labels are the real ADD phases (grounded in the method, never invented; grounding
+// itself is folded into step 3, Plan, not a separate phase). Fail-soft: any draw error is
+// swallowed so a banner can never abort the install. No color is emitted (default accent:
+// none); the glyphs / tagline / accent are a SWAPPABLE content slot.
+const BRAND_LOOP = ["Specify", "Plan", "Tests", "Build", "Verify"];
 
 function terminalCaps(env, stream) {
   const width = Number(env.COLUMNS) || (stream && stream.columns) || 80;
@@ -481,7 +481,7 @@ async function runClackPreamble(clack, target, detected, askScope) {
     initialValue: target, defaultValue: target,
   });
   if (clack.isCancel(chosen)) return { cancelled: true, target: target };
-  const ok = await clack.confirm({ message: "Write the ADD skill + tooling + book here?" });
+  const ok = await clack.confirm({ message: "Write the ADD skill + tooling here?" });
   if (clack.isCancel(ok) || !ok) return { cancelled: true, target: target };
   // global-first SCOPE step (after the target confirm, before agent-detect) — recommended
   // global home, explicit pick; skipped when --global already chose. global stays ADDITIVE.
@@ -671,7 +671,7 @@ function dropFiles(args, target, profile, intent) {
   // NO step 4: the installer DROPS FILES ONLY. Initialisation is deferred to the AI
   // (via `/add`) or a CLI user — a pre-run plain `add.py init` would grandfather-lock
   // the v12 lock-down gate before `/add` runs (see file header). So no Python is run here.
-  log("\nDone. " + (args.noSkill ? "The engine + book are" : "The `add` skill + tooling are") +
+  log("\nDone. " + (args.noSkill ? "The engine is" : "The `add` skill + tooling are") +
       " installed (no project state yet — that's intentional).");
   if (profile.id === "generic") {
     // the generic onramp line — kept literal so the conversational-only handoff is stable
@@ -753,7 +753,6 @@ const MANAGED = [
   ["skill/add", [".claude", "skills", "add"], false],
   ["agents", [".claude", "agents"], false],
   ["tooling", [".add", "tooling"], true],
-  ["docs", [".add", "docs"], false],
   ["personas-teacher", [".add", "personas-teacher"], false],
 ];
 // Optional managed trees: an ENHANCEMENT the persona phase reads, not core runtime. The real
@@ -762,6 +761,18 @@ const MANAGED = [
 // _installer.py:OPTIONAL. Design-for-failure. `agents` joins here (roster-install-drift): the
 // phase-agent roster is a spawn-acceleration enhancement, not core runtime.
 const OPTIONAL = new Set(["personas-teacher", "agents"]);
+// SHARED-namespace managed trees (installer-shared-namespace-guard): destinations OTHER
+// TOOLS also write — `.claude/agents` holds the user's own Claude Code subagents. A
+// whole-dir clean-replace there sweeps the user's files as "orphans" (the reported
+// data-loss bug), so these trees route to sharedFileReplace: per-file atomic landings of
+// the shipped files + removal of ONLY the explicit tombstones below. Twin of
+// _installer.py:_SHARED / _RETIRED_AGENTS.
+const SHARED = new Set(["agents"]);
+// Roster names retired upstream — the ONLY names the shared lander may remove (never a
+// pattern/prefix heuristic: a USER file named add-anything.md must survive).
+// roster-distill (ADD 2.0 M1): the 5-agent roster collapsed into the ONE `add` agent.
+const RETIRED_AGENTS = ["add-design.md", "add-build.md", "add-verify.md",
+                        "add-persona.md", "add-advisor.md"];
 const STAMP_FILE = ".add-version";
 const LOCK_FILE = ".update.lock";   // the `update --global` home lock (never user-data)
 const LOCK_STALE_DEFAULT = 600;     // seconds (10 min); ADD_LOCK_STALE_SECONDS env-overridable
@@ -948,7 +959,7 @@ function cleanReplaceTree(src, dest, stripTests) {
   return { restored: restored, refreshed: refreshed };
 }
 
-const TREE_LABEL = { "skill/add": "skill", "agents": "agents", "tooling": "tooling", "docs": "docs", "personas-teacher": "personas" };
+const TREE_LABEL = { "skill/add": "skill", "agents": "agents", "tooling": "tooling", "personas-teacher": "personas" };
 
 // Per managed tree: "missing" (dest absent OR empty) or "present".
 function managedStatus(target) {
@@ -961,6 +972,36 @@ function managedStatus(target) {
   return status;
 }
 
+// installer-shared-namespace-guard: land a SHARED-namespace managed tree per FILE.
+// `.claude/agents` belongs to the user as much as to ADD — only the shipped files are
+// written (temp-sibling + atomic rename each, so a crash never leaves a torn file) and
+// only the explicit RETIRED_AGENTS tombstones are removed; every other destination file
+// is never opened. Returns the same { restored, refreshed } roll-up shape as
+// cleanReplaceTree so the reconcile reporting is agnostic. Mirror of
+// _installer.py:_shared_file_replace.
+function sharedFileReplace(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  let restored = 0, refreshed = 0;
+  const entries = fs.readdirSync(src).filter((n) => fs.statSync(path.join(src, n)).isFile()).sort();
+  for (const name of entries) {
+    const target = path.join(dest, name);
+    const existed = fs.existsSync(target);
+    const tmp = path.join(dest, name + ".add-tmp-" + Math.random().toString(36).slice(2, 10));
+    try {
+      fs.copyFileSync(path.join(src, name), tmp);
+      fs.renameSync(tmp, target);   // atomic overwrite (same directory)
+    } catch (e) {
+      fs.rmSync(tmp, { force: true });   // dest entry untouched or already whole
+      throw e;
+    }
+    if (existed) refreshed++; else restored++;
+  }
+  for (const name of RETIRED_AGENTS) {
+    fs.rmSync(path.join(dest, name), { force: true });   // absent tombstone — never fatal
+  }
+  return { restored: restored, refreshed: refreshed };
+}
+
 // reconcile: restore-missing + refresh-present (sweep orphans) across the managed trees,
 // reporting per-tree status. Honors --no-skill (the plugin provides the skill). Touches
 // ONLY managed trees — never user data. Prechecks ALL sources first (design-for-failure:
@@ -978,7 +1019,9 @@ function reconcile(args, target, srcRoot) {
   const status = managedStatus(target);
   let restored = 0, refreshed = 0;
   for (const [sub, destParts, stripTests] of trees) {
-    const roll = cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
+    const roll = SHARED.has(sub)
+      ? sharedFileReplace(path.join(srcRoot, sub), path.join(target, ...destParts))
+      : cleanReplaceTree(path.join(srcRoot, sub), path.join(target, ...destParts), stripTests);
     restored += roll.restored;
     refreshed += roll.refreshed;
     const dest = destParts.join("/");
@@ -992,7 +1035,7 @@ function reconcile(args, target, srcRoot) {
   return { restored: restored, refreshed: refreshed, trees: status };
 }
 
-// --- global home: an OPT-IN shared install (engine+book+skill) updated for all projects ----
+// --- global home: an OPT-IN shared install (engine+skill) updated for all projects ----
 // Resolution is PURE + total (never throws); the home MIRRORS the bundled managed layer so
 // `update --global` propagation reuses reconcile() unchanged. Mirror of _installer.py.
 function resolveGlobalHome(env) {
@@ -1034,12 +1077,14 @@ function writeRegistry(home, paths) {
   fs.renameSync(tmp, target);   // atomic on the same filesystem (POSIX + Windows)
 }
 
-// The home mirrors the bundled layout (skill/add + tooling + docs at the SAME relative paths
+// The home mirrors the bundled layout (skill/add + tooling at the SAME relative paths
 // the package ships) so reconcile(args, project, home) reuses MANAGED unchanged.
 const GLOBAL_TREES = [
   ["skill/add", ["skill", "add"], false],
+  // roster-drift fix: absent here, `update --global` propagation (sourced FROM the home)
+  // soft-skipped the roster forever — no refresh, no retired-agent tombstones.
+  ["agents", ["agents"], false],
   ["tooling", ["tooling"], true],
-  ["docs", ["docs"], false],
   ["personas-teacher", ["personas-teacher"], false],
 ];
 
@@ -1062,7 +1107,7 @@ function reconcileGlobal(home, claudeDir, noSkill) {
 // --- global DATA: an OPT-IN per-project user-data snapshot under <home>/data/<key> ----------
 // Strictly additive; copies ONLY user-data (managed trees + transient excluded), clean-replaced,
 // one-way (project->home). Mirror of _installer.py (identical key + include/exclude rule).
-const DATA_EXCLUDE = ["tooling", "docs", ".update-cache", STAMP_FILE, LOCK_FILE, PROJECT_LOCK_FILE];   // managed trees + meta + both locks
+const DATA_EXCLUDE = ["tooling", "docs", ".update-cache", STAMP_FILE, LOCK_FILE, PROJECT_LOCK_FILE];   // managed trees + meta + both locks ("docs" = legacy 1.x tree: still never user-data)
 
 // data_key twin: <sanitized-basename>-<sha1(abspath_utf8)[:12]>. Pure · total · separator-free.
 function dataKey(projectAbspath) {
@@ -1840,6 +1885,26 @@ function cmdUpdate(args) {
   log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
       " · managed layer reconciled (" + roll.restored + " restored · " + roll.refreshed +
       " refreshed) · your project state untouched.");
+  // crossing nudges — engine-owned follow-ups the updater must NAME, never run (python3
+  // may be absent on this PATH; both commands are idempotent). Twin of _installer.py.
+  if (cur !== version) {
+    log("next: python3 .add/tooling/add.py sync-guidelines   # refresh the CLAUDE.md guidance block to this version");
+  }
+  const tasksDir = path.join(addDir, "tasks");
+  let legacyBoard = false;
+  if (fs.existsSync(tasksDir)) {
+    for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+      if (entry.isDirectory()
+          && fs.existsSync(path.join(tasksDir, entry.name, "TASK.md"))
+          && !fs.existsSync(path.join(tasksDir, entry.name, "PLAN.md"))) {
+        legacyBoard = true;
+        break;
+      }
+    }
+  }
+  if (legacyBoard) {
+    log("next: python3 .add/tooling/add.py migrate   # 1.x board detected: TASK.md -> PLAN.md, live + archived");
+  }
 }
 
 // js-reclaim-lock-heartbeat: a test-only entrypoint so the Python subprocess suite can drive
@@ -1888,13 +1953,13 @@ async function main() {
     case "help":
     case "--help":
       log("usage: npx @pilotspace/add <init|update|prune-data> [targetDir] [--force] [--check] [--no-skill] [--global] [--yes|--non-interactive]");
-      log("  init    install the ADD skill + tooling + book into a project");
-      log("          (--no-skill drops the engine + book only — used by the Claude Code plugin)");
+      log("  init    install the ADD skill + tooling into a project");
+      log("          (--no-skill drops the engine only — used by the Claude Code plugin)");
       log("          (--global ALSO installs to a shared home [ADD_HOME|XDG_DATA_HOME/add|~/.add] + registers the project)");
       log("          (--global-data implies --global + persists this project's user-data under <home>/data/<key>)");
       log("          (--from-global-data rehydrates this project's user-data FROM the shared home on a fresh clone)");
       log("          (interactive in a real terminal; --yes / --non-interactive force the plain path)");
-      log("  update  re-materialize skill/tooling/docs to this package version (preserves your state)");
+      log("  update  re-materialize skill/tooling to this package version (preserves your state)");
       log("          (--global refreshes the shared home + propagates to every registered project)");
       log("  prune-data  remove orphaned per-project snapshots from the shared home (dry-run; --force deletes)");
       break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.17.0",
-  "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
+  "version": "2.0.0",
+  "description": "ADD (AI-Driven Development) 2.0. The agent is the hands; ADD is the memory, judgment, and conscience — a minimal, state-tracked skill: one freeze per feature, trust from passing tests, state on disk so context rot never survives a new session.",
   "bin": {
     "add": "bin/cli.js"
   },
@@ -24,7 +24,6 @@
     "!tooling/add_engine/__pycache__",
     "!**/*.pyc",
     "tooling/templates/",
-    "docs/",
     "personas-teacher/",
     "THIRD_PARTY_NOTICES.md",
     "README.md",

package/personas-teacher/VENDOR.md

@@ -11,3 +11,9 @@ KEEP: the agent-definition domain folders (engineering, security, design, produc
 DROP: the upstream `.github/` CI, `scripts/`, other-tool `integrations/`, `CONTRIBUTING*`, `SECURITY.md`, and dotfiles.
 
 Content is RAW + verbatim — regenerate with `python3 add-method/scripts/update_teacher.py`. Attribution: see the repo-root `THIRD_PARTY_NOTICES.md` and the retained `LICENSE` in this folder (MIT).
+
+## Refresh-drift check (run on every refresh PR)
+
+Distilled personas keep `source:` provenance pointing into this snapshot. In the refresh PR
+description, list every `.add/personas/*.md` whose `source:` file(s) changed or moved in the
+diff — those personas are candidates for re-distillation, otherwise their provenance rots silently.