npm - @every-env/compound-plugin - Versions diffs - 0.1.0 → 0.1.1 - Mend

@every-env/compound-plugin 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/.claude-plugin/marketplace.json CHANGED Viewed

@@ -11,14 +11,14 @@
   "plugins": [
     {
       "name": "compound-engineering",
-      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 27 specialized agents, 23 commands, and 14 skills.",
-      "version": "2.27.0",
+      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents, 24 commands, and 15 skills.",
+      "version": "2.28.0",
       "author": {
         "name": "Kieran Klaassen",
         "url": "https://github.com/kieranklaassen",
         "email": "kieran@every.to"
       },
-      "homepage": "https://github.com/kieranklaassen/compound-engineering-plugin",
+      "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
       "tags": ["ai-powered", "compound-engineering", "workflow-automation", "code-review", "quality", "knowledge-management", "image-generation"],
       "source": "./plugins/compound-engineering"
     },
@@ -29,7 +29,7 @@
       "author": {
         "name": "Nityesh Agarwal"
       },
-      "homepage": "https://github.com/kieranklaassen/compound-engineering-plugin",
+      "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
       "tags": ["coding", "programming", "tutorial", "learning", "spaced-repetition", "education"],
       "source": "./plugins/coding-tutor"
     }

package/README.md CHANGED Viewed

@@ -2,14 +2,14 @@
 A Claude Code plugin marketplace featuring the **Compound Engineering Plugin** — tools that make each unit of engineering work easier than the last.
-## Install
+## Claude Code Install
 ```bash
-/plugin marketplace add https://github.com/kieranklaassen/compound-engineering-plugin
+/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
 /plugin install compound-engineering
 ```
-## OpenCode + Codex support (experimental)
+## OpenCode + Codex (experimental) Install
 This repo includes a Bun/TypeScript CLI that converts Claude Code plugins to OpenCode and Codex.

package/docs/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
 <head>
   <meta charset="utf-8" />
   <title>Compounding Engineering - AI-Powered Development Tools for Claude Code</title>
-  <meta content="Your code reviews just got 12 expert opinions in 30 seconds. 27 specialized agents, 19 workflow commands, and 12 skills that make today's work easier than yesterday's." name="description" />
+  <meta content="Your code reviews just got 12 expert opinions in 30 seconds. 28 specialized agents, 24 workflow commands, and 15 skills that make today's work easier than yesterday's." name="description" />
   <meta content="width=device-width, initial-scale=1" name="viewport" />
   <!-- Open Graph -->
@@ -12,7 +12,7 @@
   <meta property="og:site_name" content="Compounding Engineering" />
   <meta property="og:locale" content="en_US" />
   <meta property="og:title" content="Compounding Engineering - AI Development Tools" />
-  <meta property="og:description" content="Get 12 expert code reviews in 30 seconds. 27 specialized agents that make today's work easier than yesterday's." />
+  <meta property="og:description" content="Get 12 expert code reviews in 30 seconds. 28 specialized agents that make today's work easier than yesterday's." />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="Compounding Engineering" />
   <meta name="twitter:description" content="12 expert code reviews in 30 seconds. Make today's work easier than yesterday's." />
@@ -139,7 +139,7 @@
         <a href="pages/getting-started.html" class="nav-link">Docs</a>
       </nav>
       <div class="button-group">
-        <a href="https://github.com/kieranklaassen/every-marketplace" class="button ghost compact hide-on-mobile">
+        <a href="https://github.com/EveryInc/compound-engineering-plugin" class="button ghost compact hide-on-mobile">
           <div class="fa-brands fa-github icon l"></div>
         </a>
         <a href="#install" class="button primary compact">Install</a>
@@ -154,14 +154,14 @@
       <section class="hero-section">
         <div class="hero-decoration"></div>
         <div class="heading hero centered">
-          <a href="https://github.com/kieranklaassen/every-marketplace/releases" class="eyebrow">
-            <i class="fa-solid fa-rocket"></i> Version 2.6.0 released!
+          <a href="https://github.com/EveryInc/compound-engineering-plugin/releases" class="eyebrow">
+            <i class="fa-solid fa-rocket"></i> Version 2.28.0 released!
           </a>
           <h1 class="balanced" style="margin-bottom: 32px;">
             Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.
           </h1>
           <p class="paragraph m secondary balanced" style="margin-bottom: 32px;">
-            Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 27 specialized agents, 19 workflow commands, and 12 skills that make today's work easier than yesterday's.
+            Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 28 specialized agents, 24 workflow commands, and 15 skills that make today's work easier than yesterday's.
           </p>
           <div class="button-group margin-paragraph centered">
             <a href="#install" class="button primary">
@@ -179,23 +179,23 @@
         <div class="stats-container">
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-users-gear"></i></div>
-            <div class="stat-number">27</div>
+            <div class="stat-number">28</div>
             <div class="stat-label">Specialized Agents</div>
           </div>
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-terminal"></i></div>
-            <div class="stat-number">19</div>
+            <div class="stat-number">24</div>
             <div class="stat-label">Slash Commands</div>
           </div>
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-wand-magic-sparkles"></i></div>
-            <div class="stat-number">12</div>
+            <div class="stat-number">15</div>
             <div class="stat-label">Intelligent Skills</div>
           </div>
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-server"></i></div>
-            <div class="stat-number">2</div>
-            <div class="stat-label">MCP Servers</div>
+            <div class="stat-number">1</div>
+            <div class="stat-label">MCP Server</div>
           </div>
         </div>
       </section>
@@ -884,7 +884,7 @@
             <div class="step-content">
               <h3>Add the Marketplace</h3>
               <div class="card-code-block">
-                <pre><code>claude /plugin marketplace add https://github.com/kieranklaassen/every-marketplace</code></pre>
+                <pre><code>claude /plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin</code></pre>
               </div>
             </div>
           </div>
@@ -996,7 +996,7 @@ skill: gemini-imagegen</code></pre>
               <i class="fa-solid fa-download"></i> Install Plugin Now
               <span class="button-arrow">→</span>
             </a>
-            <a href="https://github.com/kieranklaassen/every-marketplace" class="button tertiary cta-secondary">
+            <a href="https://github.com/EveryInc/compound-engineering-plugin" class="button tertiary cta-secondary">
               <i class="fa-brands fa-github"></i> View on GitHub
             </a>
           </div>
@@ -1024,7 +1024,7 @@ skill: gemini-imagegen</code></pre>
         </div>
         <div>
           <div class="link-list">
-            <a href="https://github.com/kieranklaassen/every-marketplace" class="icon-link ui s" target="_blank">
+            <a href="https://github.com/EveryInc/compound-engineering-plugin" class="icon-link ui s" target="_blank">
               <div class="fa-brands fa-github icon m color-accent"></div>
               <div class="pseudo-link">GitHub</div>
             </a>

package/docs/pages/changelog.html CHANGED Viewed

@@ -118,7 +118,7 @@
                 <strong><code>/report-bug</code> command</strong> - New slash command for reporting bugs in the
                 compound-engineering plugin. Provides a structured workflow that gathers bug information
                 through guided questions, collects environment details automatically, and creates a GitHub
-                issue in the kieranklaassen/every-marketplace repository.
+                issue in the EveryInc/compound-engineering-plugin repository.
               </li>
             </ul>
           </div>

package/docs/pages/getting-started.html CHANGED Viewed

@@ -97,7 +97,7 @@
           <h3>Step 1: Add the Marketplace</h3>
           <p>Think of the marketplace as an app store. You're adding it to Claude Code's list of places to look for plugins:</p>
           <div class="card-code-block">
-            <pre><code>claude /plugin marketplace add https://github.com/kieranklaassen/every-marketplace</code></pre>
+            <pre><code>claude /plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin</code></pre>
           </div>
           <h3>Step 2: Install the Plugin</h3>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "private": false,
   "bin": {

package/plugins/compound-engineering/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,14 +1,14 @@
 {
   "name": "compound-engineering",
-  "version": "2.27.0",
-  "description": "AI-powered development tools. 27 agents, 23 commands, 14 skills, 1 MCP server for code review, research, design, and workflow automation.",
+  "version": "2.28.0",
+  "description": "AI-powered development tools. 28 agents, 24 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",
     "email": "kieran@every.to",
     "url": "https://github.com/kieranklaassen"
   },
   "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
-  "repository": "https://github.com/kieranklaassen/every-marketplace",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
   "license": "MIT",
   "keywords": [
     "ai-powered",

package/plugins/compound-engineering/README.md CHANGED Viewed

@@ -75,6 +75,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 | Command | Description |
 |---------|-------------|
+| `/workflows:brainstorm` | Explore requirements and approaches before planning |
 | `/workflows:plan` | Create implementation plans |
 | `/workflows:review` | Run comprehensive code reviews |
 | `/workflows:work` | Execute work items systematically |

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

@@ -37,12 +37,23 @@ Before going online, check if curated knowledge already exists in skills:
 4. **Assess Coverage**:
    - If skills provide comprehensive guidance → summarize and deliver
-   - If skills provide partial guidance → note what's covered, proceed to Phase 2 for gaps
-   - If no relevant skills found → proceed to Phase 2
+   - If skills provide partial guidance → note what's covered, proceed to Phase 1.5 and Phase 2 for gaps
+   - If no relevant skills found → proceed to Phase 1.5 and Phase 2
+### Phase 1.5: MANDATORY Deprecation Check (for external APIs/services)
+**Before recommending any external API, OAuth flow, SDK, or third-party service:**
+1. Search for deprecation: `"[API name] deprecated [current year] sunset shutdown"`
+2. Search for breaking changes: `"[API name] breaking changes migration"`
+3. Check official documentation for deprecation banners or sunset notices
+4. **Report findings before proceeding** - do not recommend deprecated APIs
+**Why this matters:** Google Photos Library API scopes were deprecated March 2025. Without this check, developers can waste hours debugging "insufficient scopes" errors on dead APIs. 5 minutes of validation saves hours of debugging.
 ### Phase 2: Online Research (If Needed)
-Only after checking skills, gather additional information:
+Only after checking skills AND verifying API availability, gather additional information:
 1. **Leverage External Sources**:
    - Use Context7 MCP to access official documentation from GitHub, framework docs, and library references

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

@@ -41,19 +41,26 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin
    - Determine the installed version from Gemfile.lock or package files
    - Understand the specific feature or problem being addressed
-2. **Documentation Collection**:
+2. **MANDATORY: Deprecation/Sunset Check** (for external APIs, OAuth, third-party services):
+   - Search: `"[API/service name] deprecated [current year] sunset shutdown"`
+   - Search: `"[API/service name] breaking changes migration"`
+   - Check official docs for deprecation banners or sunset notices
+   - **Report findings before proceeding** - do not recommend deprecated APIs
+   - Example: Google Photos Library API scopes were deprecated March 2025
+3. **Documentation Collection**:
    - Start with Context7 to fetch official documentation
    - If Context7 is unavailable or incomplete, use web search as fallback
    - Prioritize official sources over third-party tutorials
    - Collect multiple perspectives when official docs are unclear
-3. **Source Exploration**:
+4. **Source Exploration**:
    - Use `bundle show` to find gem locations
    - Read through key source files related to the feature
    - Look for tests that demonstrate usage patterns
    - Check for configuration examples in the codebase
-4. **Synthesis and Reporting**:
+5. **Synthesis and Reporting**:
    - Organize findings by relevance to the current task
    - Highlight version-specific considerations
    - Provide code examples adapted to the project's style
@@ -61,6 +68,7 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin
 **Quality Standards:**
+- **ALWAYS check for API deprecation first** when researching external APIs or services
 - Always verify version compatibility with the project's dependencies
 - Prioritize official documentation but supplement with community resources
 - Provide practical, actionable insights rather than generic information

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

@@ -0,0 +1,243 @@
+---
+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>"
+model: haiku
+---
+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)
+The `docs/solutions/` directory contains documented solutions with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls:
+### Step 1: Extract Keywords from Feature Description
+From the feature/task description, identify:
+- **Module names**: e.g., "BriefSystem", "EmailProcessing", "payments"
+- **Technical terms**: e.g., "N+1", "caching", "authentication"
+- **Problem indicators**: e.g., "slow", "error", "timeout", "memory"
+- **Component types**: e.g., "model", "controller", "job", "api"
+### Step 2: Category-Based Narrowing (Optional but Recommended)
+If the feature type is clear, narrow the search to relevant category directories:
+| Feature Type | Search Directory |
+|--------------|------------------|
+| Performance work | `docs/solutions/performance-issues/` |
+| Database changes | `docs/solutions/database-issues/` |
+| Bug fix | `docs/solutions/runtime-errors/`, `docs/solutions/logic-errors/` |
+| Security | `docs/solutions/security-issues/` |
+| UI work | `docs/solutions/ui-bugs/` |
+| Integration | `docs/solutions/integration-issues/` |
+| General/unclear | `docs/solutions/` (all) |
+### Step 3: Grep Pre-Filter (Critical for Efficiency)
+**Use Grep to find candidate files BEFORE reading any content.** Run multiple Grep calls in parallel:
+```bash
+# Search for keyword matches in frontmatter fields (run in PARALLEL, case-insensitive)
+Grep: pattern="title:.*email" path=docs/solutions/ output_mode=files_with_matches -i=true
+Grep: pattern="tags:.*(email|mail|smtp)" path=docs/solutions/ output_mode=files_with_matches -i=true
+Grep: pattern="module:.*(Brief|Email)" path=docs/solutions/ output_mode=files_with_matches -i=true
+Grep: pattern="component:.*background_job" path=docs/solutions/ output_mode=files_with_matches -i=true
+```
+**Pattern construction tips:**
+- Use `|` for synonyms: `tags:.*(payment|billing|stripe|subscription)`
+- Include `title:` - often the most descriptive field
+- Use `-i=true` for case-insensitive matching
+- Include related terms the user might not have mentioned
+**Why this works:** Grep scans file contents without reading into context. Only matching filenames are returned, dramatically reducing the set of files to examine.
+**Combine results** from all Grep calls to get candidate files (typically 5-20 files instead of 200).
+**If Grep returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
+**If Grep returns <3 candidates:** Do a broader content search (not just frontmatter fields) as fallback:
+```bash
+Grep: pattern="email" path=docs/solutions/ output_mode=files_with_matches -i=true
+```
+### Step 3b: Always Check Critical Patterns
+**Regardless of Grep results**, always read the critical patterns file:
+```bash
+Read: docs/solutions/patterns/cora-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.
+### Step 4: Read Frontmatter of Candidates Only
+For each candidate file from Step 3, read the frontmatter:
+```bash
+# Read frontmatter only (limit to first 30 lines)
+Read: [file_path] with limit:30
+```
+Extract these fields from the YAML frontmatter:
+- **module**: Which module/system the solution applies to
+- **problem_type**: Category of issue (see schema below)
+- **component**: Technical component affected
+- **symptoms**: Array of observable symptoms
+- **root_cause**: What caused the issue
+- **tags**: Searchable keywords
+- **severity**: critical, high, medium, low
+### Step 5: Score and Rank Relevance
+Match frontmatter fields against the feature/task description:
+**Strong matches (prioritize):**
+- `module` matches the feature's target module
+- `tags` contain keywords from the feature description
+- `symptoms` describe similar observable behaviors
+- `component` matches the technical area being touched
+**Moderate matches (include):**
+- `problem_type` is relevant (e.g., `performance_issue` for optimization work)
+- `root_cause` suggests a pattern that might apply
+- Related modules or components mentioned
+**Weak matches (skip):**
+- No overlapping tags, symptoms, or modules
+- Unrelated problem types
+### Step 6: Full Read of Relevant Files
+Only for files that pass the filter (strong or moderate matches), read the complete document to extract:
+- The full problem description
+- The solution implemented
+- Prevention guidance
+- Code examples
+### Step 7: Return Distilled Summaries
+For each relevant document, return a summary in this format:
+```markdown
+### [Title from document]
+- **File**: docs/solutions/[category]/[filename].md
+- **Module**: [module from frontmatter]
+- **Problem Type**: [problem_type]
+- **Relevance**: [Brief explanation of why this is relevant to the current task]
+- **Key Insight**: [The most important takeaway - the thing that prevents repeating the mistake]
+- **Severity**: [severity level]
+```
+## Frontmatter Schema Reference
+Reference the [yaml-schema.md](../../skills/compound-docs/references/yaml-schema.md) for the complete schema. Key enum values:
+**problem_type values:**
+- 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 values:**
+- 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
+**root_cause values:**
+- 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
+**Category directories (mapped from problem_type):**
+- `docs/solutions/build-errors/`
+- `docs/solutions/test-failures/`
+- `docs/solutions/runtime-errors/`
+- `docs/solutions/performance-issues/`
+- `docs/solutions/database-issues/`
+- `docs/solutions/security-issues/`
+- `docs/solutions/ui-bugs/`
+- `docs/solutions/integration-issues/`
+- `docs/solutions/logic-errors/`
+- `docs/solutions/developer-experience/`
+- `docs/solutions/workflow-issues/`
+- `docs/solutions/best-practices/`
+- `docs/solutions/documentation-gaps/`
+## Output Format
+Structure your findings as:
+```markdown
+## Institutional Learnings Search Results
+### Search Context
+- **Feature/Task**: [Description of what's being implemented]
+- **Keywords Used**: [tags, modules, symptoms searched]
+- **Files Scanned**: [X total files]
+- **Relevant Matches**: [Y files]
+### Critical Patterns (Always Check)
+[Any matching patterns from cora-critical-patterns.md]
+### Relevant Learnings
+#### 1. [Title]
+- **File**: [path]
+- **Module**: [module]
+- **Relevance**: [why this matters for current task]
+- **Key Insight**: [the gotcha or pattern to apply]
+#### 2. [Title]
+...
+### Recommendations
+- [Specific actions to take based on learnings]
+- [Patterns to follow]
+- [Gotchas to avoid]
+### No Matches
+[If no relevant learnings found, explicitly state this]
+```
+## Efficiency Guidelines
+**DO:**
+- Use Grep to pre-filter files BEFORE reading any content (critical for 100+ files)
+- Run multiple Grep calls in PARALLEL for different keywords
+- Include `title:` in Grep patterns - often the most descriptive field
+- Use OR patterns for synonyms: `tags:.*(payment|billing|stripe)`
+- Use `-i=true` for case-insensitive matching
+- Use category directories to narrow scope when feature type is clear
+- Do a broader content Grep as fallback if <3 candidates found
+- Re-narrow with more specific patterns if >25 candidates found
+- Always read the critical patterns file (Step 3b)
+- Only read frontmatter of Grep-matched candidates (not all files)
+- Filter aggressively - only fully read truly relevant files
+- Prioritize high-severity and critical patterns
+- Extract actionable insights, not just summaries
+- Note when no relevant learnings exist (this is valuable information too)
+**DON'T:**
+- Read frontmatter of ALL files (use Grep to pre-filter first)
+- Run Grep calls sequentially when they can be parallel
+- Use only exact keyword matches (include synonyms)
+- Skip the `title:` field in Grep patterns
+- Proceed with >25 candidates without narrowing first
+- Read every file in full (wasteful)
+- Return raw document contents (distill instead)
+- Include tangentially related learnings (focus on relevance)
+- Skip the critical patterns file (always check it)
+## Integration Points
+This agent is designed to be invoked by:
+- `/workflows:plan` - To inform planning with institutional knowledge
+- `/deepen-plan` - To add depth with relevant learnings
+- Manual invocation before starting work on a feature
+The goal is to surface relevant learnings in under 30 seconds for a typical solutions directory, enabling fast knowledge retrieval during planning phases.

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

@@ -96,10 +96,11 @@ Structure your findings as:
 **Search Strategies:**
-When using search tools:
-- For Ruby code patterns: `ast-grep --lang ruby -p 'pattern'`
-- For general text search: `rg -i 'search term' --type md`
-- For file discovery: `find . -name 'pattern' -type f`
+Use the built-in tools for efficient searching:
+- **Grep tool**: For text/code pattern searches with regex support (uses ripgrep under the hood)
+- **Glob tool**: For file discovery by pattern (e.g., `**/*.md`, `**/CLAUDE.md`)
+- **Read tool**: For reading file contents once located
+- For AST-based code patterns: `ast-grep --lang ruby -p 'pattern'` or `ast-grep --lang typescript -p 'pattern'`
 - Check multiple variations of common file names
 **Important Considerations:**

package/plugins/compound-engineering/agents/review/pattern-recognition-specialist.md CHANGED Viewed

@@ -34,7 +34,7 @@ Your primary responsibilities:
 Your workflow:
-1. Start with a broad pattern search using grep or ast-grep for structural matching
+1. Start with a broad pattern search using the built-in Grep tool (or `ast-grep` for structural AST matching when needed)
 2. Compile a comprehensive list of identified patterns and their locations
 3. Search for common anti-pattern indicators (TODO, FIXME, HACK, XXX)
 4. Analyze naming conventions by sampling representative files

package/plugins/compound-engineering/commands/deepen-plan.md CHANGED Viewed

@@ -24,8 +24,8 @@ The result is a deeply grounded, production-ready plan with concrete implementat
 <plan_path> #$ARGUMENTS </plan_path>
 **If the plan path above is empty:**
-1. Check for recent plans: `ls -la plans/`
-2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., `plans/my-feature.md`)."
+1. Check for recent plans: `ls -la docs/plans/`
+2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., `docs/plans/2026-01-15-feat-my-feature-plan.md`)."
 Do not proceed until you have a valid plan file path.
@@ -460,7 +460,7 @@ At the top of the plan, add a summary section:
 ## Output Format
-Update the plan file in place (or create `plans/<original-name>-deepened.md` if requested).
+Update the plan file in place (or if user requests a separate file, append `-deepened` after `-plan`, e.g., `2026-01-15-feat-auth-plan-deepened.md`).
 ## Quality Checks

package/plugins/compound-engineering/commands/report-bug.md CHANGED Viewed

@@ -100,7 +100,7 @@ Use the GitHub CLI to create the issue:
 ```bash
 gh issue create \
-  --repo kieranklaassen/every-marketplace \
+  --repo EveryInc/compound-engineering-plugin \
   --title "[compound-engineering] Bug: [Brief description]" \
   --body "[Formatted bug report from Step 3]" \
   --label "bug,compound-engineering"
@@ -109,7 +109,7 @@ gh issue create \
 **Note:** If labels don't exist, create without labels:
 ```bash
 gh issue create \
-  --repo kieranklaassen/every-marketplace \
+  --repo EveryInc/compound-engineering-plugin \
   --title "[compound-engineering] Bug: [Brief description]" \
   --body "[Formatted bug report]"
 ```
@@ -126,7 +126,7 @@ After the issue is created:
 ```
 ✅ Bug report submitted successfully!
-Issue: https://github.com/kieranklaassen/every-marketplace/issues/[NUMBER]
+Issue: https://github.com/EveryInc/compound-engineering-plugin/issues/[NUMBER]
 Title: [compound-engineering] Bug: [description]
 Thank you for helping improve the compound-engineering plugin!

package/plugins/compound-engineering/commands/workflows/brainstorm.md ADDED Viewed

@@ -0,0 +1,115 @@
+---
+name: workflows:brainstorm
+description: Explore requirements and approaches through collaborative dialogue before planning implementation
+argument-hint: "[feature idea or problem to explore]"
+---
+# Brainstorm a Feature or Improvement
+**Note: The current year is 2026.** Use this when dating brainstorm documents.
+Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/workflows:plan`, which answers **HOW** to build it.
+**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
+## Feature Description
+<feature_description> #$ARGUMENTS </feature_description>
+**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
+Do not proceed until you have a feature description from the user.
+## Execution Flow
+### Phase 0: Assess Requirements Clarity
+Evaluate whether brainstorming is needed based on the feature description.
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+**If requirements are already clear:**
+Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
+### Phase 1: Understand the Idea
+#### 1.1 Repository Research (Lightweight)
+Run a quick repo scan to understand existing patterns:
+- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
+Focus on: similar features, established patterns, CLAUDE.md guidance.
+#### 1.2 Collaborative Dialogue
+Use the **AskUserQuestion tool** to ask questions **one at a time**.
+**Guidelines (see `brainstorming` skill for detailed techniques):**
+- Prefer multiple choice when natural options exist
+- Start broad (purpose, users) then narrow (constraints, edge cases)
+- Validate assumptions explicitly
+- Ask about success criteria
+**Exit condition:** Continue until the idea is clear OR user says "proceed"
+### Phase 2: Explore Approaches
+Propose **2-3 concrete approaches** based on research and conversation.
+For each approach, provide:
+- Brief description (2-3 sentences)
+- Pros and cons
+- When it's best suited
+Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
+Use **AskUserQuestion tool** to ask which approach the user prefers.
+### Phase 3: Capture the Design
+Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`.
+**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
+Ensure `docs/brainstorms/` directory exists before writing.
+### Phase 4: Handoff
+Use **AskUserQuestion tool** to present next steps:
+**Question:** "Brainstorm captured. What would you like to do next?"
+**Options:**
+1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
+2. **Refine design further** - Continue exploring
+3. **Done for now** - Return later
+## Output Summary
+When complete, display:
+```
+Brainstorm complete!
+Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
+Key decisions:
+- [Decision 1]
+- [Decision 2]
+Next: Run `/workflows:plan` when ready to implement.
+```
+## Important Guidelines
+- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
+- **Ask one question at a time** - Don't overwhelm
+- **Apply YAGNI** - Prefer simpler approaches
+- **Keep outputs concise** - 200-300 words per section max
+NEVER CODE! Just explore and document decisions.

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

@@ -22,44 +22,103 @@ 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**:
+**Check for brainstorm output first:**
+Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
+```bash
+ls -la docs/brainstorms/*.md 2>/dev/null | head -10
+```
+**Relevance criteria:** A brainstorm is relevant if:
+- The topic (from filename or YAML frontmatter) semantically matches the feature description
+- Created within the last 14 days
+- If multiple candidates match, use the most recent one
+**If a relevant brainstorm exists:**
+1. Read the brainstorm document
+2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
+3. Extract key decisions, chosen approach, and open questions
+4. **Skip the idea refinement questions below** - the brainstorm already answered WHAT to build
+5. Use brainstorm decisions as input to the research phase
+**If multiple brainstorms could match:**
+Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
+**If no brainstorm found (or not relevant), run idea refinement:**
+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"
+**Gather signals for research decision.** During refinement, note:
+- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
+- **User's intent**: Speed vs thoroughness? Exploration vs execution?
+- **Topic risk**: Security, payments, external APIs warrant more caution
+- **Uncertainty level**: Is the approach clear or open-ended?
 **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
+### 1. Local Research (Always Runs - Parallel)
 <thinking>
-First, I need to understand the project's conventions and existing patterns, leveraging all available resources and use paralel subagents to do this.
+First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
 </thinking>
-Runn these three agents in paralel at the same time:
+Run these agents **in parallel** to gather local context:
 - Task repo-research-analyst(feature_description)
+- Task learnings-researcher(feature_description)
+**What to look for:**
+- **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
+- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
+These findings inform the next step.
+### 1.5. Research Decision
+Based on signals from Step 0 and findings from Step 1, decide on external research.
+**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
+**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.
+**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
+**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
+Examples:
+- "Your codebase has solid patterns for this. Proceeding without external research."
+- "This involves payment processing, so I'll research current best practices first."
+### 1.5b. External Research (Conditional)
+**Only run if Step 1.5 indicates external research is valuable.**
+Run these agents in parallel:
 - 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
+### 1.6. Consolidate Research
-### Research Validation (Optional)
+After all research steps complete, consolidate findings:
-After research agents complete, briefly validate alignment:
+- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
+- **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
+- Note external documentation URLs and best practices (if external research was done)
+- List related issues or PRs discovered
+- Capture CLAUDE.md conventions
-- Summarize key findings from research
-- Ask if anything looks off or is missing
-- User can confirm or request additional research on specific topics
+**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
 ### 2. Issue Planning & Structure
@@ -71,8 +130,8 @@ Think like a product manager - what would make this issue clear and actionable?
 - [ ] 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`
+- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix
+  - Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md`
   - Keep it descriptive (3-5 words after prefix) so plans are findable by context
 **Stakeholder Analysis:**
@@ -116,6 +175,14 @@ Select how comprehensive you want the issue to be, simpler is mostly better.
 **Structure:**
 ````markdown
+---
+title: [Issue Title]
+type: [feat|fix|refactor]
+date: YYYY-MM-DD
+---
+# [Issue Title]
 [Brief problem/feature description]
 ## Acceptance Criteria
@@ -160,6 +227,14 @@ end
 **Structure:**
 ```markdown
+---
+title: [Issue Title]
+type: [feat|fix|refactor]
+date: YYYY-MM-DD
+---
+# [Issue Title]
 ## Overview
 [Comprehensive description]
@@ -216,6 +291,14 @@ end
 **Structure:**
 ```markdown
+---
+title: [Issue Title]
+type: [feat|fix|refactor]
+date: YYYY-MM-DD
+---
+# [Issue Title]
 ## Overview
 [Executive summary]
@@ -391,25 +474,26 @@ end
 ## Output Format
-**Filename:** Use the kebab-case filename from Step 2 Title & Categorization.
+**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.
 ```
-plans/<type>-<descriptive-name>.md
+docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.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)
+- ✅ `docs/plans/2026-01-15-feat-user-authentication-flow-plan.md`
+- ✅ `docs/plans/2026-02-03-fix-checkout-race-condition-plan.md`
+- ✅ `docs/plans/2026-03-10-refactor-api-client-extraction-plan.md`
+- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (not descriptive - what "thing"?)
+- ❌ `docs/plans/2026-01-15-feat-new-feature-plan.md` (too vague - what feature?)
+- ❌ `docs/plans/2026-01-15-feat: user auth-plan.md` (invalid characters - colon and space)
+- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix)
 ## 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?"
+**Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<name>-plan.md`. What would you like to do next?"
 **Options:**
 1. **Open plan in editor** - Open the plan file for review
@@ -421,11 +505,11 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o
 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
+- **Open plan in editor** → Run `open docs/plans/<plan_filename>.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
+- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.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
@@ -443,16 +527,17 @@ When user selects "Create Issue", detect their project tracker from CLAUDE.md:
    - Or look for mentions of "GitHub Issues" or "Linear" in their workflow section
 2. **If GitHub:**
+   Use the title and type from Step 2 (already in context - no need to re-read the file):
    ```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
+   gh issue create --title "<type>: <title>" --body-file <plan_path>
    ```
 3. **If Linear:**
    ```bash
-   # Use linear CLI if available, or provide instructions
-   # linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.md)"
+   linear issue create --title "<title>" --description "$(cat <plan_path>)"
    ```
 4. **If no tracker configured:**

package/plugins/compound-engineering/commands/workflows/work.md CHANGED Viewed

@@ -279,7 +279,7 @@ This command takes a work document (plan, specification, or todo file) and execu
    ---
-   [![Compound Engineered](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/kieranklaassen/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   [![Compound Engineered](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
    EOF
    )"
    ```

package/plugins/compound-engineering/skills/brainstorming/SKILL.md ADDED Viewed

@@ -0,0 +1,190 @@
+---
+name: brainstorming
+description: This skill should be used before implementing features, building components, or making changes. It guides exploring user intent, approaches, and design decisions before planning. Triggers on "let's brainstorm", "help me think through", "what should we build", "explore approaches", ambiguous feature requests, or when the user's request has multiple valid interpretations that need clarification.
+---
+# Brainstorming
+This skill provides detailed process knowledge for effective brainstorming sessions that clarify **WHAT** to build before diving into **HOW** to build it.
+## When to Use This Skill
+Brainstorming is valuable when:
+- Requirements are unclear or ambiguous
+- Multiple approaches could solve the problem
+- Trade-offs need to be explored with the user
+- The user hasn't fully articulated what they want
+- The feature scope needs refinement
+Brainstorming can be skipped when:
+- Requirements are explicit and detailed
+- The user knows exactly what they want
+- The task is a straightforward bug fix or well-defined change
+## Core Process
+### Phase 0: Assess Requirement Clarity
+Before diving into questions, assess whether brainstorming is needed.
+**Signals that requirements are clear:**
+- User provided specific acceptance criteria
+- User referenced existing patterns to follow
+- User described exact behavior expected
+- Scope is constrained and well-defined
+**Signals that brainstorming is needed:**
+- User used vague terms ("make it better", "add something like")
+- Multiple reasonable interpretations exist
+- Trade-offs haven't been discussed
+- User seems unsure about the approach
+If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."
+### Phase 1: Understand the Idea
+Ask questions **one at a time** to understand the user's intent. Avoid overwhelming with multiple questions.
+**Question Techniques:**
+1. **Prefer multiple choice when natural options exist**
+   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
+   - Avoid: "How should users be notified?"
+2. **Start broad, then narrow**
+   - First: What is the core purpose?
+   - Then: Who are the users?
+   - Finally: What constraints exist?
+3. **Validate assumptions explicitly**
+   - "I'm assuming users will be logged in. Is that correct?"
+4. **Ask about success criteria early**
+   - "How will you know this feature is working well?"
+**Key Topics to Explore:**
+| Topic | Example Questions |
+|-------|-------------------|
+| Purpose | What problem does this solve? What's the motivation? |
+| Users | Who uses this? What's their context? |
+| Constraints | Any technical limitations? Timeline? Dependencies? |
+| Success | How will you measure success? What's the happy path? |
+| Edge Cases | What shouldn't happen? Any error states to consider? |
+| Existing Patterns | Are there similar features in the codebase to follow? |
+**Exit Condition:** Continue until the idea is clear OR user says "proceed" or "let's move on"
+### Phase 2: Explore Approaches
+After understanding the idea, propose 2-3 concrete approaches.
+**Structure for Each Approach:**
+```markdown
+### Approach A: [Name]
+[2-3 sentence description]
+**Pros:**
+- [Benefit 1]
+- [Benefit 2]
+**Cons:**
+- [Drawback 1]
+- [Drawback 2]
+**Best when:** [Circumstances where this approach shines]
+```
+**Guidelines:**
+- Lead with a recommendation and explain why
+- Be honest about trade-offs
+- Consider YAGNI—simpler is usually better
+- Reference codebase patterns when relevant
+### Phase 3: Capture the Design
+Summarize key decisions in a structured format.
+**Design Doc Structure:**
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+---
+# <Topic Title>
+## What We're Building
+[Concise description—1-2 paragraphs max]
+## Why This Approach
+[Brief explanation of approaches considered and why this one was chosen]
+## Key Decisions
+- [Decision 1]: [Rationale]
+- [Decision 2]: [Rationale]
+## Open Questions
+- [Any unresolved questions for the planning phase]
+## Next Steps
+→ `/workflows:plan` for implementation details
+```
+**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
+### Phase 4: Handoff
+Present clear options for what to do next:
+1. **Proceed to planning** → Run `/workflows:plan`
+2. **Refine further** → Continue exploring the design
+3. **Done for now** → User will return later
+## YAGNI Principles
+During brainstorming, actively resist complexity:
+- **Don't design for hypothetical future requirements**
+- **Choose the simplest approach that solves the stated problem**
+- **Prefer boring, proven patterns over clever solutions**
+- **Ask "Do we really need this?" when complexity emerges**
+- **Defer decisions that don't need to be made now**
+## Incremental Validation
+Keep sections short—200-300 words maximum. After each section of output, pause to validate understanding:
+- "Does this match what you had in mind?"
+- "Any adjustments before we continue?"
+- "Is this the direction you want to go?"
+This prevents wasted effort on misaligned designs.
+## Anti-Patterns to Avoid
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Asking 5 questions at once | Ask one at a time |
+| Jumping to implementation details | Stay focused on WHAT, not HOW |
+| Proposing overly complex solutions | Start simple, add complexity only if needed |
+| Ignoring existing codebase patterns | Research what exists first |
+| Making assumptions without validating | State assumptions explicitly and confirm |
+| Creating lengthy design documents | Keep it concise—details go in the plan |
+## Integration with Planning
+Brainstorming answers **WHAT** to build:
+- Requirements and acceptance criteria
+- Chosen approach and rationale
+- Key decisions and trade-offs
+Planning answers **HOW** to build it:
+- Implementation steps and file changes
+- Technical details and code patterns
+- Testing strategy and verification
+When brainstorm output exists, `/workflows:plan` should detect it and use it as input, skipping its own idea refinement phase.

package/plugins/compound-engineering/skills/compound-docs/SKILL.md CHANGED Viewed

@@ -159,7 +159,7 @@ Load `schema.yaml` and classify the problem against the enum values defined in [
 Errors:
 - problem_type: must be one of schema enums, got "compilation_error"
-- severity: must be one of [critical, moderate, minor], got "high"
+- severity: must be one of [critical, high, medium, low], got "invalid"
 - symptoms: must be array with 1-5 items, got string
 Please provide corrected values.

package/src/commands/install.ts CHANGED Viewed

@@ -175,7 +175,9 @@ function resolveOutputRoot(value: unknown): string {
     const expanded = expandHome(String(value).trim())
     return path.resolve(expanded)
   }
-  return path.join(os.homedir(), ".opencode")
+  // OpenCode global config lives at ~/.config/opencode per XDG spec
+  // See: https://opencode.ai/docs/config/
+  return path.join(os.homedir(), ".config", "opencode")
 }
 async function resolveGitHubPluginPath(pluginName: string): Promise<ResolvedPluginPath> {

package/src/targets/opencode.ts CHANGED Viewed

@@ -28,7 +28,10 @@ export async function writeOpenCodeBundle(outputRoot: string, bundle: OpenCodeBu
 }
 function resolveOpenCodePaths(outputRoot: string) {
-  if (path.basename(outputRoot) === ".opencode") {
+  const base = path.basename(outputRoot)
+  // Global install: ~/.config/opencode (basename is "opencode")
+  // Project install: .opencode (basename is ".opencode")
+  if (base === "opencode" || base === ".opencode") {
     return {
       root: outputRoot,
       configPath: path.join(outputRoot, "opencode.json"),
@@ -38,6 +41,7 @@ function resolveOpenCodePaths(outputRoot: string) {
     }
   }
+  // Custom output directory - nest under .opencode subdirectory
   return {
     root: outputRoot,
     configPath: path.join(outputRoot, "opencode.json"),

package/tests/cli.test.ts CHANGED Viewed

@@ -63,7 +63,7 @@ describe("CLI", () => {
     expect(await exists(path.join(tempRoot, ".opencode", "plugins", "converted-hooks.ts"))).toBe(true)
   })
-  test("install defaults output to ~/.opencode", async () => {
+  test("install defaults output to ~/.config/opencode", async () => {
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "cli-local-default-"))
     const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin")
@@ -95,8 +95,9 @@ describe("CLI", () => {
     }
     expect(stdout).toContain("Installed compound-engineering")
-    expect(await exists(path.join(tempRoot, ".opencode", "opencode.json"))).toBe(true)
-    expect(await exists(path.join(tempRoot, ".opencode", "agents", "repo-research-analyst.md"))).toBe(true)
+    // OpenCode global config lives at ~/.config/opencode per XDG spec
+    expect(await exists(path.join(tempRoot, ".config", "opencode", "opencode.json"))).toBe(true)
+    expect(await exists(path.join(tempRoot, ".config", "opencode", "agents", "repo-research-analyst.md"))).toBe(true)
   })
   test("list returns plugins in a temp workspace", async () => {
@@ -174,8 +175,9 @@ describe("CLI", () => {
     }
     expect(stdout).toContain("Installed compound-engineering")
-    expect(await exists(path.join(tempRoot, ".opencode", "opencode.json"))).toBe(true)
-    expect(await exists(path.join(tempRoot, ".opencode", "agents", "repo-research-analyst.md"))).toBe(true)
+    // OpenCode global config lives at ~/.config/opencode per XDG spec
+    expect(await exists(path.join(tempRoot, ".config", "opencode", "opencode.json"))).toBe(true)
+    expect(await exists(path.join(tempRoot, ".config", "opencode", "agents", "repo-research-analyst.md"))).toBe(true)
   })
   test("convert writes OpenCode output", async () => {

package/tests/opencode-writer.test.ts CHANGED Viewed

@@ -59,4 +59,29 @@ describe("writeOpenCodeBundle", () => {
     expect(await exists(path.join(outputRoot, "skills", "skill-one", "SKILL.md"))).toBe(true)
     expect(await exists(path.join(outputRoot, ".opencode"))).toBe(false)
   })
+  test("writes directly into ~/.config/opencode style output root", async () => {
+    // Simulates the global install path: ~/.config/opencode
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "config-opencode-"))
+    const outputRoot = path.join(tempRoot, ".config", "opencode")
+    const bundle: OpenCodeBundle = {
+      config: { $schema: "https://opencode.ai/config.json" },
+      agents: [{ name: "agent-one", content: "Agent content" }],
+      plugins: [],
+      skillDirs: [
+        {
+          name: "skill-one",
+          sourceDir: path.join(import.meta.dir, "fixtures", "sample-plugin", "skills", "skill-one"),
+        },
+      ],
+    }
+    await writeOpenCodeBundle(outputRoot, bundle)
+    // Should write directly, not nested under .opencode
+    expect(await exists(path.join(outputRoot, "opencode.json"))).toBe(true)
+    expect(await exists(path.join(outputRoot, "agents", "agent-one.md"))).toBe(true)
+    expect(await exists(path.join(outputRoot, "skills", "skill-one", "SKILL.md"))).toBe(true)
+    expect(await exists(path.join(outputRoot, ".opencode"))).toBe(false)
+  })
 })