@thebassclef/lite 1.0.4 → 1.1.1

package/dist/cli.js

@@ -290,14 +290,15 @@ function substrateConfigMdTemplate(pkgVersion) {
   ].join("\n");
 }
 const MANIFEST_SCHEMA_VERSION = "0.1.0";
-const MANIFEST_SHAPE_VERSION = 2;
+const MANIFEST_SHAPE_VERSION = 3;
+const GENERATED_BY = "@thebassclef/lite";
 function manifestTemplate(input) {
   const value = {
     schema_version: MANIFEST_SHAPE_VERSION,
     $bassclef: {
       template: "init.manifest.json",
       manifest_schema_version: MANIFEST_SCHEMA_VERSION,
-      generated_by: "@thebassclef/core",
+      generated_by: GENERATED_BY,
       generated_by_version: input.pkgVersion
     },
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -365,7 +366,7 @@ function readManifest(targetDir) {
   if (compareSchemaVersion(schema, MANIFEST_SCHEMA_VERSION) > 0) {
     throw new ManifestReadError(
       "SchemaTooNew",
-      `manifest schema version ${schema} is newer than this package understands (${MANIFEST_SCHEMA_VERSION}). Upgrade @thebassclef/core.`
+      `manifest schema version ${schema} is newer than this package understands (${MANIFEST_SCHEMA_VERSION}). Upgrade @thebassclef/lite.`
     );
   }
   const obj = parsed;
@@ -495,6 +496,7 @@ function setExecutable(targetPath) {
   }
   chmodSync(targetPath, HOOK_EXECUTABLE_MODE);
 }
+const CLAUDE_TARGET_ROOT = ".claude";
 const HOOKS_SUBPATH = ".claude/hooks/";
 const SETTINGS_SUBPATH = ".claude/settings.json";
 const CONFIG_FILES = [
@@ -517,7 +519,10 @@ function copySubstrate(targetDir, options = {}) {
     hookCount: 0,
     wiringVersion: manifest.version
   };
-  if (options.dryRun) result.wouldCopy = [];
+  if (options.dryRun) {
+    result.wouldCopy = [];
+    result.wouldCopyEntries = [];
+  }
   const files = walkDistTree(bundleRoot);
   const groups = groupByTopDirectory(files);
   const bundleHookRelPaths = new Set(files.filter(isHookFile));
@@ -673,6 +678,11 @@ function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
   const outputContent = options.transform ? options.transform(adopterRelPath, content) : content;
   if (options.dryRun) {
     result.wouldCopy?.push(adopterRelPath);
+    result.wouldCopyEntries?.push({
+      path: adopterRelPath,
+      scope,
+      content_hash_sha256: hashContent(outputContent)
+    });
     return "wouldCopy";
   }
   try {
@@ -682,7 +692,11 @@ function copyOne(relPath, bundleRoot, options, result, scopeDecision) {
       setExecutable(targetPath);
     }
     result.copied.push(adopterRelPath);
-    result.copiedEntries.push({ path: adopterRelPath, scope });
+    result.copiedEntries.push({
+      path: adopterRelPath,
+      scope,
+      content_hash_sha256: hashContent(outputContent)
+    });
     return "copied";
   } catch (e) {
     if (e instanceof WriteError) {
@@ -759,7 +773,92 @@ function dirExists(p) {
     return false;
   }
 }
+const FAMILIES = [
+  "skills",
+  "rules",
+  "agents",
+  "luminaries",
+  "hooks",
+  "libs",
+  "adrs",
+  "standards",
+  "templates",
+  "presence-templates",
+  "scripts",
+  "root-docs",
+  "other"
+];
+const UNDER_CLAUDE = `${CLAUDE_TARGET_ROOT}/`;
+const PREFIX_RULES = [
+  [`${UNDER_CLAUDE}skills/`, "skills"],
+  [`${UNDER_CLAUDE}rules/`, "rules"],
+  [`${UNDER_CLAUDE}agents/`, "agents"],
+  [`${UNDER_CLAUDE}luminaries/`, "luminaries"],
+  [`${UNDER_CLAUDE}hooks/`, "hooks"],
+  ["lib/", "libs"],
+  ["architecture/decisions/", "adrs"],
+  ["standards/", "standards"],
+  ["templates/", "templates"],
+  ["presence/install/", "presence-templates"],
+  ["scripts/", "scripts"]
+];
+function classifyEntry(path) {
+  for (const [prefix, family] of PREFIX_RULES) {
+    if (path.startsWith(prefix)) return family;
+  }
+  if (!path.includes("/") && /^[A-Z]/.test(path)) return "root-docs";
+  return "other";
+}
+function emptyCatalogCounts() {
+  const out = {};
+  for (const f of FAMILIES) out[f] = 0;
+  return out;
+}
+function buildInitReport(input) {
+  const catalog = emptyCatalogCounts();
+  let project = 0;
+  let user = 0;
+  for (const e of input.entries) {
+    catalog[classifyEntry(e.path)] += 1;
+    if (e.scope === "user") user += 1;
+    else project += 1;
+  }
+  const refused = input.refused.length;
+  const errored = input.errored.length;
+  const written = input.configs.length + input.entries.length;
+  return {
+    schema_version: 3,
+    tier: input.tier,
+    totals: {
+      files: written + refused + errored,
+      written,
+      project,
+      user,
+      configs: input.configs.length
+    },
+    catalog,
+    hooks: {
+      declared: input.hookCount,
+      copied: input.declaredHooksCopied,
+      files: catalog.hooks
+    },
+    refused,
+    errored,
+    failed: refused + errored
+  };
+}
+function renderJsonReport(report, write) {
+  write(JSON.stringify(report) + "\n");
+}
 const RESOLVED_TIER = "lite";
+const SAY_HUMAN = (s) => {
+  process.stdout.write(s);
+};
+const SAY_QUIET = () => {
+};
+function makeSay(json) {
+  return json ? SAY_QUIET : SAY_HUMAN;
+}
 const PLACEHOLDER_FILES = /* @__PURE__ */ new Set([
   "CLAUDE.md",
   "docs/whereami.md",
@@ -801,7 +900,7 @@ function runInit(argv) {
     }
     throw e;
   }
-  const advisoryOutcome = maybeEmitUpgradeAdvisory(targetDir, args.yes);
+  const advisoryOutcome = maybeEmitUpgradeAdvisory(targetDir, args.yes, args.json);
   if (advisoryOutcome === "refused") return 1;
   const upgradeApproved = advisoryOutcome === "upgrade-approved";
   if (!args.force && !args.dryRun && !upgradeApproved) {
@@ -823,26 +922,55 @@ function runInit(argv) {
       templateVersion: SUBSTRATE_CONFIG_TEMPLATE_VERSION
     }
   ];
+  const say = makeSay(args.json);
   if (args.dryRun) {
-    runDryRun$1(plans);
-    return dispatchSubstrateCopy(targetDir, args.force || upgradeApproved, args.verbose, true, args.allowRoot, args.json);
-  }
-  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json);
-}
-function maybeEmitUpgradeAdvisory(targetDir, yes) {
+    runDryRun$1(plans, say);
+    const outcome = dispatchSubstrateCopy(
+      targetDir,
+      args.force || upgradeApproved,
+      args.verbose,
+      true,
+      args.allowRoot,
+      say
+    );
+    if (args.json) {
+      const report = buildInitReport({
+        entries: outcome.result?.wouldCopyEntries ?? [],
+        configs: plans.map((pl) => ({ path: pl.relativePath })),
+        refused: outcome.result?.refused ?? [],
+        // A dry run still reads every source file, so it can still fail
+        // to read one. Hard-coding this empty hid those failures from
+        // the JSON (RFC-0005 A-3).
+        errored: outcome.result?.errored ?? [],
+        hookCount: outcome.result?.hookCount ?? 0,
+        declaredHooksCopied: 0,
+        tier: RESOLVED_TIER
+      });
+      renderJsonReport(report, (t) => {
+        process.stdout.write(t);
+      });
+    }
+    return outcome.code;
+  }
+  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json, say);
+}
+function maybeEmitUpgradeAdvisory(targetDir, yes, json) {
+  const prompt = json ? (t) => {
+    process.stderr.write(t);
+  } : SAY_HUMAN;
   const manifestPath = join(targetDir, MANIFEST_RELATIVE_PATH);
   if (!existsSync(manifestPath)) return "ok";
   const version2 = readManifestShapeVersion(targetDir);
   if (version2 !== null && version2 >= 2) return "ok";
-  process.stdout.write(
+  prompt(
     `bassclef init: cli 1.0.1 introduces user-scope hook installation at ~/${HOOKS_SUBPATH}. cli 1.0.0 did not write there.
 `
   );
   if (yes) return "upgrade-approved";
-  process.stdout.write("bassclef init: continue? (y/N) ");
+  prompt("bassclef init: continue? (y/N) ");
   const answer = readOneLineFromStdin();
   if (answer === "" || answer === "y" || answer === "Y") return "upgrade-approved";
-  process.stdout.write("bassclef init: aborted by adopter.\n");
+  prompt("bassclef init: aborted by adopter.\n");
   return "refused";
 }
 function readOneLineFromStdin() {
@@ -854,7 +982,7 @@ function readOneLineFromStdin() {
     return "";
   }
 }
-function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, json) {
+function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, say) {
   const substitute = makePlaceholderTransform(targetDir);
   let result;
   try {
@@ -868,9 +996,9 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
     if (e instanceof CopyFailure) {
       process.stderr.write(`bassclef init: ${e.message}
 `);
-      if (e.kind === "ManifestMissing") return 4;
-      if (e.kind === "SchemaIncompatible") return 5;
-      return 2;
+      if (e.kind === "ManifestMissing") return { code: 4 };
+      if (e.kind === "SchemaIncompatible") return { code: 5 };
+      return { code: 2 };
     }
     throw e;
   }
@@ -878,23 +1006,23 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
     const wouldCopy = result.wouldCopy ?? [];
     for (const relativePath of wouldCopy) {
       const targetPath = join(targetDir, relativePath);
-      process.stdout.write(`  ${"would create".padEnd(14)} ${targetPath}
+      say(`  ${"would create".padEnd(14)} ${targetPath}
 `);
     }
     if (wouldCopy.length > 0) {
-      process.stdout.write(
+      say(
         `bassclef init: ${wouldCopy.length} substrate files would be copied.
 `
       );
     }
-    process.stdout.write(
+    say(
       `bassclef init: ${result.hookCount} hooks armed (${RESOLVED_TIER} tier).
 `
     );
-    return 0;
+    return { code: 0, result };
   }
   if (result.copied.length === 0 && result.refused.length === 0 && result.errored.length === 0) {
-    return 0;
+    return { code: 0, result };
   }
   const groupCounts = /* @__PURE__ */ new Map();
   for (const path of result.copied) {
@@ -903,17 +1031,17 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
     groupCounts.set(top, (groupCounts.get(top) ?? 0) + 1);
   }
   for (const [directory, count] of groupCounts) {
-    process.stdout.write(`  ${directory}: ${count} files copied
+    say(`  ${directory}: ${count} files copied
 `);
   }
   const parts = [];
   if (result.copied.length > 0) parts.push(`${result.copied.length} substrate files copied`);
   if (result.refused.length > 0) parts.push(`${result.refused.length} refused`);
   if (result.errored.length > 0) parts.push(`${result.errored.length} error(s)`);
-  process.stdout.write(`bassclef init: ${parts.join(", ")}.
+  say(`bassclef init: ${parts.join(", ")}.
 `);
   const grandTotal = 1 + result.copied.length;
-  process.stdout.write(
+  say(
     `bassclef init: ${grandTotal} files total (1 config + ${result.copied.length} substrate).
 `
   );
@@ -930,33 +1058,87 @@ function dispatchSubstrateCopy(targetDir, force, verbose, dryRun, allowRoot, jso
   const projectScope = copiedHookEntries.filter((e) => e.scope === "project").length;
   const scopeSuffix = userScope + projectScope > 0 ? ` ${projectScope} in <repo>/${HOOKS_SUBPATH.replace(/\/$/, "")}, ${userScope} in ~/${HOOKS_SUBPATH.replace(/\/$/, "")}.` : "";
   if (failedCount > 0) {
-    process.stdout.write(
+    say(
       `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix} ${failedCount} failed — see errors above. Rerun bassclef init to retry.
 `
     );
   } else {
-    process.stdout.write(
+    say(
       `bassclef init: Installed ${copiedCount} of ${declaredCount} hooks (${RESOLVED_TIER} tier).${scopeSuffix}
 `
     );
   }
-  if (json) {
-    const report = {
-      copied: copiedCount,
-      declared: declaredCount,
-      failed: failedCount,
-      scope_counts: { user: userScope, project: projectScope },
-      tier: RESOLVED_TIER
-    };
-    process.stderr.write(JSON.stringify(report) + "\n");
+  const catalogCounts = {
+    skills: 0,
+    rules: 0,
+    agents: 0,
+    luminaries: 0,
+    libs: 0,
+    adrs: 0,
+    standards: 0,
+    templates: 0,
+    "presence-templates": 0,
+    scripts: 0,
+    "root-docs": 0
+  };
+  const SKILLS_PREFIX = `${CLAUDE_TARGET_ROOT}/skills/`;
+  const RULES_PREFIX = `${CLAUDE_TARGET_ROOT}/rules/`;
+  const AGENTS_PREFIX = `${CLAUDE_TARGET_ROOT}/agents/`;
+  const LUMINARIES_PREFIX = `${CLAUDE_TARGET_ROOT}/luminaries/`;
+  const CLAUDE_ROOT_PREFIX = `${CLAUDE_TARGET_ROOT}/`;
+  for (const entry of result.copiedEntries) {
+    if (entry.path.startsWith(SKILLS_PREFIX)) catalogCounts.skills += 1;
+    else if (entry.path.startsWith(RULES_PREFIX)) catalogCounts.rules += 1;
+    else if (entry.path.startsWith(AGENTS_PREFIX)) catalogCounts.agents += 1;
+    else if (entry.path.startsWith(LUMINARIES_PREFIX)) catalogCounts.luminaries += 1;
+    else if (entry.path.startsWith("lib/")) catalogCounts.libs += 1;
+    else if (entry.path.startsWith("architecture/decisions/")) catalogCounts.adrs += 1;
+    else if (entry.path.startsWith("standards/")) catalogCounts.standards += 1;
+    else if (entry.path.startsWith("templates/")) catalogCounts.templates += 1;
+    else if (entry.path.startsWith("presence/install/")) catalogCounts["presence-templates"] += 1;
+    else if (entry.path.startsWith("scripts/")) catalogCounts.scripts += 1;
+    else if (!entry.path.startsWith(CLAUDE_ROOT_PREFIX) && !entry.path.includes("/") && /^[A-Z]/.test(entry.path)) {
+      catalogCounts["root-docs"] += 1;
+    }
+  }
+  const claudeCounts = [
+    catalogCounts.skills > 0 ? `${catalogCounts.skills} skills` : null,
+    catalogCounts.rules > 0 ? `${catalogCounts.rules} rules` : null,
+    catalogCounts.agents > 0 ? `${catalogCounts.agents} agents` : null,
+    catalogCounts.luminaries > 0 ? `${catalogCounts.luminaries} luminaries` : null
+  ].filter((s) => s !== null);
+  if (claudeCounts.length > 0) {
+    say(
+      `bassclef init: Installed ${claudeCounts.join(", ")} under <repo>/.claude/.
+`
+    );
   }
+  const otherCounts = [
+    catalogCounts.libs > 0 ? `${catalogCounts.libs} libs` : null,
+    catalogCounts.adrs > 0 ? `${catalogCounts.adrs} ADRs` : null,
+    catalogCounts.templates > 0 ? `${catalogCounts.templates} templates` : null,
+    catalogCounts["presence-templates"] > 0 ? `${catalogCounts["presence-templates"]} presence-templates` : null,
+    catalogCounts.standards > 0 ? `${catalogCounts.standards} standards` : null,
+    catalogCounts["root-docs"] > 0 ? `${catalogCounts["root-docs"]} root-docs` : null,
+    catalogCounts.scripts > 0 ? `${catalogCounts.scripts} scripts` : null
+  ].filter((s) => s !== null);
+  if (otherCounts.length > 0) {
+    say(
+      `bassclef init: Installed ${otherCounts.join(", ")} under <repo>/.
+`
+    );
+  }
+  say(
+    `bassclef init: ${result.refused.length} files refused (path collision).` + (result.refused.length > 0 ? ` Use --force to overwrite existing files.` : ``) + `
+`
+  );
   if (verbose && result.erroredMessages) {
     for (const msg of result.erroredMessages) {
       process.stderr.write(`  substrate: ${msg}
 `);
     }
   }
-  return result.errored.length > 0 ? 2 : 0;
+  return { code: result.errored.length > 0 ? 2 : 0, result };
 }
 function makePlaceholderTransform(targetDir) {
   const repoName = basename$1(targetDir);
@@ -966,7 +1148,7 @@ function makePlaceholderTransform(targetDir) {
     return content.replace(/\[REPO_NAME\]/g, repoName).replace(/\[ISO_TIMESTAMP\]/g, timestamp).replace(/\[TIER\]/g, RESOLVED_TIER).replace(/\[Repo name\]/g, repoName).replace(/<tier>/g, RESOLVED_TIER);
   };
 }
-function runDryRun$1(plans) {
+function runDryRun$1(plans, say) {
   for (const p of plans) {
     let planned;
     let extra = "";
@@ -986,12 +1168,12 @@ function runDryRun$1(plans) {
         planned = "would skip";
       }
     }
-    process.stdout.write(`  ${planned.padEnd(14)} ${p.fullPath}${extra}
+    say(`  ${planned.padEnd(14)} ${p.fullPath}${extra}
 `);
   }
   return 0;
 }
-function runReal$1(plans, force, verbose, targetDir, allowRoot, json) {
+function runReal$1(plans, force, verbose, targetDir, allowRoot, json, say) {
   const results = [];
   let anyRefused = false;
   let anyError = false;
@@ -1039,7 +1221,7 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json) {
       if (r.outcome === "error") label = `error (${r.message ?? "unknown"})`;
       else if (r.outcome === "refused") label = "refused";
       else label = r.outcome;
-      process.stdout.write(`  ${label.padEnd(10)} ${r.plan.fullPath}
+      say(`  ${label.padEnd(10)} ${r.plan.fullPath}
 `);
     }
   }
@@ -1061,38 +1243,59 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json) {
     return 2;
   }
   if (anyRefused && created > 0) {
-    process.stdout.write(
+    say(
       `bassclef init: ${created} config files created, ${unchanged} unchanged. Pass --force to overwrite.
 `
     );
   } else if (created === 0 && unchanged === plans.length) {
-    process.stdout.write("bassclef init: already initialized. No changes.\n");
+    say("bassclef init: already initialized. No changes.\n");
   } else {
-    process.stdout.write(`bassclef init: ${created} config files created, ${unchanged} unchanged.
+    say(`bassclef init: ${created} config files created, ${unchanged} unchanged.
 `);
   }
-  const walkerExit = dispatchSubstrateCopy(targetDir, force, verbose, false, allowRoot, json);
-  writeManifest(targetDir, results);
-  if (walkerExit === 0) {
-    process.stdout.write(
+  const walker = dispatchSubstrateCopy(targetDir, force, verbose, false, allowRoot, say);
+  const declaredLeaves = readDeclaredCommandLeaves(
+    join(targetDir, ".claude", "settings.json")
+  );
+  const declaredHooksCopied = (walker.result?.copiedEntries ?? []).filter(
+    (e) => e.path.startsWith(HOOKS_SUBPATH) && e.path.endsWith(".sh") && declaredLeaves.has(basename$1(e.path))
+  ).length;
+  const report = buildInitReport({
+    entries: walker.result?.copiedEntries ?? [],
+    configs: results.map((r) => ({ path: r.plan.relativePath })),
+    refused: walker.result?.refused ?? [],
+    errored: walker.result?.errored ?? [],
+    hookCount: walker.result?.hookCount ?? 0,
+    declaredHooksCopied,
+    tier: RESOLVED_TIER
+  });
+  writeManifest(targetDir, results, walker.result);
+  if (walker.code === 0) {
+    say(
       `bassclef init: your substrate lives under .claude/. Add .claude/ to .gitignore if you have not.
 `
     );
   }
-  return walkerExit;
+  if (json) {
+    renderJsonReport(report, (t) => {
+      process.stdout.write(t);
+    });
+  }
+  return walker.code;
 }
 function shouldRefuseRoot(currentUid, allowRoot) {
   if (currentUid === void 0) return false;
   if (currentUid !== 0) return false;
   return !allowRoot;
 }
-function writeManifest(targetDir, results) {
+function writeManifest(targetDir, results, walkerResult) {
   const entries = results.map((r) => {
     const entry = {
       path: r.plan.relativePath,
       template: r.plan.templateName,
       template_version: r.plan.templateVersion,
-      outcome: r.outcome
+      outcome: r.outcome,
+      source: "config-composer"
     };
     if (r.outcome === "created") {
       entry.content_hash_sha256 = hashContent(r.plan.content);
@@ -1100,6 +1303,38 @@ function writeManifest(targetDir, results) {
     }
     return entry;
   });
+  if (walkerResult) {
+    for (const copied of walkerResult.copiedEntries) {
+      entries.push({
+        path: copied.path,
+        template: `bundle:${copied.path}`,
+        template_version: version,
+        outcome: "created",
+        source: "bundle",
+        scope: copied.scope,
+        ...copied.content_hash_sha256 ? { content_hash_sha256: copied.content_hash_sha256 } : {},
+        updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    for (const path of walkerResult.refused) {
+      entries.push({
+        path,
+        template: `bundle:${path}`,
+        template_version: version,
+        outcome: "refused",
+        source: "bundle"
+      });
+    }
+    for (const path of walkerResult.errored) {
+      entries.push({
+        path,
+        template: `bundle:${path}`,
+        template_version: version,
+        outcome: "error",
+        source: "bundle"
+      });
+    }
+  }
   const manifestDir = join(targetDir, ".bassclef");
   const manifestPath = join(manifestDir, "init.manifest.json");
   const content = manifestTemplate({
@@ -1110,7 +1345,12 @@ function writeManifest(targetDir, results) {
   try {
     mkdirSafely(manifestDir);
     writeSafely(manifestPath, content, { force: true });
-  } catch {
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `bassclef init: could not write ${manifestPath} (${reason}). The files were written. Run \`bassclef init --force\` to rebuild the record.
+`
+    );
   }
 }
 function usage$2() {
@@ -1561,7 +1801,10 @@ function emitL2Output(decisions, verbose) {
   }
 }
 function updateManifestEntry(manifest, path, patch) {
-  const idx = manifest.files.findIndex((f) => f.path === path);
+  const wantScope = patch.scope;
+  const idx = manifest.files.findIndex(
+    (f) => f.path === path && (wantScope === void 0 || f.scope === wantScope)
+  );
   if (idx < 0) {
     manifest.files.push({
       path,

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.0.4";
+const version = "1.1.1";
 exports.version = version;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export declare const version: "1.0.4";
+export declare const version: "1.1.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.0.4";
+const version = "1.1.1";
 export {
   version
 };

package/dist/lite/.claude/agents/architect.md

@@ -0,0 +1,70 @@
+---
+tier: lite
+name: Architect
+description: "Opinionated. Builds C4 diagrams, writes ADRs, proves architecture against risks. Prefers boring technology. Documents why, not just what."
+tools: Read, Write, Glob, Grep, WebSearch
+model: claude-sonnet-4-6
+---
+
+You are the Architect. Your discipline is Analysis & Design.
+
+## Persona
+Opinionated. You prefer boring technology. You document *why*, not just *what*. You prove things before committing to them.
+
+## When active
+- Elaboration (primary)
+- Consulted during Construction for ADR violations
+
+## Responsibilities
+- Build C4 Context and Container diagrams
+- Write ADRs for load-bearing decisions
+- Prove or disprove architecture against top technical risks
+- Define component boundaries and interfaces
+- Invoke /architect-review skill at Lifecycle Architecture Milestone gate
+- Invoke /pattern-review skill for pattern review
+
+## Decision authority
+Architecture. You own ADRs. No code without a container it belongs to.
+
+## Handoff
+Accepted ADRs + C4 substrate → Builder picks up.
+
+## Luminaries
+
+- **Simon Brown** — *"Architecture should be as easy to explain as it is to code."*
+  - C4 Model: Context → Container → Component → Code (four zoom levels)
+  - You produce Level 2 component diagrams — the sweet spot for decision-making
+  - Diagrams are communication tools, not decoration
+
+- **Michael Nygard** — *"Architecture decisions are the ones you wish you could get right early."*
+  - Architecture Decision Records: capture the "why," not just the "what"
+  - Status lifecycle: proposed → accepted → deprecated → superseded
+  - Record context and consequences — future-you will thank present-you
+
+- **Robert C. Martin (Uncle Bob)** — *"Architecture is about intent, not frameworks."*
+  - SOLID principles: five rules you check every module against
+  - The dependency rule: source code dependencies point inward
+  - Boundaries protect business rules from infrastructure details
+
+- **Eric Evans** — *"The model is the backbone of the design."*
+  - Domain-Driven Design: code structure mirrors business domains
+  - Bounded Contexts: different parts of the system may model the same concept differently
+  - Ubiquitous Language: if the team uses different words for the same thing, the architecture is wrong
+
+- **Craig Larman** — *"Models are not right or wrong — they are more or less useful."*
+  - Applying UML and Patterns: bridges formal modeling to practical implementation
+  - Iterative development: architecture emerges through feedback, not big upfront design
+  - Responsibility-Driven Design: assign behavior where the data lives
+
+## Checkpointing
+After completing each major artifact (C4 diagram, ADR, component boundary):
+- Update `docs/whereami.md` with current progress
+- Commit the artifact with conventional commit
+- State what was produced and what's next
+
+## Rules
+- ADR status lifecycle: proposed → accepted → deprecated → superseded
+- Only accepted ADRs govern. Proposed = under consideration.
+- ADR violations are blockers, not suggestions
+- You resolve technical risks. Market risks → PM. UX risks → Designer.
+- You do NOT implement. You architect.