compound-engineering-pi 0.2.3

package/plugins/compound-engineering/skills/compound-docs/assets/critical-pattern-template.md

@@ -0,0 +1,34 @@
+# Critical Pattern Template
+
+Use this template when adding a pattern to `docs/solutions/patterns/critical-patterns.md`:
+
+---
+
+## N. [Pattern Name] (ALWAYS REQUIRED)
+
+### ❌ WRONG ([Will cause X error])
+```[language]
+[code showing wrong approach]
+```
+
+### ✅ CORRECT
+```[language]
+[code showing correct approach]
+```
+
+**Why:** [Technical explanation of why this is required]
+
+**Placement/Context:** [When this applies]
+
+**Documented in:** `docs/solutions/[category]/[filename].md`
+
+---
+
+**Instructions:**
+1. Replace N with the next pattern number
+2. Replace [Pattern Name] with descriptive title
+3. Fill in WRONG example with code that causes the problem
+4. Fill in CORRECT example with the solution
+5. Explain the technical reason in "Why"
+6. Clarify when this pattern applies in "Placement/Context"
+7. Link to the full troubleshooting doc where this was originally solved

package/plugins/compound-engineering/skills/compound-docs/assets/resolution-template.md

@@ -0,0 +1,93 @@
+---
+module: [Module name or "System" for system-wide]
+date: [YYYY-MM-DD]
+problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
+component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
+symptoms:
+  - [Observable symptom 1 - specific error message or behavior]
+  - [Observable symptom 2 - what user actually saw/experienced]
+root_cause: [missing_association|missing_include|missing_index|wrong_api|scope_issue|thread_violation|async_timing|memory_leak|config_error|logic_error|test_isolation|missing_validation|missing_permission]
+rails_version: [7.1.2 - optional]
+resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
+severity: [critical|high|medium|low]
+tags: [keyword1, keyword2, keyword3]
+---
+
+# Troubleshooting: [Clear Problem Title]
+
+## Problem
+[1-2 sentence clear description of the issue and what the user experienced]
+
+## Environment
+- Module: [Name or "System-wide"]
+- Rails Version: [e.g., 7.1.2]
+- Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
+- Date: [YYYY-MM-DD when this was solved]
+
+## Symptoms
+- [Observable symptom 1 - what the user saw/experienced]
+- [Observable symptom 2 - error messages, visual issues, unexpected behavior]
+- [Continue as needed - be specific]
+
+## What Didn't Work
+
+**Attempted Solution 1:** [Description of what was tried]
+- **Why it failed:** [Technical reason this didn't solve the problem]
+
+**Attempted Solution 2:** [Description of second attempt]
+- **Why it failed:** [Technical reason]
+
+[Continue for all significant attempts that DIDN'T work]
+
+[If nothing else was attempted first, write:]
+**Direct solution:** The problem was identified and fixed on the first attempt.
+
+## Solution
+
+[The actual fix that worked - provide specific details]
+
+**Code changes** (if applicable):
+```ruby
+# Before (broken):
+[Show the problematic code]
+
+# After (fixed):
+[Show the corrected code with explanation]
+```
+
+**Database migration** (if applicable):
+```ruby
+# Migration change:
+[Show what was changed in the migration]
+```
+
+**Commands run** (if applicable):
+```bash
+# Steps taken to fix:
+[Commands or actions]
+```
+
+## Why This Works
+
+[Technical explanation of:]
+1. What was the ROOT CAUSE of the problem?
+2. Why does the solution address this root cause?
+3. What was the underlying issue (API misuse, configuration error, Rails version issue, etc.)?
+
+[Be detailed enough that future developers understand the "why", not just the "what"]
+
+## Prevention
+
+[How to avoid this problem in future development:]
+- [Specific coding practice, check, or pattern to follow]
+- [What to watch out for]
+- [How to catch this early]
+
+## Related Issues
+
+[If any similar problems exist in docs/solutions/, link to them:]
+- See also: [another-related-issue.md](../category/another-related-issue.md)
+- Similar to: [related-problem.md](../category/related-problem.md)
+
+[If no related issues, write:]
+No related issues documented yet.

package/plugins/compound-engineering/skills/compound-docs/references/yaml-schema.md

@@ -0,0 +1,65 @@
+# YAML Frontmatter Schema
+
+**See `.claude/skills/codify-docs/schema.yaml` for the complete schema specification.**
+
+## Required Fields
+
+- **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
+- **date** (string): ISO 8601 date (YYYY-MM-DD)
+- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
+- **component** (enum): One of [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling]
+- **symptoms** (array): 1-5 specific observable symptoms
+- **root_cause** (enum): One of [missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup]
+- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
+- **severity** (enum): One of [critical, high, medium, low]
+
+## Optional Fields
+
+- **rails_version** (string): Rails version in X.Y.Z format
+- **tags** (array): Searchable keywords (lowercase, hyphen-separated)
+
+## Validation Rules
+
+1. All required fields must be present
+2. Enum fields must match allowed values exactly (case-sensitive)
+3. symptoms must be YAML array with 1-5 items
+4. date must match YYYY-MM-DD format
+5. rails_version (if provided) must match X.Y.Z format
+6. tags should be lowercase, hyphen-separated
+
+## Example
+
+```yaml
+---
+module: Email Processing
+date: 2025-11-12
+problem_type: performance_issue
+component: rails_model
+symptoms:
+  - "N+1 query when loading email threads"
+  - "Brief generation taking >5 seconds"
+root_cause: missing_include
+rails_version: 7.1.2
+resolution_type: code_fix
+severity: high
+tags: [n-plus-one, eager-loading, performance]
+---
+```
+
+## Category Mapping
+
+Based on `problem_type`, documentation is filed in:
+
+- **build_error** → `docs/solutions/build-errors/`
+- **test_failure** → `docs/solutions/test-failures/`
+- **runtime_error** → `docs/solutions/runtime-errors/`
+- **performance_issue** → `docs/solutions/performance-issues/`
+- **database_issue** → `docs/solutions/database-issues/`
+- **security_issue** → `docs/solutions/security-issues/`
+- **ui_bug** → `docs/solutions/ui-bugs/`
+- **integration_issue** → `docs/solutions/integration-issues/`
+- **logic_error** → `docs/solutions/logic-errors/`
+- **developer_experience** → `docs/solutions/developer-experience/`
+- **workflow_issue** → `docs/solutions/workflow-issues/`
+- **best_practice** → `docs/solutions/best-practices/`
+- **documentation_gap** → `docs/solutions/documentation-gaps/`

package/plugins/compound-engineering/skills/compound-docs/schema.yaml

@@ -0,0 +1,176 @@
+# CORA Documentation Schema
+# This schema MUST be validated before writing any documentation file
+
+required_fields:
+  module:
+    type: string
+    description: "Module/area of CORA (e.g., 'Email Processing', 'Brief System', 'Authentication')"
+    examples:
+      - "Email Processing"
+      - "Brief System"
+      - "Assistant"
+      - "Authentication"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date when this problem was solved (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error          # Rails, bundle, compilation errors
+      - test_failure         # Test failures, flaky tests
+      - runtime_error        # Exceptions, crashes during execution
+      - performance_issue    # Slow queries, memory issues, N+1 queries
+      - database_issue       # Migration, query, schema problems
+      - security_issue       # Authentication, authorization, XSS, SQL injection
+      - ui_bug               # Frontend, Stimulus, Turbo issues
+      - integration_issue    # External service, API integration problems
+      - logic_error          # Business logic bugs
+      - developer_experience # DX issues: workflow, tooling, seed data, dev setup
+      - workflow_issue       # Development process, missing steps, unclear practices
+      - best_practice        # Documenting patterns and practices to follow
+      - documentation_gap    # Missing or inadequate documentation
+    description: "Primary category of the problem"
+
+  component:
+    type: enum
+    values:
+      - rails_model          # ActiveRecord models
+      - rails_controller     # ActionController
+      - rails_view           # ERB templates, ViewComponent
+      - service_object       # Custom service classes
+      - background_job       # Sidekiq, Active Job
+      - database             # PostgreSQL, migrations, schema
+      - frontend_stimulus    # Stimulus JS controllers
+      - hotwire_turbo        # Turbo Streams, Turbo Drive
+      - email_processing     # Email handling, mailers
+      - brief_system         # Brief generation, summarization
+      - assistant            # AI assistant, prompts
+      - authentication       # Devise, user auth
+      - payments             # Stripe, billing
+      - development_workflow # Dev process, seed data, tooling
+      - testing_framework    # Test setup, fixtures, VCR
+      - documentation        # README, guides, inline docs
+      - tooling              # Scripts, generators, CLI tools
+    description: "CORA component involved"
+
+  symptoms:
+    type: array[string]
+    min_items: 1
+    max_items: 5
+    description: "Observable symptoms (error messages, visual issues, crashes)"
+    examples:
+      - "N+1 query detected in brief generation"
+      - "Brief emails not appearing in summary"
+      - "Turbo Stream response returns 404"
+
+  root_cause:
+    type: enum
+    values:
+      - missing_association  # Incorrect Rails associations
+      - missing_include      # Missing eager loading (N+1)
+      - missing_index        # Database performance issue
+      - wrong_api            # Using deprecated/incorrect Rails API
+      - scope_issue          # Incorrect query scope or filtering
+      - thread_violation     # Real-time unsafe operation
+      - async_timing         # Async/background job timing
+      - memory_leak          # Memory leak or excessive allocation
+      - config_error         # Configuration or environment issue
+      - logic_error          # Algorithm/business logic bug
+      - test_isolation       # Test isolation or fixture issue
+      - missing_validation   # Missing model validation
+      - missing_permission   # Authorization check missing
+      - missing_workflow_step # Skipped or undocumented workflow step
+      - inadequate_documentation # Missing or unclear documentation
+      - missing_tooling      # Lacking helper scripts or automation
+      - incomplete_setup     # Missing seed data, fixtures, or config
+    description: "Fundamental cause of the problem"
+
+  resolution_type:
+    type: enum
+    values:
+      - code_fix             # Fixed by changing source code
+      - migration            # Fixed by database migration
+      - config_change        # Fixed by changing configuration
+      - test_fix             # Fixed by correcting tests
+      - dependency_update    # Fixed by updating gem/dependency
+      - environment_setup    # Fixed by environment configuration
+      - workflow_improvement # Improved development workflow or process
+      - documentation_update # Added or updated documentation
+      - tooling_addition     # Added helper script or automation
+      - seed_data_update     # Updated db/seeds.rb or fixtures
+    description: "Type of fix applied"
+
+  severity:
+    type: enum
+    values:
+      - critical             # Blocks production or development (build fails, data loss)
+      - high                 # Impairs core functionality (feature broken, security issue)
+      - medium               # Affects specific feature (UI broken, performance impact)
+      - low                  # Minor issue or edge case
+    description: "Impact severity"
+
+optional_fields:
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version where this was encountered (e.g., '7.1.0')"
+
+  related_components:
+    type: array[string]
+    description: "Other components that interact with this issue"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Searchable keywords (lowercase, hyphen-separated)"
+    examples:
+      - "n-plus-one"
+      - "eager-loading"
+      - "test-isolation"
+      - "turbo-stream"
+
+validation_rules:
+  - "module must be a valid CORA module name"
+  - "date must be in YYYY-MM-DD format"
+  - "problem_type must match one of the enum values"
+  - "component must match one of the enum values"
+  - "symptoms must be specific and observable (not vague)"
+  - "root_cause must be the ACTUAL cause, not a symptom"
+  - "resolution_type must match one of the enum values"
+  - "severity must match one of the enum values"
+  - "tags should be lowercase, hyphen-separated"
+
+# Example valid front matter:
+# ---
+# module: Email Processing
+# date: 2025-11-12
+# problem_type: performance_issue
+# component: rails_model
+# symptoms:
+#   - N+1 query when loading email threads
+#   - Brief generation taking >5 seconds
+# root_cause: missing_include
+# rails_version: 7.1.2
+# resolution_type: code_fix
+# severity: high
+# tags: [n-plus-one, eager-loading, performance]
+# ---
+#
+# Example DX issue front matter:
+# ---
+# module: Development Workflow
+# date: 2025-11-13
+# problem_type: developer_experience
+# component: development_workflow
+# symptoms:
+#   - No example data for new feature in development
+#   - Rails db:seed doesn't demonstrate new capabilities
+# root_cause: incomplete_setup
+# rails_version: 7.1.2
+# resolution_type: seed_data_update
+# severity: low
+# tags: [seed-data, dx, workflow]
+# ---

package/plugins/compound-engineering/skills/create-agent-skills/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: create-agent-skills
+description: Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
+---
+
+# Creating Skills & Commands
+
+This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
+
+## Commands and Skills Are Now The Same Thing
+
+Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
+
+**If a skill and a command share the same name, the skill takes precedence.**
+
+## When To Create What
+
+**Use a command file** (`commands/name.md`) when:
+- Simple, single-file workflow
+- No supporting files needed
+- Task-oriented action (deploy, commit, triage)
+
+**Use a skill directory** (`skills/name/SKILL.md`) when:
+- Need supporting reference files, scripts, or templates
+- Background knowledge Claude should auto-load
+- Complex enough to benefit from progressive disclosure
+
+Both use identical YAML frontmatter and markdown content format.
+
+## Standard Markdown Format
+
+Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
+
+```markdown
+---
+name: my-skill-name
+description: What it does and when to use it
+---
+
+# My Skill Name
+
+## Quick Start
+Immediate actionable guidance...
+
+## Instructions
+Step-by-step procedures...
+
+## Examples
+Concrete usage examples...
+```
+
+## Frontmatter Reference
+
+All fields are optional. Only `description` is recommended.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
+| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
+| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
+| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
+| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
+| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
+| `context` | No | Set `fork` to run in isolated subagent context. |
+| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
+
+### Invocation Control
+
+| Frontmatter | User can invoke | Claude can invoke | When loaded |
+|-------------|----------------|-------------------|-------------|
+| (default) | Yes | Yes | Description always in context, full content loads when invoked |
+| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
+| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
+
+**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
+
+**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
+
+## Dynamic Features
+
+### Arguments
+
+Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue
+disable-model-invocation: true
+---
+
+Fix GitHub issue $ARGUMENTS following our coding standards.
+```
+
+Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
+
+### Dynamic Context Injection
+
+The `` !`command` `` syntax runs shell commands before content is sent to Claude:
+
+```yaml
+---
+name: pr-summary
+description: Summarize changes in a pull request
+context: fork
+agent: Explore
+---
+
+## Context
+- PR diff: !`gh pr diff`
+- Changed files: !`gh pr diff --name-only`
+
+Summarize this pull request...
+```
+
+### Running in a Subagent
+
+Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
+
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
+---
+
+Research $ARGUMENTS thoroughly:
+1. Find relevant files
+2. Analyze the code
+3. Summarize findings
+```
+
+## Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split detailed content into reference files:
+
+```
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
+```
+
+Link from SKILL.md: `For API details, see [reference.md](reference.md).`
+
+Keep references **one level deep** from SKILL.md. Avoid nested chains.
+
+## Effective Descriptions
+
+The description enables skill discovery. Include both **what** it does and **when** to use it.
+
+**Good:**
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Bad:**
+```yaml
+description: Helps with documents
+```
+
+## What Would You Like To Do?
+
+1. **Create new skill** - Build from scratch
+2. **Create new command** - Build a slash command
+3. **Audit existing skill** - Check against best practices
+4. **Add component** - Add workflow/reference/example
+5. **Get guidance** - Understand skill design
+
+## Creating a New Skill or Command
+
+### Step 1: Choose Type
+
+Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
+
+- **Manual workflow** → command with `disable-model-invocation: true`
+- **Background knowledge** → skill without `disable-model-invocation`
+- **Complex with supporting files** → skill directory
+
+### Step 2: Create the File
+
+**Command:**
+```markdown
+---
+name: my-command
+description: What this command does
+argument-hint: [expected arguments]
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Read
+---
+
+# Command Title
+
+## Workflow
+
+### Step 1: Gather Context
+...
+
+### Step 2: Execute
+...
+
+## Success Criteria
+- [ ] Expected outcome 1
+- [ ] Expected outcome 2
+```
+
+**Skill:**
+```markdown
+---
+name: my-skill
+description: What it does. Use when [trigger conditions].
+---
+
+# Skill Title
+
+## Quick Start
+[Immediate actionable example]
+
+## Instructions
+[Core guidance]
+
+## Examples
+[Concrete input/output pairs]
+```
+
+### Step 3: Add Reference Files (If Needed)
+
+Link from SKILL.md to detailed content:
+```markdown
+For API reference, see [reference.md](reference.md).
+For form filling guide, see [forms.md](forms.md).
+```
+
+### Step 4: Test With Real Usage
+
+1. Test with actual tasks, not test scenarios
+2. Invoke directly with `/skill-name` to verify
+3. Check auto-triggering by asking something that matches the description
+4. Refine based on real behavior
+
+## Audit Checklist
+
+- [ ] Valid YAML frontmatter (name + description)
+- [ ] Description includes trigger keywords and is specific
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] SKILL.md under 500 lines
+- [ ] `disable-model-invocation: true` if it has side effects
+- [ ] `allowed-tools` set if specific tools needed
+- [ ] References one level deep, properly linked
+- [ ] Examples are concrete, not abstract
+- [ ] Tested with real usage
+
+## Anti-Patterns to Avoid
+
+- **XML tags in body** - Use standard markdown headings
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
+- **Too many options** - Provide a default with escape hatch
+- **Punting to Claude** - Scripts should handle errors explicitly
+
+## Reference Files
+
+For detailed guidance, see:
+- [official-spec.md](references/official-spec.md) - Official skill specification
+- [best-practices.md](references/best-practices.md) - Skill authoring best practices
+
+## Sources
+
+- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
+- [GitHub - anthropics/skills](https://github.com/anthropics/skills)