🐛 Fix agent descriptions for Claude Code YAML parser compatibility (#8)

* 🐛 Fix agent descriptions to work with Claude Code's YAML parser

Claude Code's agent discovery system doesn't parse YAML block scalars or multi-line
descriptions correctly. Prettier also wraps long lines across different repos with
varying configs, breaking agent registration.

Solution: Keep all agent descriptions under 88 characters on a single line.

Changes:
- Rewrote all agent descriptions to be concise (<88 chars) and LLM-focused
- Added CLAUDE.md files documenting the 88-char constraint and best practices
- Removed unnecessary 'tools' and 'model' frontmatter fields for cleaner config
- Descriptions now focus on WHEN to invoke agents (trigger conditions)
- Tested with prettier to verify no wrapping occurs

This ensures agents work reliably across all installations regardless of prettier config.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* 🐛 Fix prettier wrapping - actual limit is 75 chars not 88

Cursor Bug Bot caught this: prettier was still wrapping descriptions that exceeded 88
chars when including the "description: " prefix (13 chars). The actual limit for the
description VALUE is 75 characters, not 88.

Changes:
- Shortened all agent descriptions to under 75 chars
- Updated all 4 CLAUDE.md files with correct 75-char limit
- Verified with prettier - all files stay single-line now

Math: description: (13) + "value" (75) = 88 total line length (prettier's limit)

Thanks to Cursor Bug Bot for catching this immediately!

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* 📝 Run prettier on entire directory

* 📝 Format markdown prose with prettier

* 📝 Remove anti-patterns from CLAUDE.md per prompt-engineering.mdc

Claude's review correctly noted that showing 'What does NOT work' violates our own
prompt-engineering.mdc guidelines about avoiding anti-patterns.

Changes:
- Replaced negative examples with positive 'Valid formats' section
- Changed emoji markers (✅❌) to text markers (Good:/Too long:)
- Fixed inconsistency: now shows quotes in all examples

Aligns with prompt-engineering.mdc: 'Minimal bad examples - LLMs encode patterns
regardless of labels like wrong or dont do this.'

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* 🔄 Trigger CI checks

---------

Co-authored-by: Nick Sullivan <nick@technick.ai>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: 3 people

.claude/RULE_LOADING.md

@@ -2,8 +2,8 @@
 
 ## The Problem
 
-You have extensive Cursor rules in `rules/`, but Claude Code doesn't
-automatically read them. You need a way to leverage these rules intelligently without:
+You have extensive Cursor rules in `rules/`, but Claude Code doesn't automatically read
+them. You need a way to leverage these rules intelligently without:
 
 - Loading everything upfront (wastes context, dilutes focus)
 - Manually remembering which rules to reference
@@ -199,8 +199,7 @@ This documentation was created using the exact process it describes:
 2. **Explored existing structure**: Listed `rules/`, read README and samples
 3. **Designed solution**: Dynamic loading via slash command vs static loading via
    context
-4. **Implemented**: Created `.claude/context.md` and
-   `.claude/commands/load-rules.md`
+4. **Implemented**: Created `.claude/context.md` and `.claude/commands/load-rules.md`
 5. **Documented**: Wrote this explanation of the system and process
 
 The system is self-referential: `/load-rules` itself could be improved by loading

.claude/agents/CLAUDE.md

@@ -0,0 +1,51 @@
+# Creating Claude Code Agents
+
+When creating custom agent files in `.claude/agents/`, the YAML frontmatter format
+matters.
+
+## Valid Frontmatter Format
+
+```yaml
+---
+name: agent-name
+description: "Keep under 75 characters"
+---
+```
+
+**Critical constraints:**
+
+- **Single line only** - Claude Code doesn't parse block scalars (`>` or `|`) correctly
+- **Under 75 characters** - With `description: ` prefix (13 chars), total line must be
+  under 88 to prevent prettier wrapping
+- **Use quotes** - Always quote descriptions to handle special characters like colons
+
+**Valid formats:**
+
+- `description: "Double quoted under 75 chars"` (recommended)
+- `description: 'Single quoted under 75 chars'`
+- `description: Plain text under 75 chars` (only if no special characters)
+
+## Writing Concise Descriptions
+
+Keep descriptions focused on WHEN to invoke the agent:
+
+- Good: "Invoke for design review"
+- Too long: "Invoke for design review with Playwright testing checking WCAG
+  compliance..."
+
+If you need to cut content to stay under 75 chars, move that detail into the agent body
+instead.
+
+## Example Agent
+
+```yaml
+---
+name: test-runner
+description: "Invoke to run tests with terse results"
+---
+I run tests using the specified test runner (bun, pnpm, pytest, etc) and return a terse
+summary with pass count and failure details only. This preserves your context by
+filtering verbose test output to just what's needed for fixes.
+
+[Rest of agent prompt...]
+```

.claude/agents/design-reviewer.md

@@ -1,11 +1,7 @@
 ---
 name: design-reviewer
-description:
-  "Invoke for frontend design review. Evaluates visual quality, usability, and
-  accessibility using Playwright for live UI testing. Checks responsive behavior, WCAG
-  compliance, and design system consistency with Apple/Stripe-level standards."
+description: "Invoke after frontend code changes for design review"
 color: pink
-model: sonnet
 ---
 
 <identity>

.claude/agents/seo-specialist.md

@@ -1,10 +1,6 @@
 ---
 name: seo-specialist
-description:
-  "Invoke for SEO audits and optimization. Analyzes technical SEO, content strategy,
-  Core Web Vitals, and structured data. Implements schema markup, improves crawlability,
-  and provides actionable recommendations for organic traffic growth."
-tools: Read, Write, Edit, Bash
+description: "Invoke for SEO audits and optimization"
 ---
 
 <identity>

.claude/agents/site-keeper.md

@@ -1,12 +1,6 @@
 ---
 name: site-keeper
-description:
-  "Invoke for production health monitoring. Runs comprehensive checks on errors, builds,
-  and logs. Creates PRs for fixable issues, escalates P0/P1 problems immediately.
-  Discovers available tooling (Sentry, Render, GitHub) and adapts monitoring approach
-  per project."
-tools: Read, Write, Edit, Grep, Glob, Bash, TodoWrite, Task, WebFetch, WebSearch
-model: sonnet
+description: "Invoke for production health monitoring and error triage"
 ---
 
 <identity>

.claude/agents/test-runner.md

@@ -1,10 +1,6 @@
 ---
 name: test-runner
-description:
-  "Run tests and return focused results. Caller specifies the test runner (bun, pnpm,
-  pytest, etc). Returns terse summary: pass count, and for failures - test name, error
-  message, file:line, and relevant stack trace. Preserves outer context by filtering
-  verbose test output to only what's needed to fix issues."
+description: "Invoke to run tests with terse, context-efficient results"
 ---
 
 I run tests and tell you exactly what you need to know. Pass count. Fail count. For

.claude/commands/ai-coding-config.md

@@ -12,7 +12,8 @@ personalities, and GitHub workflows.
 ## Usage
 
 - `/ai-coding-config` - Interactive setup for current project
-- `/ai-coding-config update` - Update existing configs to latest versions (includes architecture migration)
+- `/ai-coding-config update` - Update existing configs to latest versions (includes
+  architecture migration)
 - `/ai-coding-config add` - Add new command/skill/agent/plugin to the repo
 
 ## Interaction Guidelines
@@ -45,9 +46,9 @@ Scenarios to handle:
 2. **Existing Cursor rules, no AI coding config yet**
    - Has `.cursor/rules/` as real directory with user's existing rules
    - May have their own customizations to preserve
-   - Offer choice:
-     a. "Migrate existing rules to cross-tool structure" - Moves their rules to `rules/`, creates symlinks
-     b. "Add configs alongside existing rules" - Merges new rules into their `.cursor/rules/`
+   - Offer choice: a. "Migrate existing rules to cross-tool structure" - Moves their
+     rules to `rules/`, creates symlinks b. "Add configs alongside existing rules" -
+     Merges new rules into their `.cursor/rules/`
    - ALWAYS preserve their existing rules, never overwrite without asking
 
 3. **Previous v1 (Cursor-first) AI coding config installation**
@@ -64,6 +65,7 @@ Scenarios to handle:
    - Proceed with normal setup/update within existing structure
 
 Detection commands:
+
 ```bash
 # Check what exists
 test -d .cursor/rules && echo "has .cursor/rules"
@@ -76,10 +78,10 @@ test -f AGENTS.md && echo "has AGENTS.md"
 ```
 
 When existing Cursor rules are detected:
+
 - List what rules the user already has
 - Explain that these will be preserved
-- Show where new rules will be added vs merged
-</existing-config-detection>
+- Show where new rules will be added vs merged </existing-config-detection>
 
 <project-understanding>
 Detect project type and framework specifics. Django differs from FastAPI. React differs from Next.js. Look for existing configurations to avoid duplicates. Understand the project's purpose - API server, web app, CLI tool.
@@ -145,15 +147,15 @@ Use AskUserQuestion to confirm skill selection, showing recommended pre-selected
 <file-installation>
 Copy selected configurations intelligently, respecting existing customizations. Compare files with diff when they exist. For conflicts, use AskUserQuestion to offer choices (overwrite, skip, show diff, or custom action). Never silently overwrite.
 
-Installation mapping: Rules → `rules/` (preserve subdirectory structure, `.cursor/rules/` symlinks here),
-Commands → `.claude/commands/` with symlinks in `.cursor/commands/`, Context →
-`.claude/context.md`, Agents → `.claude/agents/`, Skills → `.claude/skills/` (copy
-entire skill directories for selected skills only), Personalities →
-`rules/personalities/` (common always, additional with `alwaysApply: true`),
-VSCode → `.vscode/`, Prettier → `.prettierrc`, GitHub workflows → `.github/workflows/`,
-Gitignore → `.cursor/.gitignore` and `.claude/.gitignore`, Directory context →
-`.cursor/AGENTS.md` and `.claude/AGENTS.md` (explains directory purpose and references
-prompt-engineering rules).
+Installation mapping: Rules → `rules/` (preserve subdirectory structure,
+`.cursor/rules/` symlinks here), Commands → `.claude/commands/` with symlinks in
+`.cursor/commands/`, Context → `.claude/context.md`, Agents → `.claude/agents/`, Skills
+→ `.claude/skills/` (copy entire skill directories for selected skills only),
+Personalities → `rules/personalities/` (common always, additional with
+`alwaysApply: true`), VSCode → `.vscode/`, Prettier → `.prettierrc`, GitHub workflows →
+`.github/workflows/`, Gitignore → `.cursor/.gitignore` and `.claude/.gitignore`,
+Directory context → `.cursor/AGENTS.md` and `.claude/AGENTS.md` (explains directory
+purpose and references prompt-engineering rules).
 
 Report what was copied, skipped, and how conflicts were handled. </file-installation>
 
@@ -190,12 +192,14 @@ Start by pulling latest from `~/.ai_coding_config`.
 IMPORTANT: Before updating configs, detect if this project uses the legacy architecture.
 
 Legacy architecture indicators (v1 - Cursor-first):
+
 - `.cursor/rules/` is a real directory (not a symlink)
 - `rules/` at root doesn't exist OR symlinks to `.cursor/rules/`
 - `CLAUDE.md` is a real file (not a symlink)
 - No `AGENTS.md` at project root
 
 Current architecture (v2 - Cross-tool):
+
 - `rules/` at project root is the canonical directory
 - `.cursor/rules/` symlinks to `../rules/`
 - `AGENTS.md` at project root is canonical
@@ -204,27 +208,29 @@ Current architecture (v2 - Cross-tool):
 Detection: `test -L .cursor/rules && test -L CLAUDE.md && test -f AGENTS.md`
 
 If legacy architecture detected:
+
 1. Explain the architecture change clearly:
-   - "Your project uses the older Cursor-first structure. There's a newer cross-tool architecture that works better with Claude Code, Cursor, Windsurf, Aider, and other AI coding tools."
-   - "The key change: `rules/` becomes the canonical location at project root, with `.cursor/rules/` symlinked to it. This follows the emerging AGENTS.md standard (20,000+ GitHub repos)."
+   - "Your project uses the older Cursor-first structure. There's a newer cross-tool
+     architecture that works better with Claude Code, Cursor, Windsurf, Aider, and other
+     AI coding tools."
+   - "The key change: `rules/` becomes the canonical location at project root, with
+     `.cursor/rules/` symlinked to it. This follows the emerging AGENTS.md standard
+     (20,000+ GitHub repos)."
 
 2. Use AskUserQuestion to offer migration:
    - "Migrate to cross-tool architecture (Recommended)" - Performs full migration
    - "Skip migration, just update configs" - Updates within current structure
    - "Show me what would change" - Explains changes in detail
 
-3. If migration accepted:
-   a. Create backup: `cp -r .cursor/rules rules-backup`
-   b. Move rules: `mv .cursor/rules rules`
-   c. Create symlink: `ln -s ../rules .cursor/rules`
-   d. Create AGENTS.md (copy from CLAUDE.md if exists, or create new)
-   e. Replace CLAUDE.md: `rm CLAUDE.md && ln -s AGENTS.md CLAUDE.md`
-   f. Update @ references in AGENTS.md from `.cursor/rules/` to `rules/`
-   g. Rename load-cursor-rules symlink to load-rules if exists
-   h. Report migration complete, then continue with normal update
-
-4. If migration skipped, continue updating within legacy structure (but warn that some new features may not work correctly)
-</architecture-check>
+3. If migration accepted: a. Create backup: `cp -r .cursor/rules rules-backup` b. Move
+   rules: `mv .cursor/rules rules` c. Create symlink: `ln -s ../rules .cursor/rules` d.
+   Create AGENTS.md (copy from CLAUDE.md if exists, or create new) e. Replace CLAUDE.md:
+   `rm CLAUDE.md && ln -s AGENTS.md CLAUDE.md` f. Update @ references in AGENTS.md from
+   `.cursor/rules/` to `rules/` g. Rename load-cursor-rules symlink to load-rules if
+   exists h. Report migration complete, then continue with normal update
+
+4. If migration skipped, continue updating within legacy structure (but warn that some
+   new features may not work correctly) </architecture-check>
 
 Now compare against the current project.
 

.claude/commands/autotask.md

@@ -50,9 +50,9 @@ Implement the solution following project patterns and standards. Available agent
   refinement
 - Explore (general-purpose): Investigation, research, evaluates trade-offs
 
-Build an execution plan based on task type. Use /load-rules to load relevant
-project standards. Execute agents in parallel when possible, sequentially when they
-depend on each other.
+Build an execution plan based on task type. Use /load-rules to load relevant project
+standards. Execute agents in parallel when possible, sequentially when they depend on
+each other.
 
 Provide targeted context when launching agents: task requirements, implementation
 decisions, relevant standards, and specific focus area. Tailor context to agent type.

.claude/commands/generate-AGENTS-file.md

@@ -229,8 +229,8 @@ constraints that differ from root context.
 
 Scan for candidates by checking:
 
-1. **Directory-scoped cursor rules**: Rules in `rules/` with `globs` patterns
-   targeting specific directories (e.g., `globs: ["tests/**"]`, `globs: ["src/db/**"]`)
+1. **Directory-scoped cursor rules**: Rules in `rules/` with `globs` patterns targeting
+   specific directories (e.g., `globs: ["tests/**"]`, `globs: ["src/db/**"]`)
 
 2. **High-risk directories**: Places where AI mistakes are costly or common:
    - `migrations/`, `drizzle/migrations/`, `prisma/migrations/` - Never edit manually

.claude/commands/load-rules.md

@@ -6,8 +6,8 @@ Analyze the current task and load ONLY relevant rules from `rules/`.
 
 PROCESS:
 
-1. Discover available rules: use glob_file_search with pattern "\*.mdc" in rules/
-   to find all rule files recursively
+1. Discover available rules: use glob_file_search with pattern "\*.mdc" in rules/ to
+   find all rule files recursively
 2. Analyze task to identify what domains apply (languages, tools, frameworks,
    operations)
 3. Select relevant rules based on task requirements