@geraldmaron/construct 1.0.7 → 1.0.8

package/scripts/{sync-agents.mjs → sync-specialists.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * sync-agents.mjs — regenerate agent adapters for all platforms from agents/registry.json.
+ * sync-specialists.mjs — regenerate agent adapters for all platforms from specialists/registry.json.
  *
  * Reads registry.json, resolves env vars and model tiers, then writes Claude Code,
  * OpenCode, Codex, Copilot, VS Code, and Cursor adapters. Called by 'construct sync'.
@@ -50,7 +50,7 @@ for (const [key, value] of Object.entries(mergedEnv)) {
   if (!(key in process.env)) process.env[key] = value;
 }
 if (!process.env.CX_TOOLKIT_DIR) process.env.CX_TOOLKIT_DIR = root;
-const registryPath = path.join(root, "agents", "registry.json");
+const registryPath = path.join(root, "specialists", "registry.json");
 const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
 
 function validateRegistry(registry) {
@@ -58,31 +58,32 @@ function validateRegistry(registry) {
   if (!registry.version) errors.push("Missing 'version' field");
   if (!registry.system) errors.push("Missing 'system' field");
   if (!registry.prefix) errors.push("Missing 'prefix' field");
-  if (!Array.isArray(registry.agents)) errors.push("Missing or invalid 'agents' array");
-  if (!Array.isArray(registry.personas)) errors.push("Missing or invalid 'personas' array");
+  if (!registry.orchestrator) errors.push("Missing 'orchestrator' field");
+  if (!Array.isArray(registry.specialists)) errors.push("Missing or invalid 'specialists' array");
   const validTiers = new Set(["reasoning", "standard", "fast"]);
   const names = new Set();
 
-  for (const persona of registry.personas ?? []) {
-    if (!persona.name) { errors.push("Persona missing 'name'"); continue; }
-    if (names.has(persona.name)) errors.push(`Duplicate name: ${persona.name}`);
-    names.add(persona.name);
-    if (!persona.description) errors.push(`${persona.name}: missing 'description'`);
-    if (!persona.promptFile) errors.push(`${persona.name}: missing 'promptFile'`);
-    if (!persona.displayName) errors.push(`${persona.name}: missing 'displayName'`);
+  if (registry.orchestrator) {
+    const o = registry.orchestrator;
+    if (!o.name) errors.push("Orchestrator missing 'name'");
+    if (names.has(o.name)) errors.push(`Duplicate name: ${o.name}`);
+    names.add(o.name);
+    if (!o.description) errors.push("Orchestrator: missing 'description'");
+    if (!o.promptFile) errors.push("Orchestrator: missing 'promptFile'");
+    if (!o.displayName) errors.push("Orchestrator: missing 'displayName'");
   }
 
-  for (const agent of registry.agents ?? []) {
-    if (!agent.name) { errors.push("Agent missing 'name'"); continue; }
-    if (names.has(agent.name)) errors.push(`Duplicate name: ${agent.name}`);
-    names.add(agent.name);
-    if (!agent.prompt && !agent.promptFile) errors.push(`${agent.name}: missing 'prompt' or 'promptFile'`);
-    if (!agent.description) errors.push(`${agent.name}: missing 'description'`);
-    if (!agent.model && !agent.modelTier) errors.push(`${agent.name}: needs 'model' or 'modelTier'`);
-    if (agent.modelTier && !validTiers.has(agent.modelTier)) errors.push(`${agent.name}: invalid modelTier '${agent.modelTier}'`);
-    if (!agent.claudeTools) errors.push(`${agent.name}: missing 'claudeTools'`);
-    if (agent.modelGuidance && typeof agent.modelGuidance !== "object") {
-      errors.push(`${agent.name}: modelGuidance must be an object`);
+  for (const specialist of registry.specialists ?? []) {
+    if (!specialist.name) { errors.push("Specialist missing 'name'"); continue; }
+    if (names.has(specialist.name)) errors.push(`Duplicate name: ${specialist.name}`);
+    names.add(specialist.name);
+    if (!specialist.prompt && !specialist.promptFile) errors.push(`${specialist.name}: missing 'prompt' or 'promptFile'`);
+    if (!specialist.description) errors.push(`${specialist.name}: missing 'description'`);
+    if (!specialist.model && !specialist.modelTier) errors.push(`${specialist.name}: needs 'model' or 'modelTier'`);
+    if (specialist.modelTier && !validTiers.has(specialist.modelTier)) errors.push(`${specialist.name}: invalid modelTier '${specialist.modelTier}'`);
+    if (!specialist.claudeTools) errors.push(`${specialist.name}: missing 'claudeTools'`);
+    if (specialist.modelGuidance && typeof specialist.modelGuidance !== "object") {
+      errors.push(`${specialist.name}: modelGuidance must be an object`);
     }
   }
 
@@ -180,7 +181,7 @@ const _stagedPairs = []; // [{ staging, real, content }]
 
 function writeFile(file, content) {
   mkdirp(path.dirname(file));
-  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-agents' }) : content;
+  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-specialists' }) : content;
 
   if (DRY_RUN) {
     // Stage in memory only — compare against current on-disk content.
@@ -228,15 +229,15 @@ const sharedGuidance = registry.sharedGuidance ?? [];
 const platformGuidance = registry.platformGuidance ?? {};
 const globalModelGuidance = registry.modelGuidance ?? {};
 
-const generatedHeader = `# Generated by ${systemName}/sync-agents.mjs. Edit agents/registry.json instead.`;
+const generatedHeader = `# Generated by ${systemName}/sync-specialists.mjs. Edit specialists/registry.json instead.`;
 const generatedMarkdownNote = [
   '<!--',
-  `Generated by construct sync from agents/registry.json.`,
+  `Generated by construct sync from specialists/registry.json.`,
   'Do not edit this file directly — changes will be overwritten on next sync.',
   'Regenerate: construct sync',
   '-->',
   '',
-  '> Generated from `agents/registry.json`. Edit the registry, then run `construct sync`.',
+  '> Generated from `specialists/registry.json`. Edit the registry, then run `construct sync`.',
 ].join('\n');
 
 const standardConstructTools = [
@@ -362,7 +363,7 @@ function resolveModelChain(entry) {
 function mkdirp(dir) { fs.mkdirSync(dir, { recursive: true }); }
 
 function adapterName(entry) {
-  return entry.isPersona ? entry.name : `${agentPrefix}${entry.name}`;
+  return entry.isOrchestrator ? entry.name : `${agentPrefix}${entry.name}`;
 }
 
 function loadPersonaPrompt(persona) {
@@ -398,7 +399,7 @@ function buildRoleFooter(entry) {
   if (collaborators.length > 0) {
     lines.push(`Collaborators: ${collaborators.map((c) => (c.startsWith("cx-") ? c : `cx-${c}`)).join(", ")}.`);
   }
-  if (entry.isPersona !== true && entry.canEdit === false) {
+  if (entry.isOrchestrator !== true && entry.canEdit === false) {
     lines.push("Do not implement code or edit source files.");
   }
   if (entry.returnsStructured !== false) {
@@ -444,7 +445,7 @@ function buildPrompt(entry, allEntries, platform) {
       console.error(
         `[sync] Hard cap exceeded. Options:\n` +
         `   - trim the prompt body or move detail to a skill (preferred)\n` +
-        `   - set "wordCapOverride": <N> on this entry in agents/registry.json with a written reason\n` +
+        `   - set "wordCapOverride": <N> on this entry in specialists/registry.json with a written reason\n` +
         `   - re-run with --force or CONSTRUCT_SYNC_FORCE=1 as a temporary escape hatch\n` +
         `Prompt budget is a hard contract because every over-cap agent degrades every session that dispatches it.`,
       );
@@ -501,18 +502,19 @@ function removeStaleAdapters(dir, ext, entries) {
 function buildEntries() {
   const entries = [];
 
-  for (const persona of registry.personas ?? []) {
-    const personaCanEdit = persona.permissions?.edit === "allow";
+  // Orchestrator entry
+  if (registry.orchestrator) {
+    const orchestratorCanEdit = registry.orchestrator.permissions?.edit === "allow";
     entries.push({
-      ...persona,
-      isPersona: true,
-      prompt: loadPersonaPrompt(persona),
-      codexSandbox: persona.codexSandbox ?? (personaCanEdit ? "workspace-write" : "read-only"),
-      reasoningEffort: persona.reasoningEffort ?? "high",
+      ...registry.orchestrator,
+      isOrchestrator: true,
+      prompt: loadPersonaPrompt(registry.orchestrator),
+      codexSandbox: registry.orchestrator.codexSandbox ?? (orchestratorCanEdit ? "workspace-write" : "read-only"),
+      reasoningEffort: registry.orchestrator.reasoningEffort ?? "high",
     });
   }
 
-  // Filter agents by the active profile's role set. RND lists every specialist
+  // Filter specialists by the active profile's role set. RND lists every specialist
   // so behavior is unchanged for the default; non-RND profiles emit only the
   // specialists they declare. Profiles whose role list is empty (legacy/test)
   // fall through to no filter so callers don't get a silent empty registry.
@@ -521,11 +523,11 @@ function buildEntries() {
     ? new Set(activeProfile.roles)
     : null;
 
-  for (const agent of registry.agents ?? []) {
-    if (profileRoles && !profileRoles.has(agent.name)) continue;
+  for (const specialist of registry.specialists ?? []) {
+    if (profileRoles && !profileRoles.has(specialist.name)) continue;
     entries.push({
-      ...agent,
-      isPersona: false,
+      ...specialist,
+      isSpecialist: true,
     });
   }
 
@@ -650,16 +652,16 @@ function syncClaude(entries, targetDir = null) {
   if (!targetDir) {
     const claudeMdPath = path.join(home, ".claude", "CLAUDE.md");
     const existing = fs.existsSync(claudeMdPath) ? fs.readFileSync(claudeMdPath, "utf8") : "# Claude Global Instructions\n";
-    const personaList = entries.filter((e) => e.isPersona).map((e) => `- \`${adapterName(e)}\`: ${e.role} — ${e.description}`).join("\n");
-    // Only surface non-internal agents in CLAUDE.md — internal agents are dispatched by Construct, not invoked by users
-    const agentList = entries.filter((e) => !e.isPersona && !e.internal).map((e) => `- \`${adapterName(e)}\`: ${e.description}`).join("\n");
+    const personaList = entries.filter((e) => e.isOrchestrator).map((e) => `- \`${adapterName(e)}\`: ${e.role} — ${e.description}`).join("\n");
+    // Only surface non-internal specialists in CLAUDE.md — internal specialists are dispatched by Construct, not invoked by users
+    const specialistList = entries.filter((e) => !e.isOrchestrator && !e.internal).map((e) => `- \`${adapterName(e)}\`: ${e.description}`).join("\n");
     const note = `## ${systemName.charAt(0).toUpperCase() + systemName.slice(1)} Personas
 
 ${personaList}
 
 ## Internal Specialists
 
-${agentList || "(all specialists are internal — routed through Construct)"}`;
+${specialistList || "(all specialists are internal — routed through Construct)"}`;
     writeFile(claudeMdPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd));
 
     // Sync MCP servers into ~/.claude/settings.json if it exists
@@ -1011,8 +1013,8 @@ function syncOpencode(entries) {
   const prefixes = [agentPrefix];
   for (const key of Object.keys(config.agent)) {
     const isManaged = prefixes.some((p) => key.startsWith(p));
-    const isPersona = registry.personas.some((p) => p.name === key);
-    if ((isManaged || isPersona) && !entries.find((e) => adapterName(e) === key)) {
+    const isOrchestrator = registry.orchestrator?.name === key;
+    if ((isManaged || isOrchestrator) && !entries.find((e) => adapterName(e) === key)) {
       delete config.agent[key];
     }
   }
@@ -1022,10 +1024,10 @@ function syncOpencode(entries) {
     const name = adapterName(entry);
     const perms = opencodePermissions(entry);
     config.agent[name] = {
-      description: entry.isPersona
+      description: entry.isOrchestrator
         ? `${entry.role} — ${entry.description}`
         : entry.description,
-      mode: entry.isPersona ? "all" : "subagent",
+      mode: entry.isOrchestrator ? "all" : "subagent",
       prompt: buildPrompt(entry, entries, "opencode"),
       permission: {
         ...perms,
@@ -1102,6 +1104,75 @@ function syncCommands(targetDir = null) {
   return count;
 }
 
+// --- Skills sync ---
+
+/**
+ * Walk skills/ recursively and collect every .md file (flat) and every
+ * <name>/SKILL.md directory entry. Returns [{ name, content }] where name
+ * is the slash-relative path without extension, e.g. "strategy/narrative-arc".
+ */
+function collectSkills() {
+  const skillsDir = path.join(root, "skills");
+  const results = [];
+
+  function walk(dir, prefix) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        // Check if this is a SKILL.md directory form: <name>/SKILL.md
+        const skillMdPath = path.join(full, "SKILL.md");
+        if (fs.existsSync(skillMdPath)) {
+          // Avoid double-walking; record this skill and do not descend further.
+          const name = rel;
+          results.push({ name, content: fs.readFileSync(skillMdPath, "utf8") });
+        } else {
+          walk(full, rel);
+        }
+      } else if (entry.name.endsWith(".md") && entry.name !== "routing.md" && entry.name !== "SKILL.md") {
+        const name = rel.replace(/\.md$/, "");
+        results.push({ name, content: fs.readFileSync(full, "utf8") });
+      }
+    }
+  }
+
+  walk(skillsDir, "");
+  return results;
+}
+
+/**
+ * Prefix prepended to every generated SKILL.md. The comment must survive
+ * round-trips — it is the canonical signal that a file was produced by sync
+ * and must not be hand-edited.
+ */
+const SKILL_GENERATED_PREFIX = "# Generated by construct sync\n\n";
+
+/**
+ * Write collected skills to both .claude/skills/ and .agents/skills/ in
+ * SKILL.md directory format.
+ *
+ * Idempotency: content written is deterministic; writing the same content
+ * twice is a no-op because writeFile skips unchanged files in dry-run mode
+ * and two-phase staging in normal mode produces identical results.
+ */
+function syncSkills() {
+  const skills = collectSkills();
+  if (skills.length === 0) return 0;
+
+  const claudeSkillsDir = path.join(home, ".claude", "skills");
+  const agentsSkillsDir = path.join(home, ".agents", "skills");
+
+  for (const { name, content } of skills) {
+    const generated = `${SKILL_GENERATED_PREFIX}${content}`;
+    writeFile(path.join(claudeSkillsDir, name, "SKILL.md"), generated);
+    writeFile(path.join(agentsSkillsDir, name, "SKILL.md"), generated);
+  }
+
+  return skills.length;
+}
+
 // --- Main ---
 
 const projectDir = process.argv.includes("--project") ? process.cwd() : null;
@@ -1117,7 +1188,7 @@ if (COMPRESS_PERSONAS) {
   let totalIn = 0;
   let totalOut = 0;
   for (const entry of entries) {
-    if (!entry.isPersona || !entry.prompt) continue;
+    if (!entry.isOrchestrator || !entry.prompt) continue;
     const before = entry.prompt;
     try {
       const after = await compressor.compress(before, { ratio: 0.6 });
@@ -1132,7 +1203,7 @@ if (COMPRESS_PERSONAS) {
   }
   if (totalIn > 0) {
     const ratio = ((totalOut / totalIn) * 100).toFixed(0);
-    console.log(`compress-personas: ${totalIn} → ${totalOut} chars (${ratio}%) across ${entries.filter((e) => e.isPersona).length} personas`);
+    console.log(`compress-personas: ${totalIn} → ${totalOut} chars (${ratio}%) across ${entries.filter((e) => e.isOrchestrator).length} personas`);
   }
 }
 
@@ -1148,8 +1219,8 @@ try {
       console.log(`Synced ${entries.length} agents + ${cmdCount} commands to ${path.join(projectDir, ".claude/")} (project mode).`);
     }
   } else {
-    const personaCount = entries.filter((e) => e.isPersona).length;
-    const agentCount = entries.filter((e) => !e.isPersona).length;
+    const personaCount = entries.filter((e) => e.isOrchestrator).length;
+    const specialistCount = entries.filter((e) => !e.isOrchestrator).length;
 
     syncCodex(entries);
     syncClaude(entries);
@@ -1158,6 +1229,7 @@ try {
     const vscodeOk = syncVSCode();
     const cursorOk = syncCursor();
     const cmdCount = syncCommands();
+    const skillCount = syncSkills();
 
     if (DRY_RUN) {
       printDryRunDiff();
@@ -1172,7 +1244,7 @@ try {
         vscodeOk && "VS Code",
         cursorOk && "Cursor",
       ].filter(Boolean).join(", ");
-      console.log(`Synced ${personaCount} personas + ${agentCount} specialists + ${cmdCount} commands to ${targets}.`);
+      console.log(`Synced ${personaCount} orchestrator + ${specialistCount} specialists + ${cmdCount} commands + ${skillCount} skills to ${targets}.`);
 
       // Regenerate shell completions so new commands are immediately tab-completable
       const completionsDir = generateCompletions();

package/skills/ai/prompt-optimizer.md

@@ -6,7 +6,7 @@ and the agent registry + construct sync as the deployment layer.
 -->
 # Prompt Auto-Optimization Loop
 
-Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`agents/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`specialists/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
 
 ## Running the optimizer
 
@@ -34,7 +34,7 @@ The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-ins
 
 ## Step 1: Gather signal
 
-Retrieve the current production prompt for the target agent from `agents/registry.json` (or the corresponding `promptFile` if using extracted prompts).
+Retrieve the current production prompt for the target agent from `specialists/registry.json` (or the corresponding `promptFile` if using extracted prompts).
 
 Then retrieve recent traces via the telemetry backend REST API:
 
@@ -76,7 +76,7 @@ Write an improved prompt that directly addresses the diagnosed failures. Rules:
 
 ## Step 4: Push to staging
 
-Update the agent's prompt in `agents/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
+Update the agent's prompt in `specialists/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
 
 Log the candidate prompt as a span attribute on a test run batch using `cx_trace`. Tag spans with `promptVersion: staging-{timestamp}` and score them with `cx_score` as traces complete.
 

package/skills/exploration/dependency-graph-reading.md

@@ -0,0 +1,98 @@
+<!--
+skills/exploration/dependency-graph-reading.md (Dependency Graph Reading)
+Use when auditing a project's supply chain risk, evaluating upgrade paths,
+or assessing the risk surface of a new codebase. Covers npm/cargo/maven
+lockfile interpretation, transitive dependency patterns, and risk signals.
+-->
+
+# Dependency Graph Reading
+
+Use when assessing the risk surface of a project's dependencies, planning upgrades, or evaluating a new codebase's supply chain posture.
+
+## npm / package-lock.json
+
+The lockfile is the authoritative record of what actually runs in production.
+
+**What `package-lock.json` tells you:**
+- Exact resolved versions of every dependency (direct + transitive).
+- The registry URL each package resolved from (watch for non-npm registry sources).
+- Integrity hashes for tamper detection (missing or mismatched hashes are a supply chain signal).
+
+**Commands:**
+```bash
+# Tree of direct dependencies with their transitive deps
+npm ls --all --depth=5 <package>
+
+# Why is this package installed? (shows the resolution path)
+npm ls <package>
+
+# Outdated direct dependencies
+npm outdated
+
+# Audit for known CVEs
+npm audit --json | jq '.vulnerabilities | to_entries | sort_by(.value.severity) | reverse[]'
+```
+
+**Risk signals in the lockfile:**
+- Packages sourced from `github:`, `file:`, or private registries, higher supply-chain risk.
+- Very old `lockfileVersion` (v1), may not capture integrity hashes properly.
+- Transitive dependencies with `requires: {}` instead of resolved versions, resolution ambiguity.
+
+## Cargo.lock (Rust)
+
+Cargo maintains a flat lockfile with explicit source declarations.
+
+**Key fields:**
+- `[[package]]`: each entry is a resolved crate version.
+- `source = "registry+..."`: standard crates.io source. `source = "git+..."`: git dependency (less auditable).
+- `checksum`: SHA256 of the downloaded crate.
+
+**Commands:**
+```bash
+# Dependency tree with feature flags
+cargo tree
+
+# Find all versions of a crate (version conflicts)
+cargo tree -d
+
+# Audit for known vulnerabilities
+cargo audit
+```
+
+## Maven / gradle (JVM)
+
+The effective POM / resolved configuration tells you what actually runs.
+
+```bash
+# Full dependency tree with transitive
+mvn dependency:tree -Dverbose
+
+# Resolved versions for a specific scope
+mvn dependency:list -Dscope=compile
+
+# Gradle
+./gradlew dependencies --configuration runtimeClasspath
+```
+
+**Risk signals:**
+- Version range declarations (`[1.0,)`), means any future version could be resolved at build time.
+- `SNAPSHOT` versions in non-snapshot builds, unstable artifact references.
+- Duplicate versions of the same artifact (version conflict, one wins, one is silently dropped).
+
+## Cross-ecosystem risk signals
+
+| Signal | Risk | Action |
+|---|---|---|
+| Dependency with <100 weekly downloads | Supply chain (abandoned / obscure) | Evaluate inlining or replacing |
+| Dependency last published >2 years ago | Maintenance risk | Check for forks or replacements |
+| Deep transitive chain (>10 levels) | Blast radius | Map critical path; isolate |
+| Single maintainer with no 2FA | Takeover risk | Monitor; prefer alternatives with org ownership |
+| Package name squatting (typosquat) | Injection risk | Verify exact package name + registry source |
+| Wildcard `*` version pin | Reproducibility failure | Lock to exact version |
+
+## Practical audit workflow
+
+1. **Enumerate the blast radius**: which packages, if compromised, have write access to your production environment or sensitive data? These are the highest-risk nodes.
+2. **Check freshness on the critical path**: `npm audit`, `cargo audit`, `snyk test`. Focus on high/critical severity findings that affect runtime code (not devDependencies).
+3. **Identify orphaned dependencies**: packages no code imports directly but appear in the lockfile. May be safe to remove, reducing surface area.
+4. **Check for version conflicts**: multiple resolved versions of the same package indicate an incomplete deduplication. Usually benign; occasionally a security issue if an old insecure version is in the tree.

package/skills/exploration/tracer-bullet-method.md

@@ -0,0 +1,71 @@
+<!--
+skills/exploration/tracer-bullet-method.md (Tracer Bullet Method)
+Use when starting implementation in an unfamiliar or complex system.
+A tracer bullet is a minimal end-to-end path through the system,
+real code, real infrastructure, real calls, before any deep work begins.
+-->
+
+# Tracer Bullet Method
+
+Use when beginning implementation in a new system, new integration, or new architectural layer. A tracer bullet is not a prototype; it is the thinnest possible complete path through the real system.
+
+## What a tracer bullet is
+
+A tracer bullet hits every layer of the architecture, UI, API, business logic, data store, external service, with real code and real infrastructure. It is not a mock; it is a thin vertical slice.
+
+**The goal:** prove that the end-to-end path works before committing to the full implementation.
+
+**What it is not:**
+- A prototype (a prototype tests a concept; a tracer bullet tests the infrastructure).
+- A spike (a spike is time-boxed exploration; a tracer bullet produces code you keep).
+- A stub (stubs replace real behavior; the tracer bullet uses real behavior).
+
+## When to use it
+
+Use a tracer bullet when:
+- You're integrating two systems for the first time and don't know where the friction is.
+- You're adding a new capability to a system with unfamiliar internals.
+- The architecture requires multiple components to cooperate, and you need to verify the cooperation works before building each component out.
+- You're prototyping a new data model that touches multiple layers.
+
+## How to fire one
+
+**Step 1: Define the thinnest path**
+
+What is the simplest possible user action (or API call) that touches every layer you need to implement? This is your target path.
+
+Example: for a new feature "user uploads an image":
+- Thinnest path: user sends a single 1KB image, it is stored, and the storage URL is returned.
+
+**Step 2: Identify every seam**
+
+Map the layers the path crosses:
+- Presentation: what receives the request?
+- Transport: what format does the request take?
+- Validation: what checks the input?
+- Business logic: what transforms or routes it?
+- Persistence: what stores it?
+- External services: what calls are made?
+
+**Step 3: Implement one thin vertical slice**
+
+Write just enough code to make the tracer path work end-to-end. No error handling, no edge cases, no optimization. The only question is: does the path close?
+
+**Step 4: Verify closure**
+
+Run it. Check each layer produced the expected artifact. A tracer bullet that doesn't reach the end is valuable, it tells you exactly where the friction is before you've invested in the full implementation.
+
+**Step 5: Expand**
+
+Once the path closes, add error handling, validation, edge cases, and tests. You are now implementing on a system you know works.
+
+## Tracer bullet vs. walking skeleton
+
+A walking skeleton (Cockburn) is similar but broader: the minimum architecture that demonstrates a complete feature. A tracer bullet is more specific, it is a single request path through an existing or new system. The terms are used interchangeably in practice; the distinction matters less than the principle.
+
+## Anti-patterns
+
+- **Mocking too much**: if the tracer bullet uses mocked services, you haven't proved the real path works. Mocks are fine for unit tests, not for the tracer.
+- **Doing too much at once**: if the tracer path covers 5 new capabilities, you won't know which one caused the failure. Fire one bullet at a time.
+- **Skipping the tracer for "simple" changes**: the changes most likely to surprise you are the ones that seem simple. Fire anyway.
+- **Throwing the bullet away**: a tracer bullet is production-quality code on a thin path. It is not throwaway. The skeleton expands from it.

package/skills/exploration/unknown-codebase-onboarding.md

@@ -0,0 +1,91 @@
+<!--
+skills/exploration/unknown-codebase-onboarding.md (Unknown Codebase Onboarding)
+Use when a specialist is operating in a new or unfamiliar codebase and
+needs a systematic path from zero context to productive contribution.
+Covers first-hour, first-day, and first-week checkpoints.
+-->
+
+# Unknown Codebase Onboarding
+
+Use when entering an unfamiliar codebase for the first time, or when the task requires understanding a system you haven't touched before.
+
+## First-hour checklist (orientation)
+
+The goal in the first hour is to build a mental model of the system's shape, not to understand every detail.
+
+**1. Start with the entry points:**
+```bash
+# What runs? What are the main binaries / services?
+ls bin/ scripts/ cmd/ src/main*
+
+# What does the README say is the first command to run?
+cat README.md | head -60
+```
+
+**2. Understand the dependency graph:**
+```bash
+cat package.json | jq '{name, version, scripts, dependencies: (.dependencies | keys), devDependencies: (.devDependencies | keys)}'
+# or: cat Cargo.toml, go.mod, pom.xml, requirements.txt
+```
+
+**3. Find the test suite:**
+```bash
+ls tests/ test/ spec/ __tests__/
+# What's the test runner? How do you run it?
+grep -i test package.json | head -5
+```
+
+**4. Find the data model:**
+```bash
+ls db/ schema/ migrations/ prisma/ models/
+# For a service: what does it store, and how is it structured?
+```
+
+**5. Trace one request end-to-end:**
+Pick the simplest happy path through the system and trace it from entry point to output. This reveals the architectural seams and where decisions live.
+
+## First-day checklist (orientation to action)
+
+**Identify the change surface:**
+- What is the most recently changed directory? (`git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20`)
+- What directories do most PRs touch? High-churn areas are where active work lives.
+
+**Understand the invariants:**
+- Are there comments marked `INVARIANT`, `IMPORTANT`, `DO NOT CHANGE`, or `CRITICAL`? These are the load-bearing beliefs.
+- Are there tests marked `regression` or referencing bug IDs? These document specific failure modes.
+
+**Find the configuration layer:**
+```bash
+# Environment variables the system reads
+grep -r 'process\.env\.\|os\.environ\|getenv' --include='*.js' --include='*.py' --include='*.go' | grep -v test | grep -v node_modules
+```
+
+**Identify the seams:**
+- Where does the system boundary end? What does it call out to (APIs, databases, queues)?
+- What are the contracts at those seams (types, schemas, documented expectations)?
+
+## First-week checklist (productive contribution)
+
+**Build a dependency map:**
+- Which modules are leaf nodes (pure logic, few dependencies)?
+- Which modules are hubs (imported everywhere, high coupling)?
+- Leaf nodes are safe to modify; hub changes have blast radius.
+
+**Read the ADRs and postmortems:**
+- Architecture decisions (`docs/adr/`, `decisions/`, `DECISIONS.md`) explain why the code is shaped the way it is.
+- Postmortems explain what has already broken and how the system defends against it. Don't break a defense you don't understand.
+
+**Find the test coverage gaps:**
+- Which modules have no tests? These are the highest-risk areas to modify.
+- Which tests are flaky (retry logic, `skip`, `todo`)? Unreliable tests produce unreliable confidence.
+
+**Validate your mental model:**
+- Before making a change, explain to a colleague (or write down) what the change does and why it won't break anything. If you can't explain it, you don't understand it yet.
+- After making a change, check: did any behavior you didn't intend to change actually change? Diff the test output.
+
+## Anti-patterns when onboarding
+
+- **Deep-diving before breadth-surveying**: the codebase is large; get the shape before the details.
+- **Modifying without understanding invariants**: breaking a behavior that was intentional because you didn't know why it existed.
+- **Trusting test coverage numbers**: 80% coverage means 80% of lines are executed, not that 80% of behaviors are tested.
+- **Ignoring comments with bug IDs**: comments that say `// workaround for PROJ-123` are load-bearing. Look up the issue before removing them.