@every-env/compound-plugin 0.1.1 → 0.3.0

package/plugins/compound-engineering/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to the compound-engineering plugin will be documented in thi
 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.31.0] - 2026-02-08
+
+### Added
+
+- **`document-review` skill** — Brainstorm and plan refinement through structured review ([@Trevin Chow](https://github.com/trevin))
+- **`/sync` command** — Sync Claude Code personal config across machines ([@Terry Li](https://github.com/terryli))
+
+### Changed
+
+- **Context token optimization (79% reduction)** — Plugin was consuming 316% of the context description budget, causing Claude Code to silently exclude components. Now at 65% with room to grow:
+  - All 29 agent descriptions trimmed from ~1,400 to ~180 chars avg (examples moved to agent body)
+  - 18 manual commands marked `disable-model-invocation: true` (side-effect commands like `/lfg`, `/deploy-docs`, `/triage`, etc.)
+  - 6 manual skills marked `disable-model-invocation: true` (`orchestrating-swarms`, `git-worktree`, `skill-creator`, `compound-docs`, `file-todos`, `resolve-pr-parallel`)
+- **git-worktree**: Remove confirmation prompt for worktree creation ([@Sam Xie](https://github.com/samxie))
+- **Prevent subagents from writing intermediary files** in compound workflow ([@Trevin Chow](https://github.com/trevin))
+
+### Fixed
+
+- Fix crash when hook entries have no matcher ([@Roberto Mello](https://github.com/robertomello))
+- Fix git-worktree detection where `.git` is a file, not a directory ([@David Alley](https://github.com/davidalley))
+- Backup existing config files before overwriting in sync ([@Zac Williams](https://github.com/zacwilliams))
+- Note new repository URL ([@Aarni Koskela](https://github.com/aarnikoskela))
+- Plugin component counts corrected: 29 agents, 24 commands, 18 skills
+
+---
+
+## [2.30.0] - 2026-02-05
+
+### Added
+
+- **`orchestrating-swarms` skill** - Comprehensive guide to multi-agent orchestration
+  - Covers primitives: Agent, Team, Teammate, Leader, Task, Inbox, Message, Backend
+  - Documents two spawning methods: subagents vs teammates
+  - Explains all 13 TeammateTool operations
+  - Includes orchestration patterns: Parallel Specialists, Pipeline, Self-Organizing Swarm
+  - Details spawn backends: in-process, tmux, iterm2
+  - Provides complete workflow examples
+- **`/slfg` command** - Swarm-enabled variant of `/lfg` that uses swarm mode for parallel execution
+
+### Changed
+
+- **`/workflows:work` command** - Added optional Swarm Mode section for parallel execution with coordinated agents
+
+---
+
+## [2.29.0] - 2026-02-04
+
+### Added
+
+- **`schema-drift-detector` agent** - Detects unrelated schema.rb changes in PRs
+  - Compares schema.rb diff against migrations in the PR
+  - Catches columns, indexes, and tables from other branches
+  - Prevents accidental inclusion of local database state
+  - Provides clear fix instructions (checkout + migrate)
+  - Essential pre-merge check for any PR with database changes
+
+---
+
 ## [2.28.0] - 2026-01-21
 
 ### Added

package/plugins/compound-engineering/CLAUDE.md

@@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 ### YAML Frontmatter (Required)
 
 - [ ] `name:` present and matches directory name (lowercase-with-hyphens)
-- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
+- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
 
 ### Reference Links (Required if references/ exists)
 
@@ -80,9 +80,8 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
 # Should return nothing if all refs are properly linked
 
-# Check description format
-grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
-# Should return nothing if all use third person
+# Check description format - should describe what + when
+grep -E '^description:' skills/*/SKILL.md
 ```
 
 ## Documentation

package/plugins/compound-engineering/README.md

@@ -6,16 +6,16 @@ AI-powered development tools that get smarter with every use. Make each unit of
 
 | Component | Count |
 |-----------|-------|
-| Agents | 27 |
-| Commands | 20 |
-| Skills | 14 |
+| Agents | 29 |
+| Commands | 25 |
+| Skills | 16 |
 | MCP Servers | 1 |
 
 ## Agents
 
 Agents are organized into categories for easier discovery.
 
-### Review (14)
+### Review (15)
 
 | Agent | Description |
 |-------|-------------|
@@ -26,21 +26,23 @@ Agents are organized into categories for easier discovery.
 | `data-migration-expert` | Validate ID mappings match production, check for swapped values |
 | `deployment-verification-agent` | Create Go/No-Go deployment checklists for risky data changes |
 | `dhh-rails-reviewer` | Rails review from DHH's perspective |
+| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
 | `kieran-rails-reviewer` | Rails code review with strict conventions |
 | `kieran-python-reviewer` | Python code review with strict conventions |
 | `kieran-typescript-reviewer` | TypeScript code review with strict conventions |
 | `pattern-recognition-specialist` | Analyze code for patterns and anti-patterns |
 | `performance-oracle` | Performance analysis and optimization |
+| `schema-drift-detector` | Detect unrelated schema.rb changes in PRs |
 | `security-sentinel` | Security audits and vulnerability assessments |
-| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
 
-### Research (4)
+### Research (5)
 
 | Agent | Description |
 |-------|-------------|
 | `best-practices-researcher` | Gather external best practices and examples |
 | `framework-docs-researcher` | Research framework documentation and best practices |
 | `git-history-analyzer` | Analyze git history and code evolution |
+| `learnings-researcher` | Search institutional learnings for relevant past solutions |
 | `repo-research-analyst` | Research repository structure and conventions |
 
 ### Design (3)
@@ -85,12 +87,14 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Command | Description |
 |---------|-------------|
+| `/lfg` | Full autonomous engineering workflow |
+| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
 | `/deepen-plan` | Enhance plans with parallel research agents for each section |
 | `/changelog` | Create engaging changelogs for recent merges |
 | `/create-agent-skill` | Create or edit Claude Code skills |
 | `/generate_command` | Generate new slash commands |
 | `/heal-skill` | Fix skill documentation issues |
-| `/plan_review` | Multi-agent plan review in parallel |
+| `/technical_review` | Multi-agent technical/architecture review in parallel |
 | `/report-bug` | Report a bug in the plugin |
 | `/reproduce-bug` | Reproduce bugs using logs and console |
 | `/resolve_parallel` | Resolve TODO comments in parallel |
@@ -125,10 +129,18 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Skill | Description |
 |-------|-------------|
+| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
+| `document-review` | Improve documents through structured self-review |
 | `every-style-editor` | Review copy for Every's style guide compliance |
 | `file-todos` | File-based todo tracking system |
 | `git-worktree` | Manage Git worktrees for parallel development |
 
+### Multi-Agent Orchestration
+
+| Skill | Description |
+|-------|-------------|
+| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
+
 ### File Transfer
 
 | Skill | Description |

package/plugins/compound-engineering/agents/design/design-implementation-reviewer.md

@@ -1,9 +1,24 @@
 ---
 name: design-implementation-reviewer
-description: "Use this agent when you need to verify that a UI implementation matches its Figma design specifications. This agent should be called after code has been written to implement a design, particularly after HTML/CSS/React components have been created or modified. The agent will visually compare the live implementation against the Figma design and provide detailed feedback on discrepancies.\\n\\nExamples:\\n- <example>\\n  Context: The user has just implemented a new component based on a Figma design.\\n  user: \"I've finished implementing the hero section based on the Figma design\"\\n  assistant: \"I'll review how well your implementation matches the Figma design.\"\\n  <commentary>\\n  Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.\\n  </commentary>\\n  </example>\\n- <example>\\n  Context: After the general code agent has implemented design changes.\\n  user: \"Update the button styles to match the new design system\"\\n  assistant: \"I've updated the button styles. Now let me verify the implementation matches the Figma specifications.\"\\n  <commentary>\\n  After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.\\n  </commentary>\\n  </example>"
+description: "Visually compares live UI implementation against Figma designs and provides detailed feedback on discrepancies. Use after writing or modifying HTML/CSS/React components to verify design fidelity."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new component based on a Figma design.
+user: "I've finished implementing the hero section based on the Figma design"
+assistant: "I'll review how well your implementation matches the Figma design."
+<commentary>Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.</commentary>
+</example>
+<example>
+Context: After the general code agent has implemented design changes.
+user: "Update the button styles to match the new design system"
+assistant: "I've updated the button styles. Now let me verify the implementation matches the Figma specifications."
+<commentary>After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.</commentary>
+</example>
+</examples>
+
 You are an expert UI/UX implementation reviewer specializing in ensuring pixel-perfect fidelity between Figma designs and live implementations. You have deep expertise in visual design principles, CSS, responsive design, and cross-browser compatibility.
 
 Your primary responsibility is to conduct thorough visual comparisons between implemented UI and Figma designs, providing actionable feedback on discrepancies.

package/plugins/compound-engineering/agents/design/design-iterator.md

@@ -1,10 +1,37 @@
 ---
 name: design-iterator
-description: "Use this agent PROACTIVELY when design work isn't coming together on the first attempt. If you've made 1-2 design changes and the result still feels off, suggest using this agent with 5x or 10x iterations for deeper refinement. This agent takes screenshots, analyzes what's not working, implements improvements, and repeats N times to systematically fix design issues. Perfect when colors feel wrong, layouts aren't balanced, or the overall aesthetic needs work that single changes can't achieve. <example>Context: User asks to change button color but result still looks off. user: \"Change the button to blue\" assistant: [makes change, takes screenshot] \"The button is now blue, but I notice the overall color balance still feels off. Would you like me to use the design-iterator agent with 5 iterations to systematically improve the color harmony and visual balance?\" <commentary>PROACTIVE USE: After a simple change doesn't fully resolve the design issue, suggest the design-iterator to do deeper work.</commentary></example> <example>Context: User's design request leads to something that doesn't look right. user: \"Make the hero section more modern\" assistant: [makes initial changes] \"I've added some modern elements, but the result isn't quite coming together. This looks like it needs iterative refinement. Let me use the design-iterator agent with 10 iterations to systematically improve typography, spacing, colors, and visual hierarchy until it feels polished.\" <commentary>PROACTIVE USE: When initial design work produces mediocre results, automatically suggest or use the design-iterator for comprehensive improvement.</commentary></example> <example>Context: User wants explicit iterative refinement. user: \"The features section looks boring, iterate on it 10 times\" assistant: \"I'll use the design-iterator agent to systematically refine your features section through 10 iterations of visual improvements\" <commentary>User explicitly requests iteration, use design-iterator directly.</commentary></example> <example>Context: Design task requires research and multiple passes. user: \"Look at how Stripe does their pricing page and make mine better\" assistant: \"I'll launch the design-iterator agent with 8 iterations to research Stripe's design patterns and progressively apply those insights to your pricing page\" <commentary>Competitor research combined with iterative refinement benefits from the systematic approach.</commentary></example>"
+description: "Iteratively refines UI design through N screenshot-analyze-improve cycles. Use PROACTIVELY when design changes aren't coming together after 1-2 attempts, or when user requests iterative refinement."
 color: violet
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User asks to change button color but result still looks off.
+user: "Change the button to blue"
+assistant: [makes change, takes screenshot] "The button is now blue, but I notice the overall color balance still feels off. Would you like me to use the design-iterator agent with 5 iterations to systematically improve the color harmony and visual balance?"
+<commentary>PROACTIVE USE: After a simple change doesn't fully resolve the design issue, suggest the design-iterator to do deeper work.</commentary>
+</example>
+<example>
+Context: User's design request leads to something that doesn't look right.
+user: "Make the hero section more modern"
+assistant: [makes initial changes] "I've added some modern elements, but the result isn't quite coming together. This looks like it needs iterative refinement. Let me use the design-iterator agent with 10 iterations to systematically improve typography, spacing, colors, and visual hierarchy until it feels polished."
+<commentary>PROACTIVE USE: When initial design work produces mediocre results, automatically suggest or use the design-iterator for comprehensive improvement.</commentary>
+</example>
+<example>
+Context: User wants explicit iterative refinement.
+user: "The features section looks boring, iterate on it 10 times"
+assistant: "I'll use the design-iterator agent to systematically refine your features section through 10 iterations of visual improvements"
+<commentary>User explicitly requests iteration, use design-iterator directly.</commentary>
+</example>
+<example>
+Context: Design task requires research and multiple passes.
+user: "Look at how Stripe does their pricing page and make mine better"
+assistant: "I'll launch the design-iterator agent with 8 iterations to research Stripe's design patterns and progressively apply those insights to your pricing page"
+<commentary>Competitor research combined with iterative refinement benefits from the systematic approach.</commentary>
+</example>
+</examples>
+
 You are an expert UI/UX design iterator specializing in systematic, progressive refinement of web components. Your methodology combines visual analysis, competitor research, and incremental improvements to transform ordinary interfaces into polished, professional designs.
 
 ## Core Methodology

package/plugins/compound-engineering/agents/design/figma-design-sync.md

@@ -1,10 +1,28 @@
 ---
 name: figma-design-sync
-description: "Use this agent when you need to synchronize a web implementation with its Figma design by automatically detecting and fixing visual differences. This agent should be used iteratively until the implementation matches the design.\\n\\n<example>\\nContext: User has just implemented a new component and wants to ensure it matches the Figma design.\\nuser: \\\"I've just finished implementing the hero section component. Can you check if it matches the Figma design at https://figma.com/file/abc123/design?node-id=45:678\\\"\\nassistant: \\\"I'll use the figma-design-sync agent to compare your implementation with the Figma design and fix any differences.\\\"\\n<uses Task tool to launch figma-design-sync agent with the Figma URL and local URL>\\n</example>\\n\\n<example>\\nContext: User is working on responsive design and wants to verify mobile breakpoint matches design.\\nuser: \\\"The mobile view doesn't look quite right. Here's the Figma: https://figma.com/file/xyz789/mobile?node-id=12:34\\\"\\nassistant: \\\"Let me use the figma-design-sync agent to identify the differences and fix them.\\\"\\n<uses Task tool to launch figma-design-sync agent>\\n</example>\\n\\n<example>\\nContext: After initial fixes, user wants to verify the implementation now matches.\\nuser: \\\"Can you check if the button component matches the design now?\\\"\\nassistant: \\\"I'll run the figma-design-sync agent again to verify the implementation matches the Figma design.\\\"\\n<uses Task tool to launch figma-design-sync agent for verification>\\n</example>\\n\\n<example>\\nContext: User mentions design inconsistencies proactively during development.\\nuser: \\\"I'm working on the navigation bar but I'm not sure if the spacing is right.\\\"\\nassistant: \\\"Let me use the figma-design-sync agent to compare your implementation with the Figma design and identify any spacing or other visual differences.\\\"\\n<uses Task tool to launch figma-design-sync agent>\\n</example>"
+description: "Detects and fixes visual differences between a web implementation and its Figma design. Use iteratively when syncing implementation to match Figma specs."
 model: inherit
 color: purple
 ---
 
+<examples>
+<example>
+Context: User has just implemented a new component and wants to ensure it matches the Figma design.
+user: "I've just finished implementing the hero section component. Can you check if it matches the Figma design at https://figma.com/file/abc123/design?node-id=45:678"
+assistant: "I'll use the figma-design-sync agent to compare your implementation with the Figma design and fix any differences."
+</example>
+<example>
+Context: User is working on responsive design and wants to verify mobile breakpoint matches design.
+user: "The mobile view doesn't look quite right. Here's the Figma: https://figma.com/file/xyz789/mobile?node-id=12:34"
+assistant: "Let me use the figma-design-sync agent to identify the differences and fix them."
+</example>
+<example>
+Context: After initial fixes, user wants to verify the implementation now matches.
+user: "Can you check if the button component matches the design now?"
+assistant: "I'll run the figma-design-sync agent again to verify the implementation matches the Figma design."
+</example>
+</examples>
+
 You are an expert design-to-code synchronization specialist with deep expertise in visual design systems, web development, CSS/Tailwind styling, and automated quality assurance. Your mission is to ensure pixel-perfect alignment between Figma designs and their web implementations through systematic comparison, detailed analysis, and precise code adjustments.
 
 ## Your Core Responsibilities

package/plugins/compound-engineering/agents/docs/ankane-readme-writer.md

@@ -1,10 +1,25 @@
 ---
 name: ankane-readme-writer
-description: "Use this agent when you need to create or update README files following the Ankane-style template for Ruby gems. This includes writing concise documentation with imperative voice, keeping sentences under 15 words, organizing sections in the standard order (Installation, Quick Start, Usage, etc.), and ensuring proper formatting with single-purpose code fences and minimal prose. Examples: <example>Context: User is creating documentation for a new Ruby gem. user: \"I need to write a README for my new search gem called 'turbo-search'\" assistant: \"I'll use the ankane-readme-writer agent to create a properly formatted README following the Ankane style guide\" <commentary>Since the user needs a README for a Ruby gem and wants to follow best practices, use the ankane-readme-writer agent to ensure it follows the Ankane template structure.</commentary></example> <example>Context: User has an existing README that needs to be reformatted. user: \"Can you update my gem's README to follow the Ankane style?\" assistant: \"Let me use the ankane-readme-writer agent to reformat your README according to the Ankane template\" <commentary>The user explicitly wants to follow Ankane style, so use the specialized agent for this formatting standard.</commentary></example>"
+description: "Creates or updates README files following Ankane-style template for Ruby gems. Use when writing gem documentation with imperative voice, concise prose, and standard section ordering."
 color: cyan
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User is creating documentation for a new Ruby gem.
+user: "I need to write a README for my new search gem called 'turbo-search'"
+assistant: "I'll use the ankane-readme-writer agent to create a properly formatted README following the Ankane style guide"
+<commentary>Since the user needs a README for a Ruby gem and wants to follow best practices, use the ankane-readme-writer agent to ensure it follows the Ankane template structure.</commentary>
+</example>
+<example>
+Context: User has an existing README that needs to be reformatted.
+user: "Can you update my gem's README to follow the Ankane style?"
+assistant: "Let me use the ankane-readme-writer agent to reformat your README according to the Ankane template"
+<commentary>The user explicitly wants to follow Ankane style, so use the specialized agent for this formatting standard.</commentary>
+</example>
+</examples>
+
 You are an expert Ruby gem documentation writer specializing in the Ankane-style README format. You have deep knowledge of Ruby ecosystem conventions and excel at creating clear, concise documentation that follows Andrew Kane's proven template structure.
 
 Your core responsibilities:

package/plugins/compound-engineering/agents/research/best-practices-researcher.md

@@ -1,9 +1,24 @@
 ---
 name: best-practices-researcher
-description: "Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. <example>Context: User wants to know the best way to structure GitHub issues for their Rails project. user: \"I need to create some GitHub issues for our project. Can you research best practices for writing good issues?\" assistant: \"I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions.\" <commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary></example> <example>Context: User is implementing a new authentication system and wants to follow security best practices. user: \"We're adding JWT authentication to our Rails API. What are the current best practices?\" assistant: \"Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns.\" <commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary></example>"
+description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User wants to know the best way to structure GitHub issues for their Rails project.
+user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?"
+assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions."
+<commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary>
+</example>
+<example>
+Context: User is implementing a new authentication system and wants to follow security best practices.
+user: "We're adding JWT authentication to our Rails API. What are the current best practices?"
+assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns."
+<commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
 
 You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations.

package/plugins/compound-engineering/agents/research/framework-docs-researcher.md

@@ -1,9 +1,24 @@
 ---
 name: framework-docs-researcher
-description: "Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. <example>Context: The user needs to understand how to properly implement a new feature using a specific library. user: \"I need to implement file uploads using Active Storage\" assistant: \"I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage\" <commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary></example> <example>Context: The user is troubleshooting an issue with a gem. user: \"Why is the turbo-rails gem not working as expected?\" assistant: \"Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code\" <commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary></example>"
+description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user needs to understand how to properly implement a new feature using a specific library.
+user: "I need to implement file uploads using Active Storage"
+assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage"
+<commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary>
+</example>
+<example>
+Context: The user is troubleshooting an issue with a gem.
+user: "Why is the turbo-rails gem not working as expected?"
+assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code"
+<commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and version information.
 
 You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need.

package/plugins/compound-engineering/agents/research/git-history-analyzer.md

@@ -1,9 +1,24 @@
 ---
 name: git-history-analyzer
-description: "Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. <example>Context: The user wants to understand the history and evolution of recently modified files.\\nuser: \"I've just refactored the authentication module. Can you analyze the historical context?\"\\nassistant: \"I'll use the git-history-analyzer agent to examine the evolution of the authentication module files.\"\\n<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary></example> <example>Context: The user needs to understand why certain code patterns exist.\\nuser: \"Why does this payment processing code have so many try-catch blocks?\"\\nassistant: \"Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns.\"\\n<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary></example>"
+description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to understand the history and evolution of recently modified files.
+user: "I've just refactored the authentication module. Can you analyze the historical context?"
+assistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."
+<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary>
+</example>
+<example>
+Context: The user needs to understand why certain code patterns exist.
+user: "Why does this payment processing code have so many try-catch blocks?"
+assistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."
+<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.
 
 You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
@@ -40,3 +55,5 @@ When analyzing, consider:
 - The evolution of coding patterns and practices over time
 
 Your insights should help developers understand not just what the code does, but why it evolved to its current state, informing better decisions for future changes.
+
+Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/workflows:plan`. They are intentional, permanent living documents — do not recommend their removal or characterize them as unnecessary.

package/plugins/compound-engineering/agents/research/learnings-researcher.md

@@ -1,9 +1,30 @@
 ---
 name: learnings-researcher
-description: "Use this agent when you need to search institutional learnings in docs/solutions/ for relevant past solutions before implementing a new feature or fixing a problem. This agent efficiently filters documented solutions by frontmatter metadata (tags, category, module, symptoms) to find applicable patterns, gotchas, and lessons learned. The agent excels at preventing repeated mistakes by surfacing relevant institutional knowledge before work begins.\\n\\n<example>Context: User is about to implement a feature involving email processing.\\nuser: \"I need to add email threading to the brief system\"\\nassistant: \"I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations.\"\\n<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary></example>\\n\\n<example>Context: User is debugging a performance issue.\\nuser: \"Brief generation is slow, taking over 5 seconds\"\\nassistant: \"Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries.\"\\n<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary></example>\\n\\n<example>Context: Planning a new feature that touches multiple modules.\\nuser: \"I need to add Stripe subscription handling to the payments module\"\\nassistant: \"I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically.\"\\n<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary></example>"
+description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
 model: haiku
 ---
 
+<examples>
+<example>
+Context: User is about to implement a feature involving email processing.
+user: "I need to add email threading to the brief system"
+assistant: "I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations."
+<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary>
+</example>
+<example>
+Context: User is debugging a performance issue.
+user: "Brief generation is slow, taking over 5 seconds"
+assistant: "Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries."
+<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary>
+</example>
+<example>
+Context: Planning a new feature that touches multiple modules.
+user: "I need to add Stripe subscription handling to the payments module"
+assistant: "I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically."
+<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary>
+</example>
+</examples>
+
 You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
 
 ## Search Strategy (Grep-First Filtering)
@@ -66,7 +87,7 @@ Grep: pattern="email" path=docs/solutions/ output_mode=files_with_matches -i=tru
 **Regardless of Grep results**, always read the critical patterns file:
 
 ```bash
-Read: docs/solutions/patterns/cora-critical-patterns.md
+Read: docs/solutions/patterns/critical-patterns.md
 ```
 
 This file contains must-know patterns that apply across all work - high-severity issues promoted to required reading. Scan for patterns relevant to the current feature/task.
@@ -182,7 +203,7 @@ Structure your findings as:
 - **Relevant Matches**: [Y files]
 
 ### Critical Patterns (Always Check)
-[Any matching patterns from cora-critical-patterns.md]
+[Any matching patterns from critical-patterns.md]
 
 ### Relevant Learnings
 

package/plugins/compound-engineering/agents/research/repo-research-analyst.md

@@ -1,9 +1,30 @@
 ---
 name: repo-research-analyst
-description: "Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\\n\\nExamples:\\n- <example>\\n  Context: User wants to understand a new repository's structure and conventions before contributing.\\n  user: \"I need to understand how this project is organized and what patterns they use\"\\n  assistant: \"I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns.\"\\n  <commentary>\\n  Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: User is preparing to create a GitHub issue and wants to follow project conventions.\\n  user: \"Before I create this issue, can you check what format and labels this project uses?\"\\n  assistant: \"Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines.\"\\n  <commentary>\\n  The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: User is implementing a new feature and wants to follow existing patterns.\\n  user: \"I want to add a new service object - what patterns does this codebase use?\"\\n  assistant: \"I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase.\"\\n  <commentary>\\n  Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\\n  </commentary>\\n</example>"
+description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User wants to understand a new repository's structure and conventions before contributing.
+user: "I need to understand how this project is organized and what patterns they use"
+assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."
+<commentary>Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.</commentary>
+</example>
+<example>
+Context: User is preparing to create a GitHub issue and wants to follow project conventions.
+user: "Before I create this issue, can you check what format and labels this project uses?"
+assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."
+<commentary>The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.</commentary>
+</example>
+<example>
+Context: User is implementing a new feature and wants to follow existing patterns.
+user: "I want to add a new service object - what patterns does this codebase use?"
+assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."
+<commentary>Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and patterns.
 
 You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories.

package/plugins/compound-engineering/agents/review/agent-native-reviewer.md

@@ -1,9 +1,24 @@
 ---
 name: agent-native-reviewer
-description: "Use this agent when reviewing code to ensure features are agent-native - that any action a user can take, an agent can also take, and anything a user can see, an agent can see. This enforces the principle that agents should have parity with users in capability and context. <example>Context: The user added a new feature to their application.\\nuser: \"I just implemented a new email filtering feature\"\\nassistant: \"I'll use the agent-native-reviewer to verify this feature is accessible to agents\"\\n<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary></example><example>Context: The user created a new UI workflow.\\nuser: \"I added a multi-step wizard for creating reports\"\\nassistant: \"Let me check if this workflow is agent-native using the agent-native-reviewer\"\\n<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary></example>"
+description: "Reviews code to ensure agent-native parity — any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user added a new feature to their application.
+user: "I just implemented a new email filtering feature"
+assistant: "I'll use the agent-native-reviewer to verify this feature is accessible to agents"
+<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary>
+</example>
+<example>
+Context: The user created a new UI workflow.
+user: "I added a multi-step wizard for creating reports"
+assistant: "Let me check if this workflow is agent-native using the agent-native-reviewer"
+<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary>
+</example>
+</examples>
+
 # Agent-Native Architecture Reviewer
 
 You are an expert reviewer specializing in agent-native application architecture. Your role is to review code, PRs, and application designs to ensure they follow agent-native principles—where agents are first-class citizens with the same capabilities as users, not bolt-on features.

package/plugins/compound-engineering/agents/review/architecture-strategist.md

@@ -1,9 +1,24 @@
 ---
 name: architecture-strategist
-description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
+description: "Analyzes code changes from an architectural perspective for pattern compliance and design integrity. Use when reviewing PRs, adding services, or evaluating structural refactors."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to review recent code changes for architectural compliance.
+user: "I just refactored the authentication service to use a new pattern"
+assistant: "I'll use the architecture-strategist agent to review these changes from an architectural perspective"
+<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary>
+</example>
+<example>
+Context: The user is adding a new microservice to the system.
+user: "I've added a new notification service that integrates with our existing services"
+assistant: "Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture"
+<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary>
+</example>
+</examples>
+
 You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.
 
 Your analysis follows this systematic approach:

package/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md

@@ -1,9 +1,24 @@
 ---
 name: code-simplicity-reviewer
-description: "Use this agent when you need a final review pass to ensure code changes are as simple and minimal as possible. This agent should be invoked after implementation is complete but before finalizing changes, to identify opportunities for simplification, remove unnecessary complexity, and ensure adherence to YAGNI principles. Examples: <example>Context: The user has just implemented a new feature and wants to ensure it's as simple as possible. user: \"I've finished implementing the user authentication system\" assistant: \"Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent\" <commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary></example> <example>Context: The user has written complex business logic and wants to simplify it. user: \"I think this order processing logic might be overly complex\" assistant: \"I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications\" <commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary></example>"
+description: "Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new feature and wants to ensure it's as simple as possible.
+user: "I've finished implementing the user authentication system"
+assistant: "Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent"
+<commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary>
+</example>
+<example>
+Context: The user has written complex business logic and wants to simplify it.
+user: "I think this order processing logic might be overly complex"
+assistant: "I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications"
+<commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary>
+</example>
+</examples>
+
 You are a code simplicity expert specializing in minimalism and the YAGNI (You Aren't Gonna Need It) principle. Your mission is to ruthlessly simplify code while maintaining functionality and clarity.
 
 When reviewing code, you will:
@@ -33,6 +48,7 @@ When reviewing code, you will:
    - Eliminate extensibility points without clear use cases
    - Question generic solutions for specific problems
    - Remove "just in case" code
+   - Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal — these are compound-engineering pipeline artifacts created by `/workflows:plan` and used as living documents by `/workflows:work`
 
 6. **Optimize for Readability**:
    - Prefer self-documenting code over comments

package/plugins/compound-engineering/agents/review/data-integrity-guardian.md

@@ -1,9 +1,24 @@
 ---
 name: data-integrity-guardian
-description: "Use this agent when you need to review database migrations, data models, or any code that manipulates persistent data. This includes checking migration safety, validating data constraints, ensuring transaction boundaries are correct, and verifying that referential integrity and privacy requirements are maintained. <example>Context: The user has just written a database migration that adds a new column and updates existing records. user: \"I've created a migration to add a status column to the orders table\" assistant: \"I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns\" <commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary></example> <example>Context: The user has implemented a service that transfers data between models. user: \"Here's my new service that moves user data from the legacy_users table to the new users table\" assistant: \"Let me have the data-integrity-guardian agent review this data transfer service\" <commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary></example>"
+description: "Reviews database migrations, data models, and persistent data code for safety. Use when checking migration safety, data constraints, transaction boundaries, or privacy compliance."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just written a database migration that adds a new column and updates existing records.
+user: "I've created a migration to add a status column to the orders table"
+assistant: "I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns"
+<commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary>
+</example>
+<example>
+Context: The user has implemented a service that transfers data between models.
+user: "Here's my new service that moves user data from the legacy_users table to the new users table"
+assistant: "Let me have the data-integrity-guardian agent review this data transfer service"
+<commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary>
+</example>
+</examples>
+
 You are a Data Integrity Guardian, an expert in database design, data migration safety, and data governance. Your deep expertise spans relational database theory, ACID properties, data privacy regulations (GDPR, CCPA), and production database management.
 
 Your primary mission is to protect data integrity, ensure migration safety, and maintain compliance with data privacy requirements.