@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.
- package/.claude/commands/triage-prs.md +193 -0
- package/.claude-plugin/marketplace.json +2 -2
- package/.github/workflows/ci.yml +25 -0
- package/README.md +22 -1
- package/docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md +128 -0
- package/docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md +212 -0
- package/package.json +1 -1
- package/plans/grow-your-own-garden-plugin-architecture.md +1 -1
- package/plugins/compound-engineering/.claude-plugin/plugin.json +2 -2
- package/plugins/compound-engineering/CHANGELOG.md +58 -0
- package/plugins/compound-engineering/CLAUDE.md +3 -4
- package/plugins/compound-engineering/README.md +19 -7
- package/plugins/compound-engineering/agents/design/design-implementation-reviewer.md +16 -1
- package/plugins/compound-engineering/agents/design/design-iterator.md +28 -1
- package/plugins/compound-engineering/agents/design/figma-design-sync.md +19 -1
- package/plugins/compound-engineering/agents/docs/ankane-readme-writer.md +16 -1
- package/plugins/compound-engineering/agents/research/best-practices-researcher.md +16 -1
- package/plugins/compound-engineering/agents/research/framework-docs-researcher.md +16 -1
- package/plugins/compound-engineering/agents/research/git-history-analyzer.md +18 -1
- package/plugins/compound-engineering/agents/research/learnings-researcher.md +24 -3
- package/plugins/compound-engineering/agents/research/repo-research-analyst.md +22 -1
- package/plugins/compound-engineering/agents/review/agent-native-reviewer.md +16 -1
- package/plugins/compound-engineering/agents/review/architecture-strategist.md +16 -1
- package/plugins/compound-engineering/agents/review/code-simplicity-reviewer.md +17 -1
- package/plugins/compound-engineering/agents/review/data-integrity-guardian.md +16 -1
- package/plugins/compound-engineering/agents/review/data-migration-expert.md +16 -1
- package/plugins/compound-engineering/agents/review/deployment-verification-agent.md +16 -1
- package/plugins/compound-engineering/agents/review/dhh-rails-reviewer.md +22 -1
- package/plugins/compound-engineering/agents/review/julik-frontend-races-reviewer.md +20 -21
- package/plugins/compound-engineering/agents/review/kieran-python-reviewer.md +30 -1
- package/plugins/compound-engineering/agents/review/kieran-rails-reviewer.md +30 -1
- package/plugins/compound-engineering/agents/review/kieran-typescript-reviewer.md +30 -1
- package/plugins/compound-engineering/agents/review/pattern-recognition-specialist.md +16 -1
- package/plugins/compound-engineering/agents/review/performance-oracle.md +28 -1
- package/plugins/compound-engineering/agents/review/schema-drift-detector.md +154 -0
- package/plugins/compound-engineering/agents/review/security-sentinel.md +22 -1
- package/plugins/compound-engineering/agents/workflow/bug-reproduction-validator.md +16 -1
- package/plugins/compound-engineering/agents/workflow/every-style-editor.md +1 -1
- package/plugins/compound-engineering/agents/workflow/pr-comment-resolver.md +16 -1
- package/plugins/compound-engineering/agents/workflow/spec-flow-analyzer.md +22 -1
- package/plugins/compound-engineering/commands/agent-native-audit.md +1 -0
- package/plugins/compound-engineering/commands/changelog.md +1 -0
- package/plugins/compound-engineering/commands/create-agent-skill.md +1 -0
- package/plugins/compound-engineering/commands/deepen-plan.md +2 -2
- package/plugins/compound-engineering/commands/deploy-docs.md +1 -0
- package/plugins/compound-engineering/commands/generate_command.md +1 -0
- package/plugins/compound-engineering/commands/heal-skill.md +1 -0
- package/plugins/compound-engineering/commands/lfg.md +1 -0
- package/plugins/compound-engineering/commands/release-docs.md +1 -0
- package/plugins/compound-engineering/commands/report-bug.md +1 -0
- package/plugins/compound-engineering/commands/reproduce-bug.md +1 -0
- package/plugins/compound-engineering/commands/resolve_parallel.md +1 -0
- package/plugins/compound-engineering/commands/resolve_todo_parallel.md +2 -0
- package/plugins/compound-engineering/commands/slfg.md +32 -0
- package/plugins/compound-engineering/commands/technical_review.md +8 -0
- package/plugins/compound-engineering/commands/{xcode-test.md → test-xcode.md} +2 -1
- package/plugins/compound-engineering/commands/triage.md +1 -0
- package/plugins/compound-engineering/commands/workflows/brainstorm.md +11 -2
- package/plugins/compound-engineering/commands/workflows/compound.md +64 -27
- package/plugins/compound-engineering/commands/workflows/plan.md +9 -9
- package/plugins/compound-engineering/commands/workflows/review.md +12 -0
- package/plugins/compound-engineering/commands/workflows/work.md +71 -1
- package/plugins/compound-engineering/skills/compound-docs/SKILL.md +9 -8
- package/plugins/compound-engineering/skills/compound-docs/assets/critical-pattern-template.md +1 -1
- package/plugins/compound-engineering/skills/compound-docs/assets/resolution-template.md +3 -3
- package/plugins/compound-engineering/skills/compound-docs/references/yaml-schema.md +1 -1
- package/plugins/compound-engineering/skills/create-agent-skills/SKILL.md +168 -192
- package/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md +74 -125
- package/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md +109 -329
- package/plugins/compound-engineering/skills/document-review/SKILL.md +87 -0
- package/plugins/compound-engineering/skills/file-todos/SKILL.md +1 -0
- package/plugins/compound-engineering/skills/git-worktree/scripts/worktree-manager.sh +2 -10
- package/plugins/compound-engineering/skills/orchestrating-swarms/SKILL.md +1718 -0
- package/plugins/compound-engineering/skills/resolve-pr-parallel/SKILL.md +89 -0
- package/plugins/compound-engineering/skills/resolve-pr-parallel/scripts/get-pr-comments +68 -0
- package/plugins/compound-engineering/skills/resolve-pr-parallel/scripts/resolve-pr-thread +23 -0
- package/plugins/compound-engineering/skills/skill-creator/SKILL.md +1 -0
- package/src/commands/sync.ts +84 -0
- package/src/converters/claude-to-codex.ts +61 -3
- package/src/converters/claude-to-opencode.ts +8 -5
- package/src/index.ts +2 -0
- package/src/parsers/claude-home.ts +65 -0
- package/src/parsers/claude.ts +4 -0
- package/src/sync/codex.ts +92 -0
- package/src/sync/opencode.ts +75 -0
- package/src/targets/codex.ts +7 -2
- package/src/targets/opencode.ts +6 -1
- package/src/types/claude.ts +3 -1
- package/src/utils/files.ts +13 -0
- package/src/utils/symlink.ts +43 -0
- package/tests/claude-parser.test.ts +24 -2
- package/tests/codex-converter.test.ts +121 -0
- package/tests/codex-writer.test.ts +32 -0
- package/tests/converter.test.ts +15 -0
- package/tests/fixtures/sample-plugin/commands/disabled-command.md +7 -0
- package/tests/fixtures/sample-plugin/skills/disabled-skill/SKILL.md +7 -0
- package/tests/opencode-writer.test.ts +32 -0
- package/plugins/compound-engineering/commands/plan_review.md +0 -7
- 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
|
|
15
|
-
"version": "2.
|
|
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
|
+
[](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml)
|
|
4
|
+
[](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,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "compound-engineering",
|
|
3
|
-
"version": "2.
|
|
4
|
-
"description": "AI-powered development tools.
|
|
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",
|