@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

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

@@ -28,7 +28,8 @@ Task arrives
     ├── Need to plan a feature end-to-end? ─→ plan
     ├── 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
@@ -97,12 +98,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,10 +51,36 @@ 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).
-- **`paths`** — `plugin_root`, `agents_dir`, and `skills_dir`. These are the install-time
-  variables that differ per harness. `plugin_root` is the anchor; the other two resolve
-  relative to it (`{base, relative}` specs) so a harness only overrides the single root it
-  actually installs into.
+  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
+  root it actually installs into.
+  A path entry whose relative path sits under `docs/` names a document the install ships:
+  both installers copy it from the package root into the staged tree at that relative path
+  (`scripts/lib/docs.mjs`), so a skill can read it on a machine with no checkout. One copy
+  per install serves every skill that references it, and the token map decides both the
+  location and the shipment — `skill_anatomy` is read by both `write-a-skill` and
+  `refactor-skill`. The repo's `docs/` stays the single source of truth; the staged file is
+  a verbatim copy, never a second authored version.
+  A second shipped doc is declared twice: the `paths` entry sets its install location, and
+  `package.json` `files` must list the same path. The test stages from the checkout, so only
+  the `files` whitelist catches a doc that the published package omits.
   Claude's `plugin_root` stays the `${CLAUDE_PLUGIN_ROOT}` env-var token, never a literal
   `~/.agent-cortex/claude`: Claude Code **copies** marketplace-installed plugins — including
   local directory sources like `~/.agent-cortex/claude` — into its own cache, so only the
@@ -92,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,10 @@
     "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" }
   },
   "paths": {
     "plugin_root": {
@@ -39,6 +42,10 @@
     "skills_dir": {
       "claude": { "base": "plugin_root", "relative": "skills" },
       "pi": { "base": "plugin_root", "relative": "skills" }
+    },
+    "skill_anatomy": {
+      "claude": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" },
+      "pi": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" }
     }
   },
   "agents": {
@@ -58,8 +65,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": {
@@ -71,11 +78,15 @@
       "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."
     },
     "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).",
-      "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
+      "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim.",
+      "skill_anatomy": "A path entry whose relative path sits under docs/ names a document the install ships: both installers copy it from the package root into the staged tree at that relative path (scripts/lib/docs.mjs), so a skill can read it on a machine with no checkout. One copy per install serves every skill that references it — write-a-skill and refactor-skill both do. The repo's docs/ stays the single source of truth; the staged copy is a verbatim copy, never a second authored version."
     },
     "agents": {
       "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>."