Setup Style

Method: observe → confirm → record. Same family as /setup-runtime — the same method applied to a different kind of fact. /setup-runtime verifies runtime facts (how the project runs); this skill verifies convention facts (how the team writes code).

Rules

• A pattern observed in code is not necessarily a convention — it may be legacy. When memory-file-declared conventions conflict with what the code shows, present both as candidates and let the developer decide which is the team's real convention. Never record before confirmation.
• Record only project-specific conventions, not general programming knowledge.
• Confirm in groups (structure / naming / conventions / details / tests), one group at a time — not item by item.
• Ask questions in plain text, one line answerable, grouped logically. Never use the AskUserQuestion tool — its checkbox prompt UI handles grouped one-line-answerable questions poorly; plain text is more reliable.
• Never modify code.

Phase 1: Observe

Scan only the project's own source directories — exclude generated code (protobuf stubs, generated mappers), vendor dependencies (node_modules, third-party libs), and build artifacts (target/, dist/). Adjust the groups to the actual tech stack (the examples below are from a Java/Spring codebase):

Also scan config files that encode conventions — .editorconfig, lint/format configs (Checkstyle, ESLint, Prettier), CI style checks. Cross-check code patterns against them. If a common code pattern conflicts with a config rule, present both as candidates and surface the contradiction during confirmation — the developer decides whether the config or the code is the convention.

A pattern is a rule sentence that summarizes consistent instances. If you can state the convention in one sentence ("all Response DTOs end with Response") and the code shows consistent instances of it, it's a candidate — instance count doesn't matter. If no single rule sentence fits the instances (they visibly conflict), mark [INCONSISTENT]. If two rule sentences both fit and are ordered by time (new files use A, old files use B), mark [MIGRATING] — ask the developer whether to unify on the new style or keep the old one. If a group yields no rule sentence at all, note "no consistent convention observed in this group" and let the developer add any verbally during confirmation.

Tag each candidate [OBSERVED] with where it was seen (which file categories).

Also read existing convention claims in the memory file (CLAUDE.md if it exists, else AGENTS.md — its "Notes", "Conventions", "Rules" sections) and add them to the candidate list tagged [FROM-ENTRY]. They are candidates, not facts — exactly like code observations, they enter the confirmation phase and the developer decides whether they still hold, are obsolete, or migrated. Read-only: the memory file is never written by this skill; confirmed conventions are recorded to docs/house-style.md only. Skipping these claims silently leaves two convention documents that contradict each other.

Phase 2: Confirm

Present the candidates one group at a time: show the group, wait for the developer's decisions, then move to the next group. Never dump all groups in one output — the developer needs to focus on one cluster at a time, and a verdict on one group shapes how you frame the next.

Within each group, resolve every item:

• Is a convention → [CONFIRMED]
• Is legacy → [LEGACY], do not record (or mark "not recommended")
• Disputed / uncertain → ask the developer to decide

Item-level disputes and migrations are decided within their own group (e.g. a naming migration is resolved while confirming Naming, not at the end).

On a re-run, if a group has no new, changed, or obsolete items, just tell the developer "no changes in this group" and skip it.

After all groups are confirmed, ask: any conventions that don't show up in code (team docs, verbal agreements, things reviewers repeatedly flag) that should be added?

Phase 3: Record

One output — docs/house-style.md is the source of truth:

docs/house-style.md — full version. If the file does not exist, create it with this structure:

# House Style

> Generated by /setup-style on {date}.

## {Group}

### {Rule name}
- **Rule**: {the convention, one sentence}
- **Example**: {short code snippet showing the right way}
- **✗ Counter-example**: {short snippet showing the wrong way}
- **Source**: {where observed — file categories, or "confirmed by developer"}

Tool-agnostic — any review flow (agent review, human review) checks against it. If the file already exists, update it incrementally — keep rules that still hold (including any hand-written notes), remove obsolete ones, insert new/changed ones per group. Never rebuild it from the template from scratch.

Re-run

Compare this run's candidate list against the valid rules in docs/house-style.md:

• Unchanged → keep as-is, no confirmation needed.
• New or changed → enter the confirmation phase.
• No longer present in the codebase → propose removal in the confirmation phase; once the developer confirms, delete the rule outright — no marker stays in the document. A convention whose practice has died (e.g. hand-written getters after the team moved to Lombok) has no place in the docs.

After confirmation, apply the changes exactly as in Phase 3 — incremental update of docs/house-style.md. Conventions evolve — re-run after a refactor or when team agreements change.