🐛 Fix agent descriptions for Claude Code YAML parser compatibility

.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

.claude/commands/personality-change.md

@@ -22,18 +22,18 @@ Change the active AI personality to create consistent behavior across Claude Cod
 <workflow>
 If no personality name provided, show available personalities and ask which to activate.
 
-Validate that `rules/personalities/<name>.mdc` exists. If `none` requested,
-remove personality.
+Validate that `rules/personalities/<name>.mdc` exists. If `none` requested, remove
+personality.
 
 For Claude Code: Read or create `.claude/context.md`. Check for existing
 `## Active Personality` section with `<!-- personality-<name> -->` comment. If
 personality exists and matches requested, confirm already active and stop. If different,
 remove entire section. If not removing (name != "none"), read personality file, strip
 frontmatter, append to `.claude/context.md` with HTML comments marking boundaries.
 
-For Cursor: Find all personality files in `rules/personalities/`. For each file,
-update frontmatter: set `alwaysApply: true` for selected personality, set
-`alwaysApply: false` for all others.
+For Cursor: Find all personality files in `rules/personalities/`. For each file, update
+frontmatter: set `alwaysApply: true` for selected personality, set `alwaysApply: false`
+for all others.
 
 Report results clearly showing what changed in both Claude Code and Cursor
 configurations. </workflow>

.claude/commands/troubleshoot.md

@@ -81,8 +81,7 @@ for related errors, check deployment timelines. Generate hypotheses about actual
 problems.
 
 Git Worktree Workflow: Each bug fix in isolated worktree. Read
-rules/git-worktree-task.mdc for full workflow. Clean up worktrees after PRs
-merge.
+rules/git-worktree-task.mdc for full workflow. Clean up worktrees after PRs merge.
 
 Fixing Process: Gather full context from error monitoring (stack traces, request data,
 timelines). Read failing code and context. Identify root cause. Implement fix handling

.claude/context.md

@@ -13,5 +13,5 @@ co-creative evolution for the whole.
 
 # Rule Loading
 
-Coding rules are available in `rules/`. Use `/load-rules` to analyze the
-current task and load relevant rules dynamically.
+Coding rules are available in `rules/`. Use `/load-rules` to analyze the current task
+and load relevant rules dynamically.

README.md

@@ -233,8 +233,8 @@ Each personality is a complete communication style overlay - see
   (symlinks)     (copies)
 ```
 
-**Single source of truth**: `rules/` and `.claude/commands/` are canonical.
-Plugins use symlinks for packaging.
+**Single source of truth**: `rules/` and `.claude/commands/` are canonical. Plugins use
+symlinks for packaging.
 
 **Plugin distribution**: Claude Code uses marketplace.json. Cursor, Windsurf, Cline, and
 others use bootstrap script. All reference same source files.
@@ -284,9 +284,9 @@ ai-coding-config/
 
 ## What You Get
 
-**Rules** ([`rules/`](rules/)) - LLM-optimized coding standards.
-Framework patterns, testing approaches, commit formats, naming conventions. AI
-references these automatically based on file types and task context.
+**Rules** ([`rules/`](rules/)) - LLM-optimized coding standards. Framework patterns,
+testing approaches, commit formats, naming conventions. AI references these
+automatically based on file types and task context.
 
 **Commands** ([`.claude/commands/`](.claude/commands/)) - Active workflows. From simple
 setup to autonomous task execution. Designed for LLM-to-LLM communication with clear
@@ -296,9 +296,8 @@ goals and adaptive behavior.
 domains - debugging, development, UX, code review, architecture. See
 [Claude Code agents docs](https://docs.anthropic.com/en/docs/agents/overview#specialized-agents).
 
-**Personalities** ([`rules/personalities/`](rules/personalities/)) -
-Communication style overlays. Changes how AI talks to you without changing technical
-capabilities.
+**Personalities** ([`rules/personalities/`](rules/personalities/)) - Communication style
+overlays. Changes how AI talks to you without changing technical capabilities.
 
 **GitHub workflows** ([`.github/workflows/`](.github/workflows/)) - CI/CD integration
 with Claude-powered automation.
@@ -414,3 +413,4 @@ This repository contains instructions for AI behavior in [CLAUDE.md](CLAUDE.md)
 
 **License**: MIT **Author**: [TechNickAI](https://github.com/TechNickAI) **Repository**:
 https://github.com/TechNickAI/ai-coding-config
+