@jaybeeuu/agent-cortex 2.7.0 → 2.9.0

package/skills/workflow/using-agent-skills/SKILL.md

@@ -26,9 +26,15 @@ Task arrives
     ├── Spec approved, need tickets? ───────→ spec-to-tickets
     ├── Need a single task tracked? ────────→ create-task
     ├── Need to plan a feature end-to-end? ─→ plan
+    ├── Deciding what to work on next? ─────→ guppi
+    │   └── Strategy stale or missing? ────→ prioritise-work
+    ├── Scoring or banding one bead? ──────→ score-bead
+    ├── Ranking the HITL decision queue? ──→ hitl-queue
+    ├── Collaborating on HITL work? ────────→ guppi
     ├── Running beads / task execution? ────→ ralph
     │   └── Single stage? ─────────────────→ run-pipeline-stage
-    ├── Implementing code? ────────────────→ tdd
+    ├── Implementing a task? ──────────────→ implement-task
+    │   ├── Proving one behaviour? ────────→ tdd
     │   ├── Designing an interface? ───────→ design-an-interface
     │   └── Need style conventions? ───────→ style-code
     ├── Reviewing code? ───────────────────→ style-code
@@ -42,7 +48,7 @@ Task arrives
     ├── Evaluating architecture? ──────────→ technical-direction
     ├── Finding refactor opportunities? ───→ improve-codebase-architecture
     ├── Need task tracking? ───────────────→ bd-tool
-    ├── Need human review / HITL? ─────────→ hitl-collab
+    ├── Need a human handoff document? ────→ hitl-collab
     ├── Need a handoff doc? ───────────────→ handoff
     ├── Writing a ticket for Jira? ────────→ write-a-ticket
     ├── Creating a new skill? ─────────────→ write-a-skill
@@ -97,12 +103,19 @@ For a complete feature, the typical skill sequence is:
 4. `prd-to-tasks` → Break into verifiable chunks
 5. `plan` → Orchestrate the full flow end-to-end
 6. `ralph` → Execute all pending beads
-7. `tdd` → Prove each slice works
-8. `style-code` → Review before merge
-9. `review-security` → Check for secrets
-10. `git-workflow` → Clean commit history
-
-Not every task needs every skill. A bug fix might only need: `tdd` → `style-code` → `review-security`.
+7. `implement-task` → Own the criteria, the scope, and the proof
+8. `tdd` → Prove each slice works
+9. `style-code` → Review before merge
+10. `review-security` → Check for secrets
+11. `git-workflow` → Clean commit history
+
+Not every task needs every skill. A bug fix might only need: `implement-task` → `tdd` →
+`style-code` → `review-security`.
+
+Routing boundary: `implement-task` owns the request — its criteria, its scope, its evidence. `tdd`
+owns the loop inside one criterion, and answers "how do I prove this behaviour" once the task is
+already understood. A request with acceptance criteria to satisfy starts at `implement-task`; a
+bare "write a test for X" still starts at `tdd`.
 
 ## Red Flags
 

package/token-map.README.md

@@ -51,6 +51,22 @@ rather than inventing a dotted form:
   `ask_user`) — and `task` / `read_agent` / `wait_for_agents` subagent tools, the last three
   supplied by this repo's own `extensions/subagent` rather than by pi; `skill` maps
   to `read` (skills load by reading the listed SKILL.md path).
+  Two rows carry session-to-session messaging rather than a built-in tool: `peer_send` and
+  `peer_list`. On claude they are Claude Code's own `SendMessage` and `ListAgents`; on pi they
+  are the `pi-peer` package's tools, which the consuming repository installs itself. A row maps
+  a **name, never a protocol**: the message kinds and the acknowledgement rule layered above
+  the transport are harness-invariant text, so only the transport forks and the protocol stays
+  in one authored copy.
+  One row names who waits for a CI run that outlives a check's own wait window:
+  `post_merge_watch`. Its two values differ in kind — this package's own `post-merge-watch`
+  extension on pi, Claude Code's built-in `ScheduleWakeup` tool on claude — so the prose around
+  it describes only what both do (the session resumes, the check runs again) and never a call
+  shape.
+  Both values are a **self-paced re-prompt, not an event subscription**: the session asks to be
+  woken and looks again on waking. Claude Code also supplies an event-watching `Monitor` tool,
+  but that tool is gated behind a feature flag that defaults off, so a portable skill may not
+  depend on it. Naming the re-prompt is what holds on every session; the playbook's prose
+  fallback covers the session where even that is absent.
 - **`paths`** — `plugin_root`, `agents_dir`, `skills_dir`, and `skill_anatomy`. These are the
   install-time variables that differ per harness. `plugin_root` is the anchor; the others
   resolve relative to it (`{base, relative}` specs) so a harness only overrides the single
@@ -102,6 +118,17 @@ Unknown (unmapped) tokens are a **hard error**, not a null — a silently-passed
 token is exactly the bug the map exists to prevent, and mirrors the build script's
 `unknown tool "x"` throw.
 
+The peer channel is the worked example. `peer_get` and `peer_await` are `pi-peer` tools and
+Claude Code has no equivalent, so they get no row and a shared sentence never names them:
+substituting one would drop the token and leave the sentence that named it short of a name.
+Their documentation stays inside a section labelled for one harness, where nothing is
+substituted — see the `pi-peer` runbook in `skills/workflow/ralph/REFERENCE.md`.
+
+`post_merge_watch` is deliberately **not** null on either side: a null would drop the token in the
+pi render or the claude render and leave the sentence that named the mechanism short of one. The
+fallback for a session that has no watcher is therefore written as prose in the same section, so
+it survives both renders unchanged — see `skills/workflow/run-pipeline-stage/playbooks/post-merge.md`.
+
 The pi install-time installer (`bin/installers/pi.mjs`) follows the strict contract above.
 One consumer deviates deliberately: the pi `agent-modes` extension reads the map at
 **runtime** (not install time) to compose agent prompts from the composable agents

package/token-map.json

@@ -25,7 +25,13 @@
     "skill": { "claude": "Skill", "pi": "read" },
     "task": { "claude": "Task", "pi": "task" },
     "read_agent": { "claude": null, "pi": "read_agent" },
-    "wait_for_agents": { "claude": null, "pi": "wait_for_agents" }
+    "wait_for_agents": { "claude": null, "pi": "wait_for_agents" },
+    "peer_send": { "claude": "SendMessage", "pi": "peer_send" },
+    "peer_list": { "claude": "ListAgents", "pi": "peer_list" },
+    "post_merge_watch": { "claude": "ScheduleWakeup", "pi": "post-merge-watch" },
+    "interrupt_rewind": { "claude": "/rewind", "pi": "interrupt_resume" },
+    "interrupt_checkpoint": { "claude": null, "pi": "interrupt_checkpoint" },
+    "interrupt_resume": { "claude": null, "pi": "interrupt_resume" }
   },
   "paths": {
     "plugin_root": {
@@ -62,8 +68,8 @@
       "claude": "event-driven"
     },
     "notes": {
-      "pi": "Blocking wait: wait_for_agents returns as soon as one worker finishes, carrying its result inline. No timer to start, nothing to kill — there is no poll loop.",
-      "claude": "Event-driven: the harness re-invokes ralph when a worker completes and delivers the result inline. No poll timer, no sleep, no log flush."
+      "pi": "Blocking wait: wait_for_agents returns as soon as one worker finishes, carrying its result inline. No timer to start, nothing to kill — there is no poll loop. Progress is read from the bead trail the worker writes (`bd show`, `bd provenance log`).",
+      "claude": "Event-driven: the harness re-invokes ralph when a worker completes and delivers the result inline. No poll timer and no sleep. Progress is read from the bead trail the worker writes (`bd show`, `bd provenance log`), never from a file ralph tails."
     }
   },
   "notes": {
@@ -75,7 +81,13 @@
       "skill": "Claude (Skill) exposes skills as a tool. pi has no dedicated skill tool — skills are surfaced in the always-present 'Available skills' context block and loaded by reading the listed SKILL.md path ({{PATH:<skill>/SKILL.md}}). The pi mapping is read, the tool used to load a skill's file; a dedicated skill tool is a follow-on design candidate if prompting proves insufficient.",
       "read_agent": "Claude's Task returns results inline — there is no separate read step, so read_agent drops on claude (null). pi exposes read_agent as a fallback to wait_for_agents.",
       "task": "Claude provides a subagent tool natively. On pi it is supplied by this repo's own extensions/subagent extension (which also registers read_agent and wait_for_agents), not by pi itself — a pi session started before that extension was installed has no dispatch tool at all. Skills must therefore stop and report a missing subagent tool rather than improvising a backgrounded CLI run, which has no completion signal.",
-      "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Claude's Task delivers results inline with no wait step — null on claude."
+      "wait_for_agents": "PI-only blocking wait over background subagent runs (the task tool): returns the results of completed agents and STILL RUNNING for the rest. Claude's Task delivers results inline with no wait step — null on claude.",
+      "peer_send": "Session-to-session message send. pi takes it from the published pi-peer package (an ordinary package the consuming repository installs itself, never a dependency of this one). Claude Code has it built in and its docs name it there. Both address a peer by the name or address their own list reports, and neither send is proof of receipt. Only sends and discovery are tokenised: pi-peer's peer_get and peer_await have no Claude Code equivalent, and a null claude mapping drops the token and leaves the sentence that named it broken, so harness-varying prose must never name them — such passages stay inside a harness-labelled runbook.",
+      "peer_list": "Peer discovery: the peers that can receive a message, and the address each is reached by. pi's is the pi-peer package's tool. Claude Code's built-in equivalent is ListAgents (an earlier binary named it ListPeers), which also reports reachability and so doubles as the peer-state read.",
+      "post_merge_watch": "Who waits for a CI run that outlives the check's own wait window. The row maps a name, not a protocol: the verdicts and the escalation rule layered above it are harness-invariant text, so only the mechanism is tokenised. pi's name is this package's own post-merge-watch extension, which re-runs the check on a timer and wakes an idle session with the verdict. Claude Code's is its built-in ScheduleWakeup tool, which schedules the session's own resumption so it can re-run the check. The values differ in kind — an extension on pi, a tool on claude — because that is what each harness supplies; the surrounding prose therefore describes only what both do (the session resumes, the check runs again, the verdict table is unchanged) and never a call shape.",
+      "interrupt_rewind": "How an interrupted task returns to its checkpoint and leaves the interruption behind. Consumed by agents/guppi/agent.md's interrupt protocol, which names the row once and states the checkpoint, record, rewind and resume steps around it. The row maps a name, not a protocol: pi's name is this package's own interrupt-bookmark extension's resume tool, which rewinds the session tree and has pi's summariser keep the abandoned branch under a branch summary labelled `interrupt`. Claude Code's is its built-in /rewind command, which restores the conversation and the file checkpoints taken for it. The values differ in kind — a model-callable tool on pi, a user-facing command on claude — because that is what each harness supplies. Constraints on the prose: it must describe only what both do (the session returns to the earlier point, and the interrupt's turns leave the live context) and never a call shape; it must also state who acts, because the actor forks with the kind — guppi performs the rewind where the harness gives it a tool, and hands it to the human where the harness gives it a user command; and it must not tokenise the checkpoint half, because Claude Code checkpoints on its own while pi needs a tool call, and a null claude column would drop the token and leave the sentence that named it broken. test/guppi-interrupt-render.test.mjs stages both installs to prove the fork.",
+      "interrupt_checkpoint": "The checkpoint half of the interrupt protocol, pi-only: guppi takes a resume point by calling this tool, while Claude Code checkpoints on its own with no tool to call, so the claude column is null and no claude frontmatter lists it. It is a tool-list row, not a prose row — prose must never tokenise it, for the reason recorded on interrupt_rewind.",
+      "interrupt_resume": "The resume tool as a tool-list row, for an agent that declares its tools per harness (guppi lists it in agents/guppi/pi/frontmatter.json). It is distinct from the interrupt_rewind prose row, which maps the same pi name to Claude Code's user-run /rewind: a tool list cannot carry /rewind, because the agent cannot call a user command, so the claude column is null and no claude frontmatter lists it."
     },
     "paths": {
       "pi": "plugin_root is the staged package `agent-cortex install pi` materialises at ~/.agent-cortex/pi; pi loads that directory by path and the shipped extensions resolve their own resources relative to it (agent-modes computes plugin_root from its actual install location). A checkout or symlinked install differs — installers compute plugin_root from the actual resolution and can override it (--plugin-root).",