From d8bc6b3abf732cf28371cb2c75931cd668c0297c Mon Sep 17 00:00:00 2001 From: Martin Zeman Date: Mon, 13 Jul 2026 19:12:11 +0200 Subject: [PATCH] feat: add BuildRule skill for authoring module rules --- CHANGELOG.md | 1 + skills/BuildRule/SKILL.md | 53 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 skills/BuildRule/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index be3c388..1aaa499 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Added +- `skills/BuildRule/` — authoring, placement, and validation conventions for behavioral rules (one file one behavior, PascalCase naming, owning-module routing, qualifier directories, token-cost discipline), completing the Build* family - `skills/GuardRails/DestructiveCommandGuard.md` companion (dcg block anatomy and workarounds), `skills/IncrementalEdits/` (revise files as reviewable hunks), `skills/SessionSearch/LocalCheckpoints.md`; updates to SettingsMaintenance, SystemCheck, Wtf, ProvenanceAudit, and the ProvenanceAuditor agent - `skills/InitProject/` — `project` / `atlas` shell functions that scaffold a workshop project spine (git + jj colocate + entire + forge hooks, private/public/assets flow, `.tlp` manifest, vault-mounted `.claude/`) with on-demand satellites (vault folder-note, `~/Data` domain-path mirror granted to agent sessions, private remote). Config in `~/.config/forge/project.yaml` with `FORGE_*` per-shell overrides; `project init` renders `CLAUDE.md.tmpl` into each project's brief - `.githooks/` gains `commit-msg`, `prepare-commit-msg`, `post-commit`, `post-rewrite`, and the pre-entire `pre-push` variant, completing the commit-gate set that `make install` wires via `core.hooksPath`; `BACKLOG.md` tracks module-level follow-ups diff --git a/skills/BuildRule/SKILL.md b/skills/BuildRule/SKILL.md new file mode 100644 index 0000000..fe2ec17 --- /dev/null +++ b/skills/BuildRule/SKILL.md @@ -0,0 +1,53 @@ +--- +name: BuildRule +version: 0.1.0 +description: "Create, validate, or place behavioral rules in forge modules. USE WHEN create rule, new rule, write rule, capture rule, add a rule, graduate a correction or convention to a rule, validate rule, rule conventions, where does this rule belong, or the user runs /Rule." +--- + +# BuildRule + +Author, place, and validate the small always-in-context instruction files that steer every session. A rule is the durable form of a correction: when the user says "always do X" or "never do Y again", it becomes a rule, not a memory. + +## Rule Conventions + +### Shape + +A rule is a single `.md` file in the owning module's `rules/` directory. One file, one behavior — when something goes wrong, the filename names the rule that caused it. The only valid subdirectories are locale (`rules/cs-CZ/`), harness and model qualifiers (`rules/claude/`, `rules/claude/claude-opus-4-6/`), and gitignored `user/` overrides; resolution precedence is in PROV-0005. + +### Naming + +PascalCase, scope + focus, self-explanatory in English: `PreferTrash`, `VerifyClaims`, `NoEmDash`. No spaces, hyphens, or opaque acronyms. The filename is the rule's identity in every error report. + +### Frontmatter + +Optional. When present: `name`, `version`, `description`, `targets` (harness filter), `mode` (`replace` | `append` | `prepend`, qualifier variants only). Assembly strips frontmatter at deploy — never put load-bearing content there. + +### Body + +Concise, actionable prose stating the current truth (PresentTense; no backstory). A wrong/right example pair beats three paragraphs of explanation. No headings needed; max depth 3 if used. Cite sources for factual claims (CiteSources). + +**Every word costs tokens on every interaction** — rules are always in context. If the model already does it unprompted, the rule belongs in a model qualifier directory or nowhere (see OptimizeContext). If it needs more than ~20 lines, it is probably a skill, not a rule. + +### Placement + +Rules are authored in the owning module's `rules/`, never directly in `~/.claude/` (AuthorInModules — deployed files get overwritten on install). Route by subject: version-control behavior → the module owning VersionControl; vault conventions → forge-obsidian; no clear owner → forge-steering. Prefer folding a new constraint into an existing rule on the same subject over creating a near-duplicate file (LessIsMore). + +## Create Workflow + +1. **Distill the behavior** — one sentence stating what must (or must never) happen, generalized beyond the incident that prompted it. Include the why only when the rule is not self-evident. +2. **Find the owner** — `grep -l */rules/*.md` across modules; extend an existing rule if one covers the subject. +3. **Write the file** following the conventions above. +4. **Deploy** — `make install` from the module (or mirror the edit into the deployed `~/.claude/rules/` copy for immediate effect in the current session). +5. **Land it** — commit in the module repo per its VCS flow; rules ride normal PRs. + +## Validate Workflow + +- [ ] Single `.md` file in `rules/` (or a valid qualifier subdirectory) +- [ ] PascalCase filename naming the behavior +- [ ] One behavior; no bundled unrelated constraints +- [ ] Body is present-tense instruction, no narration of what changed +- [ ] Short enough to justify its permanent token cost +- [ ] Not a duplicate — no existing rule covers the same subject +- [ ] Factual claims carry sources + +Report **COMPLIANT** or **NON-COMPLIANT** with specific fixes.