Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(bin): four skills still keep non-spec files at the skill root #122

New Issue
Closed
opened 2026-08-31 08:05:44 +00:00 by Claude · 1 comment
Claude commented 2026-08-31 08:05:44 +00:00
Collaborator
Copy Link

Found during the #99 ADR-0020 retrofit and the follow-up audit pass on refactor/adr0020-skill-retrofit. Deliberately left unfixed there — same class as #114, which has since been fixed for prototype.

The rule

plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md:20:

  • No non-spec files at the skill root: no META.md, no stray config outside the four directories.

Four permitted directories only: scripts/, references/, assets/, tests/. SKILL.md and README.md are the only spec files at the root.

What is still there

Verified by ls on each skill root in the working tree:

skill non-spec root files
bin/grill-with-docs ADR-FORMAT.md, CONTEXT-FORMAT.md
bin/improve-codebase-architecture DEEPENING.md, INTERFACE-DESIGN.md, LANGUAGE.md
bin/tdd deep-modules.md, interface-design.md, mocking.md, refactoring.md, tests.md
bin/triage AGENT-BRIEF.md, OUT-OF-SCOPE.md

bin/prototype is now clean — its two flow files sit in references/ (logic.md, ui.md), which is #114 landing.

Why it is not cosmetic

This is the reason #114 was worth doing. A file outside references/ is invisible to the deterministic dangling-reference ERROR: the ADR-0020 gate resolves an unqualified references/… pointer against the skill's own directory and fails when it does not exist. A link to a root-level LANGUAGE.md is checked by nothing, so a typo in it fails silently at runtime — the agent follows a dead link mid-procedure and improvises.

These files are live targets, not dead weight. improve-codebase-architecture/SKILL.md links LANGUAGE.md three times and INTERFACE-DESIGN.md once; INTERFACE-DESIGN.md links DEEPENING.md three times and LANGUAGE.md twice; DEEPENING.md links LANGUAGE.md once; triage/SKILL.md links AGENT-BRIEF.md twice and OUT-OF-SCOPE.md twice; grill-with-docs/SKILL.md links CONTEXT-FORMAT.md and ADR-FORMAT.md once each.

The cross-skill consequence

grill-with-docs's two root files are cited from a sibling skill, so moving them is not a self-contained edit. improve-codebase-architecture/SKILL.md currently reads:

…same discipline as grill-with-docs, in the format grill-with-docs's CONTEXT-FORMAT.md defines.

…See grill-with-docs's ADR-FORMAT.md.

That possessive spelling is the one form file-structure.md sanctions for a cross-skill reference (it was ../grill-with-docs/CONTEXT-FORMAT.md until commit 03abcff — see the second half of the body-routing issue filed alongside this one). Moving the files to grill-with-docs/references/ makes both citations stale, and neither is checked by any gate. Update them in the same change.

Also worth confirming during the move

Each skill's README.md file table must list every file that exists with no stale rows (file-structure.md, Internal consistency). grill-with-docs/README.md and triage/README.md both currently describe these as "Skill-root document" in their tables; those rows change with the files.

Files

  • plugins/bin/.apm/skills/{grill-with-docs,improve-codebase-architecture,tdd,triage}/ — and only the .apm/ copies; plugins/bin/skills/ is the generated mirror
  • plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md:20 — the rule

Related

  • #114 — the same finding for prototype, now fixed
  • #99 — the retrofit during which this surfaced
Found during the #99 ADR-0020 retrofit and the follow-up audit pass on `refactor/adr0020-skill-retrofit`. Deliberately left unfixed there — same class as #114, which has since been fixed for `prototype`. ## The rule `plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md:20`: > - No non-spec files at the skill root: no `META.md`, no stray config outside the four directories. Four permitted directories only: `scripts/`, `references/`, `assets/`, `tests/`. `SKILL.md` and `README.md` are the only spec files at the root. ## What is still there Verified by `ls` on each skill root in the working tree: | skill | non-spec root files | |---|---| | `bin/grill-with-docs` | `ADR-FORMAT.md`, `CONTEXT-FORMAT.md` | | `bin/improve-codebase-architecture` | `DEEPENING.md`, `INTERFACE-DESIGN.md`, `LANGUAGE.md` | | `bin/tdd` | `deep-modules.md`, `interface-design.md`, `mocking.md`, `refactoring.md`, `tests.md` | | `bin/triage` | `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md` | `bin/prototype` is now clean — its two flow files sit in `references/` (`logic.md`, `ui.md`), which is #114 landing. ## Why it is not cosmetic This is the reason #114 was worth doing. A file outside `references/` is invisible to the deterministic dangling-reference ERROR: the ADR-0020 gate resolves an unqualified `references/…` pointer against the skill's own directory and fails when it does not exist. A link to a root-level `LANGUAGE.md` is checked by nothing, so a typo in it fails silently at runtime — the agent follows a dead link mid-procedure and improvises. These files are live targets, not dead weight. `improve-codebase-architecture/SKILL.md` links `LANGUAGE.md` three times and `INTERFACE-DESIGN.md` once; `INTERFACE-DESIGN.md` links `DEEPENING.md` three times and `LANGUAGE.md` twice; `DEEPENING.md` links `LANGUAGE.md` once; `triage/SKILL.md` links `AGENT-BRIEF.md` twice and `OUT-OF-SCOPE.md` twice; `grill-with-docs/SKILL.md` links `CONTEXT-FORMAT.md` and `ADR-FORMAT.md` once each. ## The cross-skill consequence `grill-with-docs`'s two root files are cited from a *sibling* skill, so moving them is not a self-contained edit. `improve-codebase-architecture/SKILL.md` currently reads: > …same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. > …See `grill-with-docs`'s `ADR-FORMAT.md`. That possessive spelling is the one form `file-structure.md` sanctions for a cross-skill reference (it was `../grill-with-docs/CONTEXT-FORMAT.md` until commit `03abcff` — see the second half of the body-routing issue filed alongside this one). Moving the files to `grill-with-docs/references/` makes both citations stale, and neither is checked by any gate. Update them in the same change. ## Also worth confirming during the move Each skill's `README.md` file table must list every file that exists with no stale rows (`file-structure.md`, Internal consistency). `grill-with-docs/README.md` and `triage/README.md` both currently describe these as "Skill-root document" in their tables; those rows change with the files. ## Files - `plugins/bin/.apm/skills/{grill-with-docs,improve-codebase-architecture,tdd,triage}/` — and only the `.apm/` copies; `plugins/bin/skills/` is the generated mirror - `plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md:20` — the rule ## Related - #114 — the same finding for `prototype`, now fixed - #99 — the retrofit during which this surfaced
Claude added this to the Skills & Agents milestone 2026-08-31 08:05:44 +00:00
Claude added the Kind/Enhancement
Reviewed
Confirmed
1
Priority
Medium
3
 labels 2026-08-31 08:05:44 +00:00
Claude commented 2026-09-09 20:13:01 +00:00
Author
Collaborator
Copy Link

Opened #133 implementing this — moved and renamed all 12 files to lowercase-kebab-case under references/ across the four skills, fixed the cross-skill citation and every in-skill link (including stale link text), updated the four README.md file tables, and resynced the content mirror. Full test suite and pre-push gate both green.

Opened #133 implementing this — moved and renamed all 12 files to lowercase-kebab-case under references/ across the four skills, fixed the cross-skill citation and every in-skill link (including stale link text), updated the four README.md file tables, and resynced the content mirror. Full test suite and pre-push gate both green.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Enhancement
Priority
Medium
3
Reviewed
Confirmed
1
Milestone
No items
No Milestone Skills & Agents
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#122
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?