@jaybeeuu/agent-cortex 1.37.1 → 1.39.0

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/record-ideas-as-beads.md

@@ -0,0 +1,115 @@
+# Idea: record-ideas-as-beads
+
+## Status
+Fleshed out 2026-08-25 — design decisions locked in an interview; not yet implemented.
+
+## Created
+2026-08-25
+
+## Problem
+Ideas currently live as loose markdown files in `docs/ideas/`. This sits awkwardly alongside
+the rest of the workflow, which is almost entirely bead-based (bd). Because ideas aren't beads,
+they can't be searched with `bd label`, can't express relationships/dependencies to real tasks,
+can't be given priority that surfaces alongside other work, and can't sync to remote via
+`bd dolt push`. There's no clean promotion path from "idea" to "epic" to "executable task".
+
+## Who benefits
+The author's daily planning loop. Ideas are the beginning of epics, so making them first-class
+beads gives a single coherent backlog where an idea can grow relationships to the tasks it
+spawns. The plan/agent-nexus agents benefit too: agent-nexus will eventually schedule work
+through planning stages (not just execution), and a beads-native idea record gives it a clean
+input to plan against.
+
+## Proposed outcome
+Record ideas as beads labelled `kind:idea`, replacing `docs/ideas/*.md` entirely (bead-only —
+files deleted after migration). `bd` already supports labels natively (`bd create -l`,
+`bd label add/list`). An idea bead maps directly to an epic; promoting it means spawning task
+beads as children and letting the idea bead become the epic node.
+
+## Fleshed-out design (decided 2026-08-25)
+
+### Label & identification
+- **`kind:idea` label** marks idea beads. Ideas do NOT use `deferred` status — they stay
+  `open` so they're visible to idea tooling; hiding from actionable work is done by exclusion,
+  not status.
+- **ralph excludes them**: ready queries use `bd ready --exclude-label kind:idea`
+  (verified: `bd ready` supports `--exclude-label`). Idea beads never appear as claimable work.
+- Optional companion labels: `priority:<0-4>`, `epic:<id>` once promoted.
+
+### Flesh-out workflow (the skill that consumes them)
+There should be a **flesh-out skill** (e.g. `flesh-out-idea`) that answers: *"which idea beads
+are ready to be fleshed out?"* This is `bd ready -l kind:idea` — the blocker-aware ready query
+scoped to ideas. Because `bd ready` already respects dependencies, an idea bead that
+`depends-on` in-flight work (e.g. "needs unified-ci-pipeline landed first") naturally shows as
+*not ready* until its deps close. That's exactly the semantics wanted:
+- `bd ready -l kind:idea` → list & pick an idea ready for fleshing.
+- The skill runs the record-idea-style interview (why / how / when / priority) at deeper depth,
+  updating the bead's description/design/notes as the idea ripens.
+- Once fleshed out enough, the idea can be promoted (below).
+
+### Promotion path: idea → epic → tasks
+Parent-child hierarchy (chosen over labels+deps only):
+1. Idea bead starts with `kind:idea`, type defaulted appropriately (still `task` type, or set
+   `epic` type on promotion).
+2. On promotion: `bd label add <idea> epic:<idea-id>` (or flip to an epic label), then spawn
+   task beads with `--parent <idea-id>` — children inherit the epic relationship natively.
+3. The idea bead becomes the epic node; its children are the executable tasks. Closing the
+   children resolves to the epic closing.
+
+### Content model (bead fields)
+Map the current idea-template sections onto bd fields:
+| md template field | bd field |
+|---|---|
+| Title | `--title` |
+| Problem / Why | `--description` |
+| How we might do it | `--design` |
+| When / Priority / Validity / Constraints / Notes | `--notes` (structured, keep section markers) |
+| anything referential | `--context` |
+
+Multiple sections per field use explicit markers (`## Validity check`, etc.) inside the field
+so the flesh-out interview can find/update them later.
+
+### Skill changes
+- **`record-idea`**: replace scaffold-file flow (`new-idea.sh` → `docs/ideas/x.md`) with bead
+  creation: interview → `bd create "<title>" -l kind:idea -d "<why>" --design "<how>"
+  --notes "<when/priority/validity>"`. Keep the interview; drop the markdown scaffold script.
+- New **`flesh-out-idea`** skill (see above) — validates readiness (`bd ready -l kind:idea`),
+  picks an idea, drives the deepening interview, updates the bead, optionally promotes.
+
+### Migration
+- Bulk-migrate the existing `docs/ideas/*.md` records to beads: read each file, map sections to
+  bd fields, `bd create -l kind:idea`, preserve priority. Run as a one-off (manual or scripted).
+- Then **delete `docs/ideas/`** — bead-only going forward.
+- Update `AGENTS.md` + any stale references that point at `docs/ideas/`.
+- The `record-idea` skill itself must unlearn the docs/ideas path.
+
+## Validity check
+- Evidence we already have: `bd ready --exclude-label` and `bd ready -l` both exist and compose
+  (label filtering + blocker-aware ready semantics) — the two core mechanisms this idea needs
+  are native, no feature build. `--parent` exists for the hierarchy. 9-10 idea files exist to
+  migrate; the record-idea skill and its script are the only two consumers of the file flow.
+- Riskiest assumption: that keeping ideas `open` (not `deferred`) + label exclusion is
+  discoverable enough — ralph, plan agents, and the author must remember the exclusion. The
+  `bd-tool` skill's labels table needs `kind:idea` documented with the exclusion convention.
+- What would invalidate this idea: if label-based exclusion leaks idea beads into `bd ready`
+  via some path (e.g. `bd ready` without the exclude flag), or if losing the scannable
+  `docs/ideas/` directory hurts occasional review more than bead queries help it.
+
+## Constraints
+- Ideas stay quick to scan: `bd list -l kind:idea` + `bd show <id>` should be a comfortable
+  replacement for opening the directory.
+- Idea beads must never appear in ralph's actionable-ready view.
+- `record-idea` and `bd-tool` skills stay consistent — no stale references to docs/ideas.
+- Priority of ideas uses the same P0-P4 scale as tasks (P4 = backlog default for ideas).
+
+## Next validation step
+Prototype one idea as a labelled bead: create it with `-l kind:idea`, confirm `bd ready`
+excludes it by default and `bd ready -l kind:idea` surfaces it; then promote it (add epic label,
+spawn a child task) to confirm the hierarchy reads correctly. If the prototype passes, do the
+bulk migration + skill updates.
+
+## Notes
+Interview on 2026-08-25 locked: labels over status (kind:idea + ralph exclusion), bead-only
+content (files deleted), parent-child promotion, and record-idea skill rewritten to create
+beads. Agent-nexus is the planned consumer. Once this lands, this very record becomes an
+idea-bead (and then this file is deleted — the migration eats its own tail).

package/docs/ideas/subagent-visibility.md

@@ -0,0 +1,72 @@
+# Idea: subagent-visibility
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+The bundled `subagent` extension delegates work to separate `pi` processes with isolated
+context windows. It streams output live, shows per-agent usage stats (turns, tokens, cost), and
+supports abort — but after a run there's no retained record of what each subagent actually did
+(files touched, decisions, blockers), and while a run is in flight there's no richer
+dashboard-level view of what each agent is up to. There's also no way to influence a running
+subagent: you can only watch or Ctrl+C the whole thing. For the ralph-style parallel dispatches
+(up to 5 concurrent chores) this is a real blind spot.
+
+## Who benefits
+The author, whenever running parallel subagent work (ralph pipeline chores, parallel research).
+A live dashboard helps during runs; persisted per-run reports turn subagent work into a
+reviewable after-action record (which also complements the HITL/summary flow). Mid-run steering
+reduces wasted tokens from subagents heading the wrong way and having to restart.
+
+## Proposed outcome
+Expand (or adopt, if a store extension fits) subagent tooling to give:
+
+1. **Live dashboard** — richer TUI during runs: per-agent status (phase, current tool call,
+   files touched), so you can see what each parallel subagent is doing without digging into
+   streamed output.
+2. **Persisted reports** — a per-run record per subagent (what it did, files changed,
+   decisions, blockers), stored for after-action review. Persistence should follow the repo
+   convention: write to `~/.pi/agent-cortex/`, tagged with project path for per-project slicing.
+3. **Mid-run steering** — send a message to a running subagent to change its direction
+   ("skip that, focus on X") rather than killing and restarting.
+
+Decision from the interview: **evaluate the pi extension store first** — if a maintained
+extension already covers dashboard + reports (and ideally steering), adopt it; otherwise expand
+the bundled `subagent` extension. Building is a fallback, not the default.
+
+## Validity check
+- Evidence we already have: the bundled `subagent` extension is a working base — it already
+  spawns `pi` subprocesses, streams, and collects usage data, so the hooks for a dashboard and
+  reports exist in some form. The repo has a data convention (`~/.pi/agent-cortex/`, per-project
+  tagging) that reports would slot into.
+- Riskiest assumption: that mid-run steering is technically feasible — subagents run as separate
+  `pi` processes, so steering likely needs a message channel (e.g. a FIFO / IPC pipe into the
+  running process, or a PI-native way to inject input). If the process model doesn't allow input
+  mid-run, the interaction half collapses to "abort and re-dispatch with corrected instruction".
+- What would invalidate this idea: if store extensions are all visibility-only (no steering) and
+  the process model rules out mid-run input, the remaining value is dashboard + reports only.
+  Also, if subagents use private pipes that block reading live state cheaply, the dashboard may
+  be constrained to what the streamer already shows.
+
+## Constraints
+- Keep it lightweight and consistent with the repo's extension conventions (no internal LLM
+  calls in the extension itself).
+- Should compose with ralph's parallel dispatch (up to 5 concurrent chores) without making the
+  TUI unusable.
+- Steering must be safe: a message is advisory input to the subagent, not a force-kill;
+  abort stays available.
+
+## Next validation step
+Two-part check before building: (1) search the pi extension store for subagent/dashboard/steering
+extensions and evaluate against this wishlist; (2) verify whether a running `pi` subagent
+process accepts input mid-run (checked against how the subagent extension spawns processes and
+whether PI exposes any IPC/input channel) — this decides whether steering is scoped in.
+
+## Notes
+Recorded 2026-08-25. Interview decisions: visibility = both live dashboard AND persisted
+per-run reports; interaction = mid-run steering (not approve-gates, not pause/resume); path =
+evaluate store first, fall back to expanding the bundled `subagent` extension. Complements
+`unified-ci-pipeline` (pipeline visibility) and the ralph parallelism work in this repo.

package/docs/ideas/task-session-context.md

@@ -0,0 +1,89 @@
+# Idea: task-session-context
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-08-25
+
+## Problem
+Coding sessions accumulate context turn by turn: every question, every tool call, every
+tangent stays in the window until it's manually compacted or the session is restarted. Keeping
+the context small and relevant is an active management burden — the author has to notice the
+bloat, decide what matters, and intervene. Long conversations either burn tokens or require
+frequent manual resets that drop useful memory.
+
+## Who benefits
+The author, daily. Removing context management from the loop means sessions stay small and
+focused no matter how long the overall thread runs. It also produces a durable, reviewable log
+of work: each task's bead + summary memory is an audit trail of what was done and why.
+
+## Proposed outcome
+A workflow organised around **tasks** instead of sessions. Whenever the user does something
+discrete — asks a new question, records an idea, fleshes out a piece of work — it **begins a
+task**:
+
+1. **Task = blank session with memory context.** The task starts a fresh, self-contained
+   session. It does NOT get every turn and tool call of the parent conversation — only access
+   to the accumulated **memories** of what came before (a summary/compressed view, not the raw
+   transcript).
+2. **Self-contained execution.** The task works on its own: it takes action, and **records
+   memories along the way** as it produces outcomes.
+3. **Single summary memory on completion.** The last thing a task does is write one summary
+   memory capturing its outcome. These memories are additive — the running memory store grows as
+   tasks complete.
+4. **Fresh session continues the thread.** Once the task completes, a new session starts with
+   access to the memories — including the new summary — so to the user it feels like one
+   continuous thread, but each underlying session stays small.
+
+**Ties into beads (bd):** "the completion of a bead is the completion of a task". A bead becomes
+the log of work completed: the task's outcome is recorded on/with the bead, the fresh session
+starts, and the bead is accompanied by **referential memory** (a pointer/memory entry that links
+the outcome to the bead). So the bead doubles as the durable record AND the context-boundary
+marker: starting a bead is the trigger for task-session separation.
+
+**The bead is the artifact — the session is disposable.** Once a task is complete, the whole
+conversation context is no longer needed; the bead is the artifact. The current conversation is
+the live example: recording this idea is a task, and when it's done the transcript of every turn
+and tool call can be discarded — what remains is the record plus its summary/referential memory.
+This is the load-bearing philosophical point of the idea: sessions exist to serve tasks, not the
+other way around. Context is an implementation detail of a single task; the bead is the durable
+unit of history.
+
+The mechanism likely needs: a memory store (per-project, e.g. under `~/.pi/agent-cortex/` or a
+records convention), a session-scoping rule (what memories a fresh task session is seeded with),
+the summary-writing step, and the bead ↔ memory linkage.
+
+## Validity check
+- Evidence we already have: the repo already runs on beads as the unit of work (bd), and the
+  ralph pipeline already treats beads as self-contained executable units — so task-per-bead
+  separation is a natural extension of an existing pattern. Existing ideas
+  (`record-ideas-as-beads`, `pi-task-memory`, `extension-manifests`) all push in the direction of
+  making agent-cortex the declared, memory-rich source of truth.
+- Riskiest assumption: that a fresh session seeded with *memories only* (no raw transcript) is
+  sufficient context for a task — the compression of a conversation into memories must not lose
+  the specifics a task needs. Also: whether the harness (pi/Claude) even supports programmatic
+  session spawning with a seed context cleanly enough for this to feel seamless.
+- What would invalidate this idea: if memory-as-context proves lossy in a way that keeps tasks
+  mis-executing (then the blank-session model needs the raw transcript after all, defeating the
+  point); or if the session boundary machinery (start/stop/spawn with seed) fights the harness.
+
+## Constraints
+- Sessions must stay small — this is the whole point; memory is the interface, not the transcript.
+- Memories are additive and durable; the summary memory is the handoff contract between tasks.
+- The bead is the work log AND the context boundary: no task completion without its summary
+  memory and bead record.
+- Must not break the existing task loops (ralph pipeline stages, HITL handoffs) — it should
+  compose with them, not fork them.
+
+## Next validation step
+Flesh-out session (proposed by the author): nail down the trigger rules (what counts as "begin a
+task"), the memory store schema and what a "memory" is vs a summary, how a fresh session gets
+seeded, and how the bead carries the summary + referential memory. Then a spike: one task
+completing with summary → fresh session seeded → verify the thread feels continuous.
+
+## Notes
+Recorded 2026-08-25. The author explicitly wants to flesh this out later — this record captures
+the working concept. It connects several existing ideas: `record-ideas-as-beads` (beads as the
+unit of everything), `pi-task-memory` (memory as a first-class mechanism), and
+`subagent-visibility` (visibility into what task sessions do).

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/research/skill-design-research.md

@@ -58,9 +58,9 @@ Both repos follow the same two-part format: capability sentence + `"Use when..."
 > "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says 'diagnose this' / 'debug this', reports a bug, says something is broken/throwing/failing, or describes a performance regression."
 
 **agent-cortex example** (vaguer triggers):
-> "Create a bead, classify it, and if AFK expand it into pipeline stage child beads plus a HITL PR gate task. Use when creating a new task that should be tracked and moved through implementation and human review gates."
+> "Create a task bead, classify it as AFK or HITL, and if AFK expand it into pipeline stage chores plus a HITL PR gate. Use when starting tracked work with implementation and review gates — 'create a task for this', 'track this end-to-end', or 'get this into the ralph pipeline'."
 
-The agent-cortex description describes internal mechanics rather than what the user is trying to accomplish.
+The agent-cortex description leads with internal mechanics ("task bead", "AFK", "HITL") rather than what the user is trying to accomplish — the quoted triggers were added in a later refactor, but the jargon remains.
 
 ---
 
@@ -180,7 +180,7 @@ Move to Phase 2 only when both boxes are checked.
 
 **Evidence**: Anthropic Building Effective Agents: *"Think of this as writing a great docstring for a junior developer on your team."* For agents, descriptions are the only routing signal. FLAN (Wei et al., ICLR 2022) showed instruction-tuned models generalise from natural language task descriptions — use the vocabulary a user would *actually speak*, not internal system jargon. Anthropic tool use note: `"Use when"` language *actively counteracts* the model's default tendency to solve problems without invoking tools.
 
-**Current state**: some agent-cortex descriptions describe internal mechanics rather than user intent. E.g., `create-task`: *"Use when creating a new task that should be tracked and moved through implementation and human review gates"* — references internal workflow terms a user wouldn't say.
+**Current state**: some agent-cortex descriptions describe internal mechanics rather than user intent. E.g., `create-task`: *"Use when starting tracked work with implementation and review gates — 'create a task for this', 'track this end-to-end', or 'get this into the ralph pipeline'."* — rewritten to add quoted user triggers (per this rec), though it still leans on internal jargon like "ralph pipeline" a user wouldn't say.
 
 **Recommendation**: Rewrite descriptions to lead with user-vocabulary triggers. Include 2–4 quoted phrases or scenario patterns a user might say:
 
@@ -219,7 +219,7 @@ argument-hint: "Describe the bug or paste the error message"
 
 ### Rec 10 — Fix prd-to-epics Missing SKILL.md
 
-**Current state**: `skills/prd-to-epics/` directory exists in the repo but has no `SKILL.md`. It cannot be invoked.
+**Current state**: Resolved in #16 — the broken `skills/prd-to-epics/` directory was removed; epic/task decomposition is consolidated into the `prd-to-tasks` skill (see CHANGELOG 1.0.0).
 
 **Recommendation**: Either write the missing `SKILL.md` or remove the directory. This is a straightforward bug.
 

package/docs/research/skill-improvements-analysis.md

@@ -110,7 +110,7 @@ REFERENCE.md" — keeping SKILL.md as the primary working document rather than g
 | Verification checklists | Planned |
 | Concrete examples | Planned |
 | Reconsider 100-line limit | Done (raised to 150) |
-| ASCII workflow diagrams | Not yet |
+| ASCII workflow diagrams | Done (ASCII-only style guide in skill-anatomy.md) |
 | Cross-references between skills | Planned |
 | Consistent skeleton template | Partially adopted |
 

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:
@@ -49,6 +57,23 @@ For each optional section, define **what it is**, include an **example snippet**
 | `Phase-gate checklists` | Mid-workflow gates that must pass before proceeding | `- [ ] Phase 1 complete: baseline tests captured.` | Multi-phase workflows (3+ distinct phases) | Linear single-phase tasks |
 | `Cross-skill references` | Explicit delegation to another skill for a real sub-task | `- Run \\`review-security\\` before committing.` | Another skill owns a sub-domain better than restating it | Self-contained skills |
 | `Examples` | Full worked sample of expected outcome/output | `- Input: ... Output: ...` | Any non-trivial output contract | Trivially self-evident skills |
+| `Workflow diagrams` | Inline ASCII diagram showing step flow and decision points | Fenced block of `[Box]`, `|`, `-`, `>`, `v` arrows, e.g. `[Start] --> [Validate] --> [Run]` | Multi-step or branching workflows where a glanceable flow improves comprehension | Simple linear workflows already clear from numbered steps |
+
+## Workflow diagram style guide
+
+When a skill includes a workflow diagram, follow these rules so it renders
+reliably in any CLI:
+
+- **ASCII only** — never Mermaid, images, or unicode box-drawing characters.
+  Keep to `|`, `-`, `>`, `+`, and `v`.
+- **Fenced block** — wrap the diagram in a fenced code block so monospace is
+  preserved.
+- **At most 80 characters per line** — narrow enough for terminal-width readers.
+- **Short box labels** — imperative verbs or nouns (e.g. `[Validate scope]`),
+  never full sentences.
+- **Read left-to-right, top-down** — prefer one branch level over dense joins.
+- **Mirror the numbered workflow** — the diagram is a glanceable summary of the
+  `## Workflow` steps, never a source of truth that contradicts them.
 
 ## Section ordering
 
@@ -81,8 +106,10 @@ 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.
+- [ ] Workflow diagrams (if present) are ASCII-only and follow the workflow diagram style guide.
 - [ ] Verification checklist contains concrete, machine-checkable items.
 - [ ] Supporting docs are split by purpose when `SKILL.md` would exceed ~150 lines.
 
@@ -110,8 +137,26 @@ disable-model-invocation: false
 ## Workflow
 
 1. Gather required context and validate scope boundaries.
-2. Execute deterministic steps in order, recording key decisions.
-3. Produce the required output artifact or terminal response.
+2. Reject early with the reason when validation fails; otherwise continue.
+3. Execute deterministic steps in order, recording key decisions.
+4. Produce the required output artifact or terminal response.
+
+Workflow at a glance (include only when the flow branches):
+
+              [Trigger]
+                  |
+                  v
+          [Gather context]
+                  |
+                  v
+          [Validate scope] --(invalid)--> [Reject early]
+                  |
+              (valid)
+                  v
+      [Run deterministic steps]
+                  |
+                  v
+      [Produce output artifact]
 
 ## Red Flags