@jaybeeuu/agent-cortex 2.8.0 → 2.10.0

package/token-map.README.md

@@ -87,6 +87,15 @@ rather than inventing a dotted form:
   runtime env var (expanded per context by Claude Code) points at wherever the plugin
   actually runs from. A literal home path in substituted files would break under
   cache-copy, so the installer passes the env form through verbatim.
+- **`layouts`** — the tree each installer stages a resource into, for the resources whose
+  shape differs per harness. Only `skills` differs: the repository nests every skill one group
+  deep (`skills/<group>/<name>/`), and `bin/installers/pi.mjs` preserves that, while Claude
+  Code's plugin scan discovers `skills/<name>/SKILL.md` directly under `skills/`, so
+  `bin/installers/claude.mjs` copies every skill flat. A `{{PATH:skills/…}}` row is authored
+  against the repository tree; resolution reads the harness's row here and drops the group
+  segment when the harness stages skills flat, so the row names a file the install contains.
+  The row is a harness fact, not a repository one, which is why it lives here rather than in
+  the resolver: a harness that stages skills differently changes this table, not the code.
 - **`agents`** — the `agent-cortex:` name-prefix convention per harness (claude strips the
   prefix during conversion). Agent names themselves do not get per-row mappings because
   the prefix rule covers all of them — every agent is composed from `agents/<name>/` for
@@ -147,13 +156,16 @@ The full contract is embedded in `token-map.json` under `contract`. In summary,
 3. For `TOOL`: look up the canonical key, replace with the harness name; null → drop/omit;
    unknown → throw.
 4. For `PATH`: named key → resolve from `paths`; anything else → resolve relative to
-   `plugin_root`; `${ENV_VAR}` values pass through verbatim for runtime expansion.
+   `plugin_root`, after mapping a `skills/…` row onto the harness's staged shape from
+   `layouts`; `${ENV_VAR}` values pass through verbatim for runtime expansion.
 5. Reject a map `version` they do not implement.
 
 ## Authoring guidance
 
 - Write tokens with the **canonical authoring names**: `Use {{TOOL:task}} to spawn
-  subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`.
+  subagents`, `Read {{PATH:skills/workflow/plan/SKILL.md}}`. Write a skill path row in this
+  repository's grouped form, `skills/<group>/<name>/<file>`; each install maps it onto the
+  shape it stages (see `layouts`), so one authored row names a real file on both harnesses.
 - Never embed a harness-specific name in the canonical sources (`agents/<name>/agent.md`,
   `skills/**/SKILL.md`) — that defeats the map. The materialised Claude plugin
   (`~/.agent-cortex/claude`), the generated `agents/*.agent.md` files, and any installed

package/token-map.json

@@ -8,7 +8,7 @@
     "decision": "Adopt the {{TOOL:name}} / {{PATH:name}} / {{SECTION:name}} grammar already standardised by ADR #63 (agents/README.md) rather than a dotted {{tool.name}} form. The uppercase type prefix disambiguates token kinds at a glance, keeps tool/path/section names in one namespace collision-free, and matches the token grammar skills are already written against.",
     "types": {
       "TOOL": "{{TOOL:<canonical tool key>}} — replaced at install time with the bound harness's tool name (see tools).",
-      "PATH": "{{PATH:<path key or relative path>}} — replaced at install time with the harness-resolved path (see paths).",
+      "PATH": "{{PATH:<path key or relative path>}} — replaced at install time with the harness-resolved path (see paths; a relative arg under skills/ is mapped onto the harness's staged shape first — see layouts).",
       "SECTION": "{{SECTION:<name>}} — replaced by the agent composer with <harness>/<name>.md section content. Not a global substitution; out of scope for token-map.json (see contract)."
     }
   },
@@ -28,7 +28,10 @@
     "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" }
+    "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": {
@@ -48,6 +51,13 @@
       "pi": { "base": "plugin_root", "relative": "docs/skills/skill-anatomy.md" }
     }
   },
+  "layouts": {
+    "description": "The tree each installer stages a resource into. `{{PATH:...}}` resolution reads it: a row is authored against the repository tree, so a harness that stages a resource in a different shape needs the row mapped onto its own. Only `skills` differs — Claude Code's plugin scan discovers `skills/<name>/SKILL.md` directly under `skills/`, so bin/installers/claude.mjs copies every skill flat and the group segment an authored row carries is dropped; bin/installers/pi.mjs preserves the repository grouping, so the row resolves as written.",
+    "skills": {
+      "claude": "flat",
+      "pi": "grouped"
+    }
+  },
   "agents": {
     "prefix": {
       "claude": "",
@@ -81,7 +91,10 @@
       "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."
+      "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).",
@@ -104,6 +117,7 @@
       "TOOL unknown: a {{TOOL:<key>}} with no entry in tools is a hard error — the map must be extended. This mirrors the generators (bin/installers/claude.mjs, bin/installers/pi.mjs), which throw on unknown tools.",
       "PATH named key: replace {{PATH:<key>}} with the resolved value of paths.<key>.<harness>.",
       "PATH relative: replace {{PATH:<relative>}} with plugin_root + '/' + <relative> (e.g. {{PATH:skills/workflow/plan/SKILL.md}}).",
+      "PATH relative skill: a relative arg whose first segment is `skills` is authored against the repository tree, which nests every skill at skills/<group>/<name>/<file>. Map it onto the harness's staged shape from layouts.skills.<harness>: `grouped` keeps it as written, `flat` drops the group segment (skills/<name>/<file>) because that installer copies skills flat. An arg with fewer than three segments is a hard error — no install has a skill one level under skills/.",
       "PATH resolution: a value may be a literal string, an ${ENV_VAR} token, or a {base, relative} spec. Resolve {base, relative} by joining relative onto the resolved base. Leave ${ENV_VAR} values verbatim — the harness expands them at runtime (claude's ${CLAUDE_PLUGIN_ROOT}).",
       "PATH unknown base: a {base, relative} spec whose base is not a key in paths is a hard error.",
       "SECTION: {{SECTION:<name>}} is resolved by the agent composer from <agents_dir>/<harness>/<name>.md; token-map.json does not substitute it. Installers must leave SECTION tokens untouched for the composer.",