codingbuddy-rules 1.0.0 → 1.1.0

package/.ai-rules/adapters/claude-code.md

@@ -115,3 +115,33 @@ Claude can directly read and reference:
 1. Update `.ai-rules/rules/*.md` for universal changes
 2. Update `.claude/rules/custom-instructions.md` for Claude-specific features
 3. Sync Claude Project instructions when rules change significantly
+
+## Skills
+
+CodingBuddy skills are accessible via MCP tools:
+
+### List Available Skills
+
+Use `list_skills` MCP tool to see all available skills.
+
+### Use a Skill
+
+Use `get_skill` MCP tool with skill name:
+
+- `get_skill("brainstorming")` - Explore requirements before implementation
+- `get_skill("test-driven-development")` - TDD workflow
+- `get_skill("systematic-debugging")` - Debug methodically
+- `get_skill("writing-plans")` - Create implementation plans
+- `get_skill("executing-plans")` - Execute plans with checkpoints
+- `get_skill("subagent-driven-development")` - In-session plan execution
+- `get_skill("dispatching-parallel-agents")` - Handle parallel tasks
+- `get_skill("frontend-design")` - Build production-grade UI
+
+### When to Use Skills
+
+- **brainstorming**: Before any creative work or new features
+- **test-driven-development**: Before implementing features or bugfixes
+- **systematic-debugging**: When encountering bugs or test failures
+- **writing-plans**: For multi-step tasks with specs
+- **executing-plans**: Following written implementation plans
+- **frontend-design**: Building web components or pages

package/.ai-rules/adapters/codex.md

@@ -122,3 +122,28 @@ When using Copilot Workspace:
 1. Update `.ai-rules/rules/*.md` for universal rule changes
 2. Keep `.github/copilot-instructions.md` concise (Copilot's context limit)
 3. Link to detailed rules in `.ai-rules/` rather than duplicating
+
+## Skills
+
+### Using Skills in Codex
+
+Skills are located in `.ai-rules/skills/`. To use a skill:
+
+1. Read the skill file:
+
+   ```bash
+   cat .ai-rules/skills/<skill-name>/SKILL.md
+   ```
+
+2. Follow the skill's checklist and process.
+
+### Available Skills
+
+- `brainstorming` - Explore requirements before implementation
+- `test-driven-development` - TDD workflow
+- `systematic-debugging` - Debug methodically
+- `writing-plans` - Create implementation plans
+- `executing-plans` - Execute plans with checkpoints
+- `subagent-driven-development` - In-session plan execution
+- `dispatching-parallel-agents` - Handle parallel tasks
+- `frontend-design` - Build production-grade UI

package/.ai-rules/adapters/cursor.md

@@ -126,3 +126,26 @@ When updating rules:
 1. Update `.ai-rules/rules/*.md` for changes affecting all AI tools
 2. Update `.cursor/rules/*.mdc` only for Cursor-specific changes
 3. Keep both in sync for best experience
+
+## Skills
+
+### Using Skills in Cursor
+
+Reference skills in your prompts using file inclusion:
+
+```
+@.ai-rules/skills/test-driven-development/SKILL.md
+```
+
+Or manually include skill content in `.cursorrules`.
+
+### Available Skills
+
+- `.ai-rules/skills/brainstorming/SKILL.md`
+- `.ai-rules/skills/test-driven-development/SKILL.md`
+- `.ai-rules/skills/systematic-debugging/SKILL.md`
+- `.ai-rules/skills/writing-plans/SKILL.md`
+- `.ai-rules/skills/executing-plans/SKILL.md`
+- `.ai-rules/skills/subagent-driven-development/SKILL.md`
+- `.ai-rules/skills/dispatching-parallel-agents/SKILL.md`
+- `.ai-rules/skills/frontend-design/SKILL.md`

package/.ai-rules/skills/README.md

@@ -0,0 +1,112 @@
+# CodingBuddy Skills
+
+Reusable workflows for consistent development practices.
+
+## Available Skills
+
+| Skill | Description | When to Use |
+|-------|-------------|-------------|
+| brainstorming | Explores user intent, requirements and design before implementation | Before any creative work |
+| dispatching-parallel-agents | Handle 2+ independent tasks without shared state | Parallel task execution |
+| executing-plans | Execute implementation plans with review checkpoints | Following written plans |
+| frontend-design | Create distinctive, production-grade frontend interfaces | Building web components/pages |
+| subagent-driven-development | Execute plans with independent tasks in current session | In-session plan execution |
+| systematic-debugging | Systematic approach before proposing fixes | Encountering bugs or failures |
+| test-driven-development | Write tests first, then minimal code to pass | Before implementing features |
+| writing-plans | Create implementation plans before coding | Multi-step tasks with specs |
+
+## Skill Format
+
+Skills use YAML frontmatter + Markdown:
+
+```markdown
+---
+name: skill-name
+description: "Brief description (max 500 chars)"
+---
+
+# Skill Title
+
+## When to Use
+...
+
+## Process/Checklist
+...
+```
+
+### Frontmatter Requirements
+
+- `name`: lowercase alphanumeric with hyphens only (`^[a-z0-9-]+$`)
+- `description`: 1-500 characters
+
+## Usage by Platform
+
+### Claude Code (MCP)
+
+```
+list_skills                        # List all available skills
+get_skill("test-driven-development")  # Get specific skill content
+```
+
+### Codex / GitHub Copilot
+
+```bash
+cat .ai-rules/skills/<skill-name>/SKILL.md
+```
+
+### Cursor
+
+```
+@.ai-rules/skills/test-driven-development/SKILL.md
+```
+
+## Creating Custom Skills
+
+1. Create directory: `skills/<name>/`
+2. Create `SKILL.md` with YAML frontmatter
+3. Follow the format specification above
+
+### Example
+
+```bash
+mkdir -p .ai-rules/skills/my-skill
+cat > .ai-rules/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: My custom skill for specific workflow
+---
+
+# My Skill
+
+## When to Use
+- Specific scenario 1
+- Specific scenario 2
+
+## Checklist
+- [ ] Step 1
+- [ ] Step 2
+EOF
+```
+
+## Directory Structure
+
+```
+.ai-rules/skills/
+├── README.md                       # This file
+├── brainstorming/
+│   └── SKILL.md
+├── dispatching-parallel-agents/
+│   └── SKILL.md
+├── executing-plans/
+│   └── SKILL.md
+├── frontend-design/
+│   └── SKILL.md
+├── subagent-driven-development/
+│   └── SKILL.md
+├── systematic-debugging/
+│   └── SKILL.md
+├── test-driven-development/
+│   └── SKILL.md
+└── writing-plans/
+    └── SKILL.md
+```

package/.ai-rules/skills/brainstorming/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use superpowers:using-git-worktrees to create isolated workspace
+- Use superpowers:writing-plans to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/.ai-rules/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/.ai-rules/skills/executing-plans/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess

package/.ai-rules/skills/frontend-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.