From 59c33799c5bb8f0e551adceb0e36a129ba22a27c Mon Sep 17 00:00:00 2001 From: TGPSKI Date: Sun, 9 Aug 2026 02:24:54 -0700 Subject: [PATCH] describe phase file references as backticked relative paths SKILL.md:148 required the Phase Files table to use `@` references, and CONTRIBUTING.md:72 told reviewers to check that `@`-references resolve. No template or example in the repo does this -- templates/multi-phase-router/ router.md:83-88 and all four examples list phases as backticked relative paths under references/. `@path` is a CLAUDE.md-family import mechanism that expands files into context at launch, not a markdown convention. SKILL.md is not a memory file, so `@` there is inert text. Following the spec literally would produce routers that either disagree with the template, or -- if the router text reaches a CLAUDE.md through an @AGENTS.md import -- load every phase file at launch, defeating the progressive disclosure the router pattern exists to provide. - SKILL.md:148 now states the convention the templates already use - SKILL.md Router Rules gains a rule that the router names the phase file and instructs the agent to read it; the read is the load - CONTRIBUTING.md:72 checks internal links, not `@`-references - README.md:67 notes that `@onboard-chart/SKILL.md` is a prompt mention, a different mechanism from a router's phase file references No template or example changed -- they were already correct. Closes #6 --- CONTRIBUTING.md | 2 +- README.md | 2 +- SKILL.md | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10f964f..c5dadde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ Every PR must: ### Running Validation -There is no build step. Review your markdown renders correctly and all internal `@`-references resolve to existing files. +There is no build step. Review your markdown renders correctly and all internal links resolve to existing files. ### License diff --git a/README.md b/README.md index 72fa2cb..529aa9f 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ ln -s ../../.agents/skills/onboard-chart .cursor/skills/onboard-chart ln -s ../../.agents/skills/onboard-chart .claude/skills/onboard-chart ``` -Invoke the workflow: `@onboard-chart/SKILL.md`. Come back next week, invoke the same file, and it picks up where you left off. +Invoke the workflow: `@onboard-chart/SKILL.md`. This is a prompt mention that attaches the router to the conversation -- distinct from how a router references its phase files, which is by backticked relative path. Come back next week, invoke the same file, and it picks up where you left off. --- diff --git a/SKILL.md b/SKILL.md index 738de93..91881b0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -137,6 +137,7 @@ The router: - Collects ONE key identifier (service name, account alias, hostname, etc.) - Detects progress by inspecting the repo (which files exist = which phases done) - Routes to the correct phase +- Names the phase file by relative path and instructs the agent to read it. The read is the load; a bare path is not a directive to load anything. - **Never generates files itself** The router MUST include: @@ -145,7 +146,7 @@ The router MUST include: 3. **Progress Detection table** -- maps file existence to phase completion 4. **Determine Phase table** -- maps detected state to recommended action 5. **Route to Phase** -- presents options to the user -6. **Phase Files table** -- lists all phases with `@` references +6. **Phase Files table** -- lists all phases as backticked relative paths, one level deep from the router ### Phase Module Rules