| name | agile:rules:code |
| description | Authoring + governance tool for SSO Tier-1 code rules in `.claude/rules/` (architecture, code-style/{kotlin,java,typescript,html,scss,frontend}, dependencies, testing, workers). Creates new rule files, refines wording, validates citation integrity, and detects misalignment with the constitution — orphan citations (rule cites missing principle), orphan-range citations, stale citations (cited principle was redefined), missing extractions (constitution principle has code-level guidance with no extracting rule), modality drift (MUST/SHOULD flips), wrong-domain citations, inheritance drift, and registry drift. Orchestrates a five-agent expert team (researcher, thinker, grounder, technical, reviewer) so no code-rule change ships without multi-perspective review and no rule drifts from the constitution unnoticed. Use this skill whenever the user wants to create, update, enhance, refine, validate, list, compare, detect, align, or sync a code rule; whenever they mention `.claude/rules/`, "code style", "naming convention", "package management", "package versions", "directory structure", "rule citation", "extract principle", "rule frontmatter", "paths glob", or any rule file under `code-style/`, `architecture/`, `dependencies/`, `testing/`, or `workers/`; whenever they want to bump a code-rule version; or after any constitution change to detect downstream rule drift. Also use proactively when code-rule citations stop matching the constitution registry. |
| user-invocable | true |
| disable-model-invocation | false |
| allowed-tools | Read, Edit, Write, Glob, Grep, Bash, Agent, Skill, TaskCreate, TaskList, TaskGet, TaskUpdate, AskUserQuestion, SlashCommand |
Agile Rules Code
Authoring and governance tool for SSO Tier-1 code rules at .claude/rules/.
This skill is the complement to agile-rules-constitution — that skill
authors the Tier-2 constitution at .agile/rules/; this one authors the
Tier-1 compact code rules that extract principles into actionable form.
Together they form the read/write halves of the rules system. Constitution
is the higher authority. Code rules MUST cite (extract) constitution
principles. When the two diverge, this skill detects it.
Tier Architecture
.agile/rules/ Tier 2 (HIGHER AUTHORITY)
├── constitution.md # MASTER:I-XXII (+EPIC:I-III)
├── index.md # Registry (Tier 1 ↔ Tier 2)
├── backend/constitution.md # BACKEND:I-XIV
├── common/constitution.md # COMMON:I-IX
├── services/constitution.md # SERVICES:I-VIII
├── workers/constitution.md # WORKER:I-V
└── frontend/constitution.md # FRONTEND:I-XII
.claude/rules/ Tier 1 (DERIVED, AUTO-LOADED)
├── architecture/{naming,entity-packages, # Each rule cites ≥1
│ import-hierarchy,configuration}.md # constitution principle
├── code-style/{kotlin,java,typescript, # via `extracts:` frontmatter
│ html,scss,frontend}.md # AND `> Source:` footers
├── dependencies/management.md
├── testing/conventions.md
└── workers/patterns.md
Precedence: Constitution > Code rules > Code. A code rule can NEVER
weaken or contradict the principle it extracts.
Sub-Commands
| Command | Effect | Version bump | Agents |
|---|
create --domain <d> --rule <name> | New code rule file | initial 1.0.0 | all five |
update --domain <d> --rule <r> | Add / remove / redefine constraint | MAJOR or MINOR | all five |
enhance --domain <d> --rule <r> | Expand existing constraint, add example | MINOR | all five |
refine --domain <d> --rule <r> | Wording / typo fix | PATCH | researcher + technical + reviewer |
validate [--domain <d>] [--rule <r>] | Compliance check (read-only) | none | reviewer |
list | Registry display (read-only) | none | none |
compare <r1> <r2> | Constraint diff (read-only) | none | researcher |
detect [path] | Domain detection (read-only) | none | none |
align | Detect constitution↔code-rule misalignment (read-only) | none | researcher + grounder + reviewer |
sync | Apply auto-fixes + reconcile registry | bumps as needed | grounder + reviewer |
For a deeper reference of each command, see references/command-reference.md.
The align sub-command is the alignment-detection workhorse. It walks
every code rule, validates citations against the constitution registry,
detects orphan/stale/missing/duplicate cases, and emits a Code Alignment
Report without writing anything by default (use --write to persist
the report; sync is the surgical write companion).
Five-Agent Expert Team
Authoring commands dispatch the team via the Agent tool, using the prompt
templates in agents/. Each agent has one job; together they
form a defense-in-depth review.
| Agent | File | Role | Stops the change? |
|---|
| Researcher | agents/researcher.md | Reads current state of the rule + cited principles + peer rules | No |
| Thinker | agents/thinker.md | Drafts rule body + frontmatter + version + citation footers | Proposes only |
| Grounder | agents/grounder.md | Verifies legitimacy (citations resolve, paths legitimate, scope fits domain, no master conflict) | YES — BLOCKED halts |
| Technical | agents/technical.md | Two-section pass: (A) blast radius (factual) + (B) enforceability (judgmental). Merges constitution skill's Investigator + Critic | YES — REJECT halts |
| Reviewer | agents/reviewer.md | Final gate: frontmatter integrity, version arithmetic, citation footer presence, paths glob syntax, index row update, ISO date hygiene | YES — FAIL halts |
If any of grounder/technical/reviewer halts, no file is written. The
skill reports blockers to the user and exits cleanly. Re-dispatching the
thinker is allowed; the team re-runs against the revised proposal.
User Input
$ARGUMENTS
You MUST parse the user's command from $ARGUMENTS before proceeding. The
first token is the sub-command; subsequent tokens are flags and values.
Example invocations:
/agile:rules:code list
/agile:rules:code align
/agile:rules:code validate --rule code-style/kotlin
/agile:rules:code create --domain code-style --rule json
/agile:rules:code refine --domain testing --rule conventions
/agile:rules:code sync
Hard Gates
These cannot be bypassed:
- Reviewer veto: If the reviewer issues
FAIL, no file is written.
- Constitution Citation Gate: For
create/update/enhance, every
proposed citation in the extracts: array MUST resolve to an actual
principle in the constitution. Unknown IDs trigger an AskUserQuestion
prompt: (a) pick a valid ID, (b) escalate to /agile:rules:constitution
to add the principle first, (c) abort. This gate prevents the most common
drift at source.
- Drift Impact Report: Every command that writes a code rule prepends
a Drift Impact Report (per
templates/code-rule-template.md)
listing affected globs and downstream skill references.
- Frontmatter integrity:
version:, last_amended:, extracts:,
paths: are required on every rule file. Reviewer FAILs on missing fields.
- Frontmatter ↔ footer sync:
extracts: array MUST list every ID also
appearing in > Source: footers, and vice versa. Mismatch is category CO.
Phase Flow
Phase 1 — Parse and Pre-flight
- Parse
$ARGUMENTS into <sub-command> and flags. If unrecognized, print
the sub-commands table and exit.
- For commands that take
--domain, validate against the 5-domain taxonomy
(architecture, code-style, dependencies, testing, workers).
For create, validate --rule <name> is not yet registered.
- Run
scripts/code-rule-detect.sh --json <pwd> if --rule not given;
infer the target rule from working directory or input path.
- Run
scripts/registry-sync.sh --json to load current rule metadata
(versions, last_amended, citation health). Cache for downstream agents.
Phase 2 — Authoring Path Selection
Based on the sub-command, choose the path:
- list, detect, compare — produce read-only output, no team needed.
- validate — dispatch reviewer only.
- align — dispatch researcher + grounder + reviewer (read-only).
- sync — dispatch grounder + reviewer; writes are gated per finding by
AskUserQuestion.
- refine — dispatch researcher + technical + reviewer.
- create, update, enhance — full five-agent team.
Phase 3 — Constitution Citation Gate (only for create/update/enhance)
Before dispatching the team, pre-validate the proposed extracts: IDs with
scripts/validate-citations.sh. If any cited principle does not exist in
the constitution, use AskUserQuestion:
"Citation {ID} does not exist in any constitution. Choose:
(a) Pick a valid ID from the list shown
(b) Escalate to /agile:rules:constitution to author the missing principle first
(c) Abort"
Record the resolution in session state. Forward to the grounder.
Phase 4 — Capture User Intent
Use AskUserQuestion (or read prior conversation) to capture a one-paragraph
description of the intended change. This becomes the {{user_intent}} input
to every agent prompt template.
Phase 5 — Dispatch the Team
For each agent in the chosen path, populate its prompt template (substituting
the {{...}} placeholders) and dispatch via the Agent tool. Use
subagent_type per the agent files.
The dispatch order is research-then-propose-then-judge:
- Researcher (always first; output feeds everyone)
- Thinker (consumes researcher output)
- Grounder + Technical (parallel; both consume thinker proposal)
- Reviewer (last; consumes everything)
| Agent | subagent_type |
|---|
| Researcher | Explore |
| Thinker | clean-architect (or general-purpose if unavailable) |
| Grounder | general-purpose |
| Technical | code-reviewer |
| Reviewer | agile-validator |
Phase 6 — Reviewer Verdict Handling
| Verdict | Action |
|---|
| PASS | Proceed to write. |
| PASS_WITH_FOLLOWUPS | Proceed to write. Create one TaskCreate entry per follow-up. |
| FAIL | Do not write. Report blockers verbatim. Offer to re-dispatch the thinker with the technical agent's required edits. |
Phase 7 — Writes (only on PASS)
In one logical change set:
- Prepend the Drift Impact Report HTML comment to the target rule file
(per
templates/code-rule-template.md).
- Apply the rule body edits (using
Edit against the existing file, or
Write for create).
- Update
version: and last_amended: in frontmatter (PATCH bump for
refine; MINOR/MAJOR per thinker proposal for others).
- Update
.agile/rules/index.md Tier 1 Rules table row (regenerated from
scripts/registry-sync.sh --markdown).
- For
align --write, write .agile/rules/code-alignment-report.md.
- For
sync, update .agile/rules/.alignment-state.json (state file
tracking last successful run hashes).
Phase 8 — Confirmation Output
Print a concise summary:
✓ <domain>/<rule> v<old> → v<new>
✓ Citations: <N> verified (<n_dangling> dangling, <n_stale> stale)
✓ Paths: <N> files in scope
✓ Index registry: row updated
ℹ Follow-ups queued: <count>
For align:
✓ Code Alignment scan complete
Files scanned: <N> rules / <M> citations
Verdict: {PASS | PASS-WITH-WARNINGS | FAIL}
Severity counts: BLOCKER=<n> HIGH=<n> MEDIUM=<n> LOW=<n>
Categories: {OC, OR, SC, MX, ...}
Report written: .agile/rules/code-alignment-report.md
ℹ Run `/agile:rules:code sync` to apply auto-class fixes
Triggers (when to invoke this skill)
Invoke whenever the user mentions any of:
.claude/rules/, "code rule", "compact rule", "Tier 1 rule"- "Code style", "naming convention", "package management", "package versions",
"directory structure", "import hierarchy"
- "Rule citation", "extract principle", "rule frontmatter", "paths glob",
"extracts field", "Source footer"
- A specific code-rule file (e.g.,
code-style/kotlin.md, architecture/naming.md)
- A version bump on
.claude/rules/* files
- "Add a code rule", "update the kotlin rule", "refine the testing conventions"
- The slash command
/agile:rules:code
- "Misalignment", "drift", "alignment report", "constitution mismatch"
(use the
align sub-command)
Also invoke proactively when:
- A constitution amendment via
/agile:rules:constitution may have
invalidated downstream code rules — run align to detect.
- A nightly drift check has flagged mismatch between
.claude/rules/ and
the registry.
- A code review notes that a rule's wording diverges from the cited principle.
When NOT to Invoke
- Constitution amendments — that's
/agile:rules:constitution.
- Compliance checking of an artifact — that's the
validate sub-command, but
for implementation code (not rule files), use the validation gates in
agile-epic-validate.
- Drafting feature specs — that's
agile-epic-brainstorm / agile-epic-plan.
- Modifying constitution principles directly — escalate to
/agile:rules:constitution. This skill cannot create/edit principles; it
can only consume and cite them.
References (load on demand)
Templates (used at runtime)
Scripts (self-contained, see scripts/)
| Script | Purpose |
|---|
code-rule-detect.sh | Map a path/glob → owning code-rule file |
extract-citations.sh | Parse > Source: footers + extracts: frontmatter from a rule |
extract-paths.sh | Parse paths: glob arrays |
validate-citations.sh | Cross-check every footer ID against the constitution registry |
detect-orphan-principles.sh | Find constitution principles with zero extracting code rule |
detect-stale-citations.sh | Find code rules whose last_amended predates the cited principle's last edit |
alignment-report.sh | Compose all detectors → JSON for the alignment report |
registry-sync.sh | Regenerate the Tier 1 Rules table in .agile/rules/index.md |
semver-bump.sh | Per-rule SemVer arithmetic helper |
All scripts are read-only and self-contained — they do not modify any file
under .claude/rules/ or .agile/rules/. Writes are performed only by the
SKILL.md flow after the reviewer issues PASS.
Samples (worked examples)
Examples
List the Tier 1 Rules registry
/agile:rules:code list
Runs scripts/registry-sync.sh --markdown. No team dispatched.
Detect domain for a path
/agile:rules:code detect .claude/rules/code-style/kotlin.md
/agile:rules:code detect services/sso-m40/src/main/kotlin/Foo.kt
Runs scripts/code-rule-detect.sh. Returns the owning rule file (or "no
matching rule") and the cited principles.
Validate a single rule
/agile:rules:code validate --rule code-style/kotlin
Dispatches reviewer only. Produces a per-check report (frontmatter,
citations, paths, footer integrity). Sample in
samples/sample-validation-report.md.
Detect alignment drift (THE KEY OPERATION)
/agile:rules:code align
/agile:rules:code align --write # also persist the report file
Read-only by default. Walks every rule, validates every citation, detects
all 19 categories of misalignment, emits a structured report. With --write,
also writes .agile/rules/code-alignment-report.md. Sample in
samples/sample-alignment-report.md.
Reconcile drift
/agile:rules:code sync
After align flags drift, sync walks each finding and applies fixes:
- Auto-class (DUP, FF, REGD, CO, ID, VD, PA, TX) — applied without prompt
- Semi-auto class (OR, MX, DUPX) — proposed via
AskUserQuestion
- Manual class (OC, OD, SC, SR, CT, MD, PD, CG) — created as
TaskCreate
follow-ups for human decision
Refine wording (typo fix)
/agile:rules:code refine --domain testing --rule conventions
Lighter path: researcher + technical + reviewer. Always PATCH bump. Walkthrough
in samples/sample-rule-refinement.md.
Create a new rule
/agile:rules:code create --domain code-style --rule json
Full five-agent team. Constitution Citation Gate prompts for which principles
the new rule extracts. MINOR bump (initial 1.0.0). Walkthrough in
samples/sample-rule-creation.md.
