@every-env/compound-plugin 0.1.0

package/plugins/compound-engineering/commands/workflows/compound.md

@@ -0,0 +1,202 @@
+---
+name: workflows:compound
+description: Document a recently solved problem to compound your team's knowledge
+argument-hint: "[optional: brief context about the fix]"
+---
+
+# /compound
+
+Coordinate multiple subagents working in parallel to document a recently solved problem.
+
+## Purpose
+
+Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
+
+**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
+
+## Usage
+
+```bash
+/workflows:compound                    # Document the most recent fix
+/workflows:compound [brief context]    # Provide additional context hint
+```
+
+## Execution Strategy: Parallel Subagents
+
+This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
+
+### 1. **Context Analyzer** (Parallel)
+   - Extracts conversation history
+   - Identifies problem type, component, symptoms
+   - Validates against CORA schema
+   - Returns: YAML frontmatter skeleton
+
+### 2. **Solution Extractor** (Parallel)
+   - Analyzes all investigation steps
+   - Identifies root cause
+   - Extracts working solution with code examples
+   - Returns: Solution content block
+
+### 3. **Related Docs Finder** (Parallel)
+   - Searches `docs/solutions/` for related documentation
+   - Identifies cross-references and links
+   - Finds related GitHub issues
+   - Returns: Links and relationships
+
+### 4. **Prevention Strategist** (Parallel)
+   - Develops prevention strategies
+   - Creates best practices guidance
+   - Generates test cases if applicable
+   - Returns: Prevention/testing content
+
+### 5. **Category Classifier** (Parallel)
+   - Determines optimal `docs/solutions/` category
+   - Validates category against schema
+   - Suggests filename based on slug
+   - Returns: Final path and filename
+
+### 6. **Documentation Writer** (Parallel)
+   - Assembles complete markdown file
+   - Validates YAML frontmatter
+   - Formats content for readability
+   - Creates the file in correct location
+
+### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
+   Based on problem type detected, automatically invoke applicable agents:
+   - **performance_issue** → `performance-oracle`
+   - **security_issue** → `security-sentinel`
+   - **database_issue** → `data-integrity-guardian`
+   - **test_failure** → `cora-test-reviewer`
+   - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+
+## What It Captures
+
+- **Problem symptom**: Exact error messages, observable behavior
+- **Investigation steps tried**: What didn't work and why
+- **Root cause analysis**: Technical explanation
+- **Working solution**: Step-by-step fix with code examples
+- **Prevention strategies**: How to avoid in future
+- **Cross-references**: Links to related issues and docs
+
+## Preconditions
+
+<preconditions enforcement="advisory">
+  <check condition="problem_solved">
+    Problem has been solved (not in-progress)
+  </check>
+  <check condition="solution_verified">
+    Solution has been verified working
+  </check>
+  <check condition="non_trivial">
+    Non-trivial problem (not simple typo or obvious error)
+  </check>
+</preconditions>
+
+## What It Creates
+
+**Organized documentation:**
+
+- File: `docs/solutions/[category]/[filename].md`
+
+**Categories auto-detected from problem:**
+
+- build-errors/
+- test-failures/
+- runtime-errors/
+- performance-issues/
+- database-issues/
+- security-issues/
+- ui-bugs/
+- integration-issues/
+- logic-errors/
+
+## Success Output
+
+```
+✓ Parallel documentation generation complete
+
+Primary Subagent Results:
+  ✓ Context Analyzer: Identified performance_issue in brief_system
+  ✓ Solution Extractor: Extracted 3 code fixes
+  ✓ Related Docs Finder: Found 2 related issues
+  ✓ Prevention Strategist: Generated test cases
+  ✓ Category Classifier: docs/solutions/performance-issues/
+  ✓ Documentation Writer: Created complete markdown
+
+Specialized Agent Reviews (Auto-Triggered):
+  ✓ performance-oracle: Validated query optimization approach
+  ✓ kieran-rails-reviewer: Code examples meet Rails standards
+  ✓ code-simplicity-reviewer: Solution is appropriately minimal
+  ✓ every-style-editor: Documentation style verified
+
+File created:
+- docs/solutions/performance-issues/n-plus-one-brief-generation.md
+
+This documentation will be searchable for future reference when similar
+issues occur in the Email Processing or Brief System modules.
+
+What's next?
+1. Continue workflow (recommended)
+2. Link related documentation
+3. Update other references
+4. View documentation
+5. Other
+```
+
+## The Compounding Philosophy
+
+This creates a compounding knowledge system:
+
+1. First time you solve "N+1 query in brief generation" → Research (30 min)
+2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
+3. Next time similar issue occurs → Quick lookup (2 min)
+4. Knowledge compounds → Team gets smarter
+
+The feedback loop:
+
+```
+Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
+    ↑                                                                      ↓
+    └──────────────────────────────────────────────────────────────────────┘
+```
+
+**Each unit of engineering work should make subsequent units of work easier—not harder.**
+
+## Auto-Invoke
+
+<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
+
+<manual_override> Use /workflows:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
+
+## Routes To
+
+`compound-docs` skill
+
+## Applicable Specialized Agents
+
+Based on problem type, these agents can enhance documentation:
+
+### Code Quality & Review
+- **kieran-rails-reviewer**: Reviews code examples for Rails best practices
+- **code-simplicity-reviewer**: Ensures solution code is minimal and clear
+- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues
+
+### Specific Domain Experts
+- **performance-oracle**: Analyzes performance_issue category solutions
+- **security-sentinel**: Reviews security_issue solutions for vulnerabilities
+- **cora-test-reviewer**: Creates test cases for prevention strategies
+- **data-integrity-guardian**: Reviews database_issue migrations and queries
+
+### Enhancement & Documentation
+- **best-practices-researcher**: Enriches solution with industry best practices
+- **every-style-editor**: Reviews documentation style and clarity
+- **framework-docs-researcher**: Links to Rails/gem documentation references
+
+### When to Invoke
+- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
+- **Manual trigger**: User can invoke agents after /workflows:compound completes for deeper review
+
+## Related Commands
+
+- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
+- `/workflows:plan` - Planning workflow (references documented solutions)

package/plugins/compound-engineering/commands/workflows/plan.md

@@ -0,0 +1,466 @@
+---
+name: workflows:plan
+description: Transform feature descriptions into well-structured project plans following conventions
+argument-hint: "[feature description, bug report, or improvement idea]"
+---
+
+# Create a plan for a new feature or bug fix
+
+## Introduction
+
+**Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.
+
+Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
+
+## Feature Description
+
+<feature_description> #$ARGUMENTS </feature_description>
+
+**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."
+
+Do not proceed until you have a clear feature description from the user.
+
+### 0. Idea Refinement
+
+Before running research, refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
+
+- Ask questions one at a time to understand the idea fully
+- Prefer multiple choice questions when natural options exist
+- Focus on understanding: purpose, constraints and success criteria
+- Continue until the idea is clear OR user says "proceed"
+
+**Skip option:** If the feature description is already detailed, offer:
+"Your description is clear. Should I proceed with research, or would you like to refine it further?"
+
+## Main Tasks
+
+### 1. Repository Research & Context Gathering
+
+<thinking>
+First, I need to understand the project's conventions and existing patterns, leveraging all available resources and use paralel subagents to do this.
+</thinking>
+
+Runn these three agents in paralel at the same time:
+
+- Task repo-research-analyst(feature_description)
+- Task best-practices-researcher(feature_description)
+- Task framework-docs-researcher(feature_description)
+
+**Reference Collection:**
+
+- [ ] Document all research findings with specific file paths (e.g., `app/services/example_service.rb:42`)
+- [ ] Include URLs to external documentation and best practices guides
+- [ ] Create a reference list of similar issues or PRs (e.g., `#123`, `#456`)
+- [ ] Note any team conventions discovered in `CLAUDE.md` or team documentation
+
+### Research Validation (Optional)
+
+After research agents complete, briefly validate alignment:
+
+- Summarize key findings from research
+- Ask if anything looks off or is missing
+- User can confirm or request additional research on specific topics
+
+### 2. Issue Planning & Structure
+
+<thinking>
+Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
+</thinking>
+
+**Title & Categorization:**
+
+- [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
+- [ ] Determine issue type: enhancement, bug, refactor
+- [ ] Convert title to kebab-case filename: strip prefix colon, lowercase, hyphens for spaces
+  - Example: `feat: Add User Authentication` → `feat-add-user-authentication.md`
+  - Keep it descriptive (3-5 words after prefix) so plans are findable by context
+
+**Stakeholder Analysis:**
+
+- [ ] Identify who will be affected by this issue (end users, developers, operations)
+- [ ] Consider implementation complexity and required expertise
+
+**Content Planning:**
+
+- [ ] Choose appropriate detail level based on issue complexity and audience
+- [ ] List all necessary sections for the chosen template
+- [ ] Gather supporting materials (error logs, screenshots, design mockups)
+- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
+
+### 3. SpecFlow Analysis
+
+After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
+
+- Task spec-flow-analyzer(feature_description, research_findings)
+
+**SpecFlow Analyzer Output:**
+
+- [ ] Review SpecFlow analysis results
+- [ ] Incorporate any identified gaps or edge cases into the issue
+- [ ] Update acceptance criteria based on SpecFlow findings
+
+### 4. Choose Implementation Detail Level
+
+Select how comprehensive you want the issue to be, simpler is mostly better.
+
+#### 📄 MINIMAL (Quick Issue)
+
+**Best for:** Simple bugs, small improvements, clear features
+
+**Includes:**
+
+- Problem statement or feature description
+- Basic acceptance criteria
+- Essential context only
+
+**Structure:**
+
+````markdown
+[Brief problem/feature description]
+
+## Acceptance Criteria
+
+- [ ] Core requirement 1
+- [ ] Core requirement 2
+
+## Context
+
+[Any critical information]
+
+## MVP
+
+### test.rb
+
+```ruby
+class Test
+  def initialize
+    @name = "test"
+  end
+end
+```
+
+## References
+
+- Related issue: #[issue_number]
+- Documentation: [relevant_docs_url]
+````
+
+#### 📋 MORE (Standard Issue)
+
+**Best for:** Most features, complex bugs, team collaboration
+
+**Includes everything from MINIMAL plus:**
+
+- Detailed background and motivation
+- Technical considerations
+- Success metrics
+- Dependencies and risks
+- Basic implementation suggestions
+
+**Structure:**
+
+```markdown
+## Overview
+
+[Comprehensive description]
+
+## Problem Statement / Motivation
+
+[Why this matters]
+
+## Proposed Solution
+
+[High-level approach]
+
+## Technical Considerations
+
+- Architecture impacts
+- Performance implications
+- Security considerations
+
+## Acceptance Criteria
+
+- [ ] Detailed requirement 1
+- [ ] Detailed requirement 2
+- [ ] Testing requirements
+
+## Success Metrics
+
+[How we measure success]
+
+## Dependencies & Risks
+
+[What could block or complicate this]
+
+## References & Research
+
+- Similar implementations: [file_path:line_number]
+- Best practices: [documentation_url]
+- Related PRs: #[pr_number]
+```
+
+#### 📚 A LOT (Comprehensive Issue)
+
+**Best for:** Major features, architectural changes, complex integrations
+
+**Includes everything from MORE plus:**
+
+- Detailed implementation plan with phases
+- Alternative approaches considered
+- Extensive technical specifications
+- Resource requirements and timeline
+- Future considerations and extensibility
+- Risk mitigation strategies
+- Documentation requirements
+
+**Structure:**
+
+```markdown
+## Overview
+
+[Executive summary]
+
+## Problem Statement
+
+[Detailed problem analysis]
+
+## Proposed Solution
+
+[Comprehensive solution design]
+
+## Technical Approach
+
+### Architecture
+
+[Detailed technical design]
+
+### Implementation Phases
+
+#### Phase 1: [Foundation]
+
+- Tasks and deliverables
+- Success criteria
+- Estimated effort
+
+#### Phase 2: [Core Implementation]
+
+- Tasks and deliverables
+- Success criteria
+- Estimated effort
+
+#### Phase 3: [Polish & Optimization]
+
+- Tasks and deliverables
+- Success criteria
+- Estimated effort
+
+## Alternative Approaches Considered
+
+[Other solutions evaluated and why rejected]
+
+## Acceptance Criteria
+
+### Functional Requirements
+
+- [ ] Detailed functional criteria
+
+### Non-Functional Requirements
+
+- [ ] Performance targets
+- [ ] Security requirements
+- [ ] Accessibility standards
+
+### Quality Gates
+
+- [ ] Test coverage requirements
+- [ ] Documentation completeness
+- [ ] Code review approval
+
+## Success Metrics
+
+[Detailed KPIs and measurement methods]
+
+## Dependencies & Prerequisites
+
+[Detailed dependency analysis]
+
+## Risk Analysis & Mitigation
+
+[Comprehensive risk assessment]
+
+## Resource Requirements
+
+[Team, time, infrastructure needs]
+
+## Future Considerations
+
+[Extensibility and long-term vision]
+
+## Documentation Plan
+
+[What docs need updating]
+
+## References & Research
+
+### Internal References
+
+- Architecture decisions: [file_path:line_number]
+- Similar features: [file_path:line_number]
+- Configuration: [file_path:line_number]
+
+### External References
+
+- Framework documentation: [url]
+- Best practices guide: [url]
+- Industry standards: [url]
+
+### Related Work
+
+- Previous PRs: #[pr_numbers]
+- Related issues: #[issue_numbers]
+- Design documents: [links]
+```
+
+### 5. Issue Creation & Formatting
+
+<thinking>
+Apply best practices for clarity and actionability, making the issue easy to scan and understand
+</thinking>
+
+**Content Formatting:**
+
+- [ ] Use clear, descriptive headings with proper hierarchy (##, ###)
+- [ ] Include code examples in triple backticks with language syntax highlighting
+- [ ] Add screenshots/mockups if UI-related (drag & drop or use image hosting)
+- [ ] Use task lists (- [ ]) for trackable items that can be checked off
+- [ ] Add collapsible sections for lengthy logs or optional details using `<details>` tags
+- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)
+
+**Cross-Referencing:**
+
+- [ ] Link to related issues/PRs using #number format
+- [ ] Reference specific commits with SHA hashes when relevant
+- [ ] Link to code using GitHub's permalink feature (press 'y' for permanent link)
+- [ ] Mention relevant team members with @username if needed
+- [ ] Add links to external resources with descriptive text
+
+**Code & Examples:**
+
+````markdown
+# Good example with syntax highlighting and line references
+
+
+```ruby
+# app/services/user_service.rb:42
+def process_user(user)
+
+# Implementation here
+
+end
+```
+
+# Collapsible error logs
+
+<details>
+<summary>Full error stacktrace</summary>
+
+`Error details here...`
+
+</details>
+````
+
+**AI-Era Considerations:**
+
+- [ ] Account for accelerated development with AI pair programming
+- [ ] Include prompts or instructions that worked well during research
+- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
+- [ ] Emphasize comprehensive testing given rapid implementation
+- [ ] Document any AI-generated code that needs human review
+
+### 6. Final Review & Submission
+
+**Pre-submission Checklist:**
+
+- [ ] Title is searchable and descriptive
+- [ ] Labels accurately categorize the issue
+- [ ] All template sections are complete
+- [ ] Links and references are working
+- [ ] Acceptance criteria are measurable
+- [ ] Add names of files in pseudo code examples and todo lists
+- [ ] Add an ERD mermaid diagram if applicable for new model changes
+
+## Output Format
+
+**Filename:** Use the kebab-case filename from Step 2 Title & Categorization.
+
+```
+plans/<type>-<descriptive-name>.md
+```
+
+Examples:
+- ✅ `plans/feat-user-authentication-flow.md`
+- ✅ `plans/fix-checkout-race-condition.md`
+- ✅ `plans/refactor-api-client-extraction.md`
+- ❌ `plans/plan-1.md` (not descriptive)
+- ❌ `plans/new-feature.md` (too vague)
+- ❌ `plans/feat: user auth.md` (invalid characters)
+
+## Post-Generation Options
+
+After writing the plan file, use the **AskUserQuestion tool** to present these options:
+
+**Question:** "Plan ready at `plans/<issue_title>.md`. What would you like to do next?"
+
+**Options:**
+1. **Open plan in editor** - Open the plan file for review
+2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
+3. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity)
+4. **Start `/workflows:work`** - Begin implementing this plan locally
+5. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
+6. **Create Issue** - Create issue in project tracker (GitHub/Linear)
+7. **Simplify** - Reduce detail level
+
+Based on selection:
+- **Open plan in editor** → Run `open plans/<issue_title>.md` to open the file in the user's default editor
+- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
+- **`/plan_review`** → Call the /plan_review command with the plan file path
+- **`/workflows:work`** → Call the /workflows:work command with the plan file path
+- **`/workflows:work` on remote** → Run `/workflows:work plans/<issue_title>.md &` to start work in background for Claude Code web
+- **Create Issue** → See "Issue Creation" section below
+- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
+- **Other** (automatically provided) → Accept free text for rework or specific changes
+
+**Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
+
+Loop back to options after Simplify or Other changes until user selects `/workflows: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/<issue_title>.md
+   ```
+
+3. **If Linear:**
+   ```bash
+   # Use linear CLI if available, or provide instructions
+   # linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.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 `/workflows:work` or `/plan_review`
+
+NEVER CODE! Just research and write the plan.