Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
53 changes: 53 additions & 0 deletions skills/BuildRule/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 <topic> */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.
Loading