docs(guide): name the file behind each entrypoint - #23
Merged
Conversation
A reader could not tell which of the nine entrypoints is a command file and which is a skill without listing two directories. `Commands at a glance` now carries a `Handled by` column naming the implementing file for each one, so the mapping lives beside the entrypoint rather than in the reader's head. Two corrections came out of checking that mapping against the source: - The paragraph under `How the pieces connect` said "The other entrypoints call no agent: /toque:troubleshoot writes logs". Read literally that is wrong. `skills/troubleshoot/phases/multi-agent-mode.md:7` spawns up to four specialist subagents, and `skills/plan/stages/stage-1-plan.md:108-111` deploys three research tracks in parallel. The claim was only ever true of the two agents with a file in `agents/`, and it now says so. - `The 2 agents` gains that distinction explicitly: those two are the only agents with a file of their own, only /toque:plan, /toque:quick-plan and /toque:quick-audit invoke them, and inline subagents are documented where they are used. A separate `documentation/the-moving-parts.md` page was drafted for this and then dropped. GUIDE already owned every section it had, and the visuals audit had assigned that explanation here — `docs/plans/2026-09-04-documentation-visuals/audit.md:74` routes "How do commands, skills, agents, hooks, and scripts connect?" to this file, and `:98` requires one home per explanation. Only the entrypoint mapping was missing, so only the entrypoint mapping was added. Verified: every path in the new column exists; `help.md:89-92` lists the two agents in a reference table but does not invoke them; `plan-status.md`, `plan-export.md`, `quick-cleanup.md` and the documentation skill reference neither. `bash tests/run-all.sh` at 72935f2 with this change staged: 8/8 layers, 0 failed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tpozfu6ca1bx5YmaLY2TgE
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. One commit, one file:
plugins/toque/GUIDE.md.What changes
Every entrypoint now names the file that handles it. The entrypoint table gained a "Handled by" column, so
/toque:quick-auditresolves visibly tocommands/quick-audit.mdand/toque:plantoskills/plan/SKILL.mdrather than leaving the reader to guess which of the two kinds it is. Paths are relative toplugins/toque/.A claim about the agents is corrected. The guide said the other entrypoints "call no agent".
/toque:troubleshootcan escalate to as many as four specialists, so that was wrong as written. It now says no other entrypoint invokes the two agents inagents/, and a new paragraph draws the distinction the old wording blurred: an instruction file may define subagents inline with no file inagents/— Stage 1 of/toque:planruns up to three research tracks,/toque:troubleshootup to four specialists — and points at where each is described.Why it matters
The guide is the reference someone reads to find out which file to open. Naming the handler turns a lookup into a fact on the page, and the agents correction removes a statement that a reader could check and find false.
Verification
Full suite passes 8 of 8 layers locally. No instruction, script, or test behaviour changes — this is prose in a reference document.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Fx5CCdiv5HdUrakHhCfMAq