@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/claude/agents/plan.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/plan.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# GENERATED from agents/plan/ by bin/installers/claude.mjs — DO NOT EDIT.
 name: plan
 description: "Guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution. Full end-to-end planning workflow using the plan skill. Use when starting a new feature, scoping work to hand off to ralph, or saying 'plan this'."
 tools: Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion, Task, Skill
 ---
 
+# plan — end-to-end feature planning agent
+
 You are a planning agent. Your job is to guide a feature from first discussion through PRD and task breakdown to classified beads ready for ralph execution.
 
 You follow the **plan** skill workflow. The skill is defined in `skills/workflow/plan/SKILL.md`. Read it now to load the full instructions.

package/claude/agents/ralph-plan.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/ralph-plan.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# GENERATED from agents/ralph-plan/ by bin/installers/claude.mjs — DO NOT EDIT.
 name: ralph-plan
 description: "Plans changes by exploring codebases and creating beads to track the work. Use when you want to scope a feature, bug fix, or refactor — the agent reads, reasons, grills the user, writes a high-level plan into the top-level bead, then files child beads ready for ralph."
 tools: Bash, Read, Edit, Write, Grep, Glob, AskUserQuestion
 ---
 
+# ralph-plan — planning agent for ralph
+
 You are a planning agent. Your job is to understand a task, explore the codebase, grill the user until the design is clear, write a concise implementation plan, and file beads for ralph to implement. You **must not** modify any source code or tracked documentation — your writes are limited to `.agent-cortex/working-docs/` and bead fields.
 
 ## Permitted writes
@@ -32,7 +34,7 @@ Invoke the **beads** skill (set workspace root, run `bd prime`). Hold the output
 If the input looks like a PRD (product requirements document), invoke the **prd-to-tasks** skill first — it handles exploration, user quizzing, and creates epics and task beads directly. Then continue from step 7 (Agree with the user).
 
 ### 2. Understand the request
-If the request is ambiguous or incomplete, use `AskUserQuestion` to resolve blockers before exploring. One question at a time.
+If the request is ambiguous or incomplete, use AskUserQuestion to resolve blockers before exploring. One question at a time.
 
 If the domain language is unclear or inconsistent, invoke the **grill-with-docs** skill to extract canonical terms. It updates `CONTEXT.md` inline and surfaces ambiguities.
 
@@ -116,4 +118,4 @@ Every explore sub-agent prompt must include:
 - Never assume — verify by reading actual code before creating a bead.
 - Never write outside `.agent-cortex/working-docs/` or bead fields.
 - Never make commits, open PRs, or run shell commands that modify the repo.
-- Use `Bash` only for read-only commands (`git log`, `find`, `cat`, etc.).
+- Use Bash only for read-only commands (`git log`, `find`, `cat`, etc.).

package/claude/agents/strategy.md

@@ -1,10 +1,12 @@
 ---
-# GENERATED from agents/strategy.agent.md by scripts/build-claude-agents.mjs — DO NOT EDIT.
+# GENERATED from agents/strategy/ by bin/installers/claude.mjs — DO NOT EDIT.
 name: strategy
 description: "Creates top-level design documents across strategy, PRD, and technical direction so delivery planning starts with clear intent and justified decisions. Use when defining product direction before implementation planning, shaping a feature PRD, or selecting technical direction before ralph-plan."
 tools: Bash, Read, Grep, Glob, AskUserQuestion, WebFetch, Skill, Edit, Write
 ---
 
+# strategy — pre-delivery design agent
+
 You are a pre-delivery design agent. Your job is to produce high-quality design artifacts that set up `ralph-plan` for success.
 
 ## Scope

package/claude/hooks/scripts/notify.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Claude Code Notification hook — desktop notification on task completion/error.
+//
+// Reads the Notification hook JSON payload from stdin and prints a
+// `{ "terminalSequence": "..." }` response for Claude Code to emit. Hooks run
+// without a controlling terminal, so OSC sequences must go through Claude Code
+// itself (it handles tmux/screen re-wrapping); writing /dev/tty directly fails.
+//
+// Mapped from the pi `notify` extension (extensions/notify/): pi notifies on
+// agent_end for multi-turn or long tasks. Claude Code's Notification matcher is an
+// exact-string list over `notification_type` values (there are no `success`/
+// `error` types) — hooks.json selects `agent_completed|agent_needs_input|permission_prompt`
+// to mirror "task completed / failed / needs approval". The payload already carries
+// a message + title, so no summarization LLM call is needed here.
+//
+// Zero dependencies; runs on the Node that ships with Claude Code.
+
+let raw = "";
+for await (const chunk of process.stdin) {
+  raw += chunk;
+}
+
+let payload = {};
+try {
+  payload = raw.trim() ? JSON.parse(raw) : {};
+} catch {
+  process.exit(0); // never fail a session on an unparsable payload
+}
+
+const message = typeof payload.message === "string" ? payload.message.trim() : "";
+if (!message) process.exit(0); // nothing worth notifying (e.g. autocompact events)
+
+const title =
+  typeof payload.title === "string" && payload.title.trim() ? payload.title.trim() : "Claude Code";
+const type = typeof payload.notification_type === "string" ? payload.notification_type : "";
+
+process.stdout.write(JSON.stringify({ terminalSequence: pickSequence(title, message, type) }) + "\n");
+
+/** Pick an OSC notification escape sequence for the detected terminal. */
+function pickSequence(title, message, type) {
+  const body = message.replace(/\u001b/g, "").replace(/\n/g, " ").trim();
+  const label = type ? `${type}: ${title}` : title;
+
+  if (process.env.KITTY_WINDOW_ID) {
+    // Kitty: two-part persistent notification (title + body) — same form as the pi notify extension.
+    return `\u001b]99;i=1:d=1;${title}\u001b\\\u001b]99;i=1:p=body;${body}\u001b\\`;
+  }
+  if (process.env.TERM_PROGRAM === "iTerm.app" || process.env.ITERM_SESSION_ID) {
+    // iTerm2 / ConEmu / Windows Terminal / WezTerm: OSC 9.
+    return `\u001b]9;${label}: ${body}\u0007`;
+  }
+  // urxvt / Ghostty / Warp, and default fallback: OSC 777.
+  return `\u001b]777;notify;${label};${body}\u0007`;
+}

package/claude/hooks.json

@@ -12,12 +12,27 @@
             "type": "command",
             "command": "echo 'Style policy: this project ships style skills — prefer them over ad-hoc choices. Invoke style-code BEFORE writing or editing code (and when refactoring); style-tests BEFORE writing or changing tests; style-documentation BEFORE writing or updating docs; style-comms BEFORE composing commit messages, PR descriptions, tickets, or other written deliverables.'"
           },
+          {
+            "type": "command",
+            "command": "echo 'Skill policy: agent-cortex ships skills — prefer them over ad-hoc choices. using-agent-skills routes work to the right skill (check it first when unsure); bd-tool tracks beads tasks (run bd ready for available work); git-workflow enforces branch and PR discipline. Invoke skills via the Skill tool.'"
+          },
           {
             "type": "command",
             "command": "echo 'Be extremely concise. Sacrifice grammar for the sake of concision.'"
           }
         ]
       }
+    ],
+    "Notification": [
+      {
+        "matcher": "agent_completed|agent_needs_input|permission_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/notify.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/docs/claude-hooks.md

@@ -0,0 +1,115 @@
+# Claude Code hooks — extension port audit
+
+The pi extensions in `extensions/` were audited for Claude Code equivalents.
+Implemented ports live in `hooks/claude/hooks.json` (copied verbatim into the
+generated plugin as `claude/hooks.json`); support scripts live in
+`hooks/claude/scripts/` and are bundled into `claude/hooks/scripts/` by
+`bin/installers/claude.mjs` (referenced from hooks.json via `$CLAUDE_PLUGIN_ROOT`).
+
+Claude Code's hook model differs from PI's: hooks are shell commands fed a JSON
+payload on stdin, with events like `SessionStart`, `SessionEnd`, `Stop`,
+`SubagentStop`, and `Notification` — there is no `before_agent_start` /
+`agent_end` / `tool_call` extension API, no runtime tool registration, and no
+UI surface. Each decision below is grounded in the Claude Code hooks reference.
+
+| pi extension | Claude port | Decision |
+|---|---|---|
+| `session-start.ts` | `SessionStart` hook commands | **Port** (extended) |
+| `auto-name.ts` | — | **Reject** — built-in |
+| `notify/` | `Notification` hook + `scripts/notify.mjs` | **Port** |
+| `skill-stats/` | — | **Reject** — no equivalent |
+| `subagent/` | — | **Reject** — native |
+| `agent-modes/` | — | **Reject** — no equivalent |
+
+## `session-start.ts` → SessionStart (port)
+
+pi injects skill-availability hints + project context files (AGENTS.md,
+`docs/user-preferences.md`) into every session. Claude Code already loads
+`AGENTS.md` natively and the existing SessionStart hook nudge ("Load AGENTS.md
+and active beads context…") plus the style-skill policy (PR #57) cover the
+context side. This bead closes the remaining gap: a skill-policy command listing
+the meta-skills (`using-agent-skills` for routing, `bd-tool` for beads context,
+`git-workflow` for branch/PR discipline). SessionStart command-hook stdout is
+added to Claude's context, so plain `echo` commands are the right shape —
+keep them fast and dependency-free. Skipped from the pi original: the dynamic
+file read of AGENTS.md/user-preferences.md, since Claude Code loads AGENTS.md
+itself and user-preferences.md is a pi-harness document.
+
+## `auto-name.ts` → Reject (built-in)
+
+pi names sessions via a tiny side-model call on the first prompt. Claude Code
+already auto-generates descriptive session titles (visible in `claude --resume`;
+a background model request in interactive and headless/SDK sessions) and supports
+explicit naming via `--name` / `/rename`. A hook-based title generator would
+duplicate platform behaviour with an extra LLM call — rejected. (SessionStart
+hooks can also set `sessionTitle` in JSON output for the rare case where a
+custom title is genuinely needed.)
+
+## `notify/` → Notification hook (port)
+
+pi notifies on `agent_end` for multi-turn/long tasks with a desktop notification
++ bell. Claude Code's native `Notification` event fires at the equivalent
+completion points and already carries `message`, `title`, and `notification_type`
+in the payload — and hooks emit desktop notifications by returning a
+`terminalSequence` JSON field (hooks have no controlling terminal; Claude Code
+emits the sequence itself, including inside tmux/screen).
+
+Implemented as a `Notification` hook with matcher
+`agent_completed|agent_needs_input|permission_prompt` invoking `scripts/notify.mjs`,
+which reads the payload from stdin and prints the OSC sequence for the detected
+terminal (Kitty OSC 99, iTerm2/Windows Terminal OSC 9, default urxvt/Ghostty/Warp
+OSC 777 — same detection as the pi `notify` extension). The Notification matcher
+is an **exact-string list** over the `notification_type` field; there are no
+`success`/`error` types (an earlier draft used that matcher, which silently never
+fired). The documented types are `permission_prompt`, `idle_prompt`, `auth_success`,
+`elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`,
+`elicitation_response`, `agent_needs_input`, `agent_completed`,
+`quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`
+(the `agent_*` types require Claude Code v2.1.198+, the `quota_auto_resume_*`
+types v2.1.234+). The selection maps to pi's "task completed / failed / needs
+approval" semantics: `agent_completed` covers completion and failure ("finishes
+or fails"), `agent_needs_input` covers a background session waiting on input, and
+`permission_prompt` covers an awaited approval. Explicitly excluded as noise:
+`idle_prompt` (fires ~60s after every turn you don't answer within a minute — a
+desktop ping on every pause), `auth_success` and `quota_auto_resume_*` (not task
+events), and `elicitation_*` (dialog trivia). Skipped from the pi original: the LLM
+response summary (Claude's notification message is already the summary) and the tmux
+session:window.pane title (unavailable to hooks; the plugin title suffices).
+
+## `skill-stats/` → Reject (no equivalent)
+
+pi tracks skills loaded into the system prompt, `/skill:` invocations, SKILL.md
+reads, and turns, exposing a `/skill-stats` query. Claude Code exposes none of
+the required observability to hooks:
+
+- **No "loaded" event** — nothing fires when a skill enters context, and hooks
+  never see system-prompt contents, so the primary "loaded" metric has no source.
+- **Partial invocation/read observability only** — `PreToolUse` on the `Skill`
+  tool and `UserPromptExpansion` on slash commands would approximate
+  invocations, and `PostToolUse` on `Read` would approximate skill reads, but
+  the signals are fuzzy (Read covers any file; direct `/skill` typing bypasses
+  `PreToolUse`).
+- **No query surface** — Claude Code plugin commands are markdown files, not
+  scripts, so there is no equivalent of the pi `/skill-stats` command, and
+  persistent state would live outside the plugin model.
+
+A half-observable port would diverge from the pi semantics and add moving parts
+for little signal. Rejected; Claude Code ships its own usage analytics
+(`/usage`, sessions list, statsig) if insights are needed.
+
+## `subagent/` → Reject (native)
+
+pi's `subagent` tool spawns isolated `pi --mode json` processes. Claude Code has
+native subagents — the plugin already ships `claude/agents/*.md` (including
+`ralph`, `plan`, `strategy`, `ralph-plan`) executed via the built-in Agent/Task
+tools with per-session context isolation — so a hook-based workaround would be
+strictly worse.
+
+## `agent-modes/` → Reject (no equivalent)
+
+pi switches system prompts + tool restrictions at runtime with a TUI mode
+selector. Claude Code exposes no hook or settings surface for dynamic
+tool-restriction/prompt-switching of the main agent; the closest equivalents are
+native (permission modes like plan mode configured via settings, and subagents
+— already covered above). The `--agent <name>` start flag is covered by
+`claude --agent` in newer versions. Rejected.

package/docs/ideas/auto-model-selection.md

@@ -0,0 +1,75 @@
+# Idea: Auto-Model Selection Plugin
+
+## Status
+Backlog idea (not implementation-ready) — **direction: evaluate and adopt existing package**
+
+## Why it might be useful
+PI has no intelligent model selection. Users must manually choose models, which means they either over-provision (expensive models for simple tasks) or under-provision (weak models for complex work). Rate limits hit without warning, forcing manual model switching mid-session. An auto-selection plugin would optimize cost/performance by matching model capability to task complexity, and provide seamless fallbacks when rate limits are hit.
+
+## How we might do it
+**Evaluate and adopt an existing PI extension** rather than building from scratch. The ecosystem already has well-maintained packages that cover task-based routing and rate-limit fallbacks. The goal is to:
+
+1. **Evaluate the top candidates** (see "Packages to evaluate" below)
+2. **Pick the best fit** for agent-cortex's workflow (beads, pipeline stages, HITL/AFK classification)
+3. **Install and configure** it, possibly with light customisation if needed
+4. **Document** the chosen package and configuration in agent-cortex docs
+
+## Packages to evaluate (in priority order)
+**Top candidates — cover both task-based routing AND fallbacks:**
+1. **`@kylebrodeur/pi-model-router`** — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallback chains and rate-limit recovery. Well-documented fork of yeliu84's original.
+2. **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies, and quota-aware fallback.
+3. **`pi-tiered-router`** — routes different *phases* (planner/validator/executor/tool-parser) to different models. Quality-first, not cost-saving.
+
+**Fallback-only (simpler, if routing is overkill):**
+- **`pi-auto-models`** — Claude→Codex quota switching with 429/529 recovery
+- **`pi-provider-fallback`** — cross-provider fallback chain with TUI config
+
+**Evaluation criteria:**
+- Does it integrate cleanly with PI's existing provider/model system?
+- Does it respect user's explicit model choice, or override it?
+- How does it handle context window mismatches on fallback?
+- Is it configurable per-project?
+- Does it have fallback chains or just single fallback?
+- Rate-limit detection and retry logic
+- Documentation quality and maintenance status
+
+## When to think about it
+- After current feature stabilisation (refactor-to-template epic, npm publishing, system prompt improvements)
+- Not blocked, but benefits from stable extension infrastructure
+
+## Priority
+Medium / backlog — valuable for cost optimisation and reliability, but not urgent. Current manual model selection works, just isn't optimal.
+
+## Open questions
+- How to classify task complexity? Heuristics (file count, prompt length, keywords)? Or let user tag tasks?
+- What defines a "model class"? Cost tier, context window size, reasoning capability, speed?
+- Should the plugin override the user's explicit model choice, or only activate when no model is selected?
+- How to handle context window mismatches when falling back (e.g., 200k → 128k)?
+- Should this be configurable per-project (different policies for different repos)?
+
+## Existing packages in the ecosystem
+Several published packages already address parts of this problem:
+
+### Fallback / rate-limit recovery
+- **`pi-provider-fallback`** — cross-provider fallback with interactive TUI config
+- **`pi-auto-models`** — primary/fallback switching on quota (Claude→Codex default), 429/529 recovery
+
+### Task-based / tier routing
+- **`pi-model-router`** (yeliu84, forked by @kdejaeger and @kylebrodeur) — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallbacks
+- **`pi-model-auto`** — routes by Low/Medium/High/Ultra capability modes per turn
+- **`pi-tiered-router`** — routes different phases (planner/validator/executor/tool-parser) to different models
+
+### Full auto-router with failover
+- **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies
+- **`@ifi/pi-extension-adaptive-routing`** — adaptive routing with local telemetry persistence
+
+### Model selection (manual)
+- **`pi-model-switch`** — direct model switching tool
+- **`pi-model-select`** — `/select-model` with favourites and fuzzy search
+
+## Notes
+- **The ecosystem is active** — this space is already well-served. Before building, evaluate whether an existing package (especially `pi-model-router` or `pi-auto-router`) already meets the need.
+- **Gap analysis needed**: compare existing packages against the original requirements (task-based class selection + rate-limit fallbacks) to see if anything is genuinely missing.
+- **Partial solutions exist in PI core**: OpenRouter's routing config supports fallbacks and provider ordering, but only within OpenRouter. Cross-provider fallback requires an extension.
+- **Implementation approach** (if building): likely a PI extension that registers a "smart-router" provider, which internally delegates to real providers based on task classification and availability.
+- **Research done**: reviewed PI docs on providers, models, and extensions. Searched npm and pi.dev for existing packages.

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

@@ -0,0 +1,34 @@
+# Idea: Improve PI System Prompt
+
+## Status
+Backlog idea (not implementation-ready)
+
+## 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.
+
+## How we might do it
+Build improved behavioural instructions into agent-cortex — layered on top of or replacing PI's default system prompt. Key improvements:
+
+1. **Loop prevention / circuit-breakers** — hard limits on retry attempts (e.g. 2-attempt limit before stopping and asking), no repeated tool execution without rationale
+2. **Task-focus discipline** — stronger scoping instructions, no tangential refactoring, atomic changes
+3. **Check-in triggers** — explicit rules for when the agent must stop and present options to the user
+
+A Gemini-generated execution protocol prompt exists as a possible starting point (see Notes), but will need significant customisation for agent-cortex.
+
+## When to think about it
+- Land the current work first (refactor-to-template epic, bead workflow polish, CI/CD pipeline)
+- **Next priority after current work** — this is urgent-ish
+
+## Priority
+High — after current work lands. Directly impacts daily productivity and token efficiency.
+
+## Open questions
+- Layer on top of PI's default prompt, or replace it entirely?
+- Should PI's current system prompt be reviewed for nonsense that can be chopped out?
+- 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)?
+- How should circuit-breakers interact with skills like `run-pipeline-stage` that already have structured workflows?
+
+## Notes
+- **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.
+- **Incompatibility to fix**: the starter's "Working State Maintenance" section proposes `.pi/PLAN.md` files for complex tasks. This is incompatible with agent-cortex — we use **beads (bd)** for task tracking and pipeline stages, not flat markdown plan files. This section needs to be replaced with bead-aware equivalents (e.g. updating bead notes, using pipeline stage state).
+- **Overlap with existing skills**: several guardrails already exist in agent-cortex skills (`git-workflow`, `style-code`, `run-pipeline-stage`). The biggest gaps are **loop prevention / circuit-breakers** and **check-in discipline** — these aren't enforced anywhere today.

package/docs/ideas/model-selector.md

@@ -0,0 +1,40 @@
+# Idea: model-selector
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-07-12
+
+## Problem
+Selecting the right model for a task is manual and brittle. When a model is unavailable (rate-limited, down, or lacking capability), there's no automatic fallback. You have to know which model IDs to type into `/model` and remember which providers offer which capabilities.
+
+## Who benefits
+Anyone using PI who runs multiple models/providers. The extension makes model selection declarative: "I want to write code" → extension picks the best available model (and falls back if limits are hit).
+
+## Proposed outcome
+A PI extension that defines an abstraction for selecting models based on task/use case. Users declare "use case → model(s) with fallbacks" in config, and the extension handles selection and failover automatically.
+
+Key capabilities:
+- **Use-case profiles**: e.g. `code`, `chat`, `review`, `architect` — each maps to a primary model + ordered fallbacks
+- **Automatic fallback**: if the primary model returns a 429 or error, drop to the next in the chain
+- **Task-based selection**: think "I want this model to write code" instead of choosing a specific model ID
+- **Configurable**: profiles defined in settings.json or a dedicated config file
+
+## Validity check
+- Evidence we already have: The existing `tiny-model.ts` lib in this repo already shows the pattern of configuring a model by provider/id string and looking it up via `modelRegistry.find()`. The PI extension API supports `before_provider_response` (for catching 429s) and `model_select` events.
+- Riskiest assumption: That use-case profiles are a useful abstraction — users may prefer to just name a model family and let fallback be implicit.
+- What would invalidate this idea: If PI adds built-in model routing/fallback, or if users find the abstraction adds confusion rather than removing it.
+
+## Constraints
+- Must not add LLM calls internally (per extension conventions in AGENTS.md)
+- Must work with the existing `modelRegistry` API — no monkey-patching
+- Storage/config should go in settings.json or `~/.pi/agent-cortex/` (global, cross-project)
+
+## Next validation step
+Sketch the config schema and test it against real usage patterns. Does the profile abstraction hold up for the models/providers you actually use?
+
+## Notes
+- Initial conversation during planning session 2026-07-12. Idea recorded as backlog, to be fleshed out when time permits.
+- Could draw on patterns from OpenRouter's routing and the existing `modelOverrides` in models.json.
+- The `notify` extension already intercepts provider responses — similar pattern for catching rate limits.

package/docs/ideas/pi-task-memory.md

@@ -0,0 +1,34 @@
+# Idea: PI Task Memory Skill
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Why it might be useful
+PI has no built-in task memory. Agents lose context between sessions — they can't track what a task has done, what decisions were made, or where they left off. A skill that persists task-scoped knowledge in structured markdown would let agents pick up work without re-discovering context from scratch, and give humans a readable audit trail they can review or promote into real documentation.
+
+## How we might do it
+**Possibly build on top of `bd remember`** rather than creating a separate storage system. Worth exploring whether `bd remember`'s existing infrastructure (persistence, cross-session survival, auto-injection) could be extended with task-scoping and structure, vs building something standalone.
+- **Task-linked** — memories keyed to specific bead/task IDs so they can be retrieved in context
+- **Progressively discoverable** — the agent recalls relevant memories as it picks up work, not all at once
+- **Structured** — consistent format that's easy to scan, edit, or promote
+- **Promotable** — easy to elevate a memory into real repo documentation (e.g. `docs/`, `AGENTS.md`) once it's proven stable
+
+If `bd remember` turns out to be the right foundation, the skill would add **task-scoping discipline, structure, and a promotion workflow** on top. But that's to be determined.
+
+## When to think about it
+- After the current skill set stabilises (refactor-to-template work, bead workflow, CI/CD pipeline)
+- Not blocked by anything, but benefits from a stable foundation
+
+## Priority
+Low / backlog — useful but not urgent. Current memory surfaces (bd remember, context-mode) cover some of the gap already.
+
+## Open questions
+- What triggers writing a memory? (Agent decides? Skill hook on task close? Specific prompts?)
+- What does "progressively discoverable" mean in practice — agent reads task memories at session start, or on-demand when picking up a task?
+- What does "elevate into docs" look like — export memory to markdown file, or just reference the memory in docs?
+- How to structure memory keys for task-scoping? (e.g. `task-<bead-id>-<topic>`, or a naming convention?)
+
+## Notes
+- **What bd remember already provides**: persistent cross-session memories, auto-injection at `bd prime`, searchable via `bd memories <keyword>`, stored in Dolt database.
+- **Worth exploring**: could this skill layer task-scoping discipline (memories keyed to bead IDs), structured format, progressive discovery (not all memories at once), and a promotion workflow on top of `bd remember`? Or does it need its own system?
+- Could be a **PI extension** (event hooks) rather than a skill (invoked on-demand) if memories should be written automatically during task work.

package/docs/ideas/qa-extension.md

@@ -0,0 +1,43 @@
+# Idea: qa-extension
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-07-12
+
+## Problem
+When an agent needs clarification during a task (e.g. during a grilling session, resolving ambiguity, or making a recommendation), it has no structured way to ask the user a question and wait for an answer. The current workaround is unstructured prompting — the agent guesses, rambles, or proceeds with incomplete information. This makes grilling sessions less productive and wastes turns.
+
+## Who benefits
+Anyone using PI agents for interactive work — especially during planning, grilling, and design sessions where the model needs to ask a series of questions one at a time and get focused answers.
+
+## Proposed outcome
+A PI extension that registers a `qa` or `ask` tool that the LLM can call to ask the user a question. The tool:
+- Presents the question (and optionally multiple-choice options or a recommendation)
+- Pauses the agent and waits for the user's response
+- Returns the user's answer to the model so it can continue
+- Supports multi-turn Q&A sessions (series of questions)
+
+This mirrors the built-in `ask_clarification` / `question` tools in Claude Code, GitHub Copilot Chat, and similar coding agents.
+
+## Validity check
+- Evidence we already have: The PI extension API supports custom tools with user interaction via `ctx.ui` (input, confirm, select). The `subagent` extension already demonstrates complex async tool patterns. Claude Code and Copilot both ship this — it's a proven pattern.
+- Riskiest assumption: That the tool execution model in PI can support a "pause and wait for user input" flow without blocking the agent loop awkwardly.
+- What would invalidate this idea: If PI adds a built-in `ask_user` tool, or if the UX of blocking the agent loop for input feels worse than the current unstructured approach.
+
+## Constraints
+- Must work in both TUI and RPC modes (graceful fallback in non-interactive modes)
+- Should support at minimum: free-text input, confirm/deny, and multiple-choice selection
+- Questions and answers should be visible in the session history so they survive compaction
+- Must handle abort (Ctrl+C mid-question) gracefully
+
+## Next validation step
+1. **Investigate existing extensions first** — search PI's built-in tools, extension registry, and community repos for an existing `ask`/`qa`/`question` tool before building. May already be available.
+2. If no existing extension: check the PI tool execution model to see if a custom tool can return a partial result and then receive follow-up input from the user. Look at how `ctx.ui.input()` and `ctx.ui.confirm()` behave inside tool execution — can they block and return, or do they need a different pattern?
+
+## Notes
+- **Needs investigation** — check for existing PI extensions/tools before building.
+- Initial conversation 2026-07-12. Motivated by making grilling sessions more efficient — the grill-me skill asks one question at a time, and a structured Q&A tool would make that flow tighter.
+- Related to `grill-me` skill (`skills/productivity/grill-me/SKILL.md`) — this extension could become the runtime that grill-me delegates its questioning to.
+- Possible names: `/ask`, `qa`, `question` tool.

package/docs/ideas/unified-ci-pipeline.md

@@ -0,0 +1,28 @@
+# Idea: Unified CI Pipeline with Parallel Checks
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Why it might be useful
+The current CI setup has two problems:
+1. **Slow feedback** — checks run serially, making the pipeline slower than it needs to be.
+2. **Broken releases** — the release job (version branch creation) is a separate pipeline, so it can fire even when checks fail. A broken commit can reach the version branch.
+
+Combining them gives faster feedback (parallel checks) and a safety gate (release step only runs if all checks pass).
+
+## How we might do it
+- Merge the check pipeline and release pipeline into a single pipeline.
+- Fan out all checks to run in parallel.
+- Make the version branch creation a downstream job/step that depends on all checks passing.
+
+## When to think about it
+When CI pipeline speed or release safety becomes a recurring friction — e.g. after the changesets/release workflow is fully set up and seeing real traffic.
+
+## Priority
+P2 — infrastructure quality-of-life. Not blocking current work, but a clear improvement once the release flow stabilises.
+
+## Notes
+- Setup job with artifact infrastructure added (2026-08): install + build now happen once in a `setup` job, artifacts are shared with downstream jobs via upload/download-artifact. This is the first step toward the unified pipeline vision.
+- Depends on the changesets release workflow being in place (P1 beads `agnt-ctx-d1ht`, `agnt-ctx-5bcu`).
+- Should be straightforward once the pipeline shape is settled.
+- **Release pipeline fires on every push to main** — this wastes CI minutes. It should only run when there are changesets to process (e.g. when the version packages PR is merged, or when new changesets land on main). Add a path filter or a pre-check that skips the job when no `.changeset/*.md` files changed.

package/docs/skills/skill-anatomy.md

@@ -29,6 +29,14 @@ Optional fields:
 - Add one rationale sentence for non-obvious rules so behavior generalizes in novel cases.
 - Avoid ALL-CAPS emphasis.
 
+## Tool references
+
+Reference agent tools by `{{TOOL:name}}` token (canonical copilot 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
+`token-map.README.md` for the full authoring rules.
+
 ## Required sections
 
 Every skill must include:
@@ -81,6 +89,7 @@ Provide completion gates that are testable and stage-scoped.
 
 A skill passes anatomy review when:
 - [ ] Front matter uses required fields and valid description format.
+- [ ] Tool references use `{{TOOL:name}}` tokens, not hardcoded tool names.
 - [ ] Required sections exist and follow canonical ordering.
 - [ ] Optional sections (if present) include what/when/example guidance.
 - [ ] Verification checklist contains concrete, machine-checkable items.

package/extensions/agent-modes/README.md

@@ -0,0 +1,54 @@
+# Agent Modes Extension
+
+Makes the agent-cortex agents (ralph, ralph-plan, plan, strategy) available as
+switchable PI modes. Each mode injects the agent's full system prompt into the
+running context, restricts tools to the agent's declared tool set, and shows a
+status indicator with the active agent name.
+
+## Usage
+
+| Command | Description |
+| --- | --- |
+| `/agent` | Show the agent mode selector |
+| `/agent <name>` | Switch to an agent mode directly (e.g. `/agent ralph`) |
+| `/agent default` | Return to default mode (full tool access) |
+| `Ctrl+Shift+A` | Cycle through agent modes |
+| `--agent <name>` | Start PI in a specific agent mode |
+
+## How agents are discovered
+
+Agents are read from the **composable source format** in the package's
+`agents/` directory:
+
+```
+agents/<name>/
+├── agent.md             # Shared body (harness-agnostic)
+└── pi/
+    ├── frontmatter.json # PI metadata: name, description, tools
+    └── <section>.md     # Optional sections referenced by {{SECTION:name}}
+```
+
+The PI system prompt is composed from `agent.md` per the token-map.json
+contract:
+
+1. `{{SECTION:name}}` tokens are replaced with the agent's `pi/<name>.md`.
+2. `{{TOOL:key}}` / `{{PATH:key}}` tokens are substituted against the pi column
+   of `token-map.json`, with the plugin root resolved from the actual extension
+   location. Tools without a PI equivalent (`ask_user`, `skill`) are omitted
+   from the tool set.
+
+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.
+
+## Development
+
+Discovery and prompt composition live in `discover.ts` (unit-tested against
+fixture directories in `discover.test.ts`); `index.ts` only wires discovery
+into the extension API.
+
+```bash
+pnpm test        # run discover.test.ts
+pnpm typecheck   # tsc --noEmit
+```