spec: route every session through the entrypoint before it acts on the workflow - #29
Merged
Merged
Conversation
…efore citing it An agent using this skill read the three long prompts, did not recheck the entrypoint, and then told its operator that a combined step/PR document violated Structured Coding. Rule 2 and workflow section 3 say the opposite: a one-PR step is expanded in place. The rule was present, required reading, and byte-identical in the source and the distributed package. What was missing was the recheck. Two additions, both aimed at that failure rather than at restating the rule it got wrong: Rule 5 already required re-reading the PR design and execution rules after compaction. It now covers the other ways a session arrives at work it did not plan: a new session, one replacing another, or a delegated agent. The trigger is stated as a session boundary and explicitly not something to repeat every turn, because a rule that asks for the whole library on each turn is a rule agents work around. The phase table gains two sentences. The first says the table is the required resource list, so nobody assembles one from whichever prompt names a kickoff message happened to mention -- the incident's session had the prompts and only the prompts. The second says that before asserting compliance or non-compliance, read the rule being cited in this session, because the routing rules are not in the long prompts and recall from an earlier session is not evidence. The specification baseline in translations.json is updated deliberately for the changed SKILL.md; the check refused the change until it was, which is the point of pinning it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The prose rule added in the previous commit only helps a session that reads the entrypoint. This commit is the mechanism for the case that motivated the issue: a session that arrives at work it did not plan, and has no reason to know where the routing table lives. Both SessionStart branches now name the installed SKILL.md by absolute path. The unbound message already resolved the skill directory to build its activate invocation, and the recovery message already listed the two prompt paths, so this is a path the handler was computing anyway rather than new state, a new event, or a new registration. In the recovery list the entrypoint goes first, because a recovering session is precisely the one that reads the prompts and skips the routing rules the prompts do not contain. The entrypoint is resolved, not assumed: an installation missing SKILL.md omits the sentence instead of printing a path that would 404 for the agent, and the handler still returns its advisory message. Tests cover a relocated copy of the skill, so a message that hardcoded the development checkout would fail, and reverting the source fails all four assertions. references/continuity.md gains a row saying what this does and does not establish, in the same voice as the rows around it: naming the entrypoint is not delivering it, and reaching a session is not reading. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
verify_skill checked the preset runtimes and interfaces. It did not check SKILL.md, agent-workflow.md or adaptation.md, so an installation could pass doctor while missing the files the entrypoint requires -- and, after the previous commit, while a hook was naming a SKILL.md that is not there. All three are now required for every preset, which makes doctor's existing sentence about registration and runtime files cover them with no new wording. Each removed file fails the same check a removed runtime fails, and restoring them all reports healthy again. The limit of this check is unchanged and worth stating: it compares the installation against this repository's source, so it answers for a clone-based install. It is not validation of an arbitrary distributed copy, and doctor does not claim to be. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The execution kickoff named Implementation Working Rules and TEST / CI / GATE and nothing else. That is issue #25's complaint stated exactly: a session can follow the prominent prompt names, report compliance, and never expose which routing material it missed. The incident's session had those two prompts and only those two. All three kickoff messages now read the entrypoint first and load what its phase row lists, so a user with no hooks installed still hands the agent the route. promptNote says what that establishes: the phase table is the required list, so the agent need not reconstruct one from whichever names a message mentions -- and asking is still not evidence it read them. Tutorial step 4 gains the same recheck the entrypoint's rule 5 now states. The example paths move from docs/plan/ to .structured-coding/plans/, which has been the convention since v0.1.2 and which the kickoff text had not caught up with. Edited in docs/content.{en,zh-CN}.json, the generated source, rather than in the READMEs they produce -- an omission issue #25 calls out by name. Regenerated README, TUTORIAL, both HTML pages and both packages; mirror and presentation hashes refreshed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A real install probe caught this: the message claimed the entrypoint "comes first", but the path was inserted at the head of the rules list and the reported list is documents followed by rules, so it appeared fourth, after the three bound documents. The claim and the list disagreed, which is the specific kind of wrong this hook must not be -- an agent that trusts the ordering statement looks in the wrong place. The entrypoint now leads the whole list, matching both the statement and the reason for listing it at all. The test asserted only that it precedes the prompts, which is why the suite stayed green through the defect; it now asserts it precedes the bound design document too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Sep 10, 2026
Merged
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.
Closes #25.
The failure this answers
An agent read the three long prompts, did not recheck the entrypoint, and told its operator that a combined step/PR document violated Structured Coding. Rule 2 and workflow §3 say the opposite — a one-PR step is expanded in place. The rule was present, required reading, and byte-identical in source and package. What was missing was the recheck, so this PR is about routing, not about restating the rule that was misread.
Five commits
SKILL.md— rule 5 extends from "resume after compaction" to any new, replacing, or delegated session, stated as a session boundary and explicitly not a per-turn reread. The phase table gains two sentences: it is the required resource list (so nobody assembles one from whichever prompt names a kickoff mentions), and before asserting compliance, read the rule you are citing in this session.specification_sha256updated deliberately — the check refused the change until it was.continuity.py— both SessionStart branches name the installedSKILL.mdby absolute path. The unbound branch already resolved the skill directory for itsactivateline and the recovery branch already listed prompt paths, so this is a path the handler was computing anyway: no new state, event, or registration. An installation missingSKILL.mdomits the sentence rather than printing a path the agent cannot open.verify_skill—SKILL.md,agent-workflow.mdandadaptation.mdjoin the required set for every preset, sodoctorno longer passes an install that is missing the files the entrypoint requires (and, after commit 2, missing the file a hook now names).docs/content.{en,zh-CN}.json— all three copyable kickoffs read the entrypoint first, so a user with no hooks still hands the agent the route. The execution kickoff naming only the two prompts was Require complete phase-aware onboarding before agents claim workflow compliance #25's complaint verbatim. Example paths also move off the staledocs/plan/onto.structured-coding/plans/. Edited in the generated source, which Require complete phase-aware onboarding before agents claim workflow compliance #25 asks for by name.documents + rules, with the insert going intorules). An agent trusting that ordering looks in the wrong place. Fixed; the test had only asserted it preceded the prompts, so it now asserts against the bound design document too.One item declined, not silently
Issue #25 item 3 asks for a recorded onboarding READY state. Item 4 of the same issue says a checkbox or file hash cannot prove the model received the content — which rules out the mechanism item 3 needs. A helper printing READY would assert exactly what it cannot observe. The honest subset is "these files exist, are readable, and match the installed version", which is commit 3. The operator agreed to close #25 on that basis.
verify_skillcompares against this repository's source, so it answers for a clone-based install; it is not validation of an arbitrary distributed copy, anddoctordoes not claim to be.Evidence
Probed on a real
claude-codeinstall into a temporary project:<project>/.claude/skills/structured-coding/SKILL.md— the installed copy, not this checkoutdesign.md--check-hookswithSKILL.mdremoved:Installed skill lacks this preset version; restored: healthyRan 171 tests ... OK (skipped=1). All five--checkvalidations PASS. Packages at codex 23 / claude-code 22 files.Not observed: a real host delivering these messages under an authenticated turn.
SessionStartdelivery on both hosts was measured in the continuity work; what is new here is message content, exercised through the installed runtime directly.Nothing here blocks anything — a missed recheck cannot refuse work.
🤖 Generated with Claude Code