refactor(aidd-context): citations are markdown links at their point of use - #569
Merged
Conversation
R6 mandated a markdown link only for what an action cites from a reference, and said nothing about where the citation goes. Authors could legally gather every reference in a block above the first step, which is what several skills did. R6 now covers everything an action cites, reference or asset alike, and requires the citation to sit where it is used rather than in a list of its own. The rule stays scoped to actions: no router in the repo cites a path, and R8 forbids a reference from linking a sibling, so R8 now states that counterpart instead of leaving it implicit. Placement is deliberately "where it is used", not "inside a Process step": three of skill-generate's own actions cite from Output or Test at their point of use, and a stricter rule would make the contract flag its own source. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Commit 7661980 converted @-citations to markdown links in skill-generate and project-memory only. Every other skill kept the @ form, so 143 citations across six plugins pointed at files with a notation nothing reads: @path is inert in a skill body, resolving only in a CLAUDE.md import. A markdown link is what an agent follows and what the markdown-links pre-commit hook verifies, so a stale @ rots silently. 133 inline citations convert one for one, keeping their surrounding punctuation so no sentence is restructured. Eight more sat alone inside a fenced block; those are inlined into the step that consumes them, which also removes the three references upsert stacked above its Input section. Left alone: @ as a literal character in onboard's reserved-key list, the glob in cook's list action (a glob is not a citation, so it just loses the @), @claude in the orchestrator routing regex, and the npm scope in a cook recipe. rule-generate's tool-paths named a sibling reference with a @; per R8 a reference names, never links, so the @ is dropped and the backticks stay. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
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.
🎯 What & why
Two claims were reported against
aidd-context:04-skill-generate: it never says to use markdown links, and never says to cite a reference at the point it is used. The first is half true, the second is true. Fixing the contract exposed that the rule was never applied outside the two skills a July migration touched, so 143 citations across six plugins still used a notation nothing reads.🛠️ How it works
Commit 1 rewrites the contract. skill-authoring.md R6 covered only what an action cites from a reference, and said nothing about placement. It now covers assets too and requires a citation to sit where it is used, never gathered in a list of its own. R8 gains the counterpart it always implied: a reference names a sibling, never links it.
Three deliberate scope calls:
## Processstep" — which is weaker than reported, on purpose. Three of skill-generate's own actions cite from## Outputor## Testat their point of use (01-scope.md:19). The strict rule would make04-validateflag its own source.grep '](\.\|@' plugins/*/skills/*/SKILL.mdreturns nothing; the action table names slugs on purpose.naming.mdstays in backticks. A global link rule would force a reference to link a sibling, which R8 forbids.Commit 2 migrates the fleet. 7661980 converted
skill-generateandproject-memoryonly, as its own message states. Both are still at zero; nothing regressed. Everything else was never in scope and inherited nothing, becauseskill-authoring.mdis local to04-skill-generate.143 citations, three shapes:
`@../references/x.md`@pathalone in a fenced block@as a literal character@../assets/recipes/*.md@dropped, backticks kept — a glob is not a citationThe eight fenced ones were first carved out as "load mechanics". That was wrong: nothing parses them, a link inside a fence renders as literal text, and 02-upsert.md stacked three of them in a block above
## Inputwith no step naming any — the exact shape R6 now forbids.Out of scope:
@claudein the orchestrator routing regex and@playwright/mcpin a cook recipe. Neither is a citation.Full reasoning and the counts behind each decision: proposal.md.
🧪 How to verify
grep -rn '@\.\.\?/' plugins/→ empty.markdown-linkspre-commit hook passes:0 broken in 561 files. The two pre-existing failures inplan-template.mdare scaffold placeholders in an untouched asset.skill-authoring.mdstays local to04-skill-generate. The other generators (05-rule-generate,06-agent-generate,07-command-generate,08-hook-generate) each carry their own*-authoring.mdand inherit nothing, so R6 does not reach what they emit. This conversion holds until one of them generates the next skill. Propagating the contract is a separate subject, not folded in here.✅ I certify