---
name: superdev-rules
description: Use ALWAYS when the user wants to discover, capture, or maintain project coding conventions as .claude/rules files - learn the codebase's conventions, set up path-scoped rules, teach Claude the project's style. Triggers include "create rules", "set up .claude/rules", "capture coding conventions", "learn our conventions", "add naming/testing/error-handling rules", "audit rules". Discovers dominant patterns from the host code with real examples, confirms each in an interview, and writes MANY SMALL path-scoped rule files (one convention area per file, YAML paths: gating) instead of a monolith, plus a maintenance mode to audit existing rules against the actual code and find new candidates.
user-invocable: true
allowed-tools: Read, Write, AskUserQuestion, Skill, Agent, Task, Bash, Bash(date:*), Bash(${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/detect_state.sh:*), Bash(${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/scan_conventions.sh:*)
---

# SuperDev Rules

Discovers the host project's coding conventions (naming, testing, error-handling, imports, ...) and persists them as `.claude/rules/*.md`. This skill is the interactive front: it scans, asks, and resolves every decision with the user, then hands ONE capture file to the `superdev:rules-writer` agent, which writes the rule files.

## Core Principle

**Many SMALL files, one convention area per file**, each gated by a narrow frontmatter `paths:` glob list - the harness loads a rule only when Claude reads a matching file. No monolith; no global rule where a narrow glob suffices. Record only the DELTA from what a competent developer would do anyway.

**Frozen `_` convention.** A basename with a leading underscore (`_{topic}.md`) is frozen: the native loader still loads it, but this skill never reads, scores, audits, or proposes it - reserved for hand-authored or bootstrap meta-rules that must stay immutable. Never emit a capture slug starting with `_`.

**The `superdev:rules-writer` agent writes this skill's output - you never write a rule file yourself.** The `Agent` tool missing from your tool pool means the harness lost the tool, never that you may stand in for the writer: STOP at once, report exactly these four lines, and end the turn.

```
AGENT TOOL UNAVAILABLE - stopped at <step>.
Nothing was written in its place.
State: .temp/superdev/rules/capture-<RUN_ID>.md, or "no capture written yet".
Fix: exit this session, restart with `claude --resume`, then run `superdev-rules` again.
```

## Run ID

!`date +%Y%m%d-%H%M%S`

The line above is `<RUN_ID>` - use it verbatim. Every run writes a fresh capture file `.temp/superdev/rules/capture-<RUN_ID>.md`; never reuse or overwrite an existing one.

## Workflow

```
0. Preflight
   `Agent` tool present in your tool pool? Absent → STOP and report per `## Core Principle`
   (State: no capture written yet). Do not run the scripts, do not start the interview.

1. Detect state
   "${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/detect_state.sh" /path/to/project
   → Returns: none | partial | complete

2. Route
   none/partial → Discovery (steps 3-5)
   complete     → Maintenance (step 6)

3. Scan [gate - show findings first]
   "${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/scan_conventions.sh" /path/to/project
   Then Read 2-3 representative files per candidate area - a convention is
   proposable only with a dominant pattern + a real example; never invent one.
   Show: | Area | Discovered convention (real example) | Proposed paths: |

4. Interview
   Confirm every candidate with the user - accept / adjust / drop, plus the
   Capture Questions. Only confirmed conventions reach the capture.

5. Capture + hand off
   Write .temp/superdev/rules/capture-<RUN_ID>.md (format below)
   Run `printf '%s\n' "${CLAUDE_PLUGIN_ROOT}/references"` and keep its output as `<refs>`
   Invoke `Agent` with `subagent_type: superdev:rules-writer` and a labeled-line prompt:
     capture: .temp/superdev/rules/capture-<RUN_ID>.md
     refs: <refs>
   Relay its VERDICT/RULE lines verbatim - do NOT re-verify or rewrite the rule files yourself

6. Maintenance mode (when state=complete)
   Ask user:
   a) Audit rules     → Read each rule, check it against the code its globs gate:
                        contradictions between rules, dead rules (globs match
                        nothing / convention gone), drift from the dominant pattern
   b) Find candidates → Re-scan (step 3) for areas no existing rule covers
   c) Both
   Resolved changes go through step 5 (capture + writer handoff);
   a dead rule becomes a `delete:` line.
```

## Capture file format

```
# Rules capture
## Rules
- <file-slug> - paths: <glob>[, <glob>] - <one-line scope>
- delete: <existing rule path> - <one-line reason>
## Facts
### <file-slug>
- <confirmed convention - imperative, carrying the real example from code>
```

Globs narrow (a directory or an extension in every glob); `paths: global` only when the convention is truly repo-wide.

## Capture Questions

Per candidate area:
1. Is this pattern intentional, or an accident of history?
2. Should new code follow it, or is a different target convention desired?
3. Which paths does it apply to - and where does it NOT apply?
4. Any exceptions worth recording?

## Resources

**Scripts:**
- `${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/detect_state.sh` - Check .claude/rules state (none/partial/complete, per-file paths: presence)
- `${CLAUDE_PLUGIN_ROOT}/skills/superdev-rules/scripts/scan_conventions.sh` - Deterministic convention signals (languages, naming styles, test patterns, tool configs, layout)