agile-rules-code

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

1. Parse $ARGUMENTS into <sub-command> and flags. If unrecognized, print the sub-commands table and exit.
2. 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.
3. Run scripts/code-rule-detect.sh --json <pwd> if --rule not given; infer the target rule from working directory or input path.
4. 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:

1. Researcher (always first; output feeds everyone)
2. Thinker (consumes researcher output)
3. Grounder + Technical (parallel; both consume thinker proposal)
4. 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:

1. Prepend the Drift Impact Report HTML comment to the target rule file (per templates/code-rule-template.md).
2. Apply the rule body edits (using Edit against the existing file, or Write for create).
3. Update version: and last_amended: in frontmatter (PATCH bump for refine; MINOR/MAJOR per thinker proposal for others).
4. Update .agile/rules/index.md Tier 1 Rules table row (regenerated from scripts/registry-sync.sh --markdown).
5. For align --write, write .agile/rules/code-alignment-report.md.
6. 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)

File	When to read
references/command-reference.md	Deep-dive per sub-command
references/domain-taxonomy.md	The 5 code-rule domains and their scope
references/citation-grammar.md	Exact grammar of extracts: and > Source:
references/alignment-rubric.md	The 19 misalignment categories + severity matrix
references/versioning-policy.md	The MAJOR/MINOR/PATCH rubric for code rules

Templates (used at runtime)

File	Purpose
templates/code-rule-template.md	Skeleton for a brand-new Tier 1 code rule
templates/code-rule-frontmatter-template.md	Just the YAML frontmatter block
templates/citation-footer-template.md	The > Source: blockquote format
templates/alignment-report-template.md	The 12-section HTML header + body of the alignment report
templates/index-row-template.md	Row format for .agile/rules/index.md Tier 1 Rules table

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)

File	Walks through
samples/sample-rule-creation.md	Creating a new code-style/json.md rule with full team review
samples/sample-rule-refinement.md	Lighter-path PATCH bump (typo fix in testing/conventions.md)
samples/sample-alignment-report.md	Real-shape alignment report against the current corpus (6 known drift items)
samples/sample-validation-report.md	Output of validate --rule code-style/kotlin (FAIL on OC-001)
samples/sample-sync-report.md	Reconciling drift via sync after align

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.