CLAUDE.md

1# AI Coding Configuration - Development Guide
2 
3This document covers conventions for developing agents, skills, and commands in this
4repo.
5 
6## YAML Frontmatter Conventions
7 
8### Prettier-Ignore for Long Descriptions
9 
10Add `# prettier-ignore` before description fields to prevent line wrapping:
11 
12```yaml
13---
14name: example-agent
15# prettier-ignore
16description: "Use when reviewing for production readiness, fragile code, error handling, resilience, reliability, or catching bugs before deployment"
17---
18```
19 
20This allows richer, more comprehensive descriptions that help Claude Code understand
21exactly when to trigger each agent or skill.
22 
23### Description Format by Type
24 
25**Agents & Skills (LLM-triggered):**
26 
27Use "Use when..." format for semantic matching. Think about what users will say:
28 
29```yaml
30# prettier-ignore
31description: "Use when reviewing error handling, finding silent failures, checking try-catch patterns, or ensuring errors surface properly"
32```
33 
34Match user language: "review the code", "check for bugs", "debug this error" - include
35these exact phrases.
36 
37**Commands (user-invoked):**
38 
39Explain what the command does for human users:
40 
41```yaml
42# prettier-ignore
43description: "Triage and address PR comments from code review bots - analyzes feedback, prioritizes issues, and creates fixes"
44```
45 
46Commands are invoked directly by users (`/command-name`), so descriptions should clearly
47explain functionality.
48 
49## Agent Color Scheme
50 
51Colors are grouped by category:
52 
53| Color       | Category          | Purpose                                           |
54| ----------- | ----------------- | ------------------------------------------------- |
55| **red**     | Security          | Danger, security vulnerabilities                  |
56| **orange**  | Bugs/correctness  | Logic errors, error handling issues               |
57| **yellow**  | Performance       | Efficiency, speed, resource usage                 |
58| **green**   | Testing/quality   | Test coverage, test running, QA                   |
59| **cyan**    | Observability     | Logging, monitoring, reliability                  |
60| **blue**    | Style/conventions | Code style, comments, documentation               |
61| **purple**  | Design/UX         | UI design, UX, SEO, user-facing                   |
62| **magenta** | Meta/architecture | Architecture, prompts, git, debugging, automation |
63 
64## Skill Triggers Field
65 
66Skills have a `triggers` array for natural language phrases that activate them:
67 
68```yaml
69triggers:
70  - "debug"
71  - "investigate"
72  - "root cause"
73  - "why is this"
74  - "not working"
75  - "test failing"
76```
77 
78Include: keywords users say, questions they ask, symptoms they describe, tool names.
79 
80## Skill Composition Frontmatter
81 
82Optional fields for declarative composition. The Claude Code harness ignores them; the
83LLM reads them as part of the skill content and acts accordingly.
84 
85| Field        | Type          | Purpose                                                                         |
86| ------------ | ------------- | ------------------------------------------------------------------------------- |
87| `next-skill` | string        | Happy-path handoff — the skill or command to invoke after this one completes    |
88| `requires`   | YAML sequence | Prerequisites; each entry is `skill:name`, `tool:name`, or `mcp:name`           |
89| `model-hint` | string        | Preferred model tier when delegated as a subagent: `sonnet`, `opus`, or `haiku` |
90| `stability`  | string        | `stable` (default) or `experimental` — signals maturity for opt-in gating       |
91 
92All fields are optional. Skills without them work unchanged.
93 
94**Example — planning chain:**
95 
96```yaml
97---
98name: brainstorm-synthesis
99version: 1.1.1
100category: planning
101model-hint: opus
102stability: experimental
103next-skill: ship
104requires:
105  - skill:brainstorming
106triggers:
107  - "synthesize approaches"
108---
109```
110 
111**`next-skill` convention:** Use the bare skill/command name (same as the slash command
112without the `/`). Commands and skills are both valid targets. The LLM reads this and
113offers the handoff when its task is complete — the user confirms before the next skill
114runs. This is a suggestion, not an auto-chain; the LLM should never silently invoke the
115next skill without user awareness.
116 
117**`requires` convention:** Use `skill:name` for skill dependencies, `tool:name` for
118Claude Code tools (Read, Bash, etc.), `mcp:name` for MCP servers. Informational for now;
119`/ai-coding-config doctor` can validate these in the future.
120 
121**Annotated chains in this repo** (source skills only — downstream commands like
122`verify-fix` can't declare `requires` back, and terminal skills like `ship` are
123invokable standalone):
124 
125- `brainstorming → brainstorm-synthesis → ship` (planning)
126- `systematic-debugging → verify-fix` (debugging)
127 
128## Command Update Protocol
129 
130When a user runs `/ai-coding-config update`, after pulling the latest changes from this
131repository, check if their local command file is outdated and offer to update it.
132 
133The ai-coding-config.md command file in the user's project may be stale. Users who ran
134bootstrap.sh have a copied file that doesn't automatically update when the repo is
135pulled.
136 
137Compare versions using the version field in YAML frontmatter. Check the user's
138`.claude/commands/ai-coding-config.md` against the repo version at
139`~/.ai_coding_config/.claude/commands/ai-coding-config.md`. If the repo version is newer
140than the user's local copy, offer to update it.
141 
142Present two options: replace with the latest copy from the repo, or skip the update and
143keep their current version.
144