@jaybeeuu/agent-cortex 2.0.0 → 2.1.0

package/AGENTS.md

@@ -71,7 +71,9 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   checkout (branch bases, merge method, signature rules, required checks, release mechanics) belong
   in `AGENTS.md`, `docs/`, or the tracker. Repo-local `.agents/skills/` follows the same rule: a
   skill is a skill, not a place for this repo's configuration.
-- `SKILL.md` must include a YAML front-matter block with `name` and `description`.
+- `SKILL.md` must include a YAML front-matter block with `name` and `description`. `pnpm lint`
+  enforces this (`pnpm check:skills`), because PI silently drops a skill whose frontmatter it
+  cannot parse.
 - `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
 - Keep `SKILL.md` near the ~150-line target in `docs/skills/skill-anatomy.md`, overflowing into
   purpose-named support files (`REFERENCE.md`, `EXAMPLES.md`, `FORMAT.md`). `style-tests`

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 2.1.0
+
+### Minor Changes
+
+- a4658cf: Add the `output-style` pi extension: it appends an always-on reply-shape block to the PI
+  system prompt — lead with the action, write in Simplified Technical English (ASD-STE100),
+  and restate context instead of citing beads, phases, or stages by ID alone.
+
+  The block lives in `extensions/output-style/output-style.md` and is also written to the managed
+  section of `~/.claude/CLAUDE.md` by `agent-cortex install claude`, so Claude Code receives the
+  same rules alongside pi.
+
+### Patch Changes
+
+- a30f3c4: Make ralph's PR gate brake depend on a gate being _unblocked_, and count gates
+  on the current HITL label axis.
+
+  `create-chores` pre-creates a `lifecycle:feature-pr` gate for every planned
+  feature, blocked behind that feature's own `document` chore. Ralph's rule — "do
+  not schedule new parent features while any HITL gate bead is open" — therefore
+  matched every unstarted feature, so the brake was permanently on: with eight
+  open gates, none of them actionable, no new feature could ever be dispatched.
+  The pause query had drifted the other way: it filtered on the legacy
+  `implementation-type:hitl` axis only, so gates migrated to `execution:hitl`
+  were invisible and pending human action was under-reported.
+
+  - `skills/workflow/ralph/scripts/pending-gates.mjs` resolves the question in one
+    place: `pendingHumanAction` holds unblocked gates plus epics tagged
+    `awaiting-epic-pr-merge` and is the only scheduling brake; `parked` holds
+    gates still blocked behind their own pipeline, which never stop dispatch and
+    never appear in the Pending Human Action table.
+  - Gate queries match `lifecycle:feature-pr` on either HITL axis, so gates
+    created on either side of the two-axis migration are counted.
+  - ralph's composable agent source (`agents/ralph/agent.md`) and the ralph skill
+    and REFERENCE now point at the script instead of restating ad-hoc `bd` queries
+    that had already drifted.
+  - `agents-native/ralph.md` (the Claude harness) keeps the **open**-gate form and
+    only takes the dual-axis query: its gates stay blocked for their whole life —
+    `create-task` blocks them behind a `document` chore no Claude ralph closes, and
+    the native route deps them onto the still-open feature bead — so the unblocked
+    predicate would never fire there and ralph would report "All beads complete."
+    with PRs unmerged. REFERENCE.md now states the invariant: a gate blocked by its
+    parent feature bead is not parked in any harness, so a gate must not carry a
+    `blocks` dependency onto its own feature.
+
+  Reconcile with agnt-ctx-s5xd.10 (ralph harness unification) when that rewrites
+  ralph's agent files — it owns collapsing the two predicates into one.
+
+- e5e7683: Fail `pnpm lint` when a SKILL.md frontmatter cannot be parsed, is missing `name` or `description`, or has a description longer than 1024 characters. PI previously dropped such skills silently.
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -24,6 +24,7 @@ agent-cortex/
 ├── extensions/               # pi extensions (pi only)
 │   ├── agent-guardrails/     #   behavioural circuit-breakers in the system prompt
 │   ├── agent-modes/          #   switchable agent modes (reads composable agents/)
+│   ├── output-style/         #   reply shape: STE, action-first, restated context
 │   ├── skill-stats/
 │   └── notify/
 ├── pi/                       # Committed pi config templates (see below)
@@ -279,7 +280,10 @@ manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude
 registers it with Claude Code, and merges the committed `claude/settings.json` template into
 `~/.claude/settings.json`: the template supplies defaults, personal values win, and the
 installer owns exactly `enabledPlugins` + `extraKnownMarketplaces` — every other key
-(`permissions`, `hooks`, `env`, `statusLine`, unknown keys) is preserved. The only committed
+(`permissions`, `hooks`, `env`, `statusLine`, unknown keys) is preserved. It also writes the
+managed section of `~/.claude/CLAUDE.md` — the reply-shape block the pi `output-style`
+extension appends, taken from the same source file — and leaves every other line of that
+file alone. The only committed
 Claude config is that template plus the hand-authored extras in `claude-extras/`
 (`.mcp.json`, `scripts/`); the plugin subtree is generated at install time — there is nothing
 to drift.
@@ -341,6 +345,12 @@ supplies defaults and personal values win; the installer owns exactly `enabledPl
 never touched. A legacy symlinked `settings.json` is replaced with a real file rather than
 written through, and `--output` leaves the user's Claude config alone.
 
+It also writes the managed section of `~/.claude/CLAUDE.md` (Claude's user memory), delimited
+by `<!-- BEGIN agent-cortex:output-style -->` / `<!-- END agent-cortex:output-style -->`. The
+content is `extensions/output-style/output-style.md` — the same file the pi extension appends
+to its system prompt — so both harnesses carry one copy of the rules. Text outside the
+markers is never touched; a file with only one marker is left unchanged with a warning.
+
 The equivalent manual registration adds a marketplace root by **absolute path** (a bare `.` is
 rejected) — the home install root (`~/.agent-cortex`) is the marketplace root written by
 the plain install; the repo checkout ships no manifest:
@@ -419,7 +429,8 @@ extension→hook audit.
 #### Not ported / follow-ups
 
 - Only `session-start` and `notify` had Claude equivalents (both ported to hooks); the other
-  pi `extensions/` (auto-name, agent-guardrails, skill-stats, subagent, agent-modes) have none — the audit and
+  pi `extensions/` (auto-name, agent-guardrails, skill-stats, subagent, agent-modes) have none — `output-style`
+  reaches Claude through the managed `CLAUDE.md` section instead; the audit and
   rejection rationale live in `docs/claude-hooks.md`.
 - Ralph follow-ups: multi-feature epic branches, and a GitHub-trigger routine to auto-resume
   after a PR merge (instead of manual re-invocation).

package/agents/ralph/agent.md

@@ -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 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_).
 
 ---
 
@@ -140,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
@@ -165,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.

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/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"];
@@ -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/skills/skill-anatomy.md

@@ -9,6 +9,9 @@ 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

package/extensions/output-style/README.md

@@ -0,0 +1,58 @@
+# Output Style
+
+Appends the always-on reply shape to the PI system prompt once per user prompt.
+
+This is the second slice of `docs/ideas/improve-pi-system-prompt.md`: the first
+(`agent-guardrails`) stops wasted work; this one stops the answer getting buried in
+it. The extension injects a stable block via the `before_agent_start` hook — which
+fires once per user prompt, before the agent loop — so the rules apply to every
+turn of the run without rewriting Pi's default prompt.
+
+## Rules
+
+- **Lead with the action** — the first line is the answer, command, path, or next
+  action; multi-step work is numbered; the reply ends with one next step.
+- **Keep the prose short** — no preamble, no recap, no closing offer; five items
+  per list at most; one topic per reply.
+- **Write Simplified Technical English (ASD-STE100)** — active voice, 20-word
+  sentences for instructions and 25-word sentences for description, verb over
+  noun, one word one meaning, literal words, no marketing adjectives, articles
+  kept.
+- **Restate the context** — never cite a bead, ticket, phase, or stage by ID alone;
+  say what it is in plain words first, and restate state after a gap or topic
+  switch.
+
+The rules shape the reply, never the work. When a rule would delete the answer,
+the task wins.
+
+## Structure
+
+```
+output-style/
+├── README.md              # This file
+├── index.ts               # Extension entry point — appends on before_agent_start
+├── output-style.ts        # Loads the block + appendOutputStyle composition
+├── output-style.md        # The block text (single source, also shipped to Claude)
+├── output-style.test.ts   # Composition tests
+├── package.json
+└── tsconfig.json
+```
+
+## Testing
+
+```bash
+cd extensions/output-style
+node --test --import tsx/esm output-style.test.ts
+```
+
+## Design notes
+
+- The block is a stable constant appended after any chained system-prompt changes,
+  so the prompt-cache prefix is preserved.
+- `appendOutputStyle` is idempotent — a prompt that already carries the marker is
+  returned unchanged, so a duplicate extension load cannot double the rules.
+- Separate from `agent-guardrails` because it is a different failure: guardrails
+  govern *whether* work continues, this governs *how the result is reported*.
+- The prose lives in `output-style.md`, not in the TypeScript, because there is a
+  second consumer: `agent-cortex install claude` wraps that file in the managed
+  `~/.claude/CLAUDE.md` section. One file, two harnesses, no drift.

package/extensions/output-style/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Output Style Extension
+ *
+ * Appends the always-on reply shape to the PI system prompt on every turn: lead
+ * with the action, write in Simplified Technical English (ASD-STE100), restate the
+ * context the reader cannot remember (the second slice of
+ * docs/ideas/improve-pi-system-prompt.md).
+ *
+ * The block is stable text appended after any chained system-prompt changes, so it
+ * keeps the prompt-cache prefix intact while remaining authoritative for the model.
+ * See output-style.ts for the rules and appendOutputStyle for composition.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendOutputStyle } from "./output-style.ts";
+
+export { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+export default function outputStyleExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => {
+    return { systemPrompt: appendOutputStyle(event.systemPrompt) };
+  });
+}

package/extensions/output-style/output-style.md

@@ -0,0 +1,43 @@
+## Output style (agent-cortex)
+
+How every reply is written. These rules shape the reply, never the work: do all
+the analysis and tool calls the task needs, then report the result this way. If a
+rule would delete the answer itself, the task wins; the shape stays.
+
+### Lead with the action
+
+- The first line is the answer, the command, the path, or the next action. Not
+  context, not a plan, not "Let me…".
+- Number multi-step work. One bounded action per step.
+- End with one concrete next step. Omit it when the work is finished.
+
+### Keep the prose short
+
+- No preamble ("Great question", "I'll now…"), no recap of work just completed,
+  no closing offer ("Let me know if…", "Hope this helps").
+- Five items maximum per list. Rank them; group related items.
+- One topic per reply. Name a tangent in one line at the end, then stop.
+
+### Write Simplified Technical English (ASD-STE100)
+
+- Active voice. Imperative for instructions.
+- Sentence limit: 20 words for instructions, 25 for descriptive text. One
+  instruction per sentence.
+- Use the verb, not the noun: "check the file", not "perform a check of the file".
+- One word, one meaning: pick the term for a thing, then reuse it.
+- Literal words only. No idioms, metaphors, or figures of speech ("circle back",
+  "under the hood", "ballpark").
+- No marketing adjectives or filler ("seamless", "robust", "comprehensive").
+- Keep articles and subjects. Do not compress into fragments that lose meaning.
+- Give times in concrete units ("about 10 minutes"), never "a bit of work".
+
+### Restate the context, never assume it
+
+The reader cannot hold earlier turns in working memory.
+
+- Never name a bead, ticket, phase, or pipeline stage by ID or number alone. Say
+  what it is in plain words first — "the login fix, verify step (bd-142)" — and
+  give the ID at most once.
+- After a gap, a topic switch, or a long tool run, restate in one line: what is
+  done, what is next.
+- Mark progress concretely: "Step 2 of 4 done: schema updated."

package/extensions/output-style/output-style.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+// ─── appendOutputStyle ────────────────────────────────────────────────────────
+
+describe("appendOutputStyle", () => {
+  it("appends the output-style block after the base prompt", () => {
+    const result = appendOutputStyle("You are a helpful agent.");
+
+    assert.ok(result.startsWith("You are a helpful agent."));
+    assert.ok(result.includes(OUTPUT_STYLE));
+  });
+
+  it("preserves a chained base prompt from earlier handlers", () => {
+    const base = "Base prompt.\n\n---\nAgent mode instructions.";
+    const result = appendOutputStyle(base);
+
+    assert.ok(result.startsWith(base));
+  });
+
+  it("trims trailing whitespace before appending", () => {
+    const result = appendOutputStyle("Base prompt.\n\n");
+
+    assert.equal(result, `Base prompt.\n\n${OUTPUT_STYLE}`);
+  });
+
+  it("keeps a block appended by another extension", () => {
+    const withGuardrails = "Base prompt.\n\n## Operating discipline (agent-cortex)\n\nRules.\n";
+    const result = appendOutputStyle(withGuardrails);
+
+    assert.ok(result.includes("## Operating discipline (agent-cortex)"));
+    assert.ok(result.endsWith(OUTPUT_STYLE));
+  });
+
+  it("is idempotent when applied twice", () => {
+    const once = appendOutputStyle("Base prompt.");
+    const twice = appendOutputStyle(once);
+
+    assert.equal(twice, once);
+    assert.equal(twice.split(OUTPUT_STYLE_MARKER).length - 1, 1);
+  });
+
+  it("returns the prompt unchanged when the output style is already present", () => {
+    const existing = `Base prompt.\n\n${OUTPUT_STYLE}`;
+
+    assert.equal(appendOutputStyle(existing), existing);
+  });
+});