diff --git a/LESSONS.md b/LESSONS.md index 00518a3..1b9a1ed 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -245,3 +245,19 @@ noticed — and before describing any defect as pre-existing, run `git log -S` o plugin-content and vale-style drift deterministically and has no equivalent gate asserting tool-owned paths stay out of formatter scope — `.claude/settings.json` was the sixteenth exclude and nothing prevents a seventeenth. + +## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down + +`skill-author/SKILL.md:204` on `main` said "Keep reference chains one level deep — a reference file +that references another reference file is rarely loaded correctly." The ADR-0020 retrofit replaced it +with "Two hops from `SKILL.md`, never three" in `references/create.md` and `references/retrofit.md`, +which permits exactly the chain the old rule banned. The looser rule is the right one and the +retrofit could not have shipped without it: dispatch pushes each flow into its own file, so the +shipped structure is `SKILL.md` → `improve.md` → `retrofit.md`, and a one-level ceiling would have +made the mandatory dispatch pattern illegal. But ADR-0020 says nothing about chain depth, so the +reversal was carried entirely by the diff — the new text asserts the new rule with no sign that a +contradicting rule ever existed, and a reader who remembers the old one has no way to tell whether it +was overturned or overlooked. Fix: when a change inverts a standing authoring rule rather than +tightening or restating it, record the inversion where the rule's rationale lives — the ADR if the +ADR is the reason, here otherwise. A rule that quietly flips is indistinguishable from a rule that +was forgotten, and the second reading is the one that gets it re-added later. diff --git a/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md b/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md index 2a41718..d3863af 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md @@ -111,9 +111,12 @@ Flag as FAIL if: available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is judgment. - **A boundary clause naming a target that does not resolve** to a real skill directory or agent - file in the authoring source. No script checks this for an agent file — `validate.sh` resolves - boundary targets for skills only, so resolve the name yourself against `plugins/*/.apm/skills/` - and `plugins/*/.apm/agents/`. + file in the authoring source. `validate.sh` resolves this for agent files at both scopes and + reports each unresolved target itself — take its verdict rather than re-resolving the name by + hand, because a hand-walk over a different universe can contradict it. What is left to you is + semantic and the script cannot reach it: whether a target that *does* resolve is the right + sibling to exclude, and whether a clause naming no target at all ("examine the files manually") + should have named one. - **`Use proactively` in a Copilot or vendor-neutral description.** `KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour. diff --git a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md index c7af792..c6ca310 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md @@ -53,6 +53,8 @@ Gates `agent-audit` enforces at every scope: - **Body** — no word gate, and a delegation check in its place: name the skill to invoke rather than restating what it does. - **Invocation** — decide whether the agent is model-delegated or reached only by name. Only Copilot's cloud/IDE format expresses that in frontmatter (`disable-model-invocation`, `user-invocable`). +At every scope, five tools reach no subagent whatever `tools` says — `AskUserQuestion`, `EnterPlanMode`, `ExitPlanMode`, `ScheduleWakeup`, `WaitForMcpServers`. Never write a body that has the agent ask the user a question or enter plan mode; it describes a turn the runtime cannot give it. + ## Step 4 — Validate and close Invoke `agent-audit` on each file written and resolve every FAIL before reporting done. It checks the field allowlist, name-to-stem match, leftover placeholders and template comments, the description budget and the Copilot body limit — do not hand-check those. diff --git a/plugins/kyberforge/.apm/skills/agent-author/assets/templates/claude-code.md b/plugins/kyberforge/.apm/skills/agent-author/assets/templates/claude-code.md index a09f07f..15a4175 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/assets/templates/claude-code.md +++ b/plugins/kyberforge/.apm/skills/agent-author/assets/templates/claude-code.md @@ -25,12 +25,13 @@ description: FILL IN: Use when . Not - + Listing any of them is a finding: agent-audit enforces the flat rule. --> + Listing any of them is a finding: agent-audit enforces the flat rule. -->