From f2db1277e608a6554dba9df504bb37bc16f951b5 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 20:02:09 -0800 Subject: [PATCH] Simplify grow-your-own-garden plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reduced from ~645 lines to ~100 lines while keeping the core concepts: - The seed (4 commands + universal agents) - The growth loop via /compound - Agent storage hierarchy - Implementation phases πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...row-your-own-garden-plugin-architecture.md | 674 ++---------------- 1 file changed, 66 insertions(+), 608 deletions(-) diff --git a/plans/grow-your-own-garden-plugin-architecture.md b/plans/grow-your-own-garden-plugin-architecture.md index 729a0ba..b21746c 100644 --- a/plans/grow-your-own-garden-plugin-architecture.md +++ b/plans/grow-your-own-garden-plugin-architecture.md @@ -1,644 +1,102 @@ # Grow Your Own Garden: Adaptive Agent Ecosystem -> **Issue Reference:** https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -> **Date:** 2025-11-27 -> **Status:** Draft Plan +> **Issue:** https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -## Overview +## The Idea -Transform the compounding-engineering plugin from a monolithic collection into an **adaptive ecosystem** where users grow their own personalized agent gardens from a minimal seed. The core loop (`/plan`, `/work`, `/review`, `/compound`) stays universal, but each user's agent collection evolves based on their learnings. +Everyone grows their own garden, but we're all using the same process. -**Philosophy:** Everyone grows their own garden, but we're all using the same process. +Start from a **seed** (minimal core: `/plan`, `/work`, `/review`, `/compound`). Each `/compound` loop can suggest adding agents based on what you're working onβ€”like building up a test suite to prevent regressions, but for code review expertise. ---- +## Current Problem -## Problem Statement - -### Current State -- Monolithic plugin: 24 agents, 16 commands, 11 skills -- Users get everything, use maybe 30% -- No personalization - same agents for Rails developer and Python developer -- No growth mechanism - static collection that doesn't adapt - -### Desired State -- Minimal seed: 4 commands + ~6 core agents -- Organic growth: `/compound` suggests relevant agents based on learnings -- Personalized gardens: Rails developer accumulates Rails experts, Python developer accumulates Python experts -- Shared process: Core workflow identical across all users - ---- +- Monolithic plugin: 24 agents, users use ~30% +- No personalization (same agents for Rails dev and Python dev) +- Static collection that doesn't adapt ## Proposed Solution -### Architecture: Seed + Growth Model +### The Seed (Core Plugin) -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SEED PLUGIN (Core) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ /plan β”‚ β”‚ /work β”‚ β”‚ /review β”‚ β”‚/compound β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ β”‚ -β”‚ Core Agents: security-sentinel, performance-oracle, β”‚ -β”‚ code-simplicity-reviewer, architecture-strategist β”‚ -β”‚ pattern-recognition-specialist β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”‚ /compound triggers growth - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ USER'S GARDEN (~/.claude/agents/) β”‚ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Predefined β”‚ β”‚ Dynamic β”‚ β”‚ Custom β”‚ β”‚ -β”‚ β”‚ (from library) β”‚ β”‚ (generated) β”‚ β”‚ (user-written) β”‚ β”‚ -β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ β€’ dhh-rails β”‚ β”‚ β€’ actor-model β”‚ β”‚ β€’ our-api-style β”‚ β”‚ -β”‚ β”‚ β€’ kieran-python β”‚ β”‚ expert β”‚ β”‚ β€’ team-patterns β”‚ β”‚ -β”‚ β”‚ β€’ typescript β”‚ β”‚ β€’ graphql-best β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ reviewer β”‚ β”‚ practices β”‚ β”‚ β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”‚ /review discovers all agents - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ PROJECT OVERRIDES (.claude/agents/) β”‚ -β”‚ β”‚ -β”‚ Project-specific agents that override or supplement global β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ β€’ cora-specific β”‚ (only runs in ~/Reels/cora/) β”‚ -β”‚ β”‚ β€’ hotwire-nativeβ”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +4 commands + minimal agents: + +| Component | What's Included | +|-----------|-----------------| +| Commands | `/plan`, `/work`, `/review`, `/compound` | +| Review Agents | security, performance, simplicity, architecture, patterns | +| Research Agents | best-practices, framework-docs, git-history, repo-analyst | +| Skills | compound-docs, file-todos, git-worktree | +| MCP Servers | playwright, context7 | ### The Growth Loop -``` -User completes work - β”‚ - β–Ό - Runs /compound - β”‚ - β–Ό -System analyzes: -β€’ Git diff (files changed, patterns) -β€’ Tech stack (Gemfile, package.json) -β€’ Learning content - β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SUGGESTION ENGINE β”‚ -β”‚ β”‚ -β”‚ Match detected patterns against: β”‚ -β”‚ 1. Predefined agent library (curated) β”‚ -β”‚ 2. Dynamic generation capability β”‚ -β”‚ 3. User's existing agents (avoid duplicates) β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - Three possible outcomes: - β”‚ - β”œβ”€β–Ί "You're using Rails. Add DHH reviewer?" [y/n] - β”‚ (Predefined agent from library) - β”‚ - β”œβ”€β–Ί "You're using actor model. Create an expert?" [y/n] - β”‚ (Dynamic agent generation) - β”‚ - └─► "Want to create a custom agent for this pattern?" [y/n] - (User-defined agent) - β”‚ - β–Ό - Agent added to ~/.claude/agents/ - β”‚ - β–Ό - Next /review includes new agent -``` - ---- - -## Technical Approach - -### Phase 1: Split Into Core + Agent Library - -**New Marketplace Structure:** +After each `/compound`: ``` -every-marketplace/ -β”œβ”€β”€ .claude-plugin/ -β”‚ └── marketplace.json -β”œβ”€β”€ plugins/ -β”‚ β”œβ”€β”€ compounding-engineering/ # CORE (seed) -β”‚ β”‚ β”œβ”€β”€ .claude-plugin/plugin.json -β”‚ β”‚ β”œβ”€β”€ agents/ -β”‚ β”‚ β”‚ β”œβ”€β”€ review/ -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ security-sentinel.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ performance-oracle.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ code-simplicity-reviewer.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ architecture-strategist.md -β”‚ β”‚ β”‚ β”‚ └── pattern-recognition-specialist.md -β”‚ β”‚ β”‚ β”œβ”€β”€ research/ -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ best-practices-researcher.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ framework-docs-researcher.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ git-history-analyzer.md -β”‚ β”‚ β”‚ β”‚ └── repo-research-analyst.md -β”‚ β”‚ β”‚ └── workflow/ -β”‚ β”‚ β”‚ β”œβ”€β”€ bug-reproduction-validator.md -β”‚ β”‚ β”‚ └── spec-flow-analyzer.md -β”‚ β”‚ β”œβ”€β”€ commands/ -β”‚ β”‚ β”‚ └── workflows/ -β”‚ β”‚ β”‚ β”œβ”€β”€ plan.md -β”‚ β”‚ β”‚ β”œβ”€β”€ work.md -β”‚ β”‚ β”‚ β”œβ”€β”€ review.md -β”‚ β”‚ β”‚ └── compound.md -β”‚ β”‚ β”œβ”€β”€ skills/ -β”‚ β”‚ β”‚ β”œβ”€β”€ compound-docs/ -β”‚ β”‚ β”‚ β”œβ”€β”€ file-todos/ -β”‚ β”‚ β”‚ β”œβ”€β”€ git-worktree/ -β”‚ β”‚ β”‚ β”œβ”€β”€ create-agent-skills/ -β”‚ β”‚ β”‚ └── skill-creator/ -β”‚ β”‚ └── mcp-servers/ -β”‚ β”‚ β”œβ”€β”€ playwright -β”‚ β”‚ └── context7 -β”‚ β”‚ -β”‚ └── agent-library/ # OPTIONAL (predefined agents) -β”‚ β”œβ”€β”€ .claude-plugin/plugin.json -β”‚ β”œβ”€β”€ rails/ -β”‚ β”‚ β”œβ”€β”€ kieran-rails-reviewer.md -β”‚ β”‚ β”œβ”€β”€ dhh-rails-reviewer.md -β”‚ β”‚ └── data-integrity-guardian.md -β”‚ β”œβ”€β”€ python/ -β”‚ β”‚ └── kieran-python-reviewer.md -β”‚ β”œβ”€β”€ typescript/ -β”‚ β”‚ └── kieran-typescript-reviewer.md -β”‚ β”œβ”€β”€ frontend/ -β”‚ β”‚ β”œβ”€β”€ julik-frontend-races-reviewer.md -β”‚ β”‚ β”œβ”€β”€ design-iterator.md -β”‚ β”‚ β”œβ”€β”€ design-implementation-reviewer.md -β”‚ β”‚ └── figma-design-sync.md -β”‚ └── editorial/ -β”‚ └── every-style-editor.md -└── docs/ +βœ… Learning documented + +πŸ’‘ It looks like you're using Rails. + Would you like to add the "DHH Rails Reviewer"? + + [y] Yes [n] No [x] Never ask ``` -**Core Plugin Components (Seed):** +Three sources of new agents: +1. **Predefined** - "You're using Rails, add DHH reviewer?" +2. **Dynamic** - "You're using actor model, create an expert?" +3. **Custom** - "Want to create an agent for this pattern?" -| Category | Components | Count | -|----------|------------|-------| -| Commands | /plan, /work, /review, /compound | 4 | -| Review Agents | security, performance, simplicity, architecture, patterns | 5 | -| Research Agents | best-practices, framework-docs, git-history, repo-analyst | 4 | -| Workflow Agents | bug-reproduction, spec-flow | 2 | -| Skills | compound-docs, file-todos, git-worktree, create-agent-skills, skill-creator | 5 | -| MCP Servers | playwright, context7 | 2 | -| **TOTAL** | | **22 components** | - -**Agent Library (Optional Install):** - -| Category | Agents | Count | -|----------|--------|-------| -| Rails | kieran-rails, dhh-rails, data-integrity | 3 | -| Python | kieran-python | 1 | -| TypeScript | kieran-typescript | 1 | -| Frontend | julik-races, design-iterator, design-reviewer, figma-sync | 4 | -| Editorial | every-style-editor | 1 | -| **TOTAL** | | **10 agents** | - -### Phase 2: Agent Discovery & Storage - -**Agent Storage Locations (priority order):** +### Agent Storage ``` -1. Project agents: .claude/agents/*.md (highest priority) -2. User agents: ~/.claude/agents/*.md (user's garden) -3. Plugin agents: plugin/agents/*.md (from installed plugins) +.claude/agents/ β†’ Project-specific (highest priority) +~/.claude/agents/ β†’ User's garden +plugin/agents/ β†’ From installed plugins ``` -**Agent Metadata Format (frontmatter):** - -```yaml ---- -name: dhh-rails-reviewer -description: Reviews Rails code from DHH's perspective -tech_stack: [rails, ruby] # When to suggest -commands: [review] # Which commands use this -priority: 10 # Execution order (higher = first) -source: predefined # predefined | dynamic | custom -version: 1.0.0 -enabled: true # Can be disabled without deletion ---- -``` - -**Discovery Mechanism:** - -```ruby -# Pseudocode for /review agent discovery -def discover_agents(command: "review") - agents = [] - - # 1. Project agents (highest priority) - agents += glob(".claude/agents/**/*.md") - .filter { |a| a.commands.include?(command) && a.enabled } - - # 2. User's garden - agents += glob("~/.claude/agents/**/*.md") - .filter { |a| a.commands.include?(command) && a.enabled } - .reject { |a| agents.any? { |pa| pa.name == a.name } } # no duplicates - - # 3. Plugin agents - installed_plugins.each do |plugin| - agents += plugin.agents - .filter { |a| a.commands.include?(command) && a.enabled } - .reject { |a| agents.any? { |ea| ea.name == a.name } } - end - - agents.sort_by(&:priority).reverse -end -``` - -### Phase 3: Enhanced /compound with Growth - -**Updated /compound Flow:** - -```markdown -## /compound command (enhanced) - -1. Document the learning (existing behavior) - - Capture solution to compound-docs - -2. Analyze context (NEW) - - Detect tech stack from project files - - Analyze git diff for patterns - - Check user's existing agents - -3. Suggest growth (NEW) - - Match patterns to agent library - - Consider dynamic agent generation - - Present suggestion with clear UX - -4. Handle response (NEW) - - Accept: Install agent to ~/.claude/agents/ - - Decline: Record preference, don't ask again for this agent - - Custom: Launch agent creation workflow -``` - -**Suggestion UX (non-blocking):** - -``` -βœ… Learning documented to compound-docs - -πŸ’‘ Growth suggestion: - Your solution uses Rails conventions extensively. - - Would you like to add the "DHH Rails Reviewer" agent? - This agent reviews code from DHH's perspective, checking for: - β€’ Rails conventions and idioms - β€’ Hotwire/Turbo patterns - β€’ Fat models, skinny controllers - - [y] Yes, add it [n] No thanks [?] Tell me more [x] Never suggest this -``` - -**Tech Stack Detection:** - -```ruby -def detect_tech_stack(project_root) - stack = [] - - # Ruby/Rails - stack << :rails if File.exist?("Gemfile") && - File.read("Gemfile").include?("rails") - stack << :ruby if File.exist?("Gemfile") - - # JavaScript/TypeScript - if File.exist?("package.json") - pkg = JSON.parse(File.read("package.json")) - stack << :react if pkg.dig("dependencies", "react") - stack << :vue if pkg.dig("dependencies", "vue") - stack << :typescript if pkg.dig("devDependencies", "typescript") - stack << :node if pkg["type"] == "module" || pkg["main"] - end - - # Python - stack << :python if File.exist?("requirements.txt") || - File.exist?("pyproject.toml") - stack << :django if File.exist?("manage.py") - stack << :fastapi if File.read("requirements.txt")&.include?("fastapi") - - # Go - stack << :go if File.exist?("go.mod") - - stack -end -``` - -### Phase 4: Agent Management Commands - -**New Commands:** - -```bash -# List all agents in user's garden + plugins -/agents list -/agents list --tech rails # Filter by tech stack -/agents list --command review # Filter by command - -# Add agent from library -/agents add dhh-rails-reviewer -/agents add kieran-python-reviewer - -# Remove agent from garden -/agents remove dhh-rails-reviewer - -# Disable without removing -/agents disable dhh-rails-reviewer -/agents enable dhh-rails-reviewer - -# Create custom agent -/agents create "Our API Style Guide" - -# View agent details -/agents show dhh-rails-reviewer - -# Export for sharing -/agents export dhh-rails-reviewer > my-dhh-tweaks.md - -# Import shared agent -/agents import ./shared-agents/team-patterns.md -``` - ---- - -## Alternative Approaches Considered - -### Option A: Keep Monolithic (Current) -- **Pros:** Simple, one install, everything works -- **Cons:** Bloated, no personalization, no growth -- **Decision:** Rejected - doesn't support the "grow your garden" vision - -### Option B: Separate Plugins per Tech Stack -- **Pros:** Users install only what they need -- **Cons:** No dependency support in Claude Code, manual multi-install required -- **Decision:** Rejected - friction too high, doesn't enable organic growth - -### Option C: Core + Agent Library + Growth (Proposed) -- **Pros:** Minimal start, organic growth, personalized, shared process -- **Cons:** More complex implementation, new UX to design -- **Decision:** Selected - best aligns with vision - ---- - -## Acceptance Criteria - -### Functional Requirements - -- [ ] Core plugin installs with 4 commands + ~11 core agents -- [ ] `/review` discovers agents from project β†’ user β†’ plugin locations -- [ ] `/compound` detects tech stack and suggests relevant agents -- [ ] Users can accept/decline/never-ask for suggestions -- [ ] `/agents` command manages user's garden -- [ ] Predefined agents installable from library -- [ ] Custom agents creatable and storable - -### Non-Functional Requirements - -- [ ] Agent discovery < 100ms for 50 agents -- [ ] Suggestion analysis adds < 2s to /compound -- [ ] No breaking changes for existing users -- [ ] Clear migration path from monolithic plugin - -### Quality Gates - -- [ ] Documentation for growth model -- [ ] Tests for agent discovery priority -- [ ] Tests for tech stack detection -- [ ] User feedback mechanism in suggestions - ---- - -## Success Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Adoption | 50% of users add β‰₯1 agent within 30 days | Track /agents add usage | -| Engagement | Average 3+ agents per active user | Count ~/.claude/agents/ | -| Retention | 80% of added agents still enabled after 30 days | Track disable/remove | -| Satisfaction | Suggestion acceptance rate > 40% | Track y/n responses | - ---- - ## Implementation Phases -### Phase 1: Split (No Breaking Changes) -**Goal:** Separate core from optional agents, keep everything working +### Phase 1: Split the Plugin +- Create `agent-library/` with framework-specific agents (Rails, Python, TypeScript, Frontend) +- Keep `compounding-engineering` as core with universal agents +- No breaking changesβ€”existing users unaffected -1. Create `agent-library/` directory structure -2. Move framework-specific agents to library -3. Update marketplace.json with both plugins -4. Keep `compounding-engineering` as meta-package that includes both -5. Test existing users unaffected +### Phase 2: Agent Discovery +- `/review` discovers agents from all three locations +- Project agents override user agents override plugin agents -**Files to create:** -- `plugins/agent-library/.claude-plugin/plugin.json` -- `plugins/agent-library/rails/*.md` (move existing) -- `plugins/agent-library/python/*.md` (move existing) -- `plugins/agent-library/typescript/*.md` (move existing) -- `plugins/agent-library/frontend/*.md` (move existing) - -### Phase 2: Discovery -**Goal:** Commands discover agents from multiple locations - -1. Implement agent discovery in /review -2. Support project β†’ user β†’ plugin priority -3. Add agent metadata frontmatter parsing -4. Test with agents in different locations - -**Files to modify:** -- `plugins/compounding-engineering/commands/workflows/review.md` -- All agent files (add frontmatter) - -### Phase 3: Growth -**Goal:** /compound suggests agents based on learnings - -1. Add tech stack detection -2. Implement suggestion matching against library -3. Design and implement suggestion UX -4. Handle accept/decline/never-ask responses -5. Auto-install accepted agents to ~/.claude/agents/ - -**Files to modify:** -- `plugins/compounding-engineering/commands/workflows/compound.md` -- `plugins/compounding-engineering/skills/compound-docs/SKILL.md` +### Phase 3: Growth via /compound +- Detect tech stack (Gemfile, package.json, etc.) +- Suggest relevant agents after documenting learnings +- Install accepted agents to `~/.claude/agents/` ### Phase 4: Management -**Goal:** Users can manage their garden +- `/agents list` - See your garden +- `/agents add ` - Add from library +- `/agents disable ` - Temporarily disable -1. Create `/agents` command with subcommands -2. Implement list, add, remove, disable, enable -3. Add export/import for sharing -4. Add custom agent creation wizard +## What Goes Where -**Files to create:** -- `plugins/compounding-engineering/commands/agents.md` +**Core (seed):** 11 framework-agnostic agents +- security-sentinel, performance-oracle, code-simplicity-reviewer +- architecture-strategist, pattern-recognition-specialist +- 4 research agents, 2 workflow agents ---- +**Agent Library:** 10 specialized agents +- Rails: kieran-rails, dhh-rails, data-integrity (3) +- Python: kieran-python (1) +- TypeScript: kieran-typescript (1) +- Frontend: julik-races, design-iterator, design-reviewer, figma-sync (4) +- Editorial: every-style-editor (1) -## Dependencies & Prerequisites +## Key Constraint -- [ ] Claude Code plugin system supports user-level agents (~/.claude/agents/) -- [ ] Agent frontmatter can be parsed for metadata -- [ ] /review can be modified to support dynamic agent discovery +Claude Code doesn't support plugin dependencies. Each plugin must be independent. Users manually install what they need, or we suggest additions via `/compound`. ---- +## Acceptance Criteria -## Risk Analysis & Mitigation - -| Risk | Likelihood | Impact | Mitigation | -|------|------------|--------|------------| -| User confusion with growth model | Medium | High | Clear onboarding, simple defaults | -| Performance with many agents | Low | Medium | Lazy loading, parallel execution | -| Breaking existing workflows | Low | High | Phased rollout, meta-package option | -| Suggestion fatigue | Medium | Medium | Smart throttling, "never ask" option | - ---- - -## Future Considerations - -1. **Dynamic Agent Generation:** LLM generates custom agent from learning context -2. **Agent Marketplace:** Community-contributed agents with ratings -3. **Team Gardens:** Shared agent collections for organizations -4. **Agent Composition:** Agents that build on other agents -5. **Auto-Refinement:** Agents improve from user feedback over time - ---- - -## References - -### Internal -- GitHub Issue: https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -- Current plugin structure: `plugins/compounding-engineering/` -- Agent examples: `plugins/compounding-engineering/agents/` - -### External -- [VSCode Extension Packs](https://code.visualstudio.com/api/references/extension-manifest) -- [Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins) -- [Claude Code Plugin Dependencies Request](https://github.com/anthropics/claude-code/issues/9444) - ---- - -## ERD: Agent Discovery - -```mermaid -erDiagram - USER ||--o{ USER_AGENT : "grows" - USER ||--o{ PROJECT : "works on" - PROJECT ||--o{ PROJECT_AGENT : "has" - PLUGIN ||--o{ PLUGIN_AGENT : "provides" - AGENT_LIBRARY ||--o{ PREDEFINED_AGENT : "contains" - - USER_AGENT { - string name - string tech_stack - string commands - string source - boolean enabled - } - - PROJECT_AGENT { - string name - string tech_stack - string commands - boolean enabled - } - - PLUGIN_AGENT { - string name - string tech_stack - string commands - } - - PREDEFINED_AGENT { - string name - string category - string tech_stack - string description - } - - COMMAND ||--o{ AGENT : "discovers" - COMMAND { - string name - string type - } - - AGENT { - string source_location - int priority - } -``` - ---- - -## Appendix: Component Categorization - -### Core Plugin (Seed) - 22 Components - -**Commands (4):** -| Command | Purpose | -|---------|---------| -| /plan | Create implementation plans | -| /work | Execute work systematically | -| /review | Multi-agent code review | -| /compound | Document learnings + suggest growth | - -**Core Agents (11):** -| Agent | Category | Purpose | -|-------|----------|---------| -| security-sentinel | review | Security audits | -| performance-oracle | review | Performance analysis | -| code-simplicity-reviewer | review | Simplicity checks | -| architecture-strategist | review | Architecture review | -| pattern-recognition-specialist | review | Pattern analysis | -| best-practices-researcher | research | External best practices | -| framework-docs-researcher | research | Framework documentation | -| git-history-analyzer | research | Git archaeology | -| repo-research-analyst | research | Repository analysis | -| bug-reproduction-validator | workflow | Bug reproduction | -| spec-flow-analyzer | workflow | Spec analysis | - -**Skills (5):** -| Skill | Purpose | -|-------|---------| -| compound-docs | Document learnings | -| file-todos | Todo tracking | -| git-worktree | Parallel development | -| create-agent-skills | Skill creation | -| skill-creator | Skill guidance | - -**MCP Servers (2):** -| Server | Purpose | -|--------|---------| -| playwright | Browser automation | -| context7 | Documentation lookup | - -### Agent Library - 10 Agents - -**Rails (3):** -- kieran-rails-reviewer -- dhh-rails-reviewer -- data-integrity-guardian - -**Python (1):** -- kieran-python-reviewer - -**TypeScript (1):** -- kieran-typescript-reviewer - -**Frontend (4):** -- julik-frontend-races-reviewer -- design-iterator -- design-implementation-reviewer -- figma-design-sync - -**Editorial (1):** -- every-style-editor +- [ ] Core plugin works standalone with universal agents +- [ ] `/compound` suggests agents based on detected tech stack +- [ ] Users can accept/decline suggestions +- [ ] `/agents` command for garden management +- [ ] No breaking changes for existing users