claude-engineering-plugin/plans/grow-your-own-garden-plugin-architecture.md

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

Overview

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.

Philosophy: Everyone grows their own garden, but we're all using the same process.

---

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

---

Proposed Solution

Architecture: Seed + Growth Model

┌─────────────────────────────────────────────────────────────────┐
│                    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│                                           │
│  └─────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘

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:

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/

Core Plugin Components (Seed):

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):

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)

Agent Metadata Format (frontmatter):

---
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:

# 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:

## /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:

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:

# 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

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

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 4: Management

Goal: Users can manage their garden

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

Files to create:

• plugins/compounding-engineering/commands/agents.md

---

Dependencies & Prerequisites

• 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

---

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
• Claude Code Plugin Docs
• Claude Code Plugin Dependencies Request

---

ERD: Agent Discovery

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