diff --git a/plans/grow-your-own-garden-plugin-architecture.md b/plans/grow-your-own-garden-plugin-architecture.md new file mode 100644 index 0000000..729a0ba --- /dev/null +++ b/plans/grow-your-own-garden-plugin-architecture.md @@ -0,0 +1,644 @@ +# 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):** + +```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 + +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](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 diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index 119e00f..2cb141b 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.8.0", + "version": "2.8.1", "description": "AI-powered development tools. 24 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index 61df97e..00a1800 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.8.1] - 2025-11-27 + +### Added + +- **`/plan` command** - Added "Create Issue" option to post-generation menu. Detects project tracker (GitHub or Linear) from user's CLAUDE.md (`project_tracker: github` or `project_tracker: linear`) and creates issues using `gh issue create` or Linear CLI. + ## [2.8.0] - 2025-11-27 ### Added diff --git a/plugins/compounding-engineering/commands/workflows/plan.md b/plugins/compounding-engineering/commands/workflows/plan.md index 4781f52..452408a 100644 --- a/plugins/compounding-engineering/commands/workflows/plan.md +++ b/plugins/compounding-engineering/commands/workflows/plan.md @@ -378,16 +378,47 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o **Options:** 1. **Start `/work`** - Begin implementing this plan 2. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity) -3. **Simplify** - Reduce detail level -4. **Rework** - Change approach or request specific changes +3. **Create Issue** - Create issue in project tracker (GitHub/Linear) +4. **Simplify** - Reduce detail level +5. **Rework** - Change approach or request specific changes Based on selection: - **`/work`** → Call the /work command with the plan file path - **`/plan_review`** → Call the /plan_review command with the plan file path +- **Create Issue** → See "Issue Creation" section below - **Simplify** → Ask "What should I simplify?" then regenerate simpler version - **Rework** → Ask "What would you like changed?" then regenerate with changes - **Other** (automatically provided) → Accept free text, act on it Loop back to options after Simplify/Rework until user selects `/work` or `/plan_review`. +## Issue Creation + +When user selects "Create Issue", detect their project tracker from CLAUDE.md: + +1. **Check for tracker preference** in user's CLAUDE.md (global or project): + - Look for `project_tracker: github` or `project_tracker: linear` + - Or look for mentions of "GitHub Issues" or "Linear" in their workflow section + +2. **If GitHub:** + ```bash + # Extract title from plan filename (kebab-case to Title Case) + # Read plan content for body + gh issue create --title "feat: [Plan Title]" --body-file plans/.md + ``` + +3. **If Linear:** + ```bash + # Use linear CLI if available, or provide instructions + # linear issue create --title "[Plan Title]" --description "$(cat plans/.md)" + ``` + +4. **If no tracker configured:** + Ask user: "Which project tracker do you use? (GitHub/Linear/Other)" + - Suggest adding `project_tracker: github` or `project_tracker: linear` to their CLAUDE.md + +5. **After creation:** + - Display the issue URL + - Ask if they want to proceed to `/work` or `/plan_review` + NEVER CODE! Just research and write the plan.