@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.37.1",
+  "version": "1.38.1",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -29,11 +29,13 @@
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
     "lint": "pnpm typecheck",
-    "test": "pnpm -r test",
+    "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node scripts/build-claude-agents.mjs",
+    "build:claude": "node bin/agent-cortex.mjs install claude",
+    "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh",
+    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:claude && pnpm build:copilot",
+    "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"
   }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.37.1",
+  "version": "1.38.1",
   "author": {
     "name": "jaybeeuu"
   },

package/scripts/build-copilot-agents.mjs

@@ -0,0 +1,30 @@
+// Regenerates the committed Copilot CLI flat agent files (agents/*.agent.md)
+// from the canonical composable agent sources (agents/<name>/).
+//
+// This script is a thin wrapper over the shared install-time generator
+// (bin/installers/copilot.mjs) — `agent-cortex install copilot` runs exactly the
+// same code path, so install-time and build-time output can never diverge. CI
+// runs this and checks `git diff --exit-code -- 'agents/*.agent.md'` to
+// guarantee the committed flat files are never stale: a fresh clone (or a
+// direct path plugin install) ships the Copilot plugin read-ready.
+//
+//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
+//                             agents/<name>/copilot/frontmatter.json +
+//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
+//                             with {{TOOL:...}}/{{PATH:...}} substituted against
+//                             the copilot column of token-map.json.
+//
+// The flat files live in the same agents/ directory the Copilot plugin scans
+// (plugin.json "agents": "agents/"), next to the composable dirs they come
+// from — the generator only writes *.agent.md files and never deletes.
+//
+// Run: pnpm build:copilot   (node scripts/build-copilot-agents.mjs)
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { installCopilot } from "../bin/installers/copilot.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/lib/compose-agent.mjs

@@ -0,0 +1,241 @@
+// Shared composer: reads a composable agent directory (agents/<name>/) and emits
+// the harness-specific agent content defined by agents/README.md. The Copilot
+// generator (scripts/build-copilot-agents.mjs) and the Claude install-time generator
+// (bin/installers/claude.mjs) compose from here, so the composable dirs are
+// the single source of truth and the flat/generated files stay in lockstep.
+//
+// Composition per the agents/README.md contract:
+//   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
+//   2. {{TOOL:key}} is replaced with the harness column of token-map.json.
+//   3. {{PATH:arg}} with a named key resolves through token-map.json's paths
+//      table; anything else is a relative path and stays verbatim.
+// Substitution order is SECTION → TOOL → PATH (matches extensions/agent-modes).
+// Missing sections, unknown tool keys, or schema-invalid frontmatter are hard
+// errors: a committed generated file must never ship a literal token or a
+// silently dropped section.
+//
+// Options (the pi installer passes `dropNullTools`, `pluginRoot` and
+// `resolveRelativePaths`; the copilot generator and claude installer use the strict defaults):
+//   dropNullTools          replace null-mapped tool tokens with an empty string and
+//                          warn instead of throwing (pi's prose rule per the
+//                          token-map contract)
+//   pluginRoot             override the plugin_root used for resolved paths
+//                          (installers compute it from the actual install layout)
+//   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
+//                          instead of staying verbatim (install time; the build
+//                          scripts leave them bare for Copilot CLI resolution)
+//   warn                   callback for drop/omit warnings (default: no-op; the
+//                          pi installer collects them into its result)
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Token substitution ──────────────────────────────────────────────────────
+
+const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
+const PATH_RE = /\{\{PATH:([^}]+)\}\}/g;
+
+function noop() {}
+
+/**
+ * Substitute {{TOOL:...}} and {{PATH:...}} tokens in arbitrary content (agent
+ * bodies, skill files) against one harness column of token-map.json.
+ *
+ * - TOOL: unknown key → throw (the map must stay complete); null mapping → drop
+ *   with a warning when `dropNullTools`, otherwise throw.
+ * - PATH: named key → resolve through the paths table (plugin_root overridable);
+ *   non-keyed → join(pluginRoot, arg) when `resolveRelativePaths`, else verbatim.
+ * - SECTION tokens are *not* handled here — the agent composer resolves them from
+ *   the harness's section files before calling this.
+ *
+ * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
+ * @returns {string}
+ */
+export function substituteTokens(content, harness, tokenMap, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop, context = "" } = options;
+  const ctx = context ? `${context}: ` : "";
+
+  // 2. {{TOOL:key}} → token-map.json tools.<key>.<harness>
+  content = content.replace(TOOL_RE, (_token, key) => {
+    const entry = tokenMap.tools[key];
+    if (!entry) throw new Error(`${ctx}unknown tool token {{TOOL:${key}}} — extend token-map.json`);
+    const mapped = entry[harness];
+    if (mapped == null) {
+      if (dropNullTools) {
+        warn(`tool token {{TOOL:${key}}} has no ${harness} mapping — dropped`);
+        return "";
+      }
+      throw new Error(`${ctx}tool token {{TOOL:${key}}} has no ${harness} mapping (null) — drop the token in agent.md first`);
+    }
+    return mapped;
+  });
+
+  // 3. {{PATH:arg}} → named keys via token-map.json paths; relative paths verbatim
+  //    (or resolved against pluginRoot when the installer option is set)
+  content = content.replace(PATH_RE, (_token, arg) =>
+    resolvePath(arg, harness, tokenMap, { pluginRoot, resolveRelativePaths }),
+  );
+
+  return content;
+}
+
+/**
+ * Compose the harness-specific agent content from a composable agent directory.
+ *
+ * @param {string} root    Package root (contains agents/ and token-map.json)
+ * @param {string} name    Agent directory name (e.g. "ralph", "plan")
+ * @param {string} harness Harness id: "copilot" | "claude" | "pi"
+ * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
+ */
+export function composeAgent(root, name, harness, options = {}) {
+  const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
+  const agentDir = join(root, "agents", name);
+  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = loadTokenMap(root);
+
+  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
+  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+    const sectionPath = join(agentDir, harness, `${section}.md`);
+    if (!existsSync(sectionPath)) {
+      throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
+    }
+    return readFileSync(sectionPath, "utf-8").trim();
+  });
+
+  // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
+  body = substituteTokens(body, harness, tokenMap, {
+    dropNullTools,
+    pluginRoot,
+    resolveRelativePaths,
+    warn,
+    context: `agent "${name}"`,
+  });
+
+  return { ...frontmatter, body: body.trim() };
+}
+
+// ─── Frontmatter ─────────────────────────────────────────────────────────────
+
+const REQUIRED_FIELDS = ["name", "description", "tools"];
+const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
+
+/** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
+function parseFrontmatter(path, name, harness) {
+  const raw = readFileSync(path, "utf-8");
+  let fm;
+  try {
+    fm = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`agent "${name}": invalid JSON in ${path}: ${err.message}`);
+  }
+  if (typeof fm !== "object" || fm === null) {
+    throw new Error(`agent "${name}": ${path} must be a JSON object`);
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in fm)) throw new Error(`agent "${name}": ${path} missing required field "${field}" (harness ${harness})`);
+  }
+  if (typeof fm.name !== "string" || fm.name.trim() === "") throw new Error(`agent "${name}": ${path} name must be a non-empty string`);
+  if (typeof fm.description !== "string" || fm.description.trim() === "") throw new Error(`agent "${name}": ${path} description must be a non-empty string`);
+  if (!Array.isArray(fm.tools) || fm.tools.length === 0 || !fm.tools.every((t) => typeof t === "string")) {
+    throw new Error(`agent "${name}": ${path} tools must be a non-empty array of strings`);
+  }
+  for (const key of Object.keys(fm)) {
+    if (![...REQUIRED_FIELDS, ...KNOWN_OPTIONAL_FIELDS].includes(key)) {
+      throw new Error(`agent "${name}": ${path} unknown field "${key}" — strict schema per agents/README.md`);
+    }
+  }
+  return {
+    name: fm.name,
+    description: fm.description,
+    tools: fm.tools,
+    ...(typeof fm.model === "string" ? { model: fm.model } : {}),
+    ...(typeof fm.argumentHint === "string" ? { argumentHint: fm.argumentHint } : {}),
+  };
+}
+
+// ─── Path resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a {{PATH:...}} argument for a harness's generated output.
+ * Named keys resolve through token-map.json's paths table (recursively for
+ * {base, relative} specs); non-keyed args are relative paths, kept verbatim —
+ * the installer beads own precise runtime path resolution (see token-map.README.md).
+ * With the installer options (`pluginRoot`, `resolveRelativePaths`) the
+ * plugin_root base and bare relative paths resolve against the actual install
+ * layout instead.
+ */
+function resolvePath(arg, harness, tokenMap, opts = {}) {
+  const entry = tokenMap.paths?.[arg];
+  if (!entry) {
+    if (opts.resolveRelativePaths && opts.pluginRoot) return join(opts.pluginRoot, arg);
+    return arg;
+  }
+
+  const spec = entry[harness];
+  if (typeof spec === "string") {
+    if (arg === "plugin_root" && opts.pluginRoot) return opts.pluginRoot;
+    return spec;
+  }
+  if (spec && typeof spec === "object" && typeof spec.base === "string" && typeof spec.relative === "string") {
+    return join(resolvePath(spec.base, harness, tokenMap, opts), spec.relative);
+  }
+  throw new Error(`unresolvable {{PATH:${arg}}} for harness "${harness}" — extend token-map.json`);
+}
+
+/**
+ * Translate a frontmatter tool list into one harness's tool names.
+ *
+ * Canonical keys resolve through token-map.json's tools table; a null mapping
+ * means the harness has no equivalent and the entry is omitted (the contract's
+ * tool-list rule); a name that is not a canonical key passes through untouched
+ * (it may be a native tool, e.g. pi's fetch_content). Mirrors the runtime
+ * translation in extensions/agent-modes/discover.ts.
+ *
+ * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
+ * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
+ * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {object} options  { warn }
+ * @returns {string[]}
+ */
+export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}) {
+  const out = [];
+  for (const tool of tools) {
+    const mapping = tokenMap.tools[tool];
+    if (mapping === undefined) {
+      out.push(tool);
+      continue;
+    }
+    const mapped = mapping[harness];
+    if (mapped == null) {
+      warn(`tool "${tool}" has no ${harness} mapping — omitted from the tool list`);
+      continue;
+    }
+    out.push(mapped);
+  }
+  return out;
+}
+
+// ─── Token map ───────────────────────────────────────────────────────────────
+
+/** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
+export function loadTokenMap(root) {
+  const path = join(root, "token-map.json");
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    throw new Error(`missing ${path} — the composer requires token-map.json`);
+  }
+  const parsed = JSON.parse(raw);
+  if (!parsed.tools || !parsed.paths) {
+    throw new Error(`${path}: expected "tools" and "paths" tables`);
+  }
+  return parsed;
+}

package/skills/engineering/design-an-interface/SKILL.md

@@ -23,7 +23,7 @@ Ask: "What does this module need to do? Who will use it?"
 
 ### 2. Generate Designs (Parallel Sub-Agents)
 
-Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+Spawn 3+ sub-agents simultaneously using {{TOOL:task}}. Each must produce a **radically different** approach.
 
 ```
 Prompt template for each sub-agent:

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -13,7 +13,7 @@ A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a sma
 
 ### 1. Explore the codebase
 
-Explore the codebase using your available tools (bash, rg, view, glob, find). Navigate organically and note where you experience friction:
+Explore the codebase using your available tools ({{TOOL:bash}}, {{TOOL:rg}}, {{TOOL:view}}, {{TOOL:glob}}). Navigate organically and note where you experience friction:
 
 - Where does understanding one concept require bouncing between many small files?
 - Where are modules so shallow that the interface is nearly as complex as the implementation?

package/skills/workflow/ralph/REFERENCE.md

@@ -10,7 +10,7 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
 2. **Read its `stage:*` label** from `bd show <id>`.
 3. **Load the universal stage runner prompt** from `skills/workflow/run-pipeline-stage/prompts/stage-runner.md`.
 4. **Read the parent task context**: follow the `parent-child` dependency to the parent task bead, run `bd show <parent-id>` to get the full task description.
-5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to `task`.
+5. **Ensure branch + worktree exist for this parent task** (see _Feature branches and worktrees_ below), then note the worktree path — you'll pass it as `cwd` to {{TOOL:task}}.
 6. **Fill in the prompt** — replace placeholders with:
    - Stage from bead label (`stage:<stage>`) for `<stage>`
    - `bd prime` output (held in memory from initialization)
@@ -18,7 +18,7 @@ Detailed procedures for the fleet orchestration workflow. See [SKILL.md](./SKILL
    - For `fix` stage: `FILES_CHANGED` from the preceding stage's report (the required changes come from the fix bead's own description — read via `bd show <fix-id>`)
    - For `verify`, `review`, `document` stages: `SUMMARY` and `FILES_CHANGED` from the preceding stage's report
    - Bead ID and log file path (`.agent-cortex/ralph/ralph-<bead-id>.log`)
-7. **Call the `task` tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
+7. **Call the {{TOOL:task}} tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
 8. **Map** the agent ID to the bead ID in memory for lookup on completion.
 
 ---

package/skills/workflow/ralph/SKILL.md

@@ -35,7 +35,7 @@ Run once at startup:
    - **Task or other type without an `implementation-type:*` label**: unexpected here — classification is a planning-stage concern already applied by `create-task`. Do not invoke `classify-bead`; treat as needs-refinement and note for the shutdown summary.
    - **Task labelled `implementation-type:hitl`**: skip — record the bead ID for the **Pending Human Action** summary at shutdown.
 7. For each ready chore bead (up to 5), **dispatch** it (see _Dispatching a chore bead_ in REFERENCE.md). Chores for a parent bead must run from that parent's worktree.
-8. **If** any chore beads were dispatched in step 7, start the **poll timer**: run `sleep 120` as a background bash process and hold its shellId in memory. **Otherwise**, if HITL gate beads are pending (check `bd list -l lifecycle:feature-pr -l implementation-type:hitl` and `bd list -l awaiting-epic-pr-merge`), proceed to **HITL Pause** (see REFERENCE.md) immediately.
+8. **If** any chore beads were dispatched in step 7, start the **poll timer** (Copilot only): run `sleep 120` as a background bash process and hold its shellId in memory. PI has no timer — keep a `wait_for_agents` call outstanding over every in-flight agent ID instead (see the Event Loop note). **Otherwise**, if HITL gate beads are pending (check `bd list -l lifecycle:feature-pr -l implementation-type:hitl` and `bd list -l awaiting-epic-pr-merge`), proceed to **HITL Pause** (see REFERENCE.md) immediately.
 9. Regenerate `.agent-cortex/ralph/progress.md`:
    ```bash
    # workspace must be the absolute path you cd'd into — never . or $(pwd)
@@ -47,7 +47,7 @@ Run once at startup:
 
 ## Event Loop
 
-After initialization, wait for background agents or the poll timer to complete. On each completion notification:
+After initialization, wait for background agents or the poll timer to complete. Completion detection is harness-specific: the `sleep 120` poll timer described below is the **Copilot** mechanism. **PI** replaces it with the blocking `wait_for_agents` tool — it returns as soon as any in-flight agent finishes, so each return plays the role of a poll-timer tick with its completed-agent result attached; there is no timer to start or kill on PI. On each completion notification:
 
 ### Poll timer completed
 
@@ -59,7 +59,7 @@ After initialization, wait for background agents or the poll timer to complete.
 ### Background agent completed
 
 1. **Poll that bead's log** to flush any final lines.
-2. **Read** the completed agent's full output with `read_agent`.
+2. **Read** the completed agent's full output with {{TOOL:read_agent}} (on PI the completed result arrives in the `wait_for_agents` response; read_agent remains a fallback for a specific result).
 3. **Identify the bead**: parse the `---REPORT---` block for `BEAD_ID` and `STAGE_COMPLETED`.
 4. **Close** the chore bead: `bd close <bead-id>`.
 5. **Handle stage outcome**:
@@ -90,10 +90,10 @@ After initialization, wait for background agents or the poll timer to complete.
 - **Always** run in **foreground** (interactive) mode. If you find yourself executing as a background task, immediately surface a warning to the user and ask them to re-run you in foreground mode.
 - **Never** write, edit, or create source code or documentation yourself.
 - **Never** edit bead task files directly — only use `bd` commands.
-- **ALWAYS call the `task` tool to spawn subagents** — never use bash, never run stages inline, never use any other tool. This is your only spawning mechanism.
+- **ALWAYS call the {{TOOL:task}} tool to spawn subagents** — never use {{TOOL:bash}}, never run stages inline, never use any other tool. This is your only spawning mechanism.
 - **Always** derive orchestration state from beads — do not maintain a separate state file.
-- **Always** include the full `bd prime` output verbatim in every `task` tool prompt.
-- **Always** keep the poll timer running — restart it immediately after it fires — **unless** the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending), in which case proceed to **HITL Pause** (see REFERENCE.md) and stop instead.
+- **Always** include the full `bd prime` output verbatim in every {{TOOL:task}} tool prompt.
+- **Always** keep the poll timer running (Copilot) — restart it immediately after it fires — **unless** the HITL pause condition is met (no chores in-flight, no `stage:*` chores ready, HITL gate beads pending), in which case proceed to **HITL Pause** (see REFERENCE.md) and stop instead. On PI there is no timer to keep alive — always keep one `wait_for_agents` call outstanding while agents are in-flight.
 - **Never** post empty poll updates to chat — only surface new log content.
 - **Max 5** tasks in-flight at once.
 - **Max fix rounds** per task as defined by `maxFixRounds` in `skills/planning/create-task/pipeline.json`.

package/skills/workflow/run-pipeline-stage/scripts/generate-progress.ts

@@ -50,8 +50,10 @@ const STATUS_CHAR_MAP: Record<string, BeadStatus> = {
 export function parseListLine(
   line: string,
 ): { id: string; status: BeadStatus; title: string } | null {
-  // Format: {STATUS_CHAR} {ID} ● P{N} {TITLE}
-  const match = line.trim().match(/^([○◐●✓❄])\s+(\S+)\s+●\s+P\d+\s+(.+)$/);
+  // Formats accepted:
+  //   {STATUS_CHAR} {ID} P{N} {TITLE}        — current bd list output
+  //   {STATUS_CHAR} {ID} ● P{N} {TITLE}      — older bd (● before P{N} is optional)
+  const match = line.trim().match(/^([○◐●✓❄])\s+(\S+)\s+(?:●\s+)?P\d+\s+(.+)$/);
   if (!match) return null;
   const [, statusChar, id, title] = match;
   const status = STATUS_CHAR_MAP[statusChar];

package/skills/workflow/using-agent-skills/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: using-agent-skills
+description: Routes incoming work to the right skill and enforces core agent behaviors. Use when starting a session, deciding which skill applies, or when you need to check "which skill should I use?".
+---
+
+# Using Agent Skills
+
+## When to use
+
+- Starting a new session and need to orient on available workflows.
+- A task arrives and you need to decide which skill applies.
+- The user asks "which skill should I use for this?"
+- You want to verify that core operating behaviors are being followed.
+
+## Workflow
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what to build yet? ──────→ grill-me
+    ├── Have a rough idea? ─────────────────→ record-idea
+    ├── New feature / PRD needed? ──────────→ write-a-prd
+    ├── PRD approved, need tasks? ──────────→ prd-to-tasks
+    ├── Need a single task tracked? ────────→ create-task
+    ├── Need to plan a feature end-to-end? ─→ plan
+    ├── Running beads / task execution? ────→ ralph
+    │   └── Single stage? ─────────────────→ run-pipeline-stage
+    ├── Implementing code? ────────────────→ tdd
+    │   ├── Designing an interface? ───────→ design-an-interface
+    │   └── Need style conventions? ───────→ style-code
+    ├── Reviewing code? ───────────────────→ style-code
+    │   ├── Security concerns? ────────────→ review-security
+    │   └── Reviewing tests? ──────────────→ style-tests
+    ├── Writing tests? ────────────────────→ style-tests
+    ├── Writing docs? ─────────────────────→ style-documentation
+    ├── Writing external comms? ───────────→ style-comms
+    ├── Stress-testing a plan? ────────────→ grill-with-docs
+    ├── Planning a refactor? ──────────────→ request-refactor-plan
+    ├── Evaluating architecture? ──────────→ technical-direction
+    ├── Finding refactor opportunities? ───→ improve-codebase-architecture
+    ├── Need task tracking? ───────────────→ bd-tool
+    ├── Need human review / HITL? ─────────→ hitl-collab
+    ├── Need a handoff doc? ───────────────→ handoff
+    ├── Writing a ticket for Jira? ────────→ write-a-ticket
+    ├── Creating a new skill? ─────────────→ write-a-skill
+    ├── Refactoring a skill? ──────────────→ refactor-skill
+    ├── Updating agent docs? ──────────────→ maintain-agent-docs
+    └── Setting up beads in a new project? → init-beads
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions. Don't silently fill in ambiguous requirements — surface uncertainty early, it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications: **STOP**. Name the specific confusion, present the tradeoff or ask the clarifying question, and wait for resolution before continuing.
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems, point out the issue directly, explain the concrete downside, propose an alternative, and accept the human's decision if they override with full information.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Before finishing any implementation, ask: Can this be done in fewer lines? Are these abstractions earning their complexity? Prefer the boring, obvious solution.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch. Do not clean up orthogonal code, refactor adjacent systems, or add features not in the spec. Surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence: passing tests, build output, or runtime data.
+
+### 7. Flag Persistent Failures
+
+When a tool or command fails repeatedly, stop and flag it to the user for investigation. Don't paper over failures with workarounds — workarounds waste tokens and hide real problems. Describe what failed, how many times, and any obvious patterns. Let the user decide whether to investigate in a dedicated session. Inefficiencies and failures should be squashed, not hidden.
+
+### 8. Stay On Target
+
+Stick to the task at hand. If you discover work that's outside the current scope — a tangential bug, an adjacent improvement, a missing doc — flag it to the user but don't pursue it. If the side quest blocks or slows your progress, stop and report it. Otherwise, note it and get back on track. Scope creep mid-task burns tokens and dilutes focus.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+1. `grill-me` → Extract what the user actually wants
+2. `record-idea` → Refine vague ideas
+3. `write-a-prd` → Define what we're building
+4. `prd-to-tasks` → Break into verifiable chunks
+5. `plan` → Orchestrate the full flow end-to-end
+6. `ralph` → Execute all pending beads
+7. `tdd` → Prove each slice works
+8. `style-code` → Review before merge
+9. `review-security` → Check for secrets
+10. `git-workflow` → Clean commit history
+
+Not every task needs every skill. A bug fix might only need: `tdd` → `style-code` → `review-security`.
+
+## Red Flags
+
+- Starting work without checking which skill applies.
+- Skipping verification because "it looks right."
+- Making wrong assumptions without stating them.
+- Overcomplicating code when a simple solution exists.
+- Modifying code orthogonal to the task scope.
+- Going on side-quests instead of staying on target.
+- Going on side-quests instead of staying on target.
+- Going on side-quests instead of staying on target.
+
+## Verification checklist
+
+- [ ] Correct skill identified before starting work.
+- [ ] Core operating behaviors followed throughout.
+- [ ] Verification completed with evidence (tests, build, runtime).
+- [ ] Scope limited to the task at hand.