t1k:rule-creator

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	t1k-maintainer
Version	2.18.3
Effort	medium
Tools	AskUserQuestion, Bash, Edit, Glob, Grep, Read, Write

Keywords: context budget, create rule, dedupe rules, optimize rule, rule, rules budget, trim rule, update rule

How to invoke

/t1k:rule-creator
[rule-name] [create|update|optimize|audit|validate]

---

Rule Creator

Create, update, or optimize TheOneKit behavioral rules — the .claude/rules/*.md files that auto-load into every session as normative behavioral contracts. Rules differ from skills/agents in three ways that define this skill: no t1k- prefix, minimal frontmatter, and a hard context-budget ceiling (every rule token ships into every session, forever).

Is it actually a rule? (classify first — MANDATORY)

Question	If yes
Should Claude follow this on every task, unprompted?	Rule → continue here
Is it a capability the user invokes for a task?	Skill → /t1k:skill-creator, stop
Is it a sub-persona spawned to do work?	Agent → /t1k:agent-creator, stop

If it isn’t an every-session behavioral contract, route to the right creator and stop. Rules are the most expensive surface (always-loaded) — the bar for adding one is high.

Required frontmatter (rules are minimal)

Rules have no name / description / keywords / body-version. Only:

Field	Notes
origin	Hand-stamp on creation (e.g. theonekit-core). Validator enforces presence.
repository	Hand-stamp (e.g. The1Studio/theonekit-core).
module	Hand-stamp — decides budget counting (see below). null = kit-wide core.
protected	Hand-stamp (true for kit-shipped rules).

Preserve the existing cosmetic blank line after the opening --- if the kit’s other rules use it. Rules auto-discover — they are NOT listed in module.json.skills (the packager copies rules/*.md wholesale; the manifest walks the tree). Only the module: frontmatter assigns ownership.

Naming — NO t1k- prefix

Unlike skills/agents, rules are kebab-case describing the rule (prefer-local-over-global-edits.md, branch-discipline.md) — the t1k- naming-convention gate does not apply to rules. Filename = the slug; there is no colon-form.

⚖️ Context-budget discipline — the defining constraint

Every rule auto-loads into every session, so .claude/rules/*.md is capped:

• Hard cap: 16,500 tokens total across all always-loaded rules (validate-context-window-budget.cjs). Exceeding it blocks every release in the kit.
• Only rules owned by REQUIRED modules count (module: null or a required module). Rules owned by an optional module are opt-in and excluded — a lever for niche rules.
• Before adding or growing a rule, run the gate to see headroom. If near the cap, trim first.
• Trim-to-docs pattern (#362): keep the normative core (MUST/MUST-NOT + the one actionable table/snippet) in the rule; move examples, rationale, history, recovery, enforcement to docs/<rule-name>.md under a ## Full details pointer. The rule must stay self-sufficient — a consumer who never opens the doc still gets the complete contract.
• Ship the docs companion so the pointer resolves for consumers (docs-shipping pipeline — references/architecture-rules.md § Docs companions).

No inline universal boilerplate · dedup is SSOT

validate-no-inline-universal-rules.cjs blocks inlining security / AI-driven / fork-hygiene boilerplate into skills/agents because it lives in rules. When authoring a rule: never duplicate another rule’s content — cite it (rules/<other>.md) in ## Related. Dedup is both a quality win and a budget win.

Canonical rule body (in order)

1. # Title
2. ## Rule — the normative contract (MUST / MUST-NOT / NEVER / ALWAYS), tight.
3. ## Why — 1–3 lines; if longer, move to docs.
4. ## How to apply — concrete, actionable steps.
5. ## Full details — docs/<name>.md pointer (only if trimmed).
6. ## Related — SSOT links to sibling rules (this is the dedup mechanism).

Auto-register (fast path) — never hand-stamp + hand-place

Per rules/replicate-and-automate.md: don’t repeat the manual create-file → stamp-frontmatter → place-in-right-dir → regen dance. Use the scaffolder:

t1k rule new <name> --module <owner>     # module-owned → .claude/modules/<owner>/rules/<name>.md
t1k rule new <name> --universal          # kit-wide    → .claude/rules/<name>.md (module: null)

It stamps origin/repository/module/protected, seeds the canonical body skeleton, and regenerates t1k-modules.json (via generate-modules-registry.cjs). You then fill the normative body and run the budget gate. Requires CLI ≥ 5.4.0 (t1k --version).

Manual fallback (CLI < 5.4.0): place the file yourself — .claude/modules/<owner>/rules/<name>.md (module-owned) or .claude/rules/<name>.md (module: null, universal); hand-stamp frontmatter; if the owning module’s activation changed, run node <release-action>/scripts/generate-modules-registry.cjs <kit-root> and stage t1k-modules.json in the SAME commit (rules/module-registry-sync.md).

Operations

Op	What it does
create	New rule: classify → t1k rule new (or manual) → draft tight → budget-check → (no module.json edit; rules auto-discover)
update	Edit existing; preserve the normative contract; re-run budget gate
optimize	Trim a bloated rule into docs/ (#362 pattern) + dedup vs siblings; re-run budget gate until green
audit	List rules by token size (for f in .claude/rules/*.md; do echo "$((wc -c<$f/4)) $f"; done | sort -rn); flag bloat + dup clusters + budget headroom
validate	Run validate-context-window-budget.cjs + validate-no-inline-universal-rules.cjs (exit 0 = pass)

Process

1. Classify (table above). Not a rule → route + stop.
2. Read 2 existing rules of similar shape + run the budget gate for current headroom.
3. Draft / edit — tight normative core; move detail to a docs/ companion if it would push the always-loaded budget.
4. Hand-stamp frontmatter (origin/repository/module/protected); set module: correctly (drives budget counting).
5. Run the gates — budget + no-inline. Both MUST exit 0. If budget red, optimize (trim/dedup) before proceeding.
6. Ship-back — kit-owned rule edits land in the kit source (rules/kit-wide-fix-discipline.md); recommend /t1k:sync-back from a consumer.

Anti-patterns

Anti-pattern	Severity	Fix
Adding a rule when it’s really a skill/agent	High	Classify first; route to the right creator
t1k- prefix on a rule filename	Medium	Rules are NOT prefixed — kebab slug only
Growing rules past the 16,500 cap	Blocker	Trim-to-docs (#362) + dedup before adding
Detail-heavy rule (examples/history inline)	High	Move to docs/<name>.md; keep normative core + pointer
Trim that drops the normative contract	Blocker	The rule body must stay self-sufficient; only move non-normative detail
Duplicating another rule’s content	Medium	Cite it in ## Related (SSOT)
docs/ pointer that doesn’t ship	High	Ensure the companion ships (docs-shipping pipeline)
Wrong module: value	Medium	Drives budget counting + origin; stamp the owning module

Full canon: references/architecture-rules.md · Pre-merge checklist: references/validation-checklist.md