Merge pull request #232 from mvanhorn/fix/context7-api-key-auth

fix(mcp): add API key auth support for Context7 server

plugins/compound-engineering/.mcp.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "context7": {
       "type": "http",
-      "url": "https://mcp.context7.com/mcp"
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "x-api-key": "${CONTEXT7_API_KEY:-}"
+      }
     }
   }
 }

plugins/compound-engineering/README.md

@@ -53,12 +53,11 @@ Agents are organized into categories for easier discovery.
 | `design-iterator` | Iteratively refine UI through systematic design iterations |
 | `figma-design-sync` | Synchronize web implementations with Figma designs |
 
-### Workflow (5)
+### Workflow (4)
 
 | Agent | Description |
 |-------|-------------|
 | `bug-reproduction-validator` | Systematically reproduce and validate bug reports |
-| `every-style-editor` | Edit content to conform to Every's style guide |
 | `lint` | Run linting and code quality checks on Ruby and ERB files |
 | `pr-comment-resolver` | Address PR comments and implement fixes |
 | `spec-flow-analyzer` | Analyze user flows and identify gaps in specifications |
@@ -190,6 +189,8 @@ Supports 100+ frameworks including Rails, React, Next.js, Vue, Django, Laravel,
 
 MCP servers start automatically when the plugin is enabled.
 
+**Authentication:** To avoid anonymous rate limits, set the `CONTEXT7_API_KEY` environment variable with your Context7 API key. The plugin passes this automatically via the `x-api-key` header. Without it, requests go unauthenticated and will quickly hit the anonymous quota limit.
+
 ## Browser Automation
 
 This plugin uses **agent-browser CLI** for browser automation tasks. Install it globally:
@@ -220,13 +221,16 @@ claude /plugin install compound-engineering
   "mcpServers": {
     "context7": {
       "type": "http",
-      "url": "https://mcp.context7.com/mcp"
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "x-api-key": "${CONTEXT7_API_KEY:-}"
+      }
     }
   }
 }
 ```
 
-Or add it globally in `~/.claude/settings.json` for all projects.
+Set `CONTEXT7_API_KEY` in your environment to authenticate. Or add it globally in `~/.claude/settings.json` for all projects.
 
 ## Version History
 

plugins/compound-engineering/commands/ce/compound.md

@@ -21,7 +21,45 @@ Captures problem solutions while context is fresh, creating structured documenta
 /ce:compound [brief context]    # Provide additional context hint
 ```
 
-## Execution Strategy: Two-Phase Orchestration
+## Execution Strategy: Context-Aware Orchestration
+
+### Phase 0: Context Budget Check
+
+<critical_requirement>
+**Run this check BEFORE launching any subagents.**
+
+The /compound command is token-heavy - it launches 5 parallel subagents that collectively consume ~10k tokens of context. Running near context limits risks compaction mid-compound, which degrades output quality significantly.
+</critical_requirement>
+
+Before proceeding, the orchestrator MUST:
+
+1. **Assess context usage**: Check how long the current conversation has been running. If there has been significant back-and-forth (many tool calls, large file reads, extensive debugging), context is likely constrained.
+
+2. **Warn the user**:
+   ```
+   ⚠️ Context Budget Check
+
+   /compound launches 5 parallel subagents (~10k tokens). Long conversations
+   risk compaction mid-compound, which degrades documentation quality.
+
+   Tip: For best results, run /compound early in a session - right after
+   verifying a fix, before continuing other work.
+   ```
+
+3. **Offer the user a choice**:
+   ```
+   How would you like to proceed?
+
+   1. Full compound (5 parallel subagents, ~10k tokens) - best quality
+   2. Compact-safe mode (single pass, ~2k tokens) - safe near context limits
+   ```
+
+4. **If the user picks option 1** (or confirms full mode): proceed to Phase 1 below.
+5. **If the user picks option 2** (or requests compact-safe): skip to the **Compact-Safe Mode** section below.
+
+---
+
+### Full Mode
 
 <critical_requirement>
 **Only ONE file gets written - the final documentation.**
@@ -99,6 +137,44 @@ Based on problem type, optionally invoke specialized agents to review the docume
 
 </parallel_tasks>
 
+---
+
+### Compact-Safe Mode
+
+<critical_requirement>
+**Single-pass alternative for context-constrained sessions.**
+
+When context budget is tight, this mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing a minimal but complete solution document.
+</critical_requirement>
+
+The orchestrator (main conversation) performs ALL of the following in one sequential pass:
+
+1. **Extract from conversation**: Identify the problem, root cause, and solution from conversation history
+2. **Classify**: Determine category and filename (same categories as full mode)
+3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` with:
+   - YAML frontmatter (title, category, date, tags)
+   - Problem description (1-2 sentences)
+   - Root cause (1-2 sentences)
+   - Solution with key code snippets
+   - One prevention tip
+4. **Skip specialized agent reviews** (Phase 3) to conserve context
+
+**Compact-safe output:**
+```
+✓ Documentation complete (compact-safe mode)
+
+File created:
+- docs/solutions/[category]/[filename].md
+
+Note: This was created in compact-safe mode. For richer documentation
+(cross-references, detailed prevention strategies, specialized reviews),
+re-run /compound in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. One file written.**
+
+---
+
 ## What It Captures
 
 - **Problem symptom**: Exact error messages, observable behavior