From 04001bd110177e677c955a459d11371765818366 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 07:35:02 +0200 Subject: [PATCH 1/2] refactor(aidd-context): citations are links at their point of use 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 --- .../proposal.md | 217 ++++++++++++++++++ .../references/skill-authoring.md | 4 +- 2 files changed, 219 insertions(+), 2 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_31_skill-citation-rules/proposal.md diff --git a/aidd_docs/tasks/2026_07/2026_07_31_skill-citation-rules/proposal.md b/aidd_docs/tasks/2026_07/2026_07_31_skill-citation-rules/proposal.md new file mode 100644 index 000000000..ef91276b0 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_31_skill-citation-rules/proposal.md @@ -0,0 +1,217 @@ +# Citation rules for generated skills + +Branch `docs/skill-generate-citation-rules`, worktree `.claude/worktrees/skill-citations`, based on `origin/next` (`c2c2c942`). + +## What was reported + +`04-skill-generate` does not tell the author to use markdown links, and does not +tell the author to cite references inside the process steps rather than outside. + +## What the code says + +**Claim 1 is half true.** The rule exists, but only one, and only for one edge: + +`plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md:10` + +> **R6.** One fact, one home. An action acts within a router rule and cites a +> shared reference by a markdown link `[name](path)`, never restating either. + +It covers action to reference only. Nothing covers router to action, action to +asset, or a reference citing an asset. Neither template mentions a link, so an +author filling `assets/action-template.md` never meets R6 unless they open the +contract, which `actions/03-write.md:19` does route them through. + +**Claim 2 is true.** No rule states where a citation goes. R6 says "cites", +never "where". `assets/action-template.md` has no slot for it. The only signal +is example: `actions/01-scope.md:13`, `03-write.md:16`, `04-validate.md:15` all +cite inside a step. Convention by imitation, never written down. + +## What the fleet says + +The contract is local to `04-skill-generate`, so no sibling generator inherits +it. Scan over `plugins/*/skills/*/actions/*.md` on `origin/next`: + +| Notation | Count in actions | Where | +| -------------------------------------- | ---------------- | ----------------------------------------------------------------- | +| `` `@../references/x.md` `` backticked | 135 | `aidd-context` 75, `aidd-dev` 26, `aidd-refine` 17, `aidd-pm` 13, `aidd-vcs` 4 | +| markdown link to `../references/x.md` | 24 files | mostly `aidd-context`, `aidd-pm` | + +Counting every markdown file in `plugins/`, not just actions, the `@` total is 144. + +`aidd-context/CHANGELOG.md:13` records the migration ("action citations use +markdown links, not @"), but it only landed on part of `aidd-context`. +`08-hook-generate`, a generator in the same plugin, is still fully on `@`: +`actions/02-write-hook.md:15-19`, `01-capture-hook.md:22-27`. + +Placement is not the fleet's problem. Counting both notations across the 120 +action files, 19 citations sit outside `## Process`, spread over 17 files. Every +one is at its point of use: an `## Input` bullet naming what defines it, an +`## Output` line naming the shape produced, a `## Test` asserting conformance, +or a one-line preamble naming the heuristics the action applies. Three of the 19 +are `04-skill-generate`'s own (`01-scope.md` Output, `03-write.md` Test, +`04-validate.md` Test). + +A `## Process` only rule would therefore break 17 files including the contract's +own skill, and `04-validate`'s test ("No file breaches skill-authoring.md") +would flag its own source. Point of use is the rule that matches the intent +without that contradiction. + +Nothing in the fleet gathers its citations into a list of its own, which is the +failure mode the report describes. The rule lands as a generation-time guardrail +with zero cleanup attached. + +## Why markdown over `@` + +Inside a skill body `@path` is inert text. It resolves in a `CLAUDE.md` import +and in some editor chat inputs, nowhere else. A relative markdown link is what +an agent follows and what `markdownlint` and the repo link checker verify. `@` +citations are invisible to both, so a stale one rots silently. + +## Options + +A and B are quoted as first drafted. Two of their clauses did not survive +contact with the files; see [What shipped](#what-shipped). + +### A. Fix the contract only + +Rewrite R6, no renumber, no other file touched: + +```md +- **R6.** One fact, one home. An action acts within a router rule and cites a + shared reference, never restating either. Every citation is a relative + markdown link `[name](path)`, written in the step or check that consumes it, + never collected in a list of its own. +``` + +Plus `skill-authoring.md:6`, where R2 says "Named per `naming.md`" in backticks +and would breach the rule one line above it, becomes a markdown link to +`naming.md`. + +Cost: 2 lines. Effect: generation time guardrail only, fleet unchanged. + +### B. A, plus close the notation gap the contract leaves open + +Same as A, and widen the citation sentence past action to reference so router +to action and anything to asset are covered too. `assets/` links included, since +a template is fetched by path like a reference is. + +Cost: same 2 lines, wider wording. Risk: R7 says a template holds no rule, so +still nothing lands in the templates. An author who fills a template blind stays +uncovered either way, which is a separate discoverability problem. + +### C. B, plus migrate the fleet + +Convert the 135 `@path` citations in actions (144 across every markdown file +under `plugins/`) to markdown links, so the contract and the shipped skills +agree. Notation only: the placement scan found nothing to relocate. + +Cost: mechanical, wide diff, touches 6 plugins. Should be its own PR with a +link check run after, not folded into a doc fix. + +## What shipped + +B, with three corrections found while applying it. + +R6 now reads: + +> **R6.** One fact, one home. An action acts within a router rule and cites a +> shared reference, never restating either. Every citation an action makes, +> reference or asset alike, is a relative markdown link `[name](path)`. A +> citation sits where it is used, never gathered in a list of its own. + +R8 gains its missing half: + +> **R8.** … Each stands alone, never pulling in another. It names a sibling in +> backticks and never links it. + +Correction 1: "in the step or check that consumes it" was too narrow. It broke +`01-scope.md`, whose `## Output` cites `scope-frame.md` at its point of use. +"Sits where it is used" keeps the intent and drops the false positive. + +Correction 2: the rule covers the actions, not the router. No router in the +repo cites a path (`grep '](\.\|`@' plugins/*/skills/*/SKILL.md` returns +nothing), and `skill-template.md`'s action table names slugs on purpose. +Naming the router would only have invited a reviewer to flag that table. + +Correction 3: R2's `` `naming.md` `` stays in backticks, and so does +`review-protocol.md:6`. Making the link rule global would have forced a +reference to link a sibling reference, which R8 forbids. The link rule is +therefore scoped to the actions, and R8 now states the counterpart explicitly +instead of leaving it to be inferred. + +Why the migration looked missing: commit `7661980` scoped itself to the action +files of `skill-generate` and `project-memory`, as its own message says. Both +are at zero `@` today. Every other skill was never in scope, and the contract +being local to `04-skill-generate` means none of them inherited R6 after the +fact. + +## C, same PR + +Decision: C ships with B rather than as a follow up, so the contract and the +fleet land in one state. + +143 citations in total: 135 backticked, of which 133 converted, one glob and +one literal `@` left alone, plus eight fenced ones inlined. + +The 133 were converted across 57 action files by a fence-aware script: every +`` `@` `` became `[]()`. The link text +is the file name, matching what `7661980` already established in +`skill-generate` and `project-memory`. Surrounding parentheses were kept, so the +diff is one line per citation and no sentence was restructured. + +Three cases the script left alone, handled by hand, plus one sibling-action +citation it converted like any other: + +- `12-cook/actions/01-list.md:22` cited a glob, `@../assets/recipes/*.md`. A + glob is not a citation and no link expresses it, so the `@` is dropped and the + backticks stay. Line 21 right above it already reads + `` `aidd_docs/recipes/*.md` ``, so the two now match. +- `09-for-sure/actions/01-init-tracking.md:27` cited a sibling action, not a + reference. Converted like the rest, since R6 covers everything an action + cites. +- `00-onboard/actions/03-present.md:26` uses `@` as a literal character in a + list of keys the host reserves. Untouched. +- `05-rule-generate/references/tool-paths.md:15` named a sibling reference as + `` `@rule-authoring.md` ``. The `@` is dropped, backticks kept, per R8. + +Eight more, never part of the 135 because they carry no backticks: a bare +`@` alone inside a fenced block, in `12-cook` and `00-repo-init`. The +first pass carved them out as load mechanics. That was wrong. Nothing parses +them, a fenced link renders as literal text, and `02-upsert.md` stacked three of +them in a block above `## Input` with no step naming any: the exact shape R6's +third sentence now forbids. All eight are inlined into the step that consumes +them and the fences are gone. + +- `01-list.md` cited `recipe-locations.md` in a preamble fence. Now in the + one-line description, which is what names the two homes it reads. +- `02-upsert.md` stacked `recipe-locations.md`, `recipe-template.md`, and + `recipe-contract.md`. The first was already cited at step 3; the other two + move to step 7, which scaffolds and applies them. +- `03-research.md` had one fence per step. Each becomes a link inside its step. +- `00-repo-init/01-init.md` cited the `CONTRIBUTING.md` template in a fence + under step 4. Now inline in step 4. + +Out of scope: `@claude` in `aidd-orchestrator` (a GitHub mention the routing +regex matches) and `@playwright/mcp` in a cook recipe (an npm scope). Neither is +a citation. + +Verification: a resolver over every relative link under `plugins/*/skills/` +reports 200 links, 0 broken among the converted set. The two it flags, +`plan-template.md:21-22` pointing at `./phase-1.md`, are pre-existing scaffold +placeholders in an asset the migration never touched. The repo's own `markdown-links` pre-commit hook +(lefthook) agrees: 561 files, 0 broken. No CLI test asserts on the `@` form +either (`grep -rn '@\.\./references\|@\.\./assets' cli/src cli/tests` is +empty). + +## What is not fixed + +`skill-authoring.md` stays local to `04-skill-generate`. The other generators +(`05-rule-generate`, `06-agent-generate`, `07-command-generate`, +`08-hook-generate`) each carry their own `*-authoring.md` and 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. + +Not in scope either way: putting a citation reminder into +`assets/action-template.md`. R7 forbids a template holding a rule, and +`actions/03-write.md:19` already routes the writer through the contract. diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index b38aeae1f..cd5efa047 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -7,9 +7,9 @@ The contract every generated skill satisfies. `skill-generate` obeys it too. - **R3.** `description` is the only always-on text: verb-led, third person, about 240 chars, `Use when the user wants to ` and an optional `Not for `. No colon or dash, no other skill or `/command` named. - **R4.** `argument-hint`: the action slugs when actions run one at a time, the user's cases (`setup | refresh | rewire`) for a pipeline, omitted for one action. - **R5.** `name` is not the invocation token: a colon or prefix breaks loading. In prose call a skill `plugin:folder`. -- **R6.** One fact, one home. An action acts within a router rule and cites a shared reference by a markdown link `[name](path)`, never restating either. +- **R6.** One fact, one home. An action acts within a router rule and cites a shared reference, never restating either. Every citation an action makes, reference or asset alike, is a relative markdown link `[name](path)`. A citation sits where it is used, never gathered in a list of its own. - **R7.** `references/` are read in place, `assets/` are copied or filled. A template holds no rule. -- **R8.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. +- **R8.** References stay flat, nesting one directory deep only as a load boundary. Each stands alone, never pulling in another. It names a sibling in backticks and never links it. - **R9.** One file, one artifact. Split two apart only when a path needs one without the other. - **R10.** Budget what a run reads, not file size: the router stays the leanest file. - **R11.** A section earns its content or is omitted, never invented or reordered. From 34f2ec0de82b749889b5d7387004b814b3f5d8ef Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 31 Jul 2026 07:35:13 +0200 Subject: [PATCH 2/2] refactor(plugins): action citations use markdown links, not @ 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 --- .../skills/00-onboard/actions/01-scan.md | 8 +++---- .../skills/00-onboard/actions/02-assess.md | 6 +++--- .../skills/00-onboard/actions/03-present.md | 6 +++--- .../skills/00-onboard/actions/04-run.md | 10 ++++----- .../01-bootstrap/actions/01-gather-needs.md | 4 ++-- .../actions/02-propose-candidates.md | 4 ++-- .../actions/05-write-install-md.md | 4 ++-- .../actions/01-capture-rule.md | 6 +++--- .../05-rule-generate/actions/02-write-rule.md | 10 ++++----- .../05-rule-generate/actions/03-validate.md | 4 ++-- .../05-rule-generate/references/tool-paths.md | 2 +- .../actions/01-capture-agent.md | 6 +++--- .../actions/02-write-agent.md | 10 ++++----- .../06-agent-generate/actions/03-validate.md | 2 +- .../actions/01-capture-command.md | 6 +++--- .../actions/02-write-command.md | 10 ++++----- .../actions/01-capture-hook.md | 16 +++++++------- .../08-hook-generate/actions/02-write-hook.md | 8 +++---- .../08-hook-generate/actions/03-validate.md | 4 ++-- .../skills/09-mermaid/actions/01-mermaid.md | 2 +- .../skills/11-explore/actions/01-survey.md | 4 ++-- .../skills/11-explore/actions/02-drill.md | 4 ++-- .../skills/12-cook/actions/01-list.md | 8 ++----- .../skills/12-cook/actions/02-upsert.md | 12 +++-------- .../skills/12-cook/actions/03-research.md | 21 +++---------------- .../skills/12-cook/actions/04-apply.md | 2 +- .../skills/01-plan/actions/03-wireframe.md | 2 +- .../skills/01-plan/actions/04-plan.md | 2 +- .../skills/02-implement/actions/02-execute.md | 2 +- .../03-assert/actions/03-assert-frontend.md | 2 +- .../04-audit/actions/01-code-quality.md | 4 ++-- .../04-audit/actions/02-architecture.md | 4 ++-- .../skills/04-audit/actions/03-security.md | 4 ++-- .../04-audit/actions/04-dependencies.md | 4 ++-- .../skills/04-audit/actions/05-performance.md | 4 ++-- .../skills/04-audit/actions/06-tests.md | 4 ++-- .../aidd-dev/skills/04-audit/actions/07-ui.md | 4 ++-- .../05-review/actions/01-review-code.md | 2 +- .../skills/08-debug/actions/02-debug.md | 4 ++-- .../09-for-sure/actions/01-init-tracking.md | 4 ++-- .../09-for-sure/actions/03-autonomous-loop.md | 4 ++-- .../02-user-stories/actions/02-split-epic.md | 2 +- .../actions/03-draft-stories.md | 8 +++---- .../actions/04-estimate-impact.md | 4 ++-- .../02-user-stories/actions/05-prioritize.md | 4 ++-- .../actions/06-sync-tracker.md | 2 +- .../aidd-pm/skills/03-prd/actions/01-prd.md | 2 +- .../skills/04-spec/actions/01-build.md | 2 +- .../skills/04-spec/actions/02-refine.md | 2 +- .../02-challenge/actions/01-challenge.md | 6 +++--- .../skills/03-condense/actions/01-condense.md | 2 +- .../04-shadow-areas/actions/01-detect.md | 4 ++-- .../actions/02-render-report.md | 4 ++-- .../actions/01-identify-claims.md | 2 +- .../skills/05-fact-check/actions/02-verify.md | 2 +- .../skills/05-fact-check/actions/03-report.md | 8 +++---- .../skills/00-repo-init/actions/01-init.md | 7 +------ .../02-pull-request/actions/02-draft.md | 2 +- .../03-release-tag/actions/01-release-tag.md | 2 +- .../actions/01-issue-create.md | 2 +- 60 files changed, 133 insertions(+), 163 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index 891caff1b..23bd0e70f 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -12,10 +12,10 @@ The project snapshot, printed nowhere. ## Process -1. **Zones.** Evaluate the checks per `@../references/state/zones.md`. -2. **Detect.** Resolve AI tools and wiring per `@../references/state/detection.md`. -3. **Ledger.** Drop done steps per `@../references/state/done-rule.md`. -4. **Hedge.** If a plan exists, pin the build-to-ship stage per `@../references/state/hedge.md`. +1. **Zones.** Evaluate the checks per [zones.md](../references/state/zones.md). +2. **Detect.** Resolve AI tools and wiring per [detection.md](../references/state/detection.md). +3. **Ledger.** Drop done steps per [done-rule.md](../references/state/done-rule.md). +4. **Hedge.** If a plan exists, pin the build-to-ship stage per [hedge.md](../references/state/hedge.md). 5. **List.** Gather installed AIDD plugins and skills via native discovery. 6. **Hold.** Keep the snapshot in context. Print nothing. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md index 4ba9902c5..57d1ad510 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -12,9 +12,9 @@ The decision, ready to render. ## Process -1. **Classify.** State class per `@../references/order/screen-map.md`. -2. **Rank.** Top next action per `@../references/order/ranking.md`. - - Idle: build the menu per `@../references/order/idle-menu.md`. +1. **Classify.** State class per [screen-map.md](../references/order/screen-map.md). +2. **Rank.** Top next action per [ranking.md](../references/order/ranking.md). + - Idle: build the menu per [idle-menu.md](../references/order/idle-menu.md). 3. **Resolve.** Match each command to an installed skill. - Absent: name a gap by function, never invent a command. diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 5c60a777e..ec479950e 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -12,7 +12,7 @@ The rendered screen, and the user's reply. ## Process -1. **Shape.** Fill the chosen screen from `@../assets/report.md`. +1. **Shape.** Fill the chosen screen from [report.md](../assets/report.md). - Framing line on the first report of the session only. - Exactly one action block per screen, carrying its key once. - The idle menu is a next-action block. Slot 1 is the action line, slots 2 to 4 join the options line. Never a list. @@ -25,8 +25,8 @@ The rendered screen, and the user's reply. - Command ids, tier clauses, and lookahead only under `[d]`. - Keys are letters or digits. Never `?`, `!`, `/`, `@`, `#`: the host takes those. 2. **Inject.** - - Entry screen takes `@../assets/banner.txt`. - - Flow or walk screen loads `@../references/flow.md`. + - Entry screen takes [banner.txt](../assets/banner.txt). + - Flow or walk screen loads [flow.md](../references/flow.md). 3. **Wait.** Offer the screen, take the reply. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 2791d965f..d72470913 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -4,7 +4,7 @@ Carry out the reply. ## Input -- The user's reply, per `@../references/run/replies.md`. +- The user's reply, per [replies.md](../references/run/replies.md). - The current decision, its resolved commands or a gap. ## Output @@ -13,14 +13,14 @@ The reply carried out. ## Process -1. **Route.** Carry out the reply per `@../references/run/replies.md`. +1. **Route.** Carry out the reply per [replies.md](../references/run/replies.md). 2. **Guard.** - Run only installed skills. - A gap invokes nothing. - A MANUAL step is shown, not run. -3. **Tier.** Running a step, apply `@../references/run/tiers.md`. -4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. -5. **Record.** Write the handled step to the ledger per `@../references/state/done-rule.md`. +3. **Tier.** Running a step, apply [tiers.md](../references/run/tiers.md). +4. **Return.** On a GUIDED handoff, emit the return line per [return.md](../references/run/return.md). +5. **Record.** Write the handled step to the ledger per [done-rule.md](../references/state/done-rule.md). 6. **Loop.** After a run or `OK` walk, re-scan. - A read-only reply or umbrella pick does not. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md index e8028999a..fd2d08693 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md @@ -8,11 +8,11 @@ A free-form user request to bootstrap a new SaaS project. ## Output -A filled copy of `@../assets/checklist.md` held in conversation context, not yet written to disk, with every user-input item's `<...>` placeholder replaced by a concrete value. +A filled copy of [checklist.md](../assets/checklist.md) held in conversation context, not yet written to disk, with every user-input item's `<...>` placeholder replaced by a concrete value. ## Process -1. **Show.** Read `@../assets/checklist.md` and print the four blocks as one markdown checklist so the user sees the full scope upfront. +1. **Show.** Read [checklist.md](../assets/checklist.md) and print the four blocks as one markdown checklist so the user sees the full scope upfront. 2. **Ask.** Ask block by block, one block per message, all questions in a block at once. Do not ask block 4; it is derived. 3. **Fill.** Fill each item from the answer. When an answer is vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). 4. **Check.** After block 1, sanity-check coherence: does the type match the user volume, are the integrations realistic for the platform target. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md b/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md index 8af3df853..1359ba2c7 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md @@ -1,6 +1,6 @@ # 02 - Propose candidates -Derive 2 to 3 candidate stacks from the filled checklist using the heuristics in `@../references/stack-heuristics.md`, then render a markdown comparison table. +Derive 2 to 3 candidate stacks from the filled checklist using the heuristics in [stack-heuristics.md](../references/stack-heuristics.md), then render a markdown comparison table. ## Input @@ -13,7 +13,7 @@ A markdown comparison table with 2 to 3 rows, each a candidate with its front, b ## Process 1. **Read.** Read the filled checklist from action 01. -2. **Derive.** Apply each rule from `@../references/stack-heuristics.md` to derive the recommended family for architecture pattern, front, back, DB, auth, and hosting. +2. **Derive.** Apply each rule from [stack-heuristics.md](../references/stack-heuristics.md) to derive the recommended family for architecture pattern, front, back, DB, auth, and hosting. 3. **Spread.** Build 2 to 3 candidates spanning the trade-off space, differing on at least one of hosting model (PaaS, self-host, serverless), back-end language, or architecture pattern. Never propose near-identical candidates. 4. **Cost.** Estimate each candidate's monthly cost at the user's six-month volume target with rough public pricing, flagging uncertainty. 5. **Risk.** List 1 to 3 honest risks per candidate (lock-in, ops burden, learning curve, scaling limit). No candidate has zero. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md index 210facfb0..b73a246c0 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md @@ -8,11 +8,11 @@ The filled checklist, folder-structure code block, and Mermaid diagram from acti ## Output -A new `aidd_docs/INSTALL.md` filled from `@../assets/install-template.md`, with its Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, and Audit summary sections. +A new `aidd_docs/INSTALL.md` filled from [install-template.md](../assets/install-template.md), with its Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, and Audit summary sections. ## Process -1. **Load.** Read `@../assets/install-template.md` as the skeleton. +1. **Load.** Read [install-template.md](../assets/install-template.md) as the skeleton. 2. **Fill.** Fill each placeholder from the upstream artifacts: - **Vision**: project name and one-liner from block 1. - **Decisions**: each block-4 row paired with a one-line why from the block 2 and 3 constraints. diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/01-capture-rule.md b/plugins/aidd-context/skills/05-rule-generate/actions/01-capture-rule.md index a0a306a35..6b140bae2 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/01-capture-rule.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/01-capture-rule.md @@ -12,14 +12,14 @@ In-context: the topic, its category and slug, the file scope, a one-line descrip ## Process -1. **Gate.** Run the asset-access precheck (`@../references/tool-paths.md`). +1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)). 2. **Auto or manual.** Ask whether to run auto or manual mode: - **Auto**: scan the codebase, propose a rules architecture, wait for approval. - **Manual**: ask the topic (blocking). Confirm any candidate first. -3. **Place.** Pick the category and slug from `@../references/rule-authoring.md`. The category index drives the slug prefix. +3. **Place.** Pick the category and slug from [rule-authoring.md](../references/rule-authoring.md). The category index drives the slug prefix. 4. **Scope.** State the glob the rule applies to, or note it applies to all files. Note a one-line description of what the rule governs, for tools whose scope frontmatter needs it. 5. **Write mode.** Ask where the rule goes: - - **Host project**: detect the installed tools (`@../references/tool-paths.md`), propose the supported ones, and confirm which to target. Never pick one silently. + - **Host project**: detect the installed tools ([tool-paths.md](../references/tool-paths.md)), propose the supported ones, and confirm which to target. Never pick one silently. - **Plugin source**: confirm or create `plugins//rules/`. ## Test diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md index 59e78f43e..7a77b36bc 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/02-write-rule.md @@ -12,15 +12,15 @@ One rule file per supported confirmed tool, the list of files written, and any s ## Process -1. **Build.** Copy `@../assets/rule-template.md` into one canonical rule, concise. Strip the scaffold (comments + `<...>`). -2. **Frontmatter.** Set the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field a tool does not support. -3. **Render.** Per the write mode (`@../references/tool-paths.md`): +1. **Build.** Copy [rule-template.md](../assets/rule-template.md) into one canonical rule, concise. Strip the scaffold (comments + `<...>`). +2. **Frontmatter.** Set the per-tool frontmatter from [tool-paths.md](../references/tool-paths.md). Drop a field a tool does not support. +3. **Render.** Per the write mode ([tool-paths.md](../references/tool-paths.md)): - **Host**: for each supported confirmed tool, write to its path and extension. Skip an unsupported tool, carrying its reason forward. - **Plugin source**: write one canonical `.md` rule. No per-tool fan-out. 4. **Split.** When examples warrant it, write several rule files rather than one crowded one. -5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +5. **Validate.** Run the write-target validation ([tool-paths.md](../references/tool-paths.md)). ## Test - Each rule file exists at its tool's rules path under the chosen scope. -- The scope frontmatter matches the rule's reach, per `@../references/tool-paths.md`. +- The scope frontmatter matches the rule's reach, per [tool-paths.md](../references/tool-paths.md). diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index 7e4f3495f..74c1fed76 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -13,8 +13,8 @@ A short pass or fail line per rule file. ## Process 1. **Exists.** Confirm each file is on disk at its expected path. -2. **Contract.** Validate the file against `@../references/rule-authoring.md`. -3. **Target.** Validate target path and frontmatter against `@../references/tool-paths.md`. +2. **Contract.** Validate the file against [rule-authoring.md](../references/rule-authoring.md). +3. **Target.** Validate target path and frontmatter against [tool-paths.md](../references/tool-paths.md). 4. **Report.** Emit one pass/fail line per file. ## Test diff --git a/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md b/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md index 30ad58101..8684504e2 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md @@ -12,7 +12,7 @@ The per-tool rules path and write targets. Rule slice only, nothing about skills | OpenCode | - | no | | Codex CLI | - | no | -`` is the file name `#-slug` from `@rule-authoring.md` (e.g. `2-python-fstrings`). `` is that slug with its leading category digit dropped (`python-fstrings`). `` is the folder `-`, the zero-padded category index plus the category name from the taxonomy, e.g. `01-standards`. `` is that same two-digit index. +`` is the file name `#-slug` from `rule-authoring.md` (e.g. `2-python-fstrings`). `` is that slug with its leading category digit dropped (`python-fstrings`). `` is the folder `-`, the zero-padded category index plus the category name from the taxonomy, e.g. `01-standards`. `` is that same two-digit index. Copilot is flat: no category folder. Its file is `-`, e.g. `2-python-fstrings` becomes `02-python-fstrings` (one category prefix, no folder). diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md index bf34342b3..08a33d17a 100644 --- a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md +++ b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md @@ -12,13 +12,13 @@ In-context: the role and its system prompt, the chosen name, the model, a qualit ## Process -1. **Gate.** Run the asset-access precheck (`@../references/tool-paths.md`). +1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)). 2. **Clarify.** Ask about the purpose, tools, inputs, instructions, and preferred model. If anything stays vague, ask again before moving on. -3. **Draft.** Write the canonical role (`@../references/agent-authoring.md`): a frontmatter intent + a system-prompt body. Include only the optional and orchestration sections it needs. +3. **Draft.** Write the canonical role ([agent-authoring.md](../references/agent-authoring.md)): a frontmatter intent + a system-prompt body. Include only the optional and orchestration sections it needs. 4. **Name.** Propose three short, catchy names that fit the purpose, and have the user pick one. 5. **Score.** Rate the agent 1-10 on clarity and completeness. If it scores under 8, revise and score again. 6. **Mode.** Ask where the agent goes: - - **Host project**: detect the installed tools (`@../references/tool-paths.md`), propose them, and confirm which to target. + - **Host project**: detect the installed tools ([tool-paths.md](../references/tool-paths.md)), propose them, and confirm which to target. - **Plugin source**: confirm or create `plugins//agents/`. ## Test diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md b/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md index 9b2d382e5..c40746183 100644 --- a/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md +++ b/plugins/aidd-context/skills/06-agent-generate/actions/02-write-agent.md @@ -12,13 +12,13 @@ One agent file per confirmed tool, and the list of files written. ## Process -1. **Build.** Copy `@../assets/agent-template.md` into one canonical agent. Strip the scaffold (comments + `<...>`). -2. **Frontmatter.** Apply the per-tool frontmatter from `@../references/tool-paths.md`. Drop a field where the tool does not support it. Plugin source: keep the canonical frontmatter. -3. **Convert.** Apply any per-tool structural conversion listed in `@../references/tool-paths.md`. Plugin source skips conversion. -4. **Render.** Per the write mode (`@../references/tool-paths.md`): +1. **Build.** Copy [agent-template.md](../assets/agent-template.md) into one canonical agent. Strip the scaffold (comments + `<...>`). +2. **Frontmatter.** Apply the per-tool frontmatter from [tool-paths.md](../references/tool-paths.md). Drop a field where the tool does not support it. Plugin source: keep the canonical frontmatter. +3. **Convert.** Apply any per-tool structural conversion listed in [tool-paths.md](../references/tool-paths.md). Plugin source skips conversion. +4. **Render.** Per the write mode ([tool-paths.md](../references/tool-paths.md)): - **Host**: for each confirmed tool, write to its path and extension. - **Plugin source**: write one canonical agent. No per-tool fan-out. -5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +5. **Validate.** Run the write-target validation ([tool-paths.md](../references/tool-paths.md)). ## Test diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md b/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md index ac10631a5..9169f12c2 100644 --- a/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/06-agent-generate/actions/03-validate.md @@ -13,7 +13,7 @@ A short pass or fail line per agent file. ## Process 1. **Exists.** Confirm each file is on disk at its expected path. -2. **Shape.** Confirm each file matches its target format (`@../references/tool-paths.md`), a confirmed tool's, or the canonical form in plugin source, and carries the name, description, and body. +2. **Shape.** Confirm each file matches its target format ([tool-paths.md](../references/tool-paths.md)), a confirmed tool's, or the canonical form in plugin source, and carries the name, description, and body. 3. **Concise.** Confirm the body stays focused on one role. ## Test diff --git a/plugins/aidd-context/skills/07-command-generate/actions/01-capture-command.md b/plugins/aidd-context/skills/07-command-generate/actions/01-capture-command.md index 21cfb3105..4f16ef6af 100644 --- a/plugins/aidd-context/skills/07-command-generate/actions/01-capture-command.md +++ b/plugins/aidd-context/skills/07-command-generate/actions/01-capture-command.md @@ -12,13 +12,13 @@ In-context: the command name and one-line goal, its location, its arguments, the ## Process -1. **Gate.** Run the asset-access precheck (`@../references/tool-paths.md`). +1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)). 2. **Goal.** Ask the single objective in one sentence. A command does one thing. 3. **Form.** If it needs supporting files or many steps, redirect the user to the skill generator instead. -4. **Place.** Ask the user where the command should live. An optional ordering convention is in `@../references/command-authoring.md` if they want it, but never impose a location. +4. **Place.** Ask the user where the command should live. An optional ordering convention is in [command-authoring.md](../references/command-authoring.md) if they want it, but never impose a location. 5. **Arguments.** Note any arguments it takes. If it takes input, `$ARGUMENTS` carries it. A no-argument command needs none. 6. **Write mode.** Ask where the command goes: - - **Host project**: detect the installed tools (`@../references/tool-paths.md`), propose the supported ones, and confirm which to target. Never pick one silently. + - **Host project**: detect the installed tools ([tool-paths.md](../references/tool-paths.md)), propose the supported ones, and confirm which to target. Never pick one silently. - **Plugin source**: confirm or create `plugins//commands/`. ## Test diff --git a/plugins/aidd-context/skills/07-command-generate/actions/02-write-command.md b/plugins/aidd-context/skills/07-command-generate/actions/02-write-command.md index 84b056af4..3ad15ad0c 100644 --- a/plugins/aidd-context/skills/07-command-generate/actions/02-write-command.md +++ b/plugins/aidd-context/skills/07-command-generate/actions/02-write-command.md @@ -12,13 +12,13 @@ One command file per supported confirmed tool, the list of files written, and an ## Process -1. **Build.** Copy `@../assets/command-template.md` into one canonical command: single objective, under ten steps, no Role section. Strip the scaffold (comments + `<...>`). -2. **Frontmatter.** Set the fields per tool from `@../references/tool-paths.md`. Drop a field a tool does not support. -3. **Render.** Per the write mode (`@../references/tool-paths.md`): +1. **Build.** Copy [command-template.md](../assets/command-template.md) into one canonical command: single objective, under ten steps, no Role section. Strip the scaffold (comments + `<...>`). +2. **Frontmatter.** Set the fields per tool from [tool-paths.md](../references/tool-paths.md). Drop a field a tool does not support. +3. **Render.** Per the write mode ([tool-paths.md](../references/tool-paths.md)): - **Host**: for each supported confirmed tool, write to its path at the chosen location. Skip an unsupported tool, carrying its reason forward. - **Plugin source**: write one canonical `.md` command. No per-tool fan-out. -4. **Arguments.** If the command takes input, reference it with `$ARGUMENTS`. For a CLI call, use the injection syntax only where the target tool supports it, otherwise describe the command in the body (`@../references/command-authoring.md`). -5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +4. **Arguments.** If the command takes input, reference it with `$ARGUMENTS`. For a CLI call, use the injection syntax only where the target tool supports it, otherwise describe the command in the body ([command-authoring.md](../references/command-authoring.md)). +5. **Validate.** Run the write-target validation ([tool-paths.md](../references/tool-paths.md)). ## Test diff --git a/plugins/aidd-context/skills/08-hook-generate/actions/01-capture-hook.md b/plugins/aidd-context/skills/08-hook-generate/actions/01-capture-hook.md index 064a9dba8..b5a752fd7 100644 --- a/plugins/aidd-context/skills/08-hook-generate/actions/01-capture-hook.md +++ b/plugins/aidd-context/skills/08-hook-generate/actions/01-capture-hook.md @@ -19,14 +19,14 @@ In-context decisions, nothing written yet: ## Process -1. **Gate.** Run the asset-access precheck (`@../references/tool-paths.md`). -2. **Tools.** Detect the installed tools and confirm which to target (`@../references/tool-paths.md`). Skip a tool that does not support hooks, with its reason. -3. **Moment.** Pick the narrowest lifecycle moment that fits (`@../references/hook-authoring.md`). - - Confirm each target tool exposes that moment (`@../references/tool-paths.md`). Skip a tool that lacks it, with its reason. -4. **Action.** Decide what runs at the moment, and whether it needs a backing script (`@../references/hook-authoring.md`). -5. **Matcher.** Set a matcher only when the moment must be filtered. Prefer a precise filter (`@../references/hook-authoring.md`). -6. **Scope.** Ask the user where to install: a single agent or skill component, the shared project, the project local-only, or the user's global config. Offer only the scopes the target tools support (`@../references/tool-paths.md`). - - For a component scope, name the exact skill or agent file, and confirm the moment fits a component-scoped hook (`@../references/tool-paths.md`). +1. **Gate.** Run the asset-access precheck ([tool-paths.md](../references/tool-paths.md)). +2. **Tools.** Detect the installed tools and confirm which to target ([tool-paths.md](../references/tool-paths.md)). Skip a tool that does not support hooks, with its reason. +3. **Moment.** Pick the narrowest lifecycle moment that fits ([hook-authoring.md](../references/hook-authoring.md)). + - Confirm each target tool exposes that moment ([tool-paths.md](../references/tool-paths.md)). Skip a tool that lacks it, with its reason. +4. **Action.** Decide what runs at the moment, and whether it needs a backing script ([hook-authoring.md](../references/hook-authoring.md)). +5. **Matcher.** Set a matcher only when the moment must be filtered. Prefer a precise filter ([hook-authoring.md](../references/hook-authoring.md)). +6. **Scope.** Ask the user where to install: a single agent or skill component, the shared project, the project local-only, or the user's global config. Offer only the scopes the target tools support ([tool-paths.md](../references/tool-paths.md)). + - For a component scope, name the exact skill or agent file, and confirm the moment fits a component-scoped hook ([tool-paths.md](../references/tool-paths.md)). - State the resolved file and confirm. Never pick silently. 7. **Write mode.** Host project, or a plugin source. For a plugin source, name the plugin. diff --git a/plugins/aidd-context/skills/08-hook-generate/actions/02-write-hook.md b/plugins/aidd-context/skills/08-hook-generate/actions/02-write-hook.md index c86e50776..fbddc89c1 100644 --- a/plugins/aidd-context/skills/08-hook-generate/actions/02-write-hook.md +++ b/plugins/aidd-context/skills/08-hook-generate/actions/02-write-hook.md @@ -12,11 +12,11 @@ The updated target file per tool, any script written, and the list of paths touc ## Process -1. **Script.** If the action needs a backing script (`@../references/hook-authoring.md`): copy `@../assets/hook-script-template.sh`, fill the logic, place it in the scope's script directory (`@../references/tool-paths.md`), and make it executable. One script can back every tool. -2. **Entry.** Per confirmed tool, fill `@../assets/hook-template.json` from `@../references/tool-paths.md`, using that tool's shape and stripping the scaffold. +1. **Script.** If the action needs a backing script ([hook-authoring.md](../references/hook-authoring.md)): copy [hook-script-template.sh](../assets/hook-script-template.sh), fill the logic, place it in the scope's script directory ([tool-paths.md](../references/tool-paths.md)), and make it executable. One script can back every tool. +2. **Entry.** Per confirmed tool, fill [hook-template.json](../assets/hook-template.json) from [tool-paths.md](../references/tool-paths.md), using that tool's shape and stripping the scaffold. - Point the handler at the script by absolute path or an approved `${VAR}`. -3. **Merge.** For each tool, read the target file and append the entry to the moment's list under the right key for the scope (`@../references/tool-paths.md`). Preserve every sibling, never overwrite. -4. **Validate.** Run the merge check and write-target validation (`@../references/tool-paths.md`). +3. **Merge.** For each tool, read the target file and append the entry to the moment's list under the right key for the scope ([tool-paths.md](../references/tool-paths.md)). Preserve every sibling, never overwrite. +4. **Validate.** Run the merge check and write-target validation ([tool-paths.md](../references/tool-paths.md)). ## Test diff --git a/plugins/aidd-context/skills/08-hook-generate/actions/03-validate.md b/plugins/aidd-context/skills/08-hook-generate/actions/03-validate.md index 08ff96720..ac660ec00 100644 --- a/plugins/aidd-context/skills/08-hook-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/08-hook-generate/actions/03-validate.md @@ -13,8 +13,8 @@ A short pass or fail line per tool, plus the script. ## Process 1. **Parse.** Confirm each target file still parses in its format and the entry sits at the right key for its scope. -2. **Moment.** Confirm the event name is the right one for that tool's moment, and the matcher is well-formed (`@../references/tool-paths.md`). -3. **Blocking.** If the hook blocks, confirm the moment can block on that tool (`@../references/tool-paths.md`). +2. **Moment.** Confirm the event name is the right one for that tool's moment, and the matcher is well-formed ([tool-paths.md](../references/tool-paths.md)). +3. **Blocking.** If the hook blocks, confirm the moment can block on that tool ([tool-paths.md](../references/tool-paths.md)). 4. **Script.** For a script-backed handler, confirm the script exists, is executable, and reads stdin and signals per the contract. ## Test diff --git a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md index 9ea04c445..a462f24bb 100644 --- a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md +++ b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md @@ -15,7 +15,7 @@ A Mermaid diagram in a fenced block, plus an optional review note. On the first 1. **Get the source.** Ask for the document to diagram when it is not already provided. 2. **Plan.** Analyze the source and write a plan that names: the components and their logical groups, the parent and child elements, the directions and the hierarchy, the relationships (connections, dependencies), and the labels or notes each element needs. 3. **Confirm.** Ask the user to confirm the plan. Block on the answer. -4. **Generate.** Produce a valid Mermaid diagram from the confirmed plan, following the conventions and defaults in `@../references/mermaid-conventions.md`. +4. **Generate.** Produce a valid Mermaid diagram from the confirmed plan, following the conventions and defaults in [mermaid-conventions.md](../references/mermaid-conventions.md). 5. **Offer a review.** Ask whether the user wants a review, and wait. 6. **Review on confirm.** Check the syntax, look for an empty or misplaced node, and suggest improvements. diff --git a/plugins/aidd-context/skills/11-explore/actions/01-survey.md b/plugins/aidd-context/skills/11-explore/actions/01-survey.md index 8b8688717..d4fd5f180 100644 --- a/plugins/aidd-context/skills/11-explore/actions/01-survey.md +++ b/plugins/aidd-context/skills/11-explore/actions/01-survey.md @@ -12,8 +12,8 @@ A map grouped by axis, Tooling, Context, and Codebase. Each axis lists what is t ## Process -1. **Detect the tools.** Find which AI tools the project uses by the presence signal in `@../references/ai-mapping.md`, keying on a tool's own mapped surfaces, never a shared parent directory. Propose the set when it is ambiguous, never assume one silently. -2. **Scan Tooling.** For each detected tool, gather the installed skills, agents, commands, rules, hooks, MCP servers, and plugins from the surfaces in `@../references/ai-mapping.md`. +1. **Detect the tools.** Find which AI tools the project uses by the presence signal in [ai-mapping.md](../references/ai-mapping.md), keying on a tool's own mapped surfaces, never a shared parent directory. Propose the set when it is ambiguous, never assume one silently. +2. **Scan Tooling.** For each detected tool, gather the installed skills, agents, commands, rules, hooks, MCP servers, and plugins from the surfaces in [ai-mapping.md](../references/ai-mapping.md). 3. **Scan Context.** The memory bank under `aidd_docs/memory/` and whether its files are filled, any specs or plans under `aidd_docs/`, and whether the AI context files carry the `` block. 4. **Scan Codebase.** The stack, from the manifest or from the memory bank, and the few top-level modules or layers. 5. **Present the map.** One section per axis, each a short list or count with one-line purposes. diff --git a/plugins/aidd-context/skills/11-explore/actions/02-drill.md b/plugins/aidd-context/skills/11-explore/actions/02-drill.md index 8368dda57..042b8160b 100644 --- a/plugins/aidd-context/skills/11-explore/actions/02-drill.md +++ b/plugins/aidd-context/skills/11-explore/actions/02-drill.md @@ -12,9 +12,9 @@ A full listing of the current level, and, when the user gave a goal, a single be ## Process -1. **Detect the tools if entered cold.** When the survey did not run first, detect the project's AI tools from the signals in `@../references/ai-mapping.md` before listing anything. Propose the set when it is ambiguous. +1. **Detect the tools if entered cold.** When the survey did not run first, detect the project's AI tools from the signals in [ai-mapping.md](../references/ai-mapping.md) before listing anything. Propose the set when it is ambiguous. 2. **Set the scope.** One axis, or all three. For all, take each axis in turn at one level only, never auto-descend every leaf at once. -3. **List the level.** Enumerate the current level in full from the same sources as the survey (`@../references/ai-mapping.md` for the Tooling and Context surfaces). The top level of an axis is its surfaces or items, a deeper level is one item's internals, a skill's actions, a memory file's sections, a module's files. For a Tooling surface, render a table: the item, where it lives, and its one-line purpose. For a rule scan, the `scripts/list-rules.mjs` helper inventories rules across every tool surface. +3. **List the level.** Enumerate the current level in full from the same sources as the survey ([ai-mapping.md](../references/ai-mapping.md) for the Tooling and Context surfaces). The top level of an axis is its surfaces or items, a deeper level is one item's internals, a skill's actions, a memory file's sections, a module's files. For a Tooling surface, render a table: the item, where it lives, and its one-line purpose. For a rule scan, the `scripts/list-rules.mjs` helper inventories rules across every tool surface. 4. **Match the goal.** When the user named a goal, score this level's items and pick the single best match. Mention a close second only when it is genuinely tied. 5. **Point.** Give a chosen item's exact invocation path. Never run it. 6. **Descend, loop, or stop.** Offer to expand one item one level deeper, back up, switch axis, or stop. On expand, repeat from step 3 against that item. Stop at a leaf or when the user is done. Wait for the answer. diff --git a/plugins/aidd-context/skills/12-cook/actions/01-list.md b/plugins/aidd-context/skills/12-cook/actions/01-list.md index 3ee76cd5f..695e8902c 100644 --- a/plugins/aidd-context/skills/12-cook/actions/01-list.md +++ b/plugins/aidd-context/skills/12-cook/actions/01-list.md @@ -1,10 +1,6 @@ # 01 - List recipes -List project recipes and bundled recipes as a table. - -```md -@../references/recipe-locations.md -``` +List project recipes and bundled recipes as a table, from the two homes in [recipe-locations.md](../references/recipe-locations.md). ## Output @@ -19,7 +15,7 @@ One row per recipe file, sorted by source then file name, numbered from 1 after ## Process 1. Read project recipes under `aidd_docs/recipes/*.md`, excluding `README.md`. -2. Read bundled recipes under `@../assets/recipes/*.md`, excluding `README.md`. +2. Read bundled recipes under `../assets/recipes/*.md`, excluding `README.md`. 3. Pull the H1 title and the one-sentence description right below it. 4. If a project recipe and bundled recipe share the same slug, mark the project row as active and the bundled row as shadowed. 5. Assign contiguous numbers from 1 to N after sorting. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index 8dbe2176d..79334021d 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,12 +1,6 @@ # 02 - Upsert recipe -Create or update one project recipe at `aidd_docs/recipes/.md`, scaffolded from the recipe template and following the recipe contract: - -```md -@../references/recipe-locations.md -@../assets/recipe-template.md -@../references/recipe-contract.md -``` +Create or update one project recipe at `aidd_docs/recipes/.md`, scaffolded from the recipe template and following the recipe contract. ## Input @@ -20,11 +14,11 @@ The recipe file at `aidd_docs/recipes/.md`, filled from the template. 1. **Research first.** For a new recipe or any substantial update, run `research` (03) on the topic and draft only from its verified results — never from memory. 2. Derive a kebab-case `` from the topic. -3. Resolve existing recipes with `@../references/recipe-locations.md`. +3. Resolve existing recipes with [recipe-locations.md](../references/recipe-locations.md). 4. If the project recipe exists, update `aidd_docs/recipes/.md` in place. 5. If only a bundled recipe exists, ask whether to copy/update it into `aidd_docs/recipes/.md` or edit the bundled framework recipe. Only edit bundled recipes when the user explicitly asks for that framework-source change. 6. If the recipe is new, run `list` and rate each near match in an overlap table `| Existing recipe | Source | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. -7. Scaffold from the template when needed. Apply the contract to every section. +7. Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed. Apply [recipe-contract.md](../references/recipe-contract.md) to every section. 8. Fill every placeholder. Do not maintain a separate recipe index; `list` reads the recipe files directly. ## Test diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md index 3514b6e5e..de77ccd30 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -18,24 +18,9 @@ Every presented item is confirmed to exist, with its latest state and official l ## Process -1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Resolve and read the recipe with `@../references/recipe-locations.md` when it exists. Run `list` when it is unnamed. - -```md -@../assets/research-goal-checklist.md -``` - -2. **Fan out.** Spawn one agent per angle in the playbook via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. - -```md -@../references/research-playbook.md -``` - -3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear the research checklist: gaps filled, unknowns surfaced, claims corroborated. - -```md -@../assets/research-checklist.md -``` - +1. **Refine.** Fill [research-goal-checklist.md](../assets/research-goal-checklist.md) with the user until the target is precise: outcome, level, scope, grouping. Resolve and read the recipe with [recipe-locations.md](../references/recipe-locations.md) when it exists. Run `list` when it is unnamed. +2. **Fan out.** Spawn one agent per angle in [research-playbook.md](../references/research-playbook.md) via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear [research-checklist.md](../assets/research-checklist.md): gaps filled, unknowns surfaced, claims corroborated. 4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source. 5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why. 6. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index 212bacdfd..16ea664d2 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -12,7 +12,7 @@ A short analysis of the recipe — what it achieves, and which steps the agent c ## Process -1. **Locate.** Resolve the recipe with `@../references/recipe-locations.md` and read it. Run `list` first when the recipe is unnamed or when the user gives a number but no current numbered list is available. +1. **Locate.** Resolve the recipe with [recipe-locations.md](../references/recipe-locations.md) and read it. Run `list` first when the recipe is unnamed or when the user gives a number but no current numbered list is available. 2. **Analyse.** Read each step and classify it: agent-doable (a file edit, a config change) or human-only (a TUI command, an install, anything needing the user's terminal or UI). Summarise what the recipe achieves and what is in scope for the agent. 3. **Ask.** Show the analysis and ask the user what to do — run all agent-doable steps, a subset, or just report. Never mutate before this answer. 4. **Execute.** For the chosen steps, work them as a tracked todo list, pausing for confirmation on any step that changes a file. Leave the human-only steps untouched. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md index 53d8b3a59..928b9cb95 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -13,7 +13,7 @@ A low-fidelity ASCII wireframe of each screen, its regions and key elements in p ## Process 1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. -2. **Draw.** Sketch each screen per `@../references/wireframe-conventions.md`. The wireframe feeds the plan. +2. **Draw.** Sketch each screen per [wireframe-conventions.md](../references/wireframe-conventions.md). The wireframe feeds the plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 627681e32..05d7582be 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -8,7 +8,7 @@ The explore output from `02-explore` (projection, rules, feasibility, risks), pl ## Output -A feature folder, always at `aidd_docs/tasks//_/`, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. +A feature folder, always at `aidd_docs/tasks//_/`, holding `plan.md` from [plan-template.md](../assets/plan-template.md) and one `phase-.md` per phase from [phase-template.md](../assets/phase-template.md). ## Process diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 2464642ff..2c531ffb4 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -16,7 +16,7 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the 2. **Code.** Build the phase scope against its acceptance criteria. 3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. 4. **Guard.** Stop the loop on either condition: - - **Blocked** (see `@../references/blocked.md`): set the plan `status: blocked`, commit, stop. + - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop. - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. ## Test diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 3d6a9d879..265343f9c 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -16,7 +16,7 @@ A pass or fail verdict, with the candidate causes and their fix attempts and res 2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. 3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. 4. **Locate.** Explore the codebase for the files behind the issue. -5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +5. **Track.** Fill the tracking file from [task-template.md](../assets/task-template.md) with the three best candidate causes, each with a short description and a confidence level. 6. **Fix.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. 7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. diff --git a/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md b/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md index 3dcc5e3eb..c5ce7b2b7 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md +++ b/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md @@ -17,8 +17,8 @@ The `code-quality` findings, written to `code-quality.md` in the run's audit fol - **Clean code**: naming clarity, single-responsibility and SOLID, DRY (copy-pasted logic, re-implemented stdlib helpers), readability, abstraction level, magic numbers, dead or misleading comments, code smells. - **Tech debt**: dead and unreachable code, unused exports, types, and helpers, stale TODOs, vestigial flags, cyclomatic complexity and file, function, or component length above project thresholds, nesting depth, error handling caught at the wrong boundary or silently swallowed. - Use a dedicated tool when available, for example an unused-export finder. Never assert dead code without evidence. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `code-quality`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `code-quality`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md b/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md index 69baec047..110822037 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md +++ b/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md @@ -18,8 +18,8 @@ The `architecture` findings, written to `architecture.md` in the run's audit fol - **Coupling**: identify modules that import from layers they should not depend on, a wrong dependency direction or a circular reference across bounded contexts. - **God-modules**: detect modules with an abnormally large surface area, too many exports or responsibilities, that signal architectural erosion. - When ADRs or C4 diagrams are absent, note "no architecture docs found, conformance check skipped" in `Coverage > Skipped` and limit the scan to observable coupling heuristics. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `architecture`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `architecture`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/03-security.md b/plugins/aidd-dev/skills/04-audit/actions/03-security.md index 4935fa618..a3e8ae8a4 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/03-security.md +++ b/plugins/aidd-dev/skills/04-audit/actions/03-security.md @@ -21,8 +21,8 @@ The `security` findings, written to `security.md` in the run's audit folder. - **Unsafe deserialization**: flag `eval`, unsafe YAML/pickle/JSON reviver patterns, or object deserialization from untrusted sources. - **Insecure defaults**: missing TLS enforcement, overly permissive CORS, disabled security headers, debug flags left on in non-dev code. - Use a static-analysis tool when available. Flag only findings supported by code evidence, never inferred from naming alone. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `security`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `security`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md b/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md index 50f3128f9..bd1512be7 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md +++ b/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md @@ -19,8 +19,8 @@ The `dependencies` findings, written to `dependencies.md` in the run's audit fol - **Outdated packages**: identify packages significantly behind their latest stable release, especially those with security-relevant changelogs. - **Unused declared dependencies**: flag packages listed in the manifest with no import found in the scanned source. - **Lockfile integrity and supply chain**: verify the lockfile is present and committed. Flag direct git or URL dependencies and any package with no integrity hash. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line` in the manifest or lockfile. The category is always `dependencies`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line` in the manifest or lockfile. The category is always `dependencies`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/05-performance.md b/plugins/aidd-dev/skills/04-audit/actions/05-performance.md index e19e1aed1..3026ed993 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/05-performance.md +++ b/plugins/aidd-dev/skills/04-audit/actions/05-performance.md @@ -21,8 +21,8 @@ The `performance` findings, written to `performance.md` in the run's audit folde - **Render thrash**: detect layout-thrashing DOM patterns, missing memoization on computed values used in hot render paths, or component trees that re-render without a guard on reference-stable props. - **Missing memoization on hot paths**: flag expensive pure computations inside render or tight loops that are not memoized. - When no profiler or bundle analyzer is available, degrade to static heuristics and record "no profiler, static heuristics only" in `Coverage > Skipped`. Never assert a runtime bottleneck without evidence. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `performance`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `performance`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/06-tests.md b/plugins/aidd-dev/skills/04-audit/actions/06-tests.md index 36b42e1d9..ae4c12a8e 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/06-tests.md +++ b/plugins/aidd-dev/skills/04-audit/actions/06-tests.md @@ -20,8 +20,8 @@ The `tests` findings, written to `tests.md` in the run's audit folder. - **Skipped tests without a reason**: flag `skip`, `xit`, `xfail`, `.todo`, or equivalent markers that lack an explanatory comment or issue reference. - **Test pyramid imbalance**: flag suites with disproportionately many end-to-end or integration tests and few unit tests, raising maintenance cost and slowing feedback. - When no coverage tool is available, record "no coverage tool, static inspection only" in `Coverage > Skipped` and limit findings to structurally observable issues. Do not invent coverage numbers. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `tests`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `tests`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md index 3f11a649d..fa3cdb447 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md +++ b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md @@ -20,8 +20,8 @@ The `ui` findings, written to `ui.md` in the run's audit folder. - **Responsive breakpoint gaps**: flag components or layouts that break or overflow at standard breakpoints (mobile, tablet, desktop), detectable from markup or media queries. - **Accessibility (WCAG)**: contrast-ratio failures, missing keyboard navigation, incorrect or absent aria roles and labels, missing `alt` text. Run axe or equivalent against the URL when given, otherwise inspect markup statically. - When no URL is given, record "no url provided, runtime a11y pass skipped, static inspection only" in `Coverage > Skipped`. Do not invent runtime findings from static analysis. -3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `ui`. -4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `ui`. +4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 0d9d59d4b..37de2cae9 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -14,7 +14,7 @@ Rows in the `Findings` table of the feature folder's `review.md`, kind `code`, e 1. **Resolve.** Take the diff from the arguments, otherwise the diff against the repository default branch. 2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Rule conformance is the relevancy lens, not this one. -3. **Rate.** One row per issue, rated per `@../references/review-rubric.md`, citing a `file:line`. +3. **Rate.** One row per issue, rated per [review-rubric.md](../references/review-rubric.md), citing a `file:line`. 4. **Record.** Append one row per finding to the `Findings` table: kind `code`, Phase the plan phase the file falls in or `-`. Write "None." when the run found nothing. ## Test diff --git a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md index 30b011ce9..c892bf1c8 100644 --- a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md +++ b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md @@ -13,12 +13,12 @@ A one-line root cause, the 3 to 5 hypotheses with their confidence and validated ## Process 1. **Summarize.** Restate the issue in your own words. -2. **Map.** Draw the action paths as a Mermaid flowchart (a click calls a function in one file that updates state in another), per `@../references/mermaid-conventions.md`. +2. **Map.** Draw the action paths as a Mermaid flowchart (a click calls a function in one file that updates state in another), per [mermaid-conventions.md](../references/mermaid-conventions.md). 3. **Whys.** Start from the symptom and ask "why" iteratively, three to five levels, each documented in a numbered list. 4. **Tools.** Identify the inspection tools available (MCP, CLI commands, logs, traces). 5. **Locate.** Find the relevant files in the codebase for the issue. 6. **Causes.** List 3 to 5 potential causes in a table: analysis, evidence, confidence (1 to 10). -7. **Track.** Record one task per hypothesis in the project task system, filling `@../assets/task-template.md`. +7. **Track.** Record one task per hypothesis in the project task system, filling [task-template.md](../assets/task-template.md). 8. **Validate.** Work the hypotheses one by one, ticking each as validated or invalidated with evidence in the task. Stop when the root cause is found. 9. **Conclude.** State the conclusion and next steps. 10. **Confirm.** Wait for user validation before moving on. diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md index 371ff9e83..a96224abe 100644 --- a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md +++ b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md @@ -22,9 +22,9 @@ The tracking file at `aidd_docs/tasks/.md`, marked created or resumed 5. **Condition.** It must be a runnable command. `npm test exits 0` is valid; "the code is clean" is invalid and is pushed back to `eslint . exits 0`. 6. **Pre-flight.** For each step, list tools, secrets, API access, data, and permissions. Mark `[✓]` already satisfied, `[~]` soft (the agent self-serves), `[!]` hard (only the user can provide it). Collect every `[!]` now; when any stays unresolved, stop before the next step. 7. **Map.** Project the whole path as an ASCII map of steps, dependencies, tools, and blockers. Ask the user to confirm and iterate until they do. -8. **Scaffold.** Load `@../assets/plan-template.md`, creating `aidd_docs/tasks/` when missing. +8. **Scaffold.** Load [plan-template.md](../assets/plan-template.md), creating `aidd_docs/tasks/` when missing. 9. **Create.** Write `aidd_docs/tasks/.md` from the template. Fill the frontmatter (`objective`, `success_condition`, `iteration: 0`, `status: pending`), the phases with their tasks and acceptance criteria, and the journey map. -10. **Spawn.** Read the orchestrator recipe from `@./03-autonomous-loop.md` and hand it to the Agent tool with `` filled in. +10. **Spawn.** Read the orchestrator recipe from [03-autonomous-loop.md](./03-autonomous-loop.md) and hand it to the Agent tool with `` filled in. ## Test diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md index 6778259c1..853ed248d 100644 --- a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md +++ b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md @@ -16,9 +16,9 @@ The success condition verified and the plan's `status` set to `implemented`, wit 2. **Mark.** Increment `iteration` in the frontmatter, setting `status: in-progress` when still `pending`. 3. **Learn.** Read the Log to learn from prior attempts. 4. **Next.** Find the next unchecked step. -5. **Spawn.** Spawn a worker for that step with `@../assets/autonomous-loop-worker-prompt.md`, passing the step description and the relevant context (objective, rules, prior Log entries for the step). +5. **Spawn.** Spawn a worker for that step with [autonomous-loop-worker-prompt.md](../assets/autonomous-loop-worker-prompt.md), passing the step description and the relevant context (objective, rules, prior Log entries for the step). 6. **Verify.** Read the worker's result, then verify concretely by running a check command, reading a file, or testing the output. Never trust the worker's claim alone. -7. **Record.** Read the worker's outcome. When it stopped at a money or destructive gate, surface the reason to the user and stop the loop; never retry, which would re-trigger the action. On verified success, tick the step `[x]`. On a plain failure, spawn another worker with the error context. Append a Log entry per `@../references/autonomous-loop-log-format.md`. +7. **Record.** Read the worker's outcome. When it stopped at a money or destructive gate, surface the reason to the user and stop the loop; never retry, which would re-trigger the action. On verified success, tick the step `[x]`. On a plain failure, spawn another worker with the error context. Append a Log entry per [autonomous-loop-log-format.md](../references/autonomous-loop-log-format.md). 8. **Loop.** Move to the next unchecked step and repeat from Read. 9. **Evaluate.** Once every step is checked, run the `success_condition` command and verify the result yourself. On success, set `status: implemented` and stop. On failure, add new steps addressing the root cause and continue the loop. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md index 59817d81e..71a034398 100644 --- a/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md +++ b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md @@ -14,7 +14,7 @@ An ordered list of candidate stories, each a title plus a one-line user goal. A 1. **Branch.** If the flag marks a single story, emit one candidate from the scope and stop. Otherwise continue. 2. **Slice.** Cut the epic along user outcomes, not technical layers. Each slice must deliver something a user can perceive. -3. **Check independence.** Reshape any slice that cannot ship without another, so each candidate stands alone (see `@../references/rating.md`). +3. **Check independence.** Reshape any slice that cannot ship without another, so each candidate stands alone (see [rating.md](../references/rating.md)). 4. **Name.** Give each candidate a short title and a one-line goal in user terms. 5. **Confirm.** Show the candidate list and wait for the user to confirm before handing to `03-draft-stories`. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md index 06943b70a..3064ba977 100644 --- a/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md +++ b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md @@ -8,15 +8,15 @@ The confirmed candidate list from `02-split-epic`. ## Output -One drafted story per candidate, each filling `@../assets/user-story-template.md`: the As-a/I-want/So-that statement, Gherkin acceptance criteria, and a functional DoD. +One drafted story per candidate, each filling [user-story-template.md](../assets/user-story-template.md): the As-a/I-want/So-that statement, Gherkin acceptance criteria, and a functional DoD. ## Process 1. **Frame.** Write the As-a/I-want/So-that statement, naming the role, the action, and the outcome. 2. **Criteria.** Write Gherkin scenarios covering at least one nominal case and one error or boundary case. -3. **Done.** Write the functional DoD per `@../references/rating.md`: observable, user-facing conditions only, never technical delivery steps. -4. **Check INVEST.** Verify each story against the six criteria in `@../references/rating.md`. Reshape any story that fails. -5. **Fill.** Render each story into `@../assets/user-story-template.md`, leaving estimation fields for `04-estimate-impact`. +3. **Done.** Write the functional DoD per [rating.md](../references/rating.md): observable, user-facing conditions only, never technical delivery steps. +4. **Check INVEST.** Verify each story against the six criteria in [rating.md](../references/rating.md). Reshape any story that fails. +5. **Fill.** Render each story into [user-story-template.md](../assets/user-story-template.md), leaving estimation fields for `04-estimate-impact`. ## Test diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md index 209248c8d..603552694 100644 --- a/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md +++ b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md @@ -15,9 +15,9 @@ Each story annotated with its estimate or blocking spike, its dependencies, an i 1. **Estimate effort.** Assign story points reflecting relative size. - Send a story that is too large to size back to `02-split-epic`. - When an unknown blocks sizing, discover a capability that records or investigates it. Resume after resolution, or leave the story unsized with the spike as its dependency. -2. **Rate impact.** Assign minor, major, or critic per the impact scale in `@../references/rating.md`. +2. **Rate impact.** Assign minor, major, or critic per the impact scale in [rating.md](../references/rating.md). 3. **Justify.** Write a one-line rationale for each impact rating. -4. **Record.** Fill the estimation block in `@../assets/user-story-template.md` for each story. +4. **Record.** Fill the estimation block in [user-story-template.md](../assets/user-story-template.md) for each story. ## Test diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md index ec5b98f29..9ed218ca1 100644 --- a/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md +++ b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md @@ -8,12 +8,12 @@ The estimated stories from `04-estimate-impact`. ## Output -The stories as a single ordered list, each with a priority rank, ordered by the method in `@../references/rating.md`. +The stories as a single ordered list, each with a priority rank, ordered by the method in [rating.md](../references/rating.md). ## Process 1. **Score.** For each story, weigh delivered value against its story points. -2. **Order.** Sort by descending value-to-effort, then break ties with the lower impact first, per `@../references/rating.md`. +2. **Order.** Sort by descending value-to-effort, then break ties with the lower impact first, per [rating.md](../references/rating.md). 3. **Override.** Pull a story earlier only when a later story depends on it. State that reason on the affected story. 4. **Rank.** Write the priority rank into each story's estimation block. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md index eb355962a..ae83946fe 100644 --- a/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md +++ b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md @@ -13,7 +13,7 @@ One ticket per story created in the configured tracker, each capturing the retur ## Process 1. **Resolve target.** Read the active ticketing tool from project memory. If none is declared, ask the user which tracker to use rather than assuming one. -2. **Gate.** Check every story against the Definition of Ready in `@../references/rating.md`. Send any failing story back to its action. Do not proceed while one fails. +2. **Gate.** Check every story against the Definition of Ready in [rating.md](../references/rating.md). Send any failing story back to its action. Do not proceed while one fails. 3. **Present.** Show the full ranked backlog. Wait for explicit user approval before any write. 4. **Save.** On approval, create one ticket per story in the resolved tracker. Capture the returned id and url for each. 5. **Report.** Return the created stories with their ids and urls, in priority order. diff --git a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md index 2ad3ec9ec..9b4faecd1 100644 --- a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md +++ b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md @@ -13,7 +13,7 @@ The saved PRD at `aidd_docs/tasks//--prd.md`, ## Process 1. **Parse.** Extract the feature scope, goals, and constraints from the description and any user stories. -2. **Draft.** Fill `@../assets/prd-template.md` with its eight sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions. +2. **Draft.** Fill [prd-template.md](../assets/prd-template.md) with its eight sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions. 3. **Validate.** Show the full draft, wait for explicit approval, and re-show after each revision. 4. **Save.** Write the approved PRD to its dated path, creating the month directory when missing. diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index 5f08d7fd5..b1ef4b7b5 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -21,5 +21,5 @@ The path to `spec.md` in the feature folder, drafted from the template, with the ## Test - `spec.md` exists in the feature folder. -- It contains every section the validator marks required in `@../assets/spec-validator.yml`. +- It contains every section the validator marks required in [spec-validator.yml](../assets/spec-validator.yml). - It carries no library name, framework pattern, or source-file layout. diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md index a44844dde..56d1109a0 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -20,5 +20,5 @@ The refined spec at the same path, with the changes applied and any residual `TB ## Test -- The spec still exists at its path and holds every required section in `@../assets/spec-validator.yml`. +- The spec still exists at its path and holds every required section in [spec-validator.yml](../assets/spec-validator.yml). - Every finding is reflected by a change, or by an explicit `TBD: ` when it cannot be resolved. diff --git a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md index b7167e1ac..80650c8f1 100644 --- a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md +++ b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md @@ -9,7 +9,7 @@ Rethink prior work and verify correctness against an agreed plan, then emit a st ## Output -The findings report following `@../assets/report-template.md`: a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections. +The findings report following [report-template.md](../assets/report-template.md): a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections. ## Process @@ -17,8 +17,8 @@ The findings report following `@../assets/report-template.md`: a confidence perc 2. **Challenge.** Challenge own assumptions and the user's decisions. 3. **Scan.** Scan for edge cases, errors, gaps, duplications, and inconsistencies. 4. **Classify.** Classify each finding as Correctness, Deal breaker, or Suggestion. -5. **Score.** Score confidence per the rubric in `@../references/confidence-rubric.md`. -6. **Emit.** Fill `@../assets/report-template.md` verbatim and emit it. +5. **Score.** Score confidence per the rubric in [confidence-rubric.md](../references/confidence-rubric.md). +6. **Emit.** Fill [report-template.md](../assets/report-template.md) verbatim and emit it. ## Test diff --git a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md index 92b3fa539..5049b0ef8 100644 --- a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md +++ b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md @@ -19,7 +19,7 @@ A single confirmation line: `Condense: ON ().` when enabling, or `Condens - `toggle` flips on/off; default level when turning on is `full`. - Off phrases (`stop condense`, `normal mode`) force off. 3. **Emit.** The reply MUST begin with this exact line, filled in and unaltered: `Condense: ON ().` when enabling, or `Condense: OFF.` when disabling. The stats action and the hook parse this line from the transcript, so never paraphrase, decorate, or omit it. -4. **Apply.** Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules and auto-pause passages from `@../references/intensity-levels.md`. +4. **Apply.** Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules and auto-pause passages from [intensity-levels.md](../references/intensity-levels.md). ## Test diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md index 3a7bdb83f..1c9e2a1df 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md @@ -12,10 +12,10 @@ A list of gaps, each with its category, severity, a probe question, and the quot ## Process -1. **Load.** Read the locked categories and their definitions from `@../references/locked-sets.json` and `@../references/categories.md`. +1. **Load.** Read the locked categories and their definitions from [locked-sets.json](../references/locked-sets.json) and [categories.md](../references/categories.md). 2. **Validate.** Check the source. Reject anything outside the working directory or already named `*-shadow-report.md`. 3. **Handle edges.** An empty source stops with a plain warning that there is nothing to scan, emitting no gap. A non-markdown source adds a warning that attribution may be imprecise, then continues. -4. **Scan.** Walk the seven categories in their locked order. Emit one gap per distinct issue, set its severity from `@../references/severity-rubric.md`, and write its question per `@../references/probe-style.md`. +4. **Scan.** Walk the seven categories in their locked order. Emit one gap per distinct issue, set its severity from [severity-rubric.md](../references/severity-rubric.md), and write its question per [probe-style.md](../references/probe-style.md). 5. **Dedupe.** Treat two gaps with the same category and snippet as one. A snippet-less gap falls back to its category plus severity. 6. **Return.** Hand the gaps and warnings to the next action: `03-diff` when a prior report exists, else `02-render-report`. Sorting happens there. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md index 16996ce6d..2f6212112 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md @@ -14,10 +14,10 @@ A markdown report written next to the source, named by stripping the source's la ## Process -1. **Load.** Start from the skeleton in `@../assets/report-template.md`. +1. **Load.** Start from the skeleton in [report-template.md](../assets/report-template.md). 2. **Name.** Derive the report's folder and filename from the source per the rule above. 3. **Warn.** If there are warnings, list them under `## Warnings` at the top. Otherwise omit the block. -4. **Group.** Lay gaps out by category in locked order (`@../references/locked-sets.json`). In plain mode, one heading per category that has a gap. In diff mode, split each category into Closed, Still Open, and Newly Introduced, in that order, dropping empty parts. +4. **Group.** Lay gaps out by category in locked order ([locked-sets.json](../references/locked-sets.json)). In plain mode, one heading per category that has a gap. In diff mode, split each category into Closed, Still Open, and Newly Introduced, in that order, dropping empty parts. 5. **Sort.** Within a part, order gaps blocker, then major, then minor. 6. **Render.** Write each gap as `**[severity]** `, with its snippet as a blockquote on the next line when present. 7. **Count.** Fill the header totals: overall and per severity. In diff mode, count only still-open and newly-introduced gaps. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md index 472c229a7..27bb4772e 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md @@ -14,7 +14,7 @@ A list of claims, each paired with one category from the locked taxonomy. 1. **Read.** Go through the text sentence by sentence. 2. **Decide.** For each sentence, ask whether it states a fact. Split a mixed sentence into its factual part and its opinion part. -3. **Drop.** Discard every non-claim per `@../references/claim-categories.md`: opinion, preference, trivially-known general knowledge, the AI's own intent. +3. **Drop.** Discard every non-claim per [claim-categories.md](../references/claim-categories.md): opinion, preference, trivially-known general knowledge, the AI's own intent. 4. **Tag.** Give each surviving claim one category. When two fit, pick the one routing to the cheapest tier (a repo fact over a hard-to-know fact). 5. **Emit.** Return the claim list. If it is empty, report "no verifiable claims" and stop the skill. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md index 18de95413..70ad3d8d3 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md @@ -12,7 +12,7 @@ A list of verdicts: each claim gains one verdict (verified, refuted, conflict, o ## Process -1. **Walk.** For each claim, walk the cascade in `@../references/verification-cascade.md`: first project memory and docs, then codebase inspection, then web lookup. +1. **Walk.** For each claim, walk the cascade in [verification-cascade.md](../references/verification-cascade.md): first project memory and docs, then codebase inspection, then web lookup. 2. **Route.** Send repo facts to memory and codebase first; send other claims to memory then the web. 3. **Short-circuit.** The first tier that resolves a claim sets its verdict. Do not consult later tiers. 4. **Guard.** Reach the web only after memory and codebase both fail. Prefer one authoritative source, and stop once resolved. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md index 42e4b205a..156599e06 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md @@ -9,19 +9,19 @@ Rewrite the original text on the evidence: cite verified claims, hedge unverifie ## Output -The rewritten answer per `@../assets/report-template.md`, obeying `@../references/report-output-discipline.md`. +The rewritten answer per [report-template.md](../assets/report-template.md), obeying [report-output-discipline.md](../references/report-output-discipline.md). ## Process -1. **Copy.** Start from `@../assets/report-template.md`. +1. **Copy.** Start from [report-template.md](../assets/report-template.md). 2. **Rewrite.** Carry the original text over, appending `[n]` to each verified claim, numbered in reading order. Replace each refuted claim with the corrected fact and cite the contradicting source `[n]`; never restate the false claim as true. 3. **Surface.** For each conflict, state both sides in full ("Source A reports X; source B reports Y"), choosing no winner. 4. **Mark.** Append the exact marker `(unverified - no source found)`, verbatim and unreworded, to each unverified claim. Never delete it, never assert it. 5. **Cite.** Build the `## Sources` block: one numbered entry per source, with its title or file path, location, and the claim it backs. Each side of a conflict gets its own entry. 6. **List.** Add the `## Unverified claims` section only when at least one claim is unverified; otherwise omit it. 7. **Suggest.** When a verified fact is stable (project paths, pinned-version APIs), append one cache-suggestion line with a yes/no recommendation. The skill stores nothing itself: on approval, restate the fact and its source so the user's own memory tooling can keep it. When nothing qualifies, omit the line silently. -8. **Scrub.** Before delivering, re-read the draft line by line against `@../references/report-output-discipline.md`: delete any line that carries a forbidden item, and re-render in plain prose any line an active output mode restyled. Ship plain prose whatever the surrounding style. +8. **Scrub.** Before delivering, re-read the draft line by line against [report-output-discipline.md](../references/report-output-discipline.md): delete any line that carries a forbidden item, and re-render in plain prose any line an active output mode restyled. Ship plain prose whatever the surrounding style. ## Test -- Given one verified claim and one unverified claim, the output carries a `## Sources` section with a `[1]` footnote for the verified claim, an inline `(unverified - no source found)` marker on the other, and none of the forbidden words from `@../references/report-output-discipline.md`. +- Given one verified claim and one unverified claim, the output carries a `## Sources` section with a `[1]` footnote for the verified claim, an inline `(unverified - no source found)` marker on the other, and none of the forbidden words from [report-output-discipline.md](../references/report-output-discipline.md). diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md index ffe29da6e..3f15926e4 100644 --- a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -17,12 +17,7 @@ A report of the repo root, the resolved default branch and provider, and whether 1. **Guard.** If `cwd` is already a git work tree, skip and report `created: false`. 2. **Resolve.** Resolve the default branch and provider; an explicit `default_branch` wins. 3. **Init.** Run `git init -b `. -4. **Contribute.** Write `CONTRIBUTING.md` at the repo root from the template, filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`. - - ```markdown - @../assets/CONTRIBUTING.md - ``` - +4. **Contribute.** Write `CONTRIBUTING.md` at the repo root from the template [CONTRIBUTING.md](../assets/CONTRIBUTING.md), filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`. 5. **Bootstrap.** Commit once so `HEAD` exists and is pushable: `git -C commit --allow-empty -m "chore: initialize repository"`. 6. **Remote.** If `remote_url` is given, run `git -C remote add origin `. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md index 36b5c4e6c..6ef365ec7 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md @@ -12,7 +12,7 @@ The proposed title, body, and base, approved by the user. ## Process -1. **Template.** Load the request template, the project's own when set, else the bundled `@../assets/pull_request.md`. +1. **Template.** Load the request template, the project's own when set, else the bundled [pull_request.md](../assets/pull_request.md). 2. **Write.** Draft a concise title and a body following the template from the change summary. 3. **Confirm.** Show the title, body, and base, apply any overrides, and wait for approval. diff --git a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md index b8c0dcf83..6252bcfb0 100644 --- a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md +++ b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md @@ -16,7 +16,7 @@ The created `v` tag, its bump commit sha, and the release URL, with the 2. **Latest.** Take the latest tag from `git tag --sort=-version:refname | head -1`. When there are no tags, note that there is no prior tag, never inventing one. 3. **Collect.** With a prior tag, list the commits in `..HEAD`. With no prior tag, list every commit on the branch. 4. **Compute.** Use the provided version when given. Otherwise bump major on a `BREAKING CHANGE`, minor on any `feat`, else patch. -5. **Draft.** Fill `@../assets/release-template.md` with the change list, applying any note overrides. +5. **Draft.** Fill [release-template.md](../assets/release-template.md) with the change list, applying any note overrides. 6. **Validate.** Show the full notes, the computed version, and the version-manager files about to change. Wait for explicit approval. 7. **Bump.** Stage the version-manager files and create a `chore: bump version to v` commit. 8. **Tag.** Run `git tag -a v -m `. diff --git a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md index e0419bc5b..fdf50fce6 100644 --- a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md +++ b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md @@ -13,7 +13,7 @@ The created issue's URL and number, with its title and labels. ## Process 1. **Tool.** Use the ticketing tool declared in project memory. Otherwise infer it from the remote URL. -2. **Context.** Load `@../assets/CONTRIBUTING.md` and `@../assets/issue-template.md`, and skim existing open issues via the tool to avoid duplicates. +2. **Context.** Load [CONTRIBUTING.md](../assets/CONTRIBUTING.md) and [issue-template.md](../assets/issue-template.md), and skim existing open issues via the tool to avoid duplicates. 3. **Gather.** Combine the problem description with technical context (stack, repro steps, environment). Ask follow-up questions when required fields are missing. 4. **Research.** Look up official documentation that backs the issue when applicable (linked errors, framework changelog). 5. **Fill.** Write a concise title and body matching the template.