opencodekit 0.17.10 → 0.17.11
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/dist/index.js +1 -1
- package/dist/template/.opencode/command/compound.md +143 -0
- package/dist/template/.opencode/command/lfg.md +171 -0
- package/dist/template/.opencode/command/plan.md +57 -0
- package/dist/template/.opencode/command/pr.md +28 -0
- package/dist/template/.opencode/command/ship.md +24 -19
- package/dist/template/.opencode/skill/requesting-code-review/SKILL.md +155 -68
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
|
|
|
759
759
|
// package.json
|
|
760
760
|
var package_default = {
|
|
761
761
|
name: "opencodekit",
|
|
762
|
-
version: "0.17.
|
|
762
|
+
version: "0.17.11",
|
|
763
763
|
description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
|
|
764
764
|
keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
|
|
765
765
|
license: "MIT",
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Extract and persist learnings from completed work into institutional memory
|
|
3
|
+
argument-hint: "[bead-id]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Compound: $ARGUMENTS
|
|
7
|
+
|
|
8
|
+
Capture what was learned. This is the flywheel step — each cycle makes the next cycle faster.
|
|
9
|
+
|
|
10
|
+
> **Workflow:** `/plan` → `/ship` → `/review` → **`/compound`** → `/pr`
|
|
11
|
+
>
|
|
12
|
+
> Run after every completed task, review, or PR merge. The value compounds over time.
|
|
13
|
+
|
|
14
|
+
## What This Does
|
|
15
|
+
|
|
16
|
+
Extracts learnings from the just-completed work and stores them as structured observations in memory,
|
|
17
|
+
so future Plan and Ship cycles start with institutional knowledge instead of blank slates.
|
|
18
|
+
|
|
19
|
+
## Phase 1: Gather Evidence
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# Get what changed
|
|
23
|
+
git diff origin/main..HEAD --stat
|
|
24
|
+
git log origin/main..HEAD --oneline
|
|
25
|
+
|
|
26
|
+
# Get review comments if any
|
|
27
|
+
br comments list $ARGUMENTS 2>/dev/null || echo "No bead"
|
|
28
|
+
|
|
29
|
+
# Get bead context if provided
|
|
30
|
+
br show $ARGUMENTS 2>/dev/null || echo "No bead specified"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Collect from all available sources:
|
|
34
|
+
|
|
35
|
+
- Git diff (what files changed, what patterns were used)
|
|
36
|
+
- Bead comments (review findings, decisions made)
|
|
37
|
+
- Current session context (what was discovered, what was hard)
|
|
38
|
+
- Any error messages that were solved
|
|
39
|
+
|
|
40
|
+
## Phase 2: Classify Learnings
|
|
41
|
+
|
|
42
|
+
For each finding, assign a type:
|
|
43
|
+
|
|
44
|
+
| Type | When to Use | Example |
|
|
45
|
+
| ----------- | ---------------------------------------------------------- | ----------------------------------------------- |
|
|
46
|
+
| `pattern` | A reusable approach confirmed to work in this codebase | "Always use X pattern for Y type of component" |
|
|
47
|
+
| `bugfix` | A non-obvious bug and its root cause | "Bun doesn't support X, use Y instead" |
|
|
48
|
+
| `decision` | An architectural or design choice with rationale | "Chose JWT over sessions because..." |
|
|
49
|
+
| `gotcha` | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
|
|
50
|
+
| `discovery` | A non-obvious fact about the codebase or its dependencies | "Build copies .opencode/ to dist/template/" |
|
|
51
|
+
| `warning` | Something that will break if not followed | "Always run lint:fix before commit" |
|
|
52
|
+
|
|
53
|
+
**Quality bar:** Only record learnings that would save future-you 15+ minutes.
|
|
54
|
+
Skip obvious things. Skip things already in AGENTS.md.
|
|
55
|
+
|
|
56
|
+
## Phase 3: Store Observations
|
|
57
|
+
|
|
58
|
+
For each learning worth keeping, create an observation:
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
observation({
|
|
62
|
+
type: "pattern", // or bugfix, decision, gotcha, discovery, warning
|
|
63
|
+
title: "[Concise, searchable title — what someone would search for]",
|
|
64
|
+
narrative: "[What happened, why it matters, how to apply it]",
|
|
65
|
+
facts: "[comma, separated, key, facts]",
|
|
66
|
+
concepts: "[searchable, keywords, for, future, retrieval]",
|
|
67
|
+
files_modified: "[relevant/file.ts if applicable]",
|
|
68
|
+
confidence: "high", // high=verified, medium=likely, low=speculative
|
|
69
|
+
});
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Minimum viable:** title + narrative. Everything else is bonus.
|
|
73
|
+
|
|
74
|
+
## Phase 4: Check AGENTS.md / Skill Updates
|
|
75
|
+
|
|
76
|
+
Ask: does this learning belong as a permanent rule?
|
|
77
|
+
|
|
78
|
+
If YES (it's a codebase-level constraint everyone must follow):
|
|
79
|
+
|
|
80
|
+
- Suggest updating `.opencode/memory/project/gotchas.md`
|
|
81
|
+
- Or the relevant skill file if it's procedure-level
|
|
82
|
+
|
|
83
|
+
If MAYBE (it's a pattern, not a rule):
|
|
84
|
+
|
|
85
|
+
- The observation is sufficient
|
|
86
|
+
- Don't pollute AGENTS.md with every finding
|
|
87
|
+
|
|
88
|
+
**Rule:** AGENTS.md changes require user confirmation. Observations are automatic.
|
|
89
|
+
|
|
90
|
+
## Phase 5: Search for Related Past Observations
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
// Check if this updates or supersedes an older observation
|
|
94
|
+
memory_search({ query: "[key concept from the finding]", limit: 3 });
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
If a newer finding contradicts or updates an older one, note it:
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
observation({
|
|
101
|
+
type: "decision",
|
|
102
|
+
title: "...",
|
|
103
|
+
narrative: "...",
|
|
104
|
+
supersedes: "42", // ID of the older observation
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Phase 6: Output Summary
|
|
109
|
+
|
|
110
|
+
Report what was codified:
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
## Compound Summary
|
|
114
|
+
|
|
115
|
+
**Work reviewed:** [brief description]
|
|
116
|
+
**Learnings captured:** [N] observations
|
|
117
|
+
|
|
118
|
+
| # | Type | Title | Concepts |
|
|
119
|
+
|---|-----------|------------------------------|------------------------|
|
|
120
|
+
| 1 | pattern | ... | auth, jwt |
|
|
121
|
+
| 2 | gotcha | ... | bun, build |
|
|
122
|
+
| 3 | bugfix | ... | typecheck, strict-mode |
|
|
123
|
+
|
|
124
|
+
**AGENTS.md updates suggested:** [yes/no - describe if yes]
|
|
125
|
+
**Next recommended:** /pr (or /plan <next-bead-id>)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## When Nothing to Compound
|
|
129
|
+
|
|
130
|
+
If the work was trivial (a config change, 1-line fix with no surprises):
|
|
131
|
+
|
|
132
|
+
> "Nothing worth compounding. Work was straightforward — no non-obvious patterns, bugs, or decisions encountered."
|
|
133
|
+
|
|
134
|
+
Don't force observations. Quality over quantity.
|
|
135
|
+
|
|
136
|
+
## Related Commands
|
|
137
|
+
|
|
138
|
+
| Need | Command |
|
|
139
|
+
| ---------------------- | --------- |
|
|
140
|
+
| Full chain | `/lfg` |
|
|
141
|
+
| Review before compound | `/review` |
|
|
142
|
+
| Ship the work | `/ship` |
|
|
143
|
+
| Create PR | `/pr` |
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Full autonomous chain - Plan → Ship → Review → Compound in one command
|
|
3
|
+
argument-hint: "<bead-id> [--skip-plan]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# LFG (Let's Fucking Go): $ARGUMENTS
|
|
7
|
+
|
|
8
|
+
Full compound engineering cycle. One command, all four steps.
|
|
9
|
+
|
|
10
|
+
> **When to use:** You have a bead in `in_progress` state with a PRD. You want maximum autonomous execution with minimum hand-holding.
|
|
11
|
+
>
|
|
12
|
+
> **Checkpoints happen** at decision points. Everything automatable is automated.
|
|
13
|
+
|
|
14
|
+
## Parse Arguments
|
|
15
|
+
|
|
16
|
+
| Argument | Default | Description |
|
|
17
|
+
| ------------- | -------- | --------------------------------------- |
|
|
18
|
+
| `<bead-id>` | required | The bead to execute |
|
|
19
|
+
| `--skip-plan` | false | Skip planning if plan.md already exists |
|
|
20
|
+
|
|
21
|
+
## Phase 0: Preflight
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
br show $BEAD_ID
|
|
25
|
+
ls .beads/artifacts/$BEAD_ID/
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Verify:
|
|
29
|
+
|
|
30
|
+
- Bead exists and is `in_progress`
|
|
31
|
+
- `prd.md` exists
|
|
32
|
+
- If `plan.md` exists and `--skip-plan` not set: ask user whether to replan or use existing
|
|
33
|
+
|
|
34
|
+
Report:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
## LFG: <bead-id> — <title>
|
|
38
|
+
|
|
39
|
+
Cycle: Plan → Ship → Review → Compound
|
|
40
|
+
Review mode: [Standard 3-agent / Deep 5-agent]
|
|
41
|
+
Plan: [create new / use existing]
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Step 1: PLAN
|
|
45
|
+
|
|
46
|
+
Load and execute the `/plan` command for this bead:
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
skill({ name: "writing-plans" });
|
|
50
|
+
// Run full /plan flow including Phase 0 institutional research
|
|
51
|
+
// Output: .beads/artifacts/$BEAD_ID/plan.md
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Checkpoint if plan has major unknowns or architecture questions. Otherwise proceed automatically.
|
|
55
|
+
|
|
56
|
+
## Step 2: WORK
|
|
57
|
+
|
|
58
|
+
Execute the plan:
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
skill({ name: "executing-plans" });
|
|
62
|
+
// Load plan.md, execute wave-by-wave
|
|
63
|
+
// Per-task commits after each task passes verification
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Run verification after each wave:
|
|
67
|
+
|
|
68
|
+
- `npm run typecheck`
|
|
69
|
+
- `npm run lint`
|
|
70
|
+
- `bun test` (if tests exist for changed areas)
|
|
71
|
+
|
|
72
|
+
Checkpoint only at `checkpoint:human-verify` or `checkpoint:decision` tasks.
|
|
73
|
+
|
|
74
|
+
## Step 3: REVIEW
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~$(git log --oneline | wc -l | tr -d ' '))
|
|
78
|
+
HEAD_SHA=$(git rev-parse HEAD)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Load and run the review skill:
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
skill({ name: "requesting-code-review" });
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Dispatch 5 specialized agents in parallel.
|
|
88
|
+
|
|
89
|
+
Wait for all agents to return. Synthesize findings.
|
|
90
|
+
|
|
91
|
+
**Auto-fix rule:**
|
|
92
|
+
|
|
93
|
+
- Critical issues → fix inline, re-verify, continue
|
|
94
|
+
- Important issues → fix inline, continue
|
|
95
|
+
- Minor issues → add to bead comments, continue
|
|
96
|
+
|
|
97
|
+
If Critical issues cannot be auto-fixed:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
## CHECKPOINT: Review Blocker
|
|
101
|
+
|
|
102
|
+
Critical issue found that requires architectural decision:
|
|
103
|
+
[description]
|
|
104
|
+
|
|
105
|
+
Options:
|
|
106
|
+
1. [option A]
|
|
107
|
+
2. [option B]
|
|
108
|
+
|
|
109
|
+
Awaiting your decision before continuing.
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Step 4: COMPOUND
|
|
113
|
+
|
|
114
|
+
Load and run the compound command:
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
// Run /compound $BEAD_ID
|
|
118
|
+
// Extract learnings from the full cycle
|
|
119
|
+
// Store observations to memory
|
|
120
|
+
// Suggest AGENTS.md updates if conventions changed
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Step 5: Report & Next
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
## LFG Complete: <bead-id>
|
|
127
|
+
|
|
128
|
+
### Cycle Summary
|
|
129
|
+
|
|
130
|
+
| Step | Status | Notes |
|
|
131
|
+
|----------|--------|------------------------------|
|
|
132
|
+
| Plan | ✓ | [N] waves, [M] tasks |
|
|
133
|
+
| Work | ✓ | [N] commits, [M] files |
|
|
134
|
+
| Review | ✓ | [N] agents, [M] fixes |
|
|
135
|
+
| Compound | ✓ | [N] observations stored |
|
|
136
|
+
|
|
137
|
+
### Learnings Captured
|
|
138
|
+
[list of observation titles]
|
|
139
|
+
|
|
140
|
+
### Verification
|
|
141
|
+
- typecheck: pass
|
|
142
|
+
- lint: pass
|
|
143
|
+
- tests: pass ([N] passing)
|
|
144
|
+
|
|
145
|
+
### Next Steps
|
|
146
|
+
- Review the changes: `git diff origin/main`
|
|
147
|
+
- Create PR: `/pr`
|
|
148
|
+
- Or continue with next bead: `/lfg <next-bead-id>`
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Swarm Mode (sLFG)
|
|
152
|
+
|
|
153
|
+
For large plans with 6+ independent tasks, run Work step in swarm mode:
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
skill({ name: "swarm-coordination" });
|
|
157
|
+
// Dispatch parallel worker agents per wave
|
|
158
|
+
// Leader monitors and synthesizes
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Use when: plan has 2+ independent waves with no shared file mutations.
|
|
162
|
+
|
|
163
|
+
## Related Commands
|
|
164
|
+
|
|
165
|
+
| Need | Command |
|
|
166
|
+
| --------------- | ---------------- |
|
|
167
|
+
| Plan only | `/plan <id>` |
|
|
168
|
+
| Ship only | `/ship <id>` |
|
|
169
|
+
| Review only | `/review` |
|
|
170
|
+
| Compound only | `/compound <id>` |
|
|
171
|
+
| Create PR after | `/pr` |
|
|
@@ -36,6 +36,63 @@ skill({ name: "writing-plans" }); // TDD plan format
|
|
|
36
36
|
- **Split signals**: Create child beads for complex work
|
|
37
37
|
- **Vertical slices**: Each task should cover one feature end-to-end
|
|
38
38
|
|
|
39
|
+
## Phase 0: Institutional Research (Mandatory)
|
|
40
|
+
|
|
41
|
+
Before touching the PRD or planning anything, load what the codebase already knows.
|
|
42
|
+
|
|
43
|
+
**This step is not optional.** Skipping it means planning in the dark.
|
|
44
|
+
|
|
45
|
+
### Step 1: Search institutional memory
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
// Search for past decisions, patterns, gotchas related to this work
|
|
49
|
+
memory_search({ query: "<bead-title or feature keywords>", limit: 5 });
|
|
50
|
+
memory_search({ query: "<key technical concept from bead>", type: "bugfix", limit: 3 });
|
|
51
|
+
memory_read({ file: "handoffs/last" }); // Check last session context
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
If relevant observations found: incorporate them directly into the plan. Don't re-solve solved problems.
|
|
55
|
+
|
|
56
|
+
### Step 2: Mine git history
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# What has changed recently in affected areas?
|
|
60
|
+
git log --oneline -20
|
|
61
|
+
|
|
62
|
+
# Who wrote the relevant code and when?
|
|
63
|
+
git log --oneline --follow -- <relevant-file-path>
|
|
64
|
+
|
|
65
|
+
# What patterns appear in recent commits?
|
|
66
|
+
git log --oneline --all | head -30
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Look for:
|
|
70
|
+
|
|
71
|
+
- Commit conventions (how this team names things)
|
|
72
|
+
- Recent changes to files you'll touch (merge conflict risk)
|
|
73
|
+
- How similar features were implemented before
|
|
74
|
+
- Any "fix:", "revert:", "hotfix:" commits near your scope (footgun zones)
|
|
75
|
+
|
|
76
|
+
### Step 3: Spawn learnings-researcher (if Level 2-3 work)
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
task({
|
|
80
|
+
subagent_type: "explore",
|
|
81
|
+
description: "Search codebase for patterns related to this work",
|
|
82
|
+
prompt: `Search the codebase for patterns, conventions, and existing implementations related to: [FEATURE].
|
|
83
|
+
|
|
84
|
+
Run these searches:
|
|
85
|
+
- grep for relevant function names and patterns
|
|
86
|
+
- Find similar existing features
|
|
87
|
+
- Check test patterns for this domain
|
|
88
|
+
- Look for any TODO/FIXME comments in relevant files
|
|
89
|
+
|
|
90
|
+
Return: existing patterns to follow, files to be aware of, and any gotchas.`,
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Only after completing Phase 0** do you proceed to planning. The research phases must use this context.
|
|
95
|
+
|
|
39
96
|
## Phase 1: Guards
|
|
40
97
|
|
|
41
98
|
```bash
|
|
@@ -58,6 +58,34 @@ ls .beads/artifacts/$ARGUMENTS/
|
|
|
58
58
|
|
|
59
59
|
Read the PRD to extract goal and success criteria for the PR description.
|
|
60
60
|
|
|
61
|
+
## Phase 2B: Pre-PR Review
|
|
62
|
+
|
|
63
|
+
This is the last gate before code hits GitHub. Run it every time.
|
|
64
|
+
|
|
65
|
+
Load the review skill:
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
skill({ name: "requesting-code-review" });
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Run **5 parallel agents**: security/correctness, performance/architecture, type-safety/tests, conventions/patterns, simplicity/completeness.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD origin/main)
|
|
75
|
+
HEAD_SHA=$(git rev-parse HEAD)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Fill placeholders:
|
|
79
|
+
|
|
80
|
+
- `{WHAT_WAS_IMPLEMENTED}`: what this PR delivers (from git log summary)
|
|
81
|
+
- `{PLAN_OR_REQUIREMENTS}`: PRD path or brief requirements
|
|
82
|
+
- `{BASE_SHA}` / `{HEAD_SHA}`: from above
|
|
83
|
+
|
|
84
|
+
**Gate rule:** All Critical issues must be resolved before pushing. No exceptions.
|
|
85
|
+
Important issues: fix or document as known limitation in PR body.
|
|
86
|
+
|
|
87
|
+
After fixing issues, re-run verification gates from Phase 1 if code was changed.
|
|
88
|
+
|
|
61
89
|
## Phase 3: Push and Confirm
|
|
62
90
|
|
|
63
91
|
Show what will be pushed and ask the user:
|
|
@@ -245,31 +245,36 @@ If any gate fails, fix before proceeding.
|
|
|
245
245
|
|
|
246
246
|
## Phase 6: Review
|
|
247
247
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
Spawn review agent to check changes against the PRD:
|
|
248
|
+
Load and run the review skill:
|
|
251
249
|
|
|
252
250
|
```typescript
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
description: "Review changes for $ARGUMENTS",
|
|
256
|
-
prompt: `Review changes for bead $ARGUMENTS.
|
|
257
|
-
|
|
258
|
-
Read PRD: .beads/artifacts/$ARGUMENTS/prd.md
|
|
259
|
-
Review: git diff HEAD
|
|
251
|
+
skill({ name: "requesting-code-review" });
|
|
252
|
+
```
|
|
260
253
|
|
|
261
|
-
|
|
262
|
-
1. Changes satisfy PRD success criteria
|
|
263
|
-
2. Correctness, edge cases, security
|
|
264
|
-
3. No scope creep beyond PRD files
|
|
254
|
+
Run **5 parallel agents**: security/correctness, performance/architecture, type-safety/tests, conventions/patterns, simplicity/completeness.
|
|
265
255
|
|
|
266
|
-
|
|
267
|
-
|
|
256
|
+
```bash
|
|
257
|
+
BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
|
|
258
|
+
HEAD_SHA=$(git rev-parse HEAD)
|
|
268
259
|
```
|
|
269
260
|
|
|
270
|
-
|
|
261
|
+
Fill placeholders:
|
|
262
|
+
|
|
263
|
+
- `{WHAT_WAS_IMPLEMENTED}`: bead title + brief summary of what changed
|
|
264
|
+
- `{PLAN_OR_REQUIREMENTS}`: `.beads/artifacts/$ARGUMENTS/prd.md`
|
|
265
|
+
- `{BASE_SHA}` / `{HEAD_SHA}`: from above
|
|
266
|
+
|
|
267
|
+
Wait for all 5 agents to return. Synthesize findings.
|
|
268
|
+
|
|
269
|
+
**Auto-fix rule:**
|
|
270
|
+
|
|
271
|
+
- Critical issues → fix inline, re-run Phase 5 gates, continue
|
|
272
|
+
- Important issues → fix inline, continue
|
|
273
|
+
- Minor issues → add to bead comments, note for `/compound` step
|
|
274
|
+
|
|
275
|
+
If review finds critical issues that require architectural decisions → stop → present options to user.
|
|
271
276
|
|
|
272
|
-
###
|
|
277
|
+
### Goal-Backward Verification (if plan.md exists)
|
|
273
278
|
|
|
274
279
|
Verify that tasks completed ≠ goals achieved:
|
|
275
280
|
|
|
@@ -328,7 +333,7 @@ br close $ARGUMENTS --reason "Shipped: all PRD tasks pass, verification + review
|
|
|
328
333
|
br sync --flush-only
|
|
329
334
|
```
|
|
330
335
|
|
|
331
|
-
Record significant learnings with `
|
|
336
|
+
Record significant learnings with `/compound $ARGUMENTS` after closing.
|
|
332
337
|
|
|
333
338
|
## Output
|
|
334
339
|
|
|
@@ -1,115 +1,202 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: requesting-code-review
|
|
3
|
-
description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches
|
|
3
|
+
description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches 5 parallel specialized review agents for comprehensive multi-angle review
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Requesting Code Review
|
|
7
7
|
|
|
8
|
-
Dispatch review
|
|
8
|
+
Dispatch 5 parallel specialized review agents. One generic reviewer is not review — it's a checkbox.
|
|
9
9
|
|
|
10
|
-
**Core principle:**
|
|
10
|
+
**Core principle:** All 5 angles, every time. No tiers, no exit ramps.
|
|
11
11
|
|
|
12
12
|
## When to Request Review
|
|
13
13
|
|
|
14
14
|
**Mandatory:**
|
|
15
15
|
|
|
16
|
-
- After
|
|
17
|
-
- After completing major feature
|
|
16
|
+
- After completing a feature / task batch before moving to next
|
|
18
17
|
- Before merge to main
|
|
19
18
|
|
|
20
|
-
**
|
|
19
|
+
**Not a review use case:**
|
|
21
20
|
|
|
22
|
-
- When stuck
|
|
23
|
-
-
|
|
24
|
-
- After fixing complex bug
|
|
21
|
+
- When stuck on an approach → ask one agent a specific question directly
|
|
22
|
+
- TDD RED commits (failing test commits are supposed to fail — don't review non-shippable state)
|
|
25
23
|
|
|
26
24
|
## How to Request
|
|
27
25
|
|
|
28
|
-
|
|
26
|
+
### Step 1: Get git context
|
|
29
27
|
|
|
30
28
|
```bash
|
|
31
|
-
BASE_SHA=$(git rev-parse HEAD~1)
|
|
29
|
+
BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
|
|
32
30
|
HEAD_SHA=$(git rev-parse HEAD)
|
|
33
31
|
```
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
### Step 2: Dispatch all 5 agents in parallel
|
|
36
34
|
|
|
37
|
-
|
|
35
|
+
No tiering. 5 agents always. They run simultaneously — wall-clock cost is the same as 1.
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
```typescript
|
|
38
|
+
task({
|
|
39
|
+
subagent_type: "review",
|
|
40
|
+
description: "Security + correctness review",
|
|
41
|
+
prompt: `Review this implementation for security vulnerabilities and correctness issues.
|
|
40
42
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
- `{BASE_SHA}` - Starting commit
|
|
44
|
-
- `{HEAD_SHA}` - Ending commit
|
|
45
|
-
- `{DESCRIPTION}` - Brief summary
|
|
43
|
+
What was implemented: {WHAT_WAS_IMPLEMENTED}
|
|
44
|
+
Requirements: {PLAN_OR_REQUIREMENTS}
|
|
46
45
|
|
|
47
|
-
|
|
46
|
+
Run:
|
|
47
|
+
git diff {BASE_SHA}..{HEAD_SHA}
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
49
|
+
Check for:
|
|
50
|
+
- Security vulnerabilities (injection, auth bypass, secrets exposure, input validation)
|
|
51
|
+
- Logic errors, off-by-one, null/undefined access
|
|
52
|
+
- Missing error handling on async operations
|
|
53
|
+
- Data integrity issues
|
|
53
54
|
|
|
54
|
-
|
|
55
|
+
Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
|
|
56
|
+
});
|
|
55
57
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
+
task({
|
|
59
|
+
subagent_type: "review",
|
|
60
|
+
description: "Performance + architecture review",
|
|
61
|
+
prompt: `Review this implementation for performance and architectural concerns.
|
|
58
62
|
|
|
59
|
-
|
|
63
|
+
What was implemented: {WHAT_WAS_IMPLEMENTED}
|
|
60
64
|
|
|
61
|
-
|
|
62
|
-
|
|
65
|
+
Run:
|
|
66
|
+
git diff {BASE_SHA}..{HEAD_SHA}
|
|
67
|
+
|
|
68
|
+
Check for:
|
|
69
|
+
- N+1 queries, unnecessary loops, missing indexes
|
|
70
|
+
- Over-engineering (abstraction not earned by use cases)
|
|
71
|
+
- Coupling that will make future changes painful
|
|
72
|
+
- Missing caching where obviously needed
|
|
73
|
+
- Bundle size regressions (if frontend)
|
|
74
|
+
|
|
75
|
+
Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
task({
|
|
79
|
+
subagent_type: "review",
|
|
80
|
+
description: "Type safety + test coverage review",
|
|
81
|
+
prompt: `Review this implementation for type safety and test quality.
|
|
82
|
+
|
|
83
|
+
What was implemented: {WHAT_WAS_IMPLEMENTED}
|
|
84
|
+
|
|
85
|
+
Run:
|
|
86
|
+
git diff {BASE_SHA}..{HEAD_SHA}
|
|
87
|
+
|
|
88
|
+
Check for:
|
|
89
|
+
- Type safety holes (any casts, unsafe assertions, missing generics)
|
|
90
|
+
- Tests that only test mocks instead of real behavior
|
|
91
|
+
- Missing edge case tests (null, empty, boundary values)
|
|
92
|
+
- Tests that would pass even if the implementation was wrong
|
|
93
|
+
- Coverage gaps on critical paths
|
|
94
|
+
|
|
95
|
+
Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
task({
|
|
99
|
+
subagent_type: "review",
|
|
100
|
+
description: "Conventions + patterns review",
|
|
101
|
+
prompt: `Review this implementation against codebase conventions.
|
|
102
|
+
|
|
103
|
+
What was implemented: {WHAT_WAS_IMPLEMENTED}
|
|
104
|
+
|
|
105
|
+
Run:
|
|
106
|
+
git diff {BASE_SHA}..{HEAD_SHA}
|
|
107
|
+
git log --oneline -10
|
|
108
|
+
|
|
109
|
+
Check for:
|
|
110
|
+
- Inconsistent naming vs rest of codebase
|
|
111
|
+
- Patterns that diverge from established codebase patterns
|
|
112
|
+
- Missing or wrong use of shared utilities already in the codebase
|
|
113
|
+
- File organization that doesn't match project structure
|
|
114
|
+
- Documentation drift (code does X, docs say Y)
|
|
115
|
+
|
|
116
|
+
Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
task({
|
|
120
|
+
subagent_type: "review",
|
|
121
|
+
description: "Simplicity + completeness review",
|
|
122
|
+
prompt: `Review this implementation for simplicity and completeness.
|
|
63
123
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
HEAD_SHA
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
You: [Fix progress indicators]
|
|
79
|
-
[Continue to Task 3]
|
|
124
|
+
What was implemented: {WHAT_WAS_IMPLEMENTED}
|
|
125
|
+
Requirements: {PLAN_OR_REQUIREMENTS}
|
|
126
|
+
|
|
127
|
+
Run:
|
|
128
|
+
git diff {BASE_SHA}..{HEAD_SHA}
|
|
129
|
+
|
|
130
|
+
Check for:
|
|
131
|
+
- Dead code (unreachable branches, unused variables, commented-out code)
|
|
132
|
+
- Requirements that were specified but not implemented
|
|
133
|
+
- Complexity that could be deleted without losing value
|
|
134
|
+
- TODOs left in production code paths
|
|
135
|
+
|
|
136
|
+
Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
|
|
137
|
+
});
|
|
80
138
|
```
|
|
81
139
|
|
|
82
|
-
|
|
140
|
+
### Step 3: Synthesize findings
|
|
83
141
|
|
|
84
|
-
|
|
142
|
+
After all 5 agents return:
|
|
85
143
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- Fix before moving to next task
|
|
144
|
+
```markdown
|
|
145
|
+
## Review Summary
|
|
89
146
|
|
|
90
|
-
**
|
|
147
|
+
**Agents run:** 5
|
|
148
|
+
**Critical:** [N] — BLOCK, fix before proceeding
|
|
149
|
+
**Important:** [N] — Fix in this PR
|
|
150
|
+
**Minor:** [N] — Track as improvements
|
|
91
151
|
|
|
92
|
-
|
|
93
|
-
- Get feedback, apply, continue
|
|
152
|
+
### Critical Issues
|
|
94
153
|
|
|
95
|
-
|
|
154
|
+
[List with file:line, description, suggested fix]
|
|
96
155
|
|
|
97
|
-
|
|
98
|
-
|
|
156
|
+
### Important Issues
|
|
157
|
+
|
|
158
|
+
[List with file:line, description]
|
|
159
|
+
|
|
160
|
+
### Assessment
|
|
161
|
+
|
|
162
|
+
[ ] Ready to proceed [ ] Fix required first
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Step 4: Act on findings
|
|
166
|
+
|
|
167
|
+
| Severity | Action |
|
|
168
|
+
| ------------- | ---------------------------------------- |
|
|
169
|
+
| **Critical** | Fix immediately before any other work |
|
|
170
|
+
| **Important** | Fix in this PR before merge |
|
|
171
|
+
| **Minor** | Note in bead comments, fix later or skip |
|
|
172
|
+
|
|
173
|
+
Push back if reviewer is wrong — show code/tests that prove it works.
|
|
174
|
+
|
|
175
|
+
## Placeholders Reference
|
|
176
|
+
|
|
177
|
+
| Placeholder | What to fill |
|
|
178
|
+
| ------------------------ | --------------------------------------- |
|
|
179
|
+
| `{WHAT_WAS_IMPLEMENTED}` | Brief description of the feature/fix |
|
|
180
|
+
| `{PLAN_OR_REQUIREMENTS}` | Link to plan.md or requirements summary |
|
|
181
|
+
| `{BASE_SHA}` | Starting commit SHA |
|
|
182
|
+
| `{HEAD_SHA}` | Ending commit SHA |
|
|
183
|
+
|
|
184
|
+
## Integration with Workflows
|
|
99
185
|
|
|
100
|
-
|
|
186
|
+
| Command | When review runs |
|
|
187
|
+
| ------- | ------------------------------------- |
|
|
188
|
+
| `/ship` | After all tasks complete + gates pass |
|
|
189
|
+
| `/pr` | Mandatory gate before push to GitHub |
|
|
190
|
+
| `/lfg` | Between work and compound steps |
|
|
101
191
|
|
|
102
|
-
|
|
192
|
+
All Critical issues must be resolved before proceeding. No exceptions.
|
|
103
193
|
|
|
104
|
-
|
|
105
|
-
- Ignore Critical issues
|
|
106
|
-
- Proceed with unfixed Important issues
|
|
107
|
-
- Argue with valid technical feedback
|
|
194
|
+
## After Review: Compound
|
|
108
195
|
|
|
109
|
-
|
|
196
|
+
Run `/compound` after fixing review findings to capture:
|
|
110
197
|
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
198
|
+
- What the review caught (patterns to watch for)
|
|
199
|
+
- What false positives were dismissed (and why)
|
|
200
|
+
- Any codebase conventions discovered during review
|
|
114
201
|
|
|
115
|
-
|
|
202
|
+
This is how the review step feeds the compound flywheel.
|
package/package.json
CHANGED