@jaybeeuu/agent-cortex 1.43.0 → 2.1.0

package/agents/ralph/agent.md

@@ -42,7 +42,7 @@ Run once at startup:
 5. Create Ralph's workspace directory: `mkdir -p .agent-cortex/ralph`
 6. Create `.agent-cortex/ralph/state.json` with initial content:
    ```json
-   { "timerShellId": null, "inflight": [] }
+   { "inflight": [] }
    ```
    Then generate the progress file:
    ```bash
@@ -59,7 +59,7 @@ Run once at startup:
    b. Claim the parent bead: `bd update <parent-id> --claim`.
    c. Create the first stage chore bead and dispatch it (see _Creating and dispatching a stage chore_ below).
 8. Record each launched agent in `.agent-cortex/ralph/state.json` (see format below).
-9. Hand over to the completion-detection mechanism in the polling section: it starts the Copilot poll loop, blocks with `wait_for_agents` (PI), or waits for event-driven wake-ups (Claude), and proceeds to **HITL Pause** directly when no agent work was dispatched and HITL gate beads are pending.
+9. Hand over to the completion-detection mechanism in the polling section: it blocks with `wait_for_agents` (PI) or waits for event-driven wake-ups (Claude), and proceeds to **HITL Pause** directly when no agent work was dispatched and `skills/workflow/ralph/scripts/pending-gates.mjs` reports a non-empty `pendingHumanAction` — an **unblocked** `lifecycle:feature-pr` gate or an epic tagged `awaiting-epic-pr-merge`. Gates still parked behind their own pipeline do not count (REFERENCE.md, _Gate predicate_).
 
 ---
 
@@ -101,7 +101,6 @@ All orchestration state is derived from beads:
 
 ```json
 {
-  "timerShellId": "shell-abc",
   "inflight": [
     { "choreId": "xyz-456", "parentId": "abc-123", "title": "Add auth", "agentId": "agent-xyz-456", "logLine": 4 },
     { "choreId": "def-789", "parentId": "ghi-101", "title": "Fix cache", "agentId": "agent-def-789", "logLine": 7 }
@@ -109,7 +108,6 @@ All orchestration state is derived from beads:
 }
 ```
 
-- **timerShellId**: the shellId of the active poll-timer bash process used for completion polling (Copilot; stays `null` on PI, which blocks with `wait_for_agents` instead, and on event-driven harnesses such as Claude).
 - **inflight[].choreId**: the chore bead currently being worked by the subagent.
 - **inflight[].parentId**: the parent feature task bead. Log file is `.agent-cortex/ralph/ralph-<parentId>.log`.
 - **inflight[].logLine**: the next line number to read from the parent's log file (1-based; start at 1). Updated after every poll.
@@ -127,12 +125,12 @@ Update `.agent-cortex/ralph/state.json` after **every** agent completion or disp
 
 ## Event loop
 
-After initialization, Ralph waits for background agents to complete. Completion notifications are delivered by the mechanism documented in the polling section — PI blocks with `wait_for_agents` until a worker completes and its result is returned inline; Copilot uses an active poll timer plus log polling; Claude is event-driven (you are re-invoked automatically when a worker completes, with its result delivered inline). On each completion notification:
+After initialization, Ralph waits for background agents to complete. Completion notifications are delivered by the mechanism documented in the polling section — PI blocks with `wait_for_agents` until a worker completes and its result is returned inline; Claude is event-driven (you are re-invoked automatically when a worker completes, with its result delivered inline). On each completion notification:
 
 ### If a background agent completed
 
-1. **Flush** that bead's log using the log-polling procedure in the polling section to pick up any final lines for the chat summary (PI: flush new log lines as part of handling the `wait_for_agents` result; Copilot: flush to detect completion; Claude: nothing to flush — the result is delivered with the wake-up).
-2. **Read** the completed agent's full output (PI: the result arrives in the `wait_for_agents` response, with `read_agent` as a fallback for a specific result; Copilot: `read_agent`; Claude: the result was delivered inline).
+1. **Flush** that bead's log using the log-polling procedure in the polling section to pick up any final lines for the chat summary (PI: flush new log lines as part of handling the `wait_for_agents` result; Claude: nothing to flush — the result is delivered with the wake-up).
+2. **Read** the completed agent's full output (PI: the result arrives in the `wait_for_agents` response, with `read_agent` as a fallback for a specific result; Claude: the result was delivered inline).
 3. **Re-read** `.agent-cortex/ralph/state.json` to identify the chore bead and parent for that agent ID.
 4. **Parse** the agent's `---REPORT---` block (see report format in the `run-pipeline-stage` skill).
 5. **Close** the completed chore bead: `bd close <chore-id>`.
@@ -142,13 +140,13 @@ After initialization, Ralph waits for background agents to complete. Completion
    - **Failure paths** (verify BLOCKED, review CHANGES_REQUESTED): check loop cap (see below), then create a feedback bead per the _Feedback Beads_ section in `run-pipeline-stage`. Do **not** dispatch immediately — the feedback bead appears in `bd ready` and is picked up in step 7. Remove the inflight entry for this chore; the feedback bead will create a new entry when dispatched.
 7. **Check for newly ready beads**: run `bd ready`. For each bead not yet tracked:
    - **Chore bead with `stage:*` label** (a feedback bead): find its parent via `bd show <chore-id>` (follow the `parent-child` dep). Check loop cap (see below). If under cap: dispatch it via _Creating and dispatching a stage chore_. If at cap: block it (`bd update <chore-id> --status blocked --notes "<cap> cap reached"`) and record for shutdown.
-   - **Task bead, AFK, in-flight count < 5, no open feature PR HITL gate**: claim the parent, create its first code chore, dispatch it.
+   - **Task bead, AFK, in-flight count < 5, no pending human action**: claim the parent, create its first code chore, dispatch it. Check `pendingHumanAction` with `node skills/workflow/ralph/scripts/pending-gates.mjs` — an unblocked `lifecycle:feature-pr` gate means a feature is awaiting a human merge, so hold new parent features. Gates still blocked behind their own pipeline are parked and do not count.
    - **Task bead, AFK, in-flight count at 5**: hold in memory as Waiting.
    - **HITL task bead**: note for **Pending Human Action** shutdown summary.
    - **NEEDS-REFINEMENT bead**: note for **Needs Refinement** shutdown summary.
    When a parent is removed from `inflight` (completed or failed), immediately promote the first Waiting AFK parent.
 8. **If no tasks remain in-flight** and `bd ready` returns no chore beads with `stage:*` labels and no AFK task beads:
-   - If HITL gate beads are pending (`bd list -l lifecycle:feature-pr -l implementation-type:hitl` or `bd list -l awaiting-epic-pr-merge` returns results), proceed to **HITL Pause** (see below).
+   - If `pending-gates.mjs` reports a non-empty `pendingHumanAction` (an unblocked `lifecycle:feature-pr` gate, or an epic tagged `awaiting-epic-pr-merge`), proceed to **HITL Pause** (see below).
    - Otherwise, proceed to **Shutdown** (see below).
 
 ### Loop cap check
@@ -167,15 +165,14 @@ Block command: `bd update <parent-id> --status blocked --notes "<cap> cap reache
 
 ## HITL Pause
 
-Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and HITL gate beads are pending (open `lifecycle:feature-pr` beads or epics tagged `awaiting-epic-pr-merge`). Ralph stops rather than burning requests on idle polls.
+Proceed here when no chore beads are in-flight, no `stage:*` chore beads are ready, and `pending-gates.mjs` reports a non-empty `pendingHumanAction` — an **unblocked** `lifecycle:feature-pr` gate (a feature genuinely awaiting human merge) or an epic tagged `awaiting-epic-pr-merge`. Gates still parked behind their own pipeline do not count. Ralph stops rather than burning requests on idle polls.
 
 1. Regenerate `.agent-cortex/ralph/progress.md` one final time — do not delete it.
 2. For each **multi-feature** epic whose feature beads are all closed but not yet tagged `awaiting-epic-pr-merge`, open/update an epic PR to main, then tag the epic `awaiting-epic-pr-merge`. Skip single-feature epics — their feature branch PRs already target `main` directly.
 3. Run `bd dolt push`.
-4. Collect pending HITL gate beads and their PR URLs:
-   - Run `bd list -l lifecycle:feature-pr -l implementation-type:hitl`
-   - Run `bd list -l awaiting-epic-pr-merge`
-   - For each bead, run `bd show <id>` to retrieve the PR URL from bead notes.
+4. Collect the table rows from the script's `pendingHumanAction` list:
+   - Run `node skills/workflow/ralph/scripts/pending-gates.mjs`
+   - For each entry, run `bd show <id>` to retrieve the PR URL from bead notes. `kind: "feature-pr"` rows read "review and merge the feature PR"; `kind: "epic-pr"` rows read "review and merge the epic PR into main".
 5. Output the **Pending Human Action** summary:
    ```
    ⏸️  Ralph is paused — human action required before work can continue.
@@ -188,7 +185,7 @@ Proceed here when no chore beads are in-flight, no `stage:*` chore beads are rea
 
    When you've completed the above actions, prompt me to continue.
    ```
-6. **Stop completely.** Stop the polling mechanism documented in the polling section (Copilot: kill any running timer; PI and Claude: nothing to stop — there is no timer). Do **not** restart or schedule anything. Do **not** start any background processes. Do **not** check bead status again. Do **not** continue the event loop. Output **nothing further** after the summary above. Ralph is now fully idle — it must not act again until the user explicitly re-prompts.
+6. **Stop completely.** Stop the polling mechanism documented in the polling section (PI and Claude: nothing to stop — there is no timer). Do **not** restart or schedule anything. Do **not** start any background processes. Do **not** check bead status again. Do **not** continue the event loop. Output **nothing further** after the summary above. Ralph is now fully idle — it must not act again until the user explicitly re-prompts.
 
 ---
 
@@ -258,5 +255,4 @@ All beads complete.
 - **Never** auto-merge feature or epic PRs — merge decisions are human-controlled.
 - **Never** continue past feature completion until PR `feature/<parent-id> -> epic/<epic-id>` is merged and the child HITL PR gate bead is closed by a human.
 - **Never** continue past epic completion until PR `epic/<epic-id> -> main` is merged.
-- **When a feature hits the HITL PR gate, push and open the PR immediately and report the URL — do not wait for explicit approval to push or create the PR.**
-- **Always** bump the patch version in `plugin.json` as part of any commit that changes agent or skill files.
+- **When a feature hits the HITL PR gate, push and open the PR immediately and report the URL — do not wait for explicit approval to push or create the PR.**

package/agents/ralph/claude/polling.md

@@ -20,7 +20,7 @@ Rules:
 
 Claude Code **re-invokes you automatically when a background worker completes** — the worker's result is delivered to you inline on the wake-up. **Do not poll and do not `sleep`.** React to completions as they arrive.
 
-- There is **no poll timer on Claude**: skip the PI/Copilot timer start and restart steps in initialization, and there is nothing to kill in **HITL Pause** — when you stop, you simply stop. The harness wakes you again when the user re-invokes you.
+- There is **no poll timer anywhere in this pipeline**: nothing in initialization starts one, and there is nothing to kill in **HITL Pause** — when you stop, you simply stop. The harness wakes you again when the user re-invokes you.
 - There is **no log tailing on Claude**: workers' progress lines (`.agent-cortex/ralph/ralph-<parentId>.log`) are written by the workers themselves and surfaced by the harness with the completion — nothing to flush, nothing to poll. Produce the shared chat summaries from the delivered result instead.
 - On each completion, apply the shared handling in the **Event loop** section of agent.md (steps 3–8: correlate the task ID to its bead via `state.json`, parse the REPORT, close the chore, advance the parent, check for newly ready beads, run the shutdown check). `state.json` `logLine` tracking is not used on Claude.
 

package/agents-native/ralph.md

@@ -35,7 +35,8 @@ created, so by the time a bead reaches `bd ready` here it should already carry a
 `classify-bead` from the ralph loop:
 
 - `implementation-type:afk` present → **AFK**. Done.
-- `implementation-type:hitl` present → **HITL**. Skip; record for the pending-action summary.
+- `execution:hitl` (or the legacy `implementation-type:hitl`) present → **HITL**. Skip; record for the
+  pending-action summary.
 - Neither present → treat as **NEEDS-REFINEMENT**: skip; record for the summary. A missing label
   here means the bead skipped planning-stage classification — flag it, don't classify inline.
 
@@ -52,8 +53,8 @@ Run once at startup:
 5. Read `maxFixRounds` from `${CLAUDE_PLUGIN_ROOT}/skills/create-task/pipeline.json` if present;
    otherwise default to **4**.
 6. Dispatch up to 5 AFK features (see below). Then end your turn — you will be woken on the
-   first completion. If there are zero AFK features but HITL/PR gates are pending, go straight
-   to **Idle**.
+   first completion. If there are zero AFK features but an open `lifecycle:feature-pr` gate is
+   pending (see **Idle**), go straight to **Idle**.
 
 ## Dispatching a feature
 
@@ -105,10 +106,19 @@ beads per **Classifying a bead**, and promote AFK features into free slots.
 
 When no workers are running and no AFK features remain:
 
-- **PR gates pending** (open `lifecycle:feature-pr` beads): run `bd dolt push`, then print a
+- **PR gates pending** (open `lifecycle:feature-pr` beads on either HITL axis):
+  `bd list -l lifecycle:feature-pr --label-any execution:hitl,implementation-type:hitl --limit 0`.
+  This harness keys the pause on a gate being **open**, not unblocked, because its gates stay
+  blocked for their whole life: `create-task` blocks each gate behind the feature's `document`
+  chore, which no Claude ralph claims or closes, and the native route in _When a reviewer
+  worker completes_ step 2 deps the gate onto the still-open feature bead. So never assume a gate
+  here is blocked only by its own pipeline, and never treat "no unblocked gate" as "no human
+  action owed" — that clears the loop with PRs unmerged. Run `bd dolt push`, then print a
   **Pending Human Action** table (bead id, title, PR URL, "review & merge, then `bd close <gate>`"),
   and **stop completely** — output nothing further. Do not poll. The user re-invokes you after
-  merging; you will resume from `bd ready`.
+  merging; you will resume from `bd ready`. The pi harness uses the unblocked-gate predicate
+  (`skills/workflow/ralph/scripts/pending-gates.mjs`); F10 (agnt-ctx-s5xd.10) unifies ralph's
+  agent files — reconcile the two predicates there rather than half-migrating this one.
 - **Nothing pending**: run `bd dolt push`, print any recorded HITL / needs-refinement / blocked
   beads as tables, then print **All beads complete.**
 

package/bin/agent-cortex.mjs

@@ -112,22 +112,6 @@ if (parsed.command === "install") {
       process.exit(1);
     }
   }
-
-  // copilot regenerates the flat agents/*.agent.md files the Copilot plugin
-  // loads via plugin.json ("agents": "agents/") — the same code path
-  // `pnpm build:copilot` runs.
-  if (parsed.harness === "copilot") {
-    const { installCopilot } = await import("./installers/copilot.mjs");
-    try {
-      await installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
-      process.exit(0);
-    } catch (err) {
-      process.stderr.write(`Install failed: ${err.message}\n`);
-      process.exit(1);
-    }
-  }
-
-  process.exit(0);
 }
 
 function printPiSweep({ removed }) {

package/bin/installers/claude.mjs

@@ -79,6 +79,14 @@ const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 // The committed user-settings template.
 const SETTINGS_TEMPLATE = "claude/settings.json";
 
+// Claude user memory — the global prompt. The installer owns only the marked
+// section; everything outside the markers is the user's own text.
+const DEFAULT_INSTRUCTIONS_PATH = join(homedir(), ".claude", "CLAUDE.md");
+const INSTRUCTIONS_BEGIN = "<!-- BEGIN agent-cortex:output-style -->";
+const INSTRUCTIONS_END = "<!-- END agent-cortex:output-style -->";
+// Canonical prose, shared with the pi extension (extensions/output-style).
+const INSTRUCTIONS_SOURCE = join("extensions", "output-style", "output-style.md");
+
 // The only keys the installer owns outright: everything else in the live file
 // is personal config the merge must preserve.
 const SETTINGS_OWNED_KEYS = ["enabledPlugins", "extraKnownMarketplaces"];
@@ -97,8 +105,8 @@ const DEFAULT_WARN = (msg) => console.warn(`[claude-installer] ${msg}`);
 // section composition from the poll-loop sources.
 const DEFER = new Set(["ralph"]);
 
-// Ralph-coupled Copilot skills that don't apply to the lean Claude Ralph (and carry dead
-// ~/.copilot orchestration paths). Not copied into the Claude plugin.
+// Ralph-coupled pipeline skills that don't apply to the lean Claude Ralph (its completion
+// handling is event-driven, not the pi orchestrator's). Not copied into the Claude plugin.
 const SKILL_EXCLUDE = new Set(["ralph", "run-pipeline-stage"]);
 
 const NAME_PREFIX = "agent-cortex:";
@@ -324,7 +332,7 @@ async function installSettings({ root, target, dryRun, warn }) {
   }
 
   const content = `${JSON.stringify(merged, null, 2)}\n`;
-  return writeManagedJson({ target, content, dryRun });
+  return writeManagedFile({ target, content, dryRun });
 }
 
 /**
@@ -350,12 +358,12 @@ function mergeSettings(template, existing) {
 }
 
 /**
- * Write the managed settings file. A legacy symlink is replaced with a real
- * file by writing a sibling temp file and renaming it over the target — rename
- * replaces the link itself, so the committed template is never written through.
+ * Write a managed file. A legacy symlink is replaced with a real file by writing
+ * a sibling temp file and renaming it over the target — rename replaces the link
+ * itself, so a committed template is never written through.
  * Returns the action taken so the CLI can report the plan (dry-run included).
  */
-async function writeManagedJson({ target, content, dryRun }) {
+async function writeManagedFile({ target, content, dryRun }) {
   const symlink = await isSymlink(target);
   const current = await readFileMaybe(target);
 
@@ -382,6 +390,52 @@ async function writeManagedJson({ target, content, dryRun }) {
   return { path: target, action: symlink ? "removed-symlink" : "written", removedSymlink: symlink };
 }
 
+// ─── Claude user memory (CLAUDE.md) ──────────
+
+/**
+ * Materialise the output-style block into the managed section of ~/.claude/CLAUDE.md.
+ *
+ * The section is delimited by HTML comments, so a re-install replaces only the
+ * text between them and every other line of the user's memory file survives. A
+ * file with exactly one marker (hand-edited or truncated) is left untouched with
+ * a warning, never guessed at.
+ */
+async function installInstructions({ root, target, dryRun, warn }) {
+  const block = await readFileMaybe(join(root, INSTRUCTIONS_SOURCE));
+  if (block === null) {
+    warn(`no ${INSTRUCTIONS_SOURCE} source in the package — skipping CLAUDE.md`);
+    return null;
+  }
+  const content = mergeManagedSection(await readFileMaybe(target), block);
+  if (content === null) {
+    warn(`${target} has an unterminated agent-cortex section — left unchanged; fix the markers by hand`);
+    return { path: target, action: "skipped-unmanaged", removedSymlink: false };
+  }
+  return writeManagedFile({ target, content, dryRun });
+}
+
+/**
+ * Return `existing` with the managed section replaced by `block`, or null when
+ * the file carries unmatched markers. A file without markers gets the section
+ * appended, so personal memory text is never disturbed.
+ */
+function mergeManagedSection(existing, block) {
+  const managed = `${INSTRUCTIONS_BEGIN}\n${block.trimEnd()}\n${INSTRUCTIONS_END}`;
+  if (existing === null) return `${managed}\n`;
+
+  const start = existing.indexOf(INSTRUCTIONS_BEGIN);
+  const end = existing.indexOf(INSTRUCTIONS_END);
+  if (start === -1 && end === -1) {
+    const head = existing.replace(/\s*$/, "");
+    return head === "" ? `${managed}\n` : `${head}\n\n${managed}\n`;
+  }
+  if (start === -1 || end === -1 || end < start) return null;
+
+  const before = existing.slice(0, start).replace(/\s*$/, "");
+  const after = existing.slice(end + INSTRUCTIONS_END.length).replace(/^\s*/, "").replace(/\s*$/, "");
+  return `${[before, managed, after].filter((part) => part !== "").join("\n\n")}\n`;
+}
+
 async function readTemplateJson(filePath, warn) {
   const raw = await readFileMaybe(filePath);
   if (raw === null) {
@@ -450,15 +504,20 @@ async function isSymlink(filePath) {
  *                                       (default ~/.claude/settings.json). Passing it
  *                                       explicitly materialises settings even with
  *                                       --output — the test/CI seam.
+ * @param {string} [options.instructionsPath] Claude user-memory target
+ *                                       (default ~/.claude/CLAUDE.md). Passing it
+ *                                       explicitly materialises the section even
+ *                                       with --output — the test/CI seam.
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`.
  * @returns {{ output: string, marketplaceRoot: string|null, manifestPath: string|null,
  *             marketplaceManifest: object|null, agents: string[], natives: string[],
  *             skills: {names: string[], md: number, files: number, dir: string},
  *             hooks: boolean, hookFiles: string[], handAuthored: string[],
  *             settings: {path: string, action: string, removedSymlink: boolean}|null,
+ *             instructions: {path: string, action: string, removedSymlink: boolean}|null,
  *             warnings: string[], dryRun: boolean }}
  */
-export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = false, pluginRoot, settingsPath, warn = DEFAULT_WARN } = {}) {
+export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = false, pluginRoot, settingsPath, instructionsPath, warn = DEFAULT_WARN } = {}) {
   const tokenMap = await loadTokenMap(root);
   if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
     throw new Error(
@@ -498,15 +557,22 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     await mkdir(out, { recursive: true });
   }
 
-  // The default install owns ~/.claude/settings.json; --output is the
-  // generate-only form and leaves the user's Claude config alone. An explicit
-  // settingsPath requests the write regardless (the test/CI seam).
+  // The default install owns ~/.claude/settings.json and the managed section of
+  // ~/.claude/CLAUDE.md; --output is the generate-only form and leaves the
+  // user's Claude config alone. Explicit paths request the write regardless
+  // (the test/CI seam).
   const settingsTarget = settingsPath ?? DEFAULT_SETTINGS_PATH;
   const settings =
     isDefaultInstall || settingsPath !== undefined
       ? await installSettings({ root, target: settingsTarget, dryRun, warn: warnSink })
       : null;
 
+  const instructionsTarget = instructionsPath ?? DEFAULT_INSTRUCTIONS_PATH;
+  const instructions =
+    isDefaultInstall || instructionsPath !== undefined
+      ? await installInstructions({ root, target: instructionsTarget, dryRun, warn: warnSink })
+      : null;
+
   const agents = await buildAgents(root);
   const natives = await buildNatives(root, join(root, "agents-native"));
   const skillOut = join(out, "skills");
@@ -530,6 +596,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     hookFiles: hookFiles.map((f) => f.rel),
     handAuthored: handAuthored.map((f) => f.rel),
     settings,
+    instructions,
     warnings,
     dryRun,
   };
@@ -551,11 +618,15 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     if (summary.handAuthored.length)
       console.log(`  hand-authored files: ${summary.handAuthored.join(", ")} (copied from repo claude-extras/)`);
     if (summary.settings) console.log(`  settings → ${summary.settings.path} (${summary.settings.action})`);
+    if (summary.instructions)
+      console.log(`  CLAUDE.md → ${summary.instructions.path} (${summary.instructions.action})`);
     return summary;
   }
 
   // Write phase — the cleanup before buildSkills already cleared stale children.
   if (settings) console.log(`Materialised Claude settings → ${settings.path} (${settings.action})`);
+  if (instructions && instructions.action !== "skipped-unmanaged")
+    console.log(`Materialised CLAUDE.md section → ${instructions.path} (${instructions.action})`);
   const agentOut = join(out, "agents");
   await mkdir(agentOut, { recursive: true });
   for (const { file, content } of [...agents.files, ...natives]) {

package/docs/claude-hooks.md

@@ -17,6 +17,7 @@ UI surface. Each decision below is grounded in the Claude Code hooks reference.
 | `session-start/` | `SessionStart` hook commands | **Port** (extended) |
 | `auto-name.ts` | — | **Reject** — built-in |
 | `agent-guardrails/` | — | **Reject** — pi-only (no system-prompt hook) |
+| `output-style/` | managed `CLAUDE.md` section | **Port** — user memory, not a hook |
 | `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
 | `skill-stats/` | — | **Reject** — no equivalent |
 | `subagent/` | — | **Reject** — native |
@@ -89,6 +90,21 @@ context rather than system instructions. The rules are harness-agnostic prose, s
 a future port could append them to the existing ported SessionStart hook — out of
 scope for this pi-first slice.
 
+## `output-style/` → Port (managed CLAUDE.md section)
+
+pi appends the reply shape (action first, Simplified Technical English, restated
+context) to the system prompt through `before_agent_start`. Claude Code cannot
+modify the system prompt from a hook, so the installer writes the same block into
+the managed section of `~/.claude/CLAUDE.md` — Claude's user memory, loaded every
+session.
+
+The content is not copied into a Claude-side template: `extensions/output-style/
+output-style.md` is the single source, read by the pi extension at load and by the
+installer at install time. Re-running the install replaces only the text between
+the markers; personal memory text survives untouched. The installer never writes
+the block by appending to a `SessionStart` hook — memory is the right surface
+because the rules must hold for every turn, not just the first.
+
 ## `skill-stats/` → Reject (no equivalent)
 
 pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md

package/docs/ideas/improve-pi-system-prompt.md

@@ -1,9 +1,11 @@
 # Idea: Improve PI System Prompt
 
 ## Status
-Backlog idea (not implementation-ready) — first slice (circuit-breakers, check-in triggers,
-atomic-change discipline) implemented as the `agent-guardrails` pi extension; the rest of the
-idea is unscoped.
+Backlog idea (not implementation-ready) — two slices implemented as pi extensions:
+`agent-guardrails` (circuit-breakers, check-in triggers, atomic-change discipline) and
+`output-style` (action-first reply shape, Simplified Technical English, restated context,
+shipped to pi via the system prompt and to Claude via a managed `CLAUDE.md` section).
+The rest of the idea is unscoped.
 
 ## Why it might be useful
 PI's current system prompt is weak. Agents consistently get off track, spend excessive tokens spinning their wheels or going off on tangents, fail to check in when problems are hit, and generally behave like inexperienced code goblins. This wastes tokens, slows down task completion, and forces the user to constantly redirect the agent. A stronger system prompt would produce more focused, disciplined agents that know when to stop and ask.
@@ -30,6 +32,10 @@ High — after current work lands. Directly impacts daily productivity and token
 - Which guardrails from the Gemini starter are genuinely useful vs redundant with existing skills (e.g. `git-workflow` already covers destructive commands, `style-code` covers scope discipline)?
 
 ## Notes
+- **Second slice (settled)**: reply shape is a separate extension from task discipline.
+  `agent-guardrails` decides whether work continues; `output-style` decides how the result
+  is reported (STE per ASD-STE100, action first, context restated — never a bead or phase
+  ID cited alone). Both are stable constants appended on `before_agent_start`.
 - **Precedence (settled by the first slice)**: the generic circuit-breakers yield to a structured
   workflow — a skill or pipeline stage with its own explicit retry and check-in rules wins.
 - **Gemini starter prompt** exists (see conversation from 2026-08-05) covering loop prevention, action scope, context management, execution workflow order, and working state maintenance. Useful starting material but needs heavy customisation.

package/docs/research/disable-model-invocation.md

@@ -3,8 +3,7 @@
 Decision record for the frontmatter field this repo uses to keep rare or destructive
 skills out of automatic model routing (bead `agnt-ctx-yf24`).
 
-**Verdict:** rely on it for pi and Claude Code. Do not rely on it in Copilot CLI as
-"invoke-only" — there it means "unreachable through the model-facing skill tool".
+**Verdict:** rely on it for pi and Claude Code.
 
 ## What the field does
 
@@ -19,11 +18,10 @@ previously implied.
 | --- | --- | --- | --- |
 | pi 1.4.0 | Yes — byte-identical copy | Yes — hidden from the prompt, `/skill:name` still works | `bin/installers/pi.mjs:182-204`, `scripts/lib/compose-agent.mjs:69-95`; `dist/core/skills.js:262` (parse) and `:279` (filter); `docs/skills.md:53` |
 | Claude Code 2.1.294 | Yes — byte-identical copy | Yes — Claude cannot invoke it, `/skill-name` still works | `bin/installers/claude.mjs:160-201`, same token helper; [Claude Code skills docs](https://code.claude.com/docs/en/skills) ("Control who invokes a skill") |
-| Copilot CLI (1.0.55 locally, 1.0.80/1.0.83 upstream) | N/A — no copy; `plugin.json` `"skills": "skills/"` serves the repo tree in place | Auto-invocation suppressed, but explicit model invocation fails; `/skill-name` works | `plugin.json:12`; [github/copilot-cli#4438](https://github.com/github/copilot-cli/issues/4438) (open, retested 1.0.83) |
 
 Both materialisers copy `SKILL.md` as text and rewrite only `{{TOOL:...}}` /
 `{{PATH:...}}` tokens, so frontmatter keys they do not know pass through untouched —
-nothing re-serialises YAML. Verified by installing all three harnesses into
+nothing re-serialises YAML. Verified by installing both harnesses into
 `/var/tmp/dmi-check` and diffing `skills/productivity/teach/SKILL.md` (the repo's
 only current user of the field): both copies are byte-identical to the source.
 `claude plugin validate /var/tmp/dmi-check/claude/skills` passes, i.e. Claude Code's
@@ -58,46 +56,27 @@ Two Claude-specific caveats:
   frontmatter field itself still applies there — only that settings-based alternative
   is unavailable.
 
-**Copilot CLI.** The field is not in GitHub's skill documentation, which lists only
-`name`, `description`, `license`, and `allowed-tools`. In practice the CLI filters
-flagged skills out of the `skill()` tool's resolution list, so the model cannot call
-them even when the user names one: `Skill not found`. Only the interactive
-`/skill-name` slash command reaches a flagged skill, and `-p` mode has no slash path.
-Upstream issue #4438 is open.
-
-Local probing was not possible: the installed CLI is 1.0.55 (no `copilot skill`
-subcommand), and prompt runs are refused by this machine's org policy. The upstream
-report is the evidence for Copilot, tested on 1.0.80 and 1.0.83 — newer than 1.0.55,
-so this may differ locally, in either direction.
-
 ## Options for "explicit invocation only", evaluated
 
 | Option | Portable? | Enforced? | Verdict |
 | --- | --- | --- | --- |
-| `disable-model-invocation: true` | pi + Claude Code yes; Copilot suppresses but breaks tool-based invocation | Yes on pi/Claude | **Recommended** where suppressing auto-routing is the point and the explicit path is a human typing `/name` |
+| `disable-model-invocation: true` | pi + Claude Code yes | Yes | **Recommended** where suppressing auto-routing is the point and the explicit path is a human typing `/name` |
 | Naming convention (e.g. `manual-*`) | Yes | No — no harness reads names | Rejected: a human signal we already get from the body |
-| `metadata:` block | Yes (spec-legal) | No — pi and Claude read top-level keys only, Copilot undefined | Rejected: documentation that looks like enforcement |
+| `metadata:` block | Yes (spec-legal) | No — pi and Claude read top-level keys only | Rejected: documentation that looks like enforcement |
 | Keep such skills out of `skills/` | Yes | Yes, by not shipping the skill | Rejected: gives up the per-harness install entirely |
 
 ## Recommendation
 
 Use the field when the danger is fuzzy automatic matching and the intended explicit
 path is a human typing `/skill-name`: that is the case for a migration skill whose
-`--apply` renames labels workspace-wide. Accept, and document, that on Copilot CLI it
-also blocks model-mediated invocation, including `-p` runs — if a workflow needs
-non-interactive access to such a skill, do not set the field and instead disable the
-skill in that user's Copilot config (`copilot skill disable <name>`, or the `/skills`
-toggle), which is harness-native and per-user.
+`--apply` renames labels workspace-wide.
 
 ## Reproducing
 
 ```sh
 node bin/agent-cortex.mjs install claude  --output /var/tmp/dmi-check/claude
 node bin/agent-cortex.mjs install pi      --output /var/tmp/dmi-check/pi
-node bin/agent-cortex.mjs install copilot --output /var/tmp/dmi-check/copilot
 diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/claude/skills/teach/SKILL.md
 diff skills/productivity/teach/SKILL.md /var/tmp/dmi-check/pi/skills/productivity/teach/SKILL.md
 claude plugin validate /var/tmp/dmi-check/claude/skills
 ```
-
-The Copilot run writes only composed agent files — there is no skill copy to inspect.

package/docs/skills/skill-anatomy.md

@@ -9,13 +9,15 @@ 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; Copilot CLI suppresses auto-routing but then cannot reach the skill
-  through its model-facing tool. See `docs/research/disable-model-invocation.md`.
+  Claude Code. See `docs/research/disable-model-invocation.md`.
 
 ## Description format rules
 
@@ -35,7 +37,7 @@ Optional fields:
 
 ## Tool references
 
-Reference agent tools by `{{TOOL:name}}` token (canonical copilot name), never a
+Reference agent tools by `{{TOOL:name}}` token (canonical authoring name), never a
 hardcoded harness-specific name such as `bash`, `task`, or `read_agent` — installers
 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

package/docs/technical-direction/harness-config.md

@@ -20,13 +20,14 @@ below no longer hold:
   that both load.
 
 `pi.packages` and `lib/pi-packages.mjs` are deleted, so the bespoke-pi-mechanism problem this
-memo was written to settle is closed. The Claude and Copilot analysis stands.
+memo was written to settle is closed. The Claude analysis stands; Copilot CLI is no longer a
+deploy target (`agnt-ctx-2rl`).
 
 ## Problem and target outcome
 
-- **What we are solving.** agent-cortex ships agents and skills to three harnesses (pi, Claude
-  Code, Copilot CLI) and needs a declared, reproducible set of *third-party* extensions those
-  agents depend on (pi packages / Claude plugins). Two bespoke mechanisms currently exist and
+- **What we are solving.** agent-cortex ships agents and skills to two harnesses (pi, Claude
+  Code) and needs a declared, reproducible set of *third-party* extensions those agents depend
+  on (pi packages / Claude plugins). Two bespoke mechanisms currently exist and
   disagree: `main` declares packages in `package.json` → `pi.packages` and provisions them from
   `lib/pi-packages.mjs`; the unmerged pi-harness epic (`agnt-ctx-dfq3`) declares them in
   `pi.extensions.json` / `claude.extensions.json` and provisions them via `agent-cortex ext
@@ -51,9 +52,6 @@ memo was written to settle is closed. The Claude and Copilot analysis stands.
 - **Claude is idiomatic two ways.** Machine state is `~/.claude/settings.json` → `enabledPlugins`
   + `extraKnownMarketplaces`. A plugin declares other plugins in `.claude-plugin/plugin.json` →
   `dependencies`, which Claude Code resolves and auto-installs.
-- **Copilot has no dependency mechanism.** `copilot plugin install/list/uninstall` exists, but its
-  state is auto-managed `~/.copilot/config.json` (not committable) and `plugin.json` declares no
-  dependencies.
 - **The epic already built two-thirds of the target.** Unmerged commit `afab2c6` (F3) materialises
   `pi/settings.json` + `pi/keybindings.json` from committed templates with merge-keep-personal and
   the CLI owning `packages`; `1ff212d` (F4) makes bundled pi extensions load via package
@@ -86,7 +84,7 @@ memo was written to settle is closed. The Claude and Copilot analysis stands.
   --json` are the exact machine-state comparison; drift self-heals on install.
 - **Cons.** pi bundling shifts update cadence to agent-cortex releases and grows the tarball;
   Claude cross-marketplace deps need an allowlist; the committed template also carries personal
-  settings; Copilot gets nothing.
+  settings.
 - **Risks.** Loading TS extensions from bundled `node_modules/`; maintaining the Claude
   cross-marketplace allowlist.
 
@@ -128,8 +126,6 @@ the epic, and delete `pi.packages` + `lib/pi-packages.mjs` from `main`.
 - **Committed personal settings.** `pi/settings.json` already carries models/theme; the template
   model makes the repo own the whole pi settings surface. Accepted; F3's merge preserves personal
   keys and only `packages` is CLI-owned.
-- **Copilot gets no mechanism.** Documented exception — the README says `copilot plugin install`.
-  Accepted because Copilot has no dependency field and no committable config.
 - **No dedicated diff command.** A read-only `status` is deferred until drift is shown to hurt.
 
 ## Validation plan
@@ -160,8 +156,6 @@ pi extension loads from `node_modules/` and an optional one is materialised from
   speculative and should be dropped rather than maintained.
 - Bundling `pi-web-access`'s native-ish dependency tree (unpdf, linkedom) proves brittle or
   unacceptable on a fresh machine.
-- Copilot gains a committable config or a plugin dependency field — revisit the documented
-  exception.
 - Drift between the committed template and the machine becomes a recurring annoyance — add the
   deferred read-only `status`.
 
@@ -175,8 +169,6 @@ pi extension loads from `node_modules/` and an optional one is materialised from
   (auto-install, cross-marketplace allowlist, tag naming).
 - Claude Code, *Settings* — https://code.claude.com/docs/en/settings (`enabledPlugins`,
   `extraKnownMarketplaces`).
-- GitHub Copilot CLI, *Plugin reference* — https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference
-  and *Configuration directory* — https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference
 - Code evidence (as of 2026-09 — `pi.packages` and `lib/pi-packages.mjs` were removed in
   `agnt-ctx-7kru.1`, see Status): `package.json` (`pi.packages`), `lib/pi-packages.mjs` (main's
   provisioner);

package/docs/user-preferences.md

@@ -1,8 +1,8 @@
 # User Preferences
 
 This file records personal development preferences for the author (**jaybeeuu**).
-Both Copilot CLI agents and PI coding agents should read this file for user-level
-context when making tooling and workflow decisions.
+Both pi and Claude Code agents should read this file for user-level context when
+making tooling and workflow decisions.
 
 ## Package manager
 

package/extensions/agent-modes/README.md

@@ -39,9 +39,9 @@ contract:
    from the tool set with a warning.
 
 Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
-composable directory — they are generated output (scripts/build-copilot-agents.mjs)
-but may exist for non-migrated agents. A composable directory always wins over its
-flat counterpart for the same agent id.
+composable directory — a staged pi package carries flat renders, and a hand-written
+agent may be a single flat file. A composable directory always wins over its flat
+counterpart for the same agent id.
 
 ## Development