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