General: Move on-demand agent docs out of the always-loaded rules - #37
Merged
Conversation
Finishes the restructuring #36 landed half of: rules/release.md was renamed to skills/release/SKILL.md there as a pure rename, so it has been sitting in main without YAML frontmatter and cannot load as a skill. Three bodies of reference now live in .claude/skills/, each with frontmatter, and the always-loaded rules keep only what every session needs: - release — regains its frontmatter, and takes back the screenshot workflow that build-commands.md was duplicating - device-qualification — qualification protocol, verified-device ledger and per-OEM known gaps, out of privileged-access.md - oem-adapters — per-OEM adapter detail (keys, value domains, write ordering, session overrides), out of architecture.md Content is unchanged in the move. architecture.md goes 208 -> 95 lines and privileged-access.md 231 -> 136; each keeps a pointer to its skill, and CLAUDE.md states the no-nested-CLAUDE.md rule explicitly so the adapter detail is not re-nested next to the code later. Source comments that pointed at the ledger in .claude/rules/privileged-access.md now point at the skill. Comment-only; compileFossDebugKotlin passes. The CLAUDE.md status line claimed 0.1.0-beta1 and now defers to VERSION.
d4rken
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
No user-facing behavior change — this is AI-assistant documentation under
.claude/plus four source comments.The repository guidance is split into what every session needs (always-loaded
.claude/rules/) and what only some sessions need (.claude/skills/, loaded on demand).Technical Context
Why now: #36 renamed
.claude/rules/release.md→.claude/skills/release/SKILL.mdas a pure rename with zero content change. A skill needs YAML frontmatter (name,description) to be loadable, soreleasehas been sitting inmainas a broken skill since that commit. This PR finishes the restructuring it started.What moved (content is unchanged in each move — verified verbatim):
skills/releaserules/build-commands.mdwas duplicatingskills/device-qualificationrules/privileged-access.mdskills/oem-adaptersrules/architecture.mdrules/architecture.mdgoes 208 → 95 lines,rules/privileged-access.md231 → 136. Each keeps a pointer to its skill, so the reading path from "I'm touching control code" to the adapter/ledger detail is still one hop.No nested
CLAUDE.md. An earlier draft of this work put the adapter detail inapp/src/main/java/eu/darken/amply/charging/CLAUDE.mdto get directory-scoped auto-loading. That is not a pattern this repo wants, so it became a skill instead, and.claude/CLAUDE.mdnow states the rule explicitly to stop it being re-nested next to the code later.Source comments: four files referenced the qualification ledger at
.claude/rules/privileged-access.md, which no longer holds it — they now point at.claude/skills/device-qualification/. Comment-only edits;compileFossDebugKotlinpasses.SettingsSnapshotSource.ktstill points atprivileged-access.mdfor the wizard rules, which is correct — that section did not move.Also:
.claude/CLAUDE.mdclaimed status0.1.0-beta1(actual:0.2.1-beta0); it now defers toVERSIONso it cannot drift again.Review guidance
Diff is large but almost entirely relocation. The parts worth actually reading are the three skill frontmatter blocks (do the
descriptionfields describe when to invoke them accurately?) and the pointer lines left behind inrules/architecture.md,rules/privileged-access.md,rules/agent-instructions.md, and.claude/CLAUDE.md.