@jaybeeuu/agent-cortex 2.5.1 → 2.7.0

package/docs/skills/skill-anatomy.md

@@ -0,0 +1,212 @@
+# Skill Anatomy
+
+This document is the **canonical skill anatomy** for `agent-cortex` skills.
+Use it as the source of truth for `SKILL.md` structure, language, and review quality gates.
+
+## Front-matter spec
+
+Required fields:
+- `name`: kebab-case skill identifier.
+- `description`: max 1024 characters.
+
+Frontmatter is machine-validated: `pnpm lint` runs `check:skills`, which fails on a
+frontmatter block that would make pi silently drop the skill.
+
+Optional fields:
+- `argument-hint`: input prompt shown to users at invocation.
+- `disable-model-invocation`: hides the skill from automatic model routing; explicit
+  `/skill-name` invocation still works. Set it when the danger is a fuzzy description
+  match, e.g. a skill whose steps are destructive. Preserved and honoured by pi and
+  Claude Code. See `docs/research/disable-model-invocation.md`.
+
+## Description format rules
+
+- Target ≤200 characters even though max is 1024.
+- Write in third-person declarative voice.
+- Sentence 1: what the skill does.
+- Sentence 2: starts with `Use when ...`.
+- Include 2-4 natural user trigger phrases (quoted) such as "diagnose this" or "something is broken".
+- Prefer user vocabulary over internal jargon.
+
+## Voice and tone rules
+
+- Write the body in imperative second-person: "Run X", "Check Y", "Report Z".
+- Use positive framing; reserve "do not" only for hard safety/correctness boundaries.
+- Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
+- Avoid ALL-CAPS emphasis.
+
+## Tool references
+
+Reference agent tools by token, never by a hardcoded harness-specific name such as `bash`,
+`task`, or `read_agent`. A tool token is the tool's canonical authoring name prefixed with
+`TOOL:` and wrapped in doubled curly braces — two `{` before it and two `}` after it. The
+wrapper is literal syntax: installers match it and substitute the per-harness name from
+`token-map.json` at install time. Add any new tool to the map's `tools` section in the same
+change; unknown tokens are hard errors. See `token-map.README.md` for the full authoring rules.
+
+## Required sections
+
+Every skill must include:
+1. `## When to use`
+2. `## Workflow` (numbered steps)
+3. `## Verification checklist` (`- [ ]` items)
+
+## Optional sections
+
+For each optional section, define **what it is**, include an **example snippet**, and state **when to include** and **when to omit**.
+
+| Section | What it is | Example snippet | When to include | When to omit |
+|---|---|---|---|---|
+| `When NOT to use` | Explicit out-of-scope invocation boundaries | `- When NOT to use: single-line typo fixes with no process risk.` | Skills with similar neighbors where invocation precision matters | Truly unique one-purpose utility skills |
+| `Red Flags` | Detectable anti-patterns the agent should self-correct during execution | `- Red flag: skipping boundary validation to save time.` | Discipline-enforcement skills (security, TDD, review) | Simple utility wrappers |
+| `Common Rationalizations` | Excuses models use to skip process with rebuttals | `| "This is small" | Small changes still need invariants checked. |` | Process-critical skills where shortcut pressure is common | Mechanical one-step skills |
+| `Philosophy / rationale` | Why the method exists and what trade-offs it protects | `- We front-load validation because downstream rollback cost is higher.` | Opinionated skills expected to handle novel variants | Purely mechanical instructions |
+| `Phase-gate checklists` | Mid-workflow gates that must pass before proceeding | `- [ ] Phase 1 complete: baseline tests captured.` | Multi-phase workflows (3+ distinct phases) | Linear single-phase tasks |
+| `See Also` | Explicit handoff to another skill for a real sub-task: a relative link to its `SKILL.md` plus the reason to load it | `- [review-security](../../review/review-security/SKILL.md) — run before committing.` | Another skill owns a sub-domain better than restating it | Self-contained skills |
+| `Examples` | Full worked sample of expected outcome/output | `- Input: ... Output: ...` | Any non-trivial output contract | Trivially self-evident skills |
+| `Workflow diagrams` | Inline ASCII diagram showing step flow and decision points | Fenced block of `[Box]`, `|`, `-`, `>`, `v` arrows, e.g. `[Start] --> [Validate] --> [Run]` | Multi-step or branching workflows where a glanceable flow improves comprehension | Simple linear workflows already clear from numbered steps |
+
+`## See Also` entries are one-line handoffs: a relative link to the related skill's `SKILL.md`, an
+em-dash, and the reason a reader of this skill would load that one. A bare skill name leaves the
+reader guessing whether the link matters; the reason is what turns a link list into routing.
+
+Write the path against the authored tree (`../../<group>/<skill>/SKILL.md` from a skill directory).
+The Claude Code installer flattens skills and rewrites these targets at copy time, so a hand-written
+link that resolves here resolves in both install layouts. List only genuine handoffs — inline calls
+inside `## Workflow` already cover skills used as a step, and `using-agent-skills` already maps the
+whole corpus, so a duplicate entry adds noise.
+
+## Workflow diagram style guide
+
+When a skill includes a workflow diagram, follow these rules so it renders
+reliably in any CLI:
+
+- **ASCII only** — never Mermaid, images, or unicode box-drawing characters.
+  Keep to `|`, `-`, `>`, `+`, and `v`.
+- **Fenced block** — wrap the diagram in a fenced code block so monospace is
+  preserved.
+- **At most 80 characters per line** — narrow enough for terminal-width readers.
+- **Short box labels** — imperative verbs or nouns (e.g. `[Validate scope]`),
+  never full sentences.
+- **Read left-to-right, top-down** — prefer one branch level over dense joins.
+- **Mirror the numbered workflow** — the diagram is a glanceable summary of the
+  `## Workflow` steps, never a source of truth that contradicts them.
+
+## Section ordering
+
+### When to use
+
+State concrete invocation triggers using natural language phrases users actually type.
+
+### When NOT to use
+
+Place this section immediately after `When to use` whenever present.
+
+### Workflow
+
+Provide ordered, deterministic steps with observable outcomes.
+
+### Verification checklist
+
+Provide completion gates that are testable and stage-scoped.
+
+## File layout and progressive disclosure
+
+- Target ~150 lines for `SKILL.md`.
+- Split long docs into purpose-named support files:
+  - `EXAMPLES.md` for worked examples.
+  - `FORMAT.md` for schemas/templates.
+  - `REFERENCE.md` for rare edge cases.
+- Use slash-command references when another skill should be invoked.
+
+## Acceptance criteria checklist
+
+A skill passes anatomy review when:
+- [ ] Front matter uses required fields and valid description format.
+- [ ] Tool references use doubled-brace `TOOL:` tokens, not hardcoded tool names.
+- [ ] Required sections exist and follow canonical ordering.
+- [ ] Optional sections (if present) include what/when/example guidance.
+- [ ] `See Also` entries link the target `SKILL.md` relatively and state why to load it.
+- [ ] Workflow diagrams (if present) are ASCII-only and follow the workflow diagram style guide.
+- [ ] Verification checklist contains concrete, machine-checkable items.
+- [ ] Supporting docs are split by purpose when `SKILL.md` would exceed ~150 lines.
+
+## Annotated template
+
+```md
+---
+name: skill-name
+description: This skill performs a specific capability. Use when a user asks for a matching workflow such as "triage this", "investigate this", or "prepare a handoff".
+argument-hint: Optional prompt shown to users when extra input is needed.
+disable-model-invocation: false
+---
+
+# Skill Name
+
+## When to use
+
+- Trigger phrases users actually say, e.g. "triage this failure".
+- Include 2-4 concrete patterns.
+
+## When NOT to use
+
+- Out-of-scope cases that should route elsewhere.
+
+## Workflow
+
+1. Gather required context and validate scope boundaries.
+2. Reject early with the reason when validation fails; otherwise continue.
+3. Execute deterministic steps in order, recording key decisions.
+4. Produce the required output artifact or terminal response.
+
+Workflow at a glance (include only when the flow branches):
+
+              [Trigger]
+                  |
+                  v
+          [Gather context]
+                  |
+                  v
+          [Validate scope] --(invalid)--> [Reject early]
+                  |
+              (valid)
+                  v
+      [Run deterministic steps]
+                  |
+                  v
+      [Produce output artifact]
+
+## Red Flags
+
+- Red flag: skipping validation of unknown external input.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "This is too small for process" | Process protects against regressions regardless of size. |
+
+## Philosophy / rationale
+
+- We optimize for explicit boundaries because they reduce rework and improve reliability.
+
+## Phase-gate checklist
+
+- [ ] Phase 1 complete and baseline checks captured.
+- [ ] Phase 2 complete and contract validation passed.
+
+## See Also
+
+- [review-security](../../review/review-security/SKILL.md) — run before committing any externally exposed change.
+
+## Examples
+
+Input: "Investigate this flaky suite"
+Output: concise root-cause summary, failing tests list, and next action.
+
+## Verification checklist
+
+- [ ] Output matches requested format.
+- [ ] Required tests/lints were run and results recorded.
+- [ ] No unrelated files were changed.
+```

package/lib/cli.mjs

@@ -4,8 +4,13 @@ import { basename } from "node:path";
  * Result of parsing the CLI argv. Every branch returns `command`; the rest are
  * populated only for the commands that accept them.
  * @typedef {object} ParsedArgs
- * @property {"help" | "version" | "install" | "migrate" | "unknown"} command
+ * @property {"help" | "version" | "install" | "update" | "migrate" | "unknown"} command
+ * @property {boolean} [report] `version` subcommand: report installed harnesses too
+ * @property {boolean} [json] `version --json`: print the report as JSON
  * @property {string | null} [harness]
+ * @property {string[]} [harnesses] `update`: the harnesses named on the command line
+ * @property {boolean} [all] `update -a, --all`: every harness that is not at the CLI version
+ * @property {boolean} [force] `update -f, --force`: re-run every installer regardless of version
  * @property {string} [name]
  * @property {string} [optionError]
  * @property {boolean} [dryRun]
@@ -69,6 +74,20 @@ export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
 
   const [command, ...rest] = argv;
 
+  if (command === "version") {
+    // The `version` subcommand reports the installed harness versions; the
+    // `--version` flag above stays a bare CLI version for scripts.
+    let json = false;
+    for (const arg of rest) {
+      if (arg === "--json") {
+        json = true;
+        continue;
+      }
+      return { command: "version", report: true, optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
+    }
+    return json ? { command: "version", report: true, json } : { command: "version", report: true };
+  }
+
   if (command === "install") {
     let harness = null;
     let i = 0;
@@ -109,6 +128,35 @@ export function parseArgs(argv, programName = DEFAULT_PROGRAM_NAME) {
     return { command: "install", harness, ...options };
   }
 
+  if (command === "update") {
+    // `update <harness>...` refreshes exactly those harnesses; `-a` refreshes
+    // every harness that is not at the CLI version and `-f` forces a re-run.
+    // `-f` alone has no meaning, so it is rejected rather than ignored.
+    /** @type {string[]} */
+    const harnesses = [];
+    let all = false;
+    let force = false;
+    for (const arg of rest) {
+      if (arg === "--help" || arg === "-h") return { command: "help" };
+      if (arg === "-a" || arg === "--all") {
+        all = true;
+        continue;
+      }
+      if (arg === "-f" || arg === "--force") {
+        force = true;
+        continue;
+      }
+      if (arg.startsWith("-")) {
+        return { command: "update", optionError: `Unknown option "${arg}". Run "${programName} --help" for usage.` };
+      }
+      harnesses.push(arg);
+    }
+    if (force && !all) {
+      return { command: "update", optionError: `"--force" requires "--all". Run "${programName} --help" for usage.` };
+    }
+    return { command: "update", harnesses, all, force };
+  }
+
   if (command === "migrate") {
     // Dry run is the default, so `--apply` is the only state-changing flag;
     // `--dry-run` stays accepted for scripts that pass it explicitly. `--dir`
@@ -223,6 +271,20 @@ Commands:
                                               cannot register the staged package
                                               (missing from PATH); default warns and
                                               prints the manual commands
+  update [<harness>...] Refresh installed harnesses by re-running their
+                      installers. With no argument the command lists every
+                      harness with its installed version and the CLI version,
+                      then asks which to refresh (a non-interactive shell
+                      prints the same table and the flags below, then exits
+                      non-zero without blocking).
+                      Options:
+                        <harness>...    Refresh exactly these harnesses, no prompt
+                        -a, --all       Refresh every harness that is not at the
+                                        CLI version (not installed, stale, or
+                                        ahead); ignored when harnesses are named
+                        -f, --force     With --all: re-run every installer even
+                                        when the version already matches
+                        --help, -h      Show this help text
   migrate             Migrate the current beads workspace to the latest
                       agent-cortex migration version, applying versioned steps
                       in order (repo-agnostic — works in any beads workspace)
@@ -231,6 +293,13 @@ Commands:
                         --apply         Apply every pending step, verifying each
                         --dir <path>    Read idea files from <path> instead of
                                         docs/ideas (step v2's source)
+  version             Print the running CLI version, then one line per installed
+                      harness: its name, the version its installer recorded, and
+                      a marker comparing the two — current, stale, ahead (the
+                      installed copy is newer), or unknown (no readable
+                      fingerprint). Read-only: no install, no network, no writes.
+                      Options:
+                        --json          Print the same data as JSON records
   --help, -h          Show this help text
   --version, -V       Print the package version`;
 }

package/lib/harness-update.mjs

@@ -0,0 +1,254 @@
+// The selection and reporting half of `ctx update`: which harnesses a refresh
+// covers, how the table and the report read, and the interactive prompt.
+//
+// Delegation is not here. The caller injects `refresh(harness)`, which the CLI
+// wires to the harness installers — so update-vs-install stays the installer's
+// decision and this module never writes an artifact itself.
+
+import { homedir } from "node:os";
+import { collectHarnessStatus } from "./harness-versions.mjs";
+
+/** @typedef {import("./harness-versions.mjs").HarnessStatus} HarnessStatus */
+
+const NOT_INSTALLED = "not installed";
+const UNKNOWN = "unknown";
+
+/**
+ * One refreshed harness in the update report.
+ * @typedef {object} UpdateEntry
+ * @property {string} harness
+ * @property {string} previous The version before the refresh, or "not installed"
+ * @property {string} next The version the installer recorded afterwards
+ * @property {string[]} artifacts What the installer wrote
+ */
+
+/**
+ * The harnesses an update covers, and the ones it leaves alone.
+ * @typedef {object} UpdatePlan
+ * @property {HarnessStatus[]} targets
+ * @property {HarnessStatus[]} skipped
+ * @property {string[]} unknown Names that are not supported harnesses
+ */
+
+/**
+ * Decide which harnesses an update refreshes. An explicit name is always a
+ * target (the user asked for that installer to re-run); `--all` targets every
+ * harness that is not at the CLI version; `--all --force` targets every harness.
+ * @param {object} options
+ * @param {HarnessStatus[]} options.statuses One entry per supported harness
+ * @param {string[]} [options.harnesses] Names from the command line or the prompt
+ * @param {boolean} [options.all] `ctx update -a`
+ * @param {boolean} [options.force] `ctx update -a -f`
+ * @returns {UpdatePlan}
+ */
+export function selectHarnesses({ statuses, harnesses = [], all = false, force = false }) {
+  /** @type {string[]} */
+  const unknown = [];
+  /** @type {HarnessStatus[]} */
+  let targets;
+  if (harnesses.length > 0) {
+    targets = [];
+    for (const name of harnesses) {
+      const status = statuses.find((entry) => entry.harness === name);
+      if (status === undefined) {
+        if (!unknown.includes(name)) unknown.push(name);
+        continue;
+      }
+      if (!targets.includes(status)) targets.push(status);
+    }
+  } else if (all && force) {
+    targets = [...statuses];
+  } else if (all) {
+    targets = statuses.filter((entry) => entry.staleness !== "current");
+  } else {
+    targets = [];
+  }
+  const skipped = statuses.filter((entry) => !targets.includes(entry));
+  return { targets, skipped, unknown };
+}
+
+/**
+ * Count a noun for the report: `1 file`, `4 files`.
+ * @param {number} amount
+ * @param {string} noun Singular form
+ * @returns {string}
+ */
+function count(amount, noun) {
+  return `${amount} ${noun}${amount === 1 ? "" : "s"}`;
+}
+
+/**
+ * What a pi refresh wrote, for the update report.
+ * @param {import("../bin/installers/pi.mjs").InstallPiResult} result
+ * @returns {string[]}
+ */
+export function describePiArtifacts(result) {
+  return [
+    `agents (${count(result.agents.length, "file")})`,
+    `skills (${count(result.skills.skills, "skill")}, ${count(result.skills.md, "markdown file")})`,
+    `extensions (${count(result.extensions.files, "file")})`,
+    `bundled pi packages (${result.packages.bundled.length > 0 ? result.packages.bundled.join(", ") : "none"})`,
+    `package manifest (version ${result.manifest.manifest.version})`,
+  ];
+}
+
+/**
+ * What a claude refresh wrote, for the update report.
+ * @param {import("../bin/installers/claude.mjs").InstallClaudeResult} result
+ * @returns {string[]}
+ */
+export function describeClaudeArtifacts(result) {
+  return [
+    `agents (${count(result.agents.length, "file")})`,
+    `skills (${count(result.skills.names.length, "skill")}, ${count(result.skills.md, "markdown file")})`,
+    `hooks (${count(result.hookFiles.length, "file")})`,
+    `hand-authored extras (${count(result.handAuthored.length, "file")})`,
+    `plugin manifest (version ${result.pluginVersion})`,
+    `settings (${result.settings?.action ?? "not written"})`,
+    `instructions (${result.instructions?.action ?? "not written"})`,
+  ];
+}
+
+/**
+ * Refresh every target through the injected installer and report the result.
+ * The new version is read back from the fingerprint the installer wrote, never
+ * assumed from the CLI version, so a failed materialisation shows as unknown.
+ * @param {object} options
+ * @param {string} options.cli The running CLI version
+ * @param {string} [options.home] Home directory holding the install roots
+ * @param {HarnessStatus[]} options.targets
+ * @param {(harness: string) => Promise<string[]>} options.refresh Runs one harness installer
+ * @returns {Promise<UpdateEntry[]>}
+ */
+export async function runUpdate({ cli, home = homedir(), targets, refresh }) {
+  /** @type {{ harness: string, previous: string, artifacts: string[] }[]} */
+  const refreshed = [];
+  for (const target of targets) {
+    const artifacts = await refresh(target.harness);
+    refreshed.push({ harness: target.harness, previous: target.installed ?? NOT_INSTALLED, artifacts });
+  }
+  if (refreshed.length === 0) return [];
+  const statuses = await collectHarnessStatus({ cli, home });
+  return refreshed.map((entry) => {
+    const status = statuses.find((candidate) => candidate.harness === entry.harness);
+    return { ...entry, next: status?.installed ?? UNKNOWN };
+  });
+}
+
+/**
+ * Render the harness table: one row per supported harness, so an absent
+ * install is visible instead of silently missing.
+ * @param {HarnessStatus[]} statuses
+ * @returns {string} Text without a trailing newline
+ */
+export function formatHarnessTable(statuses) {
+  /** @type {string[][]} */
+  const rows = [["harness", "installed", "cli", "status"]];
+  for (const status of statuses) {
+    rows.push([status.harness, status.installed ?? NOT_INSTALLED, status.cli, status.staleness]);
+  }
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+  return rows
+    .map((row) => row.map((cell, column) => (column === widths.length - 1 ? cell : cell.padEnd(widths[column]))).join("  "))
+    .join("\n");
+}
+
+/**
+ * The instructions a non-interactive `ctx update` prints instead of prompting.
+ * @param {string} programName The resolved command name
+ * @returns {string} Text without a trailing newline
+ */
+export function formatUpdateFlags(programName) {
+  return [
+    "No harness selected, and this shell is not interactive. Pass a selection:",
+    `  ${programName} update <harness>...   refresh the named harnesses`,
+    `  ${programName} update -a             refresh every harness that is not at the CLI version`,
+    `  ${programName} update -a -f          re-run every harness installer regardless of version`,
+  ].join("\n");
+}
+
+/**
+ * Render the outcome of an update. Only skipped harnesses that are already at
+ * the CLI version are listed; one left alone for another reason (a stale
+ * harness beside an explicit selection) is not "already at" anything.
+ * @param {object} options
+ * @param {string} options.cli The running CLI version
+ * @param {UpdateEntry[]} options.entries
+ * @param {HarnessStatus[]} [options.skipped]
+ * @returns {string} Text without a trailing newline
+ */
+export function formatUpdateReport({ cli, entries, skipped = [] }) {
+  const current = skipped.filter((entry) => entry.staleness === "current");
+  /** @type {string[]} */
+  const lines = [];
+  for (const entry of entries) {
+    lines.push(`${entry.harness} ${entry.previous} → ${entry.next}`);
+    for (const artifact of entry.artifacts) {
+      lines.push(`  ✓ ${artifact}`);
+    }
+  }
+  if (entries.length === 0) {
+    lines.push(`Nothing to update — every harness is at ${cli}.`);
+  } else if (current.length > 0) {
+    lines.push(`Skipped (already at ${cli}): ${current.map((entry) => entry.harness).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Turn a prompt answer into harness names: row numbers, `a` for every row, or
+ * blank for none.
+ * @param {string} answer
+ * @param {HarnessStatus[]} statuses The rows the prompt listed, in order
+ * @returns {string[]}
+ */
+export function parseHarnessSelection(answer, statuses) {
+  const trimmed = answer.trim();
+  if (trimmed === "") return [];
+  if (/^(a|all)$/i.test(trimmed)) return statuses.map((status) => status.harness);
+  /** @type {string[]} */
+  const chosen = [];
+  for (const token of trimmed.split(/[,\s]+/)) {
+    const index = Number(token);
+    const status = Number.isInteger(index) ? statuses[index - 1] : undefined;
+    if (status === undefined) {
+      throw new Error(`Invalid selection "${token}". Enter row numbers 1-${statuses.length}, "a", or blank to cancel.`);
+    }
+    if (!chosen.includes(status.harness)) chosen.push(status.harness);
+  }
+  return chosen;
+}
+
+/**
+ * Ask on an interactive terminal which harnesses to refresh. The table is the
+ * list the user picks from; a closed input stream cancels the selection.
+ * @param {object} options
+ * @param {HarnessStatus[]} options.statuses
+ * @param {NodeJS.ReadableStream} [options.input]
+ * @param {NodeJS.WritableStream} [options.output]
+ * @returns {Promise<string[]>}
+ */
+export async function promptHarnessSelection({ statuses, input = process.stdin, output = process.stdout }) {
+  output.write(`${formatHarnessTable(statuses)}\n\n`);
+  const answer = await readLine(input, output, `Select harnesses (row numbers, "a" for all, blank to cancel): `);
+  return parseHarnessSelection(answer, statuses);
+}
+
+/**
+ * Read one line, prompting on `output` first. A stream that ends without a
+ * newline returns what it carried, so a closed stdin cancels rather than hangs.
+ * @param {NodeJS.ReadableStream} input
+ * @param {NodeJS.WritableStream} output
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+async function readLine(input, output, question) {
+  output.write(question);
+  let buffered = "";
+  for await (const chunk of input) {
+    buffered += String(chunk);
+    const newline = buffered.indexOf("\n");
+    if (newline !== -1) return buffered.slice(0, newline);
+  }
+  return buffered;
+}