@every-env/compound-plugin 0.1.1 → 0.3.0

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 (99) hide show
  1. package/.claude/commands/triage-prs.md +193 -0
  2. package/.claude-plugin/marketplace.json +2 -2
  3. package/.github/workflows/ci.yml +25 -0
  4. package/README.md +22 -1
  5. package/docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md +128 -0
  6. package/docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md +212 -0
  7. package/package.json +1 -1
  8. package/plans/grow-your-own-garden-plugin-architecture.md +1 -1
  9. package/plugins/compound-engineering/.claude-plugin/plugin.json +2 -2
  10. package/plugins/compound-engineering/CHANGELOG.md +58 -0
  11. package/plugins/compound-engineering/CLAUDE.md +3 -4
  12. package/plugins/compound-engineering/README.md +19 -7
  13. package/plugins/compound-engineering/agents/design/design-implementation-reviewer.md +16 -1
  14. package/plugins/compound-engineering/agents/design/design-iterator.md +28 -1
  15. package/plugins/compound-engineering/agents/design/figma-design-sync.md +19 -1
  16. package/plugins/compound-engineering/agents/docs/ankane-readme-writer.md +16 -1
  17. package/plugins/compound-engineering/agents/research/best-practices-researcher.md +16 -1
  18. package/plugins/compound-engineering/agents/research/framework-docs-researcher.md +16 -1
  19. package/plugins/compound-engineering/agents/research/git-history-analyzer.md +18 -1
  20. package/plugins/compound-engineering/agents/research/learnings-researcher.md +24 -3
  21. package/plugins/compound-engineering/agents/research/repo-research-analyst.md +22 -1
  22. package/plugins/compound-engineering/agents/review/agent-native-reviewer.md +16 -1
  23. package/plugins/compound-engineering/agents/review/architecture-strategist.md +16 -1
  24. package/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md +17 -1
  25. package/plugins/compound-engineering/agents/review/data-integrity-guardian.md +16 -1
  26. package/plugins/compound-engineering/agents/review/data-migration-expert.md +16 -1
  27. package/plugins/compound-engineering/agents/review/deployment-verification-agent.md +16 -1
  28. package/plugins/compound-engineering/agents/review/dhh-rails-reviewer.md +22 -1
  29. package/plugins/compound-engineering/agents/review/julik-frontend-races-reviewer.md +20 -21
  30. package/plugins/compound-engineering/agents/review/kieran-python-reviewer.md +30 -1
  31. package/plugins/compound-engineering/agents/review/kieran-rails-reviewer.md +30 -1
  32. package/plugins/compound-engineering/agents/review/kieran-typescript-reviewer.md +30 -1
  33. package/plugins/compound-engineering/agents/review/pattern-recognition-specialist.md +16 -1
  34. package/plugins/compound-engineering/agents/review/performance-oracle.md +28 -1
  35. package/plugins/compound-engineering/agents/review/schema-drift-detector.md +154 -0
  36. package/plugins/compound-engineering/agents/review/security-sentinel.md +22 -1
  37. package/plugins/compound-engineering/agents/workflow/bug-reproduction-validator.md +16 -1
  38. package/plugins/compound-engineering/agents/workflow/every-style-editor.md +1 -1
  39. package/plugins/compound-engineering/agents/workflow/pr-comment-resolver.md +16 -1
  40. package/plugins/compound-engineering/agents/workflow/spec-flow-analyzer.md +22 -1
  41. package/plugins/compound-engineering/commands/agent-native-audit.md +1 -0
  42. package/plugins/compound-engineering/commands/changelog.md +1 -0
  43. package/plugins/compound-engineering/commands/create-agent-skill.md +1 -0
  44. package/plugins/compound-engineering/commands/deepen-plan.md +2 -2
  45. package/plugins/compound-engineering/commands/deploy-docs.md +1 -0
  46. package/plugins/compound-engineering/commands/generate_command.md +1 -0
  47. package/plugins/compound-engineering/commands/heal-skill.md +1 -0
  48. package/plugins/compound-engineering/commands/lfg.md +1 -0
  49. package/plugins/compound-engineering/commands/release-docs.md +1 -0
  50. package/plugins/compound-engineering/commands/report-bug.md +1 -0
  51. package/plugins/compound-engineering/commands/reproduce-bug.md +1 -0
  52. package/plugins/compound-engineering/commands/resolve_parallel.md +1 -0
  53. package/plugins/compound-engineering/commands/resolve_todo_parallel.md +2 -0
  54. package/plugins/compound-engineering/commands/slfg.md +32 -0
  55. package/plugins/compound-engineering/commands/technical_review.md +8 -0
  56. package/plugins/compound-engineering/commands/{xcode-test.md → test-xcode.md} +2 -1
  57. package/plugins/compound-engineering/commands/triage.md +1 -0
  58. package/plugins/compound-engineering/commands/workflows/brainstorm.md +11 -2
  59. package/plugins/compound-engineering/commands/workflows/compound.md +64 -27
  60. package/plugins/compound-engineering/commands/workflows/plan.md +9 -9
  61. package/plugins/compound-engineering/commands/workflows/review.md +12 -0
  62. package/plugins/compound-engineering/commands/workflows/work.md +71 -1
  63. package/plugins/compound-engineering/skills/compound-docs/SKILL.md +9 -8
  64. package/plugins/compound-engineering/skills/compound-docs/assets/critical-pattern-template.md +1 -1
  65. package/plugins/compound-engineering/skills/compound-docs/assets/resolution-template.md +3 -3
  66. package/plugins/compound-engineering/skills/compound-docs/references/yaml-schema.md +1 -1
  67. package/plugins/compound-engineering/skills/create-agent-skills/SKILL.md +168 -192
  68. package/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md +74 -125
  69. package/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md +109 -329
  70. package/plugins/compound-engineering/skills/document-review/SKILL.md +87 -0
  71. package/plugins/compound-engineering/skills/file-todos/SKILL.md +1 -0
  72. package/plugins/compound-engineering/skills/git-worktree/scripts/worktree-manager.sh +2 -10
  73. package/plugins/compound-engineering/skills/orchestrating-swarms/SKILL.md +1718 -0
  74. package/plugins/compound-engineering/skills/resolve-pr-parallel/SKILL.md +89 -0
  75. package/plugins/compound-engineering/skills/resolve-pr-parallel/scripts/get-pr-comments +68 -0
  76. package/plugins/compound-engineering/skills/resolve-pr-parallel/scripts/resolve-pr-thread +23 -0
  77. package/plugins/compound-engineering/skills/skill-creator/SKILL.md +1 -0
  78. package/src/commands/sync.ts +84 -0
  79. package/src/converters/claude-to-codex.ts +61 -3
  80. package/src/converters/claude-to-opencode.ts +8 -5
  81. package/src/index.ts +2 -0
  82. package/src/parsers/claude-home.ts +65 -0
  83. package/src/parsers/claude.ts +4 -0
  84. package/src/sync/codex.ts +92 -0
  85. package/src/sync/opencode.ts +75 -0
  86. package/src/targets/codex.ts +7 -2
  87. package/src/targets/opencode.ts +6 -1
  88. package/src/types/claude.ts +3 -1
  89. package/src/utils/files.ts +13 -0
  90. package/src/utils/symlink.ts +43 -0
  91. package/tests/claude-parser.test.ts +24 -2
  92. package/tests/codex-converter.test.ts +121 -0
  93. package/tests/codex-writer.test.ts +32 -0
  94. package/tests/converter.test.ts +15 -0
  95. package/tests/fixtures/sample-plugin/commands/disabled-command.md +7 -0
  96. package/tests/fixtures/sample-plugin/skills/disabled-skill/SKILL.md +7 -0
  97. package/tests/opencode-writer.test.ts +32 -0
  98. package/plugins/compound-engineering/commands/plan_review.md +0 -7
  99. package/plugins/compound-engineering/commands/resolve_pr_parallel.md +0 -49
@@ -0,0 +1,193 @@
1
+ ---
2
+ name: triage-prs
3
+ description: Triage all open PRs with parallel agents, label, group, and review one-by-one
4
+ argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
5
+ disable-model-invocation: true
6
+ allowed-tools: Bash(gh *), Bash(git log *)
7
+ ---
8
+
9
+ # Triage Open Pull Requests
10
+
11
+ Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
12
+
13
+ ## Step 0: Detect Repository
14
+
15
+ Detect repo context:
16
+ - Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
17
+ - Current branch: !`git branch --show-current 2>/dev/null`
18
+
19
+ If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
20
+
21
+ ## Step 1: Gather Context (Parallel)
22
+
23
+ Run these in parallel:
24
+
25
+ 1. **List all open PRs:**
26
+ ```bash
27
+ gh pr list --repo OWNER/REPO --state open --limit 50
28
+ ```
29
+
30
+ 2. **List all open issues:**
31
+ ```bash
32
+ gh issue list --repo OWNER/REPO --state open --limit 50
33
+ ```
34
+
35
+ 3. **List existing labels:**
36
+ ```bash
37
+ gh label list --repo OWNER/REPO --limit 50
38
+ ```
39
+
40
+ 4. **Check recent merges** (to detect duplicate/superseded PRs):
41
+ ```bash
42
+ git log --oneline -20 main
43
+ ```
44
+
45
+ ## Step 2: Batch PRs by Theme
46
+
47
+ Group PRs into review batches of 4-6 based on apparent type:
48
+
49
+ - **Bug fixes** - titles with `fix`, `bug`, error descriptions
50
+ - **Features** - titles with `feat`, `add`, new functionality
51
+ - **Documentation** - titles with `docs`, `readme`, terminology
52
+ - **Configuration/Setup** - titles with `config`, `setup`, `install`
53
+ - **Stale/Old** - PRs older than 30 days
54
+
55
+ ## Step 3: Parallel Review (Team of Agents)
56
+
57
+ Spawn one review agent per batch using the Task tool. Each agent should:
58
+
59
+ For each PR in their batch:
60
+ 1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
61
+ 2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
62
+ 3. Determine:
63
+ - **Description:** 1-2 sentence summary of the change
64
+ - **Label:** Which existing repo label fits best
65
+ - **Action:** merge / request changes / close / needs discussion
66
+ - **Related PRs:** Any PRs in this or other batches that touch the same files or feature
67
+ - **Quality notes:** Code quality, test coverage, staleness concerns
68
+
69
+ Instruct each agent to:
70
+ - Flag PRs that touch the same files (potential merge conflicts)
71
+ - Flag PRs that duplicate recently merged work
72
+ - Flag PRs that are part of a group solving the same problem differently
73
+ - Report findings as a markdown table
74
+ - Send findings back via message when done
75
+
76
+ ## Step 4: Cross-Reference Issues
77
+
78
+ After all agents report, match issues to PRs:
79
+
80
+ - Check if any PR title/body mentions `Fixes #X` or `Closes #X`
81
+ - Check if any issue title matches a PR's topic
82
+ - Look for duplicate issues (same bug reported twice)
83
+
84
+ Build a mapping table:
85
+ ```
86
+ | Issue | PR | Relationship |
87
+ |-------|-----|--------------|
88
+ | #158 | #159 | PR fixes issue |
89
+ ```
90
+
91
+ ## Step 5: Identify Themes
92
+
93
+ Group all issues into themes (3-6 themes):
94
+ - Count issues per theme
95
+ - Note which themes have PRs addressing them and which don't
96
+ - Flag themes with competing/overlapping PRs
97
+
98
+ ## Step 6: Compile Triage Report
99
+
100
+ Present a single report with:
101
+
102
+ 1. **Summary stats:** X open PRs, Y open issues, Z themes
103
+ 2. **PR groups** with recommended actions:
104
+ - Group name and related PRs
105
+ - Per-PR: #, title, author, description, label, action
106
+ 3. **Issue-to-PR mapping**
107
+ 4. **Themes across issues**
108
+ 5. **Suggested cleanup:** spam issues, duplicates, stale items
109
+
110
+ ## Step 7: Apply Labels
111
+
112
+ After presenting the report, ask user:
113
+
114
+ > "Apply these labels to all PRs on GitHub?"
115
+
116
+ If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
117
+
118
+ ## Step 8: One-by-One Review
119
+
120
+ Use **AskUserQuestion** to ask:
121
+
122
+ > "Ready to walk through PRs one-by-one for merge/comment decisions?"
123
+
124
+ Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
125
+
126
+ ### Show the PR:
127
+
128
+ ```
129
+ ### PR #<number> - <title>
130
+ Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
131
+ Label: <label>
132
+
133
+ <1-2 sentence description>
134
+
135
+ Fixes: <linked issues if any>
136
+ Related: <related PRs if any>
137
+ ```
138
+
139
+ Show the diff (trimmed to key changes if large).
140
+
141
+ ### Ask for decision:
142
+
143
+ Use **AskUserQuestion**:
144
+ - **Merge** - Merge this PR now
145
+ - **Comment & skip** - Leave a comment explaining why not merging, keep open
146
+ - **Close** - Close with a comment
147
+ - **Skip** - Move to next without action
148
+
149
+ ### Execute decision:
150
+
151
+ - **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
152
+ - If PR fixes an issue, close the issue too
153
+ - **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
154
+ - Ask user what to say, or generate a grateful + specific comment
155
+ - **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
156
+ - **Skip:** Move on
157
+
158
+ ## Step 9: Post-Merge Cleanup
159
+
160
+ After all PRs are reviewed:
161
+
162
+ 1. **Close resolved issues** that were fixed by merged PRs
163
+ 2. **Close spam/off-topic issues** (confirm with user first)
164
+ 3. **Summary of actions taken:**
165
+ ```
166
+ ## Triage Complete
167
+
168
+ Merged: X PRs
169
+ Commented: Y PRs
170
+ Closed: Z PRs
171
+ Skipped: W PRs
172
+
173
+ Issues closed: A
174
+ Labels applied: B
175
+ ```
176
+
177
+ ## Step 10: Post-Triage Options
178
+
179
+ Use **AskUserQuestion**:
180
+
181
+ 1. **Run `/release-docs`** - Update documentation site if components changed
182
+ 2. **Run `/changelog`** - Generate changelog for merged PRs
183
+ 3. **Commit any local changes** - If version bumps needed
184
+ 4. **Done** - Wrap up
185
+
186
+ ## Important Notes
187
+
188
+ - **DO NOT merge without user approval** for each PR
189
+ - **DO NOT force push or destructive actions**
190
+ - Comments on declined PRs should be grateful and constructive
191
+ - When PRs conflict with each other, note this and suggest merge order
192
+ - When multiple PRs solve the same problem differently, flag for user to pick one
193
+ - Use Haiku model for review agents to save cost (they're doing read-only analysis)
@@ -11,8 +11,8 @@
11
11
  "plugins": [
12
12
  {
13
13
  "name": "compound-engineering",
14
- "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.",
15
- "version": "2.28.0",
14
+ "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 24 commands, and 18 skills.",
15
+ "version": "2.31.0",
16
16
  "author": {
17
17
  "name": "Kieran Klaassen",
18
18
  "url": "https://github.com/kieranklaassen",
@@ -0,0 +1,25 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Setup Bun
17
+ uses: oven-sh/setup-bun@v2
18
+ with:
19
+ bun-version: latest
20
+
21
+ - name: Install dependencies
22
+ run: bun install
23
+
24
+ - name: Run tests
25
+ run: bun test
package/README.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # Compound Marketplace
2
2
 
3
+ [![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/@every-env/compound-plugin)](https://www.npmjs.com/package/@every-env/compound-plugin)
5
+
3
6
  A Claude Code plugin marketplace featuring the **Compound Engineering Plugin** — tools that make each unit of engineering work easier than the last.
4
7
 
5
8
  ## Claude Code Install
@@ -27,10 +30,28 @@ Local dev:
27
30
  bun run src/index.ts install ./plugins/compound-engineering --to opencode
28
31
  ```
29
32
 
30
- OpenCode output is written to `~/.opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
33
+ OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
31
34
  Both provider targets are experimental and may change as the formats evolve.
32
35
  Codex output is written to `~/.codex/prompts` and `~/.codex/skills`, with each Claude command converted into both a prompt and a skill (the prompt instructs Codex to load the corresponding skill). Generated Codex skill descriptions are truncated to 1024 characters (Codex limit).
33
36
 
37
+ ## Sync Personal Config
38
+
39
+ Sync your personal Claude Code config (`~/.claude/`) to OpenCode or Codex:
40
+
41
+ ```bash
42
+ # Sync skills and MCP servers to OpenCode
43
+ bunx @every-env/compound-plugin sync --target opencode
44
+
45
+ # Sync to Codex
46
+ bunx @every-env/compound-plugin sync --target codex
47
+ ```
48
+
49
+ This syncs:
50
+ - Personal skills from `~/.claude/skills/` (as symlinks)
51
+ - MCP servers from `~/.claude/settings.json`
52
+
53
+ Skills are symlinked (not copied) so changes in Claude Code are reflected immediately.
54
+
34
55
  ## Workflow
35
56
 
36
57
  ```
@@ -0,0 +1,128 @@
1
+ ---
2
+ title: PR Triage, Review & Merge
3
+ type: feat
4
+ date: 2026-02-08
5
+ ---
6
+
7
+ # PR Triage, Review & Merge
8
+
9
+ ## Overview
10
+
11
+ Review all 17 open PRs one-by-one. Merge the ones that look good, leave constructive comments on the ones we won't take (keeping them open for contributors to address). Close duplicates/spam.
12
+
13
+ ## Approach
14
+
15
+ Show the diff for each PR, get a go/no-go, then either merge or comment. PRs are ordered by priority group.
16
+
17
+ ## Group 1: Bug Fixes (high confidence merges)
18
+
19
+ ### PR #159 - fix(git-worktree): detect worktrees where .git is a file
20
+ - **Author:** dalley | **Files:** 1 | **+2/-2**
21
+ - **What:** Changes `-d` to `-e` check in `worktree-manager.sh` so `list` and `cleanup` detect worktrees (`.git` is a file in worktrees, not a dir)
22
+ - **Fixes:** Issue #158
23
+ - **Action:** Review diff → merge
24
+
25
+ ### PR #144 - Remove confirmation prompt when creating git worktrees
26
+ - **Author:** XSAM | **Files:** 1 | **+0/-8**
27
+ - **What:** Removes interactive `read -r` confirmation that breaks Claude's ability to create worktrees
28
+ - **Related:** Same file as #159 (merge #159 first)
29
+ - **Action:** Review diff → merge
30
+
31
+ ### PR #150 - fix(compound): prevent subagents from writing intermediary files
32
+ - **Author:** tmchow | **Files:** 1 | **+64/-27**
33
+ - **What:** Restructures `/workflows:compound` into 2-phase orchestration to prevent subagents from writing temp files
34
+ - **Action:** Review diff → merge
35
+
36
+ ### PR #148 - Fix: resolve_pr_parallel uses non-existent scripts
37
+ - **Author:** ajrobertsonio | **Files:** 1 | **+20/-7**
38
+ - **What:** Replaces references to non-existent `bin/get-pr-comments` with standard `gh` CLI commands
39
+ - **Fixes:** Issues #147, #54
40
+ - **Action:** Review diff → merge
41
+
42
+ ## Group 2: Documentation (clean, low-risk)
43
+
44
+ ### PR #133 - Fix terminology: third person → passive voice
45
+ - **Author:** FauxReal9999 | **Files:** 13 | docs-only
46
+ - **What:** Corrects "third person" to "passive voice" across docs (accurate fix)
47
+ - **Action:** Review diff → merge
48
+
49
+ ### PR #108 - Note new repository URL
50
+ - **Author:** akx | **Files:** 5 | docs-only
51
+ - **What:** Updates URLs from `kieranklaassen/compound-engineering-plugin` to `EveryInc/compound-engineering-plugin`
52
+ - **Action:** Review diff → merge
53
+
54
+ ### PR #113 - docs: add brainstorm command to workflow documentation
55
+ - **Author:** tmchow | docs-only
56
+ - **What:** Adds brainstorming skill and learnings-researcher agent to README, fixes component counts
57
+ - **Action:** Review diff → merge
58
+
59
+ ### PR #80 - docs: Add LSP prioritization guidance
60
+ - **Author:** kevinold | **Files:** 1 | docs-only
61
+ - **What:** Adds docs showing users how to customize agent behavior via project CLAUDE.md to prioritize LSP
62
+ - **Action:** Review diff → merge
63
+
64
+ ## Group 3: Enhancements (likely merge)
65
+
66
+ ### PR #119 - fix: backup existing config files before overwriting
67
+ - **Author:** jzw | **Files:** 5 | **+90/-3** | has tests
68
+ - **What:** Adds `backupFile()` utility to create timestamped backups before overwriting Codex/OpenCode configs
69
+ - **Fixes:** Issue #125
70
+ - **Action:** Review diff → merge
71
+
72
+ ### PR #112 - feat(skills): add document-review skill
73
+ - **Author:** tmchow | enhancement
74
+ - **What:** Adds document-review skill for brainstorm/plan refinement, renames `/plan_review` → `/technical_review`
75
+ - **Note:** Breaking rename - needs review
76
+ - **Action:** Review diff → decide
77
+
78
+ ## Group 4: Needs Discussion (comment and leave open)
79
+
80
+ ### PR #157 - Rewrite workflows:review with context-managed map-reduce
81
+ - **Author:** Drewx-Design | large rewrite
82
+ - **What:** Complete rewrite of review command with file-based map-reduce architecture
83
+ - **Comment:** Acknowledge quality, note it's a big change that needs dedicated review session
84
+
85
+ ### PR #131 - feat: add vmark-mcp plugin
86
+ - **Author:** xiaolai | new plugin
87
+ - **What:** Adds entirely new VMark markdown editor plugin to marketplace
88
+ - **Comment:** Ask for more context on fit with marketplace scope
89
+
90
+ ### PR #124 - feat(commands): add /compound-engineering-setup
91
+ - **Author:** internal | config
92
+ - **What:** Interactive setup command for configuring review agents per project
93
+ - **Comment:** Note overlap with #103, needs unified config strategy
94
+
95
+ ### PR #123 - feat: Add sync command for Claude Code personal config
96
+ - **Author:** terry-li-hm | config
97
+ - **What:** Sync personal Claude config across machines/editors
98
+ - **Comment:** Note overlap with #124 and #103, needs unified config strategy
99
+
100
+ ### PR #103 - Add /compound:configure with persistent user preferences
101
+ - **Author:** aviflombaum | **+36,866** lines
102
+ - **What:** Massive architectural change adding persistent config with build system
103
+ - **Comment:** Too large, suggest breaking into smaller PRs
104
+
105
+ ## Group 5: Close
106
+
107
+ ### PR #122 - [EXPERIMENTAL] add /slfg and /swarm-status
108
+ - **Label:** duplicate
109
+ - **What:** Already merged in v2.30.0 (commit e4ff6a8)
110
+ - **Action:** Comment explaining it's been superseded, close
111
+
112
+ ### PR #68 - Improve all 13 skills to 90%+ grades
113
+ - **Label:** wontfix
114
+ - **What:** Massive stale PR (Jan 6), based on 13 skills when we now have 16+
115
+ - **Action:** Comment thanking contributor, suggest fresh PR against current main, close
116
+
117
+ ## Post-Merge Cleanup
118
+
119
+ After merging:
120
+ - [ ] Close issues fixed by merged PRs (#158, #147, #54, #125)
121
+ - [ ] Close spam issues (#98, #56)
122
+ - [ ] Run `/release-docs` to update documentation site with new component counts
123
+ - [ ] Bump version in plugin.json if needed
124
+
125
+ ## References
126
+
127
+ - PR list: https://github.com/EveryInc/compound-engineering-plugin/pulls
128
+ - Issues: https://github.com/EveryInc/compound-engineering-plugin/issues
@@ -0,0 +1,212 @@
1
+ ---
2
+ title: Reduce compound-engineering plugin context token usage
3
+ type: refactor
4
+ date: 2026-02-08
5
+ ---
6
+
7
+ # Reduce compound-engineering Plugin Context Token Usage
8
+
9
+ ## Overview
10
+
11
+ The compound-engineering plugin is **overflowing the default context budget by ~3x**, causing Claude Code to silently drop components. The plugin consumes ~50,500 characters in always-loaded descriptions against a default budget of 16,000 characters (2% of context window). This means Claude literally doesn't know some agents/skills exist during sessions.
12
+
13
+ ## Problem Statement
14
+
15
+ ### How Context Loading Works
16
+
17
+ Claude Code uses progressive disclosure for plugin content:
18
+
19
+ | Level | What Loads | When |
20
+ |-------|-----------|------|
21
+ | **Always in context** | `description` frontmatter from skills, commands, and agents | Session startup (unless `disable-model-invocation: true`) |
22
+ | **On invocation** | Full SKILL.md / command body / agent body | When triggered |
23
+ | **On demand** | Reference files in skill directories | When Claude reads them |
24
+
25
+ The total budget for ALL descriptions combined is **2% of context window** (~16,000 chars fallback). When exceeded, components are **silently excluded**.
26
+
27
+ ### Current State: 316% of Budget
28
+
29
+ | Component | Count | Always-Loaded Chars | % of 16K Budget |
30
+ |-----------|------:|--------------------:|----------------:|
31
+ | Agent descriptions | 29 | ~41,400 | 259% |
32
+ | Skill descriptions | 16 | ~5,450 | 34% |
33
+ | Command descriptions | 24 | ~3,700 | 23% |
34
+ | **Total** | **69** | **~50,500** | **316%** |
35
+
36
+ ### Root Cause: Bloated Agent Descriptions
37
+
38
+ Agent `description` fields contain full `<example>` blocks with user/assistant dialog. These examples belong in the agent body (system prompt), not the description. The description's only job is **discovery** — helping Claude decide whether to delegate.
39
+
40
+ Examples of the problem:
41
+
42
+ - `design-iterator.md`: 2,488 chars in description (should be ~200)
43
+ - `spec-flow-analyzer.md`: 2,289 chars in description
44
+ - `security-sentinel.md`: 1,986 chars in description
45
+ - `kieran-rails-reviewer.md`: 1,822 chars in description
46
+ - Average agent description: ~1,400 chars (should be 100-250)
47
+
48
+ Compare to Anthropic's official examples at 100-200 chars:
49
+
50
+ ```yaml
51
+ # Official (140 chars)
52
+ description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
53
+
54
+ # Current plugin (1,822 chars)
55
+ description: "Use this agent when you need to review Rails code changes with an extremely high quality bar...\n\nExamples:\n- <example>\n Context: The user has just implemented..."
56
+ ```
57
+
58
+ ### Secondary Cause: No `disable-model-invocation` on Manual Commands
59
+
60
+ Zero commands set `disable-model-invocation: true`. Commands like `/deploy-docs`, `/lfg`, `/slfg`, `/triage`, `/feature-video`, `/test-browser`, `/xcode-test` are manual workflows with side effects. Their descriptions consume budget unnecessarily.
61
+
62
+ The official docs explicitly state:
63
+ > Use `disable-model-invocation: true` for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`. You don't want Claude deciding to deploy because your code looks ready.
64
+
65
+ ---
66
+
67
+ ## Proposed Solution
68
+
69
+ Three changes, ordered by impact:
70
+
71
+ ### Phase 1: Trim Agent Descriptions (saves ~35,600 chars)
72
+
73
+ For all 29 agents: move `<example>` blocks from the `description` field into the agent body markdown. Keep descriptions to 1-2 sentences (100-250 chars).
74
+
75
+ **Before** (agent frontmatter):
76
+ ```yaml
77
+ ---
78
+ name: kieran-rails-reviewer
79
+ description: "Use this agent when you need to review Rails code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Rails components. The agent applies Kieran's strict Rails conventions and taste preferences to ensure code meets exceptional standards.\n\nExamples:\n- <example>\n Context: The user has just implemented a new controller action with turbo streams.\n user: \"I've added a new update action to the posts controller\"\n ..."
80
+ ---
81
+
82
+ Detailed system prompt...
83
+ ```
84
+
85
+ **After** (agent frontmatter):
86
+ ```yaml
87
+ ---
88
+ name: kieran-rails-reviewer
89
+ description: Review Rails code with Kieran's strict conventions. Use after implementing features, modifying code, or creating new Rails components.
90
+ ---
91
+
92
+ <examples>
93
+ <example>
94
+ Context: The user has just implemented a new controller action with turbo streams.
95
+ user: "I've added a new update action to the posts controller"
96
+ ...
97
+ </example>
98
+ </examples>
99
+
100
+ Detailed system prompt...
101
+ ```
102
+
103
+ The examples move into the body (which only loads when the agent is actually invoked).
104
+
105
+ **Impact:** ~41,400 chars → ~5,800 chars (86% reduction)
106
+
107
+ ### Phase 2: Add `disable-model-invocation: true` to Manual Commands (saves ~3,100 chars)
108
+
109
+ Commands that should only run when explicitly invoked by the user:
110
+
111
+ | Command | Reason |
112
+ |---------|--------|
113
+ | `/deploy-docs` | Side effect: deploys |
114
+ | `/release-docs` | Side effect: regenerates docs |
115
+ | `/changelog` | Side effect: generates changelog |
116
+ | `/lfg` | Side effect: autonomous workflow |
117
+ | `/slfg` | Side effect: swarm workflow |
118
+ | `/triage` | Side effect: categorizes findings |
119
+ | `/resolve_parallel` | Side effect: resolves TODOs |
120
+ | `/resolve_todo_parallel` | Side effect: resolves todos |
121
+ | `/resolve_pr_parallel` | Side effect: resolves PR comments |
122
+ | `/feature-video` | Side effect: records video |
123
+ | `/test-browser` | Side effect: runs browser tests |
124
+ | `/xcode-test` | Side effect: builds/tests iOS |
125
+ | `/reproduce-bug` | Side effect: runs reproduction |
126
+ | `/report-bug` | Side effect: creates bug report |
127
+ | `/agent-native-audit` | Side effect: runs audit |
128
+ | `/heal-skill` | Side effect: modifies skill files |
129
+ | `/generate_command` | Side effect: creates files |
130
+ | `/create-agent-skill` | Side effect: creates files |
131
+
132
+ Keep these **without** the flag (Claude should know about them):
133
+ - `/workflows:plan` — Claude might suggest planning
134
+ - `/workflows:work` — Claude might suggest starting work
135
+ - `/workflows:review` — Claude might suggest review
136
+ - `/workflows:brainstorm` — Claude might suggest brainstorming
137
+ - `/workflows:compound` — Claude might suggest documenting
138
+ - `/deepen-plan` — Claude might suggest deepening a plan
139
+
140
+ **Impact:** ~3,700 chars → ~600 chars for commands in context
141
+
142
+ ### Phase 3: Add `disable-model-invocation: true` to Manual Skills (saves ~1,000 chars)
143
+
144
+ Skills that are manual workflows:
145
+
146
+ | Skill | Reason |
147
+ |-------|--------|
148
+ | `skill-creator` | Only invoked manually |
149
+ | `orchestrating-swarms` | Only invoked manually |
150
+ | `git-worktree` | Only invoked manually |
151
+ | `resolve-pr-parallel` | Side effect |
152
+ | `compound-docs` | Only invoked manually |
153
+ | `file-todos` | Only invoked manually |
154
+
155
+ Keep without the flag (Claude should auto-invoke):
156
+ - `dhh-rails-style` — Claude should use when writing Rails code
157
+ - `frontend-design` — Claude should use when building UI
158
+ - `brainstorming` — Claude should suggest before implementation
159
+ - `agent-browser` — Claude should use for browser tasks
160
+ - `gemini-imagegen` — Claude should use for image generation
161
+ - `create-agent-skills` — Claude should use when creating skills
162
+ - `every-style-editor` — Claude should use for editing
163
+ - `dspy-ruby` — Claude should use for DSPy.rb
164
+ - `agent-native-architecture` — Claude should use for agent-native design
165
+ - `andrew-kane-gem-writer` — Claude should use for gem writing
166
+ - `rclone` — Claude should use for cloud uploads
167
+ - `document-review` — Claude should use for doc review
168
+
169
+ **Impact:** ~5,450 chars → ~4,000 chars for skills in context
170
+
171
+ ---
172
+
173
+ ## Projected Result
174
+
175
+ | Component | Before (chars) | After (chars) | Reduction |
176
+ |-----------|---------------:|-------------:|-----------:|
177
+ | Agent descriptions | ~41,400 | ~5,800 | -86% |
178
+ | Command descriptions | ~3,700 | ~600 | -84% |
179
+ | Skill descriptions | ~5,450 | ~4,000 | -27% |
180
+ | **Total** | **~50,500** | **~10,400** | **-79%** |
181
+ | **% of 16K budget** | **316%** | **65%** | -- |
182
+
183
+ From 316% of budget (components silently dropped) to 65% of budget (room for growth).
184
+
185
+ ---
186
+
187
+ ## Acceptance Criteria
188
+
189
+ - [x] All 29 agent description fields are under 250 characters
190
+ - [x] All `<example>` blocks moved from description to agent body
191
+ - [x] 18 manual commands have `disable-model-invocation: true`
192
+ - [x] 6 manual skills have `disable-model-invocation: true`
193
+ - [x] Total always-loaded description content is under 16,000 characters
194
+ - [ ] Run `/context` to verify no "excluded skills" warnings
195
+ - [x] All agents still function correctly (examples are in body, not lost)
196
+ - [x] All commands still invocable via `/command-name`
197
+ - [x] Update plugin version in plugin.json and marketplace.json
198
+ - [x] Update CHANGELOG.md
199
+
200
+ ## Implementation Notes
201
+
202
+ - Agent examples should use `<examples><example>...</example></examples>` tags in the body — Claude understands these natively
203
+ - Description format: "[What it does]. Use [when/trigger condition]." — two sentences max
204
+ - The `lint` agent at 115 words shows compact agents work great
205
+ - Test with `claude --plugin-dir ./plugins/compound-engineering` after changes
206
+ - The `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var can override the default budget for testing
207
+
208
+ ## References
209
+
210
+ - [Skills docs](https://code.claude.com/docs/en/skills) — "Skill descriptions are loaded into context... If you have many skills, they may exceed the character budget"
211
+ - [Subagents docs](https://code.claude.com/docs/en/sub-agents) — description field used for automatic delegation
212
+ - [Skills troubleshooting](https://code.claude.com/docs/en/skills#claude-doesnt-see-all-my-skills) — "The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@every-env/compound-plugin",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
4
  "type": "module",
5
5
  "private": false,
6
6
  "bin": {
@@ -1,6 +1,6 @@
1
1
  # Grow Your Own Garden: Adaptive Agent Ecosystem
2
2
 
3
- > **Issue:** https://github.com/kieranklaassen/compound-engineering-plugin/issues/20
3
+ > **Issue:** https://github.com/EveryInc/compound-engineering-plugin/issues/20
4
4
 
5
5
  ## The Idea
6
6
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "compound-engineering",
3
- "version": "2.28.0",
4
- "description": "AI-powered development tools. 28 agents, 24 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.",
3
+ "version": "2.31.0",
4
+ "description": "AI-powered development tools. 29 agents, 24 commands, 18 skills, 1 MCP server for code review, research, design, and workflow automation.",
5
5
  "author": {
6
6
  "name": "Kieran Klaassen",
7
7
  "email": "kieran@every.to",