Merge upstream origin/main with local fork additions preserved
Accept upstream's ce-review pipeline rewrite (6-stage persona-based architecture with structured JSON, confidence gating, three execution modes). Retire 4 overlapping review agents (security-sentinel, performance-oracle, data-migration-expert, data-integrity-guardian) replaced by upstream equivalents. Add 5 local review agents as conditional personas in the persona catalog (kieran-python, tiangolo- fastapi, kieran-typescript, julik-frontend-races, architecture- strategist). Accept upstream skill renames (file-todos→todo-create, resolve_todo_ parallel→todo-resolve), port local Assessment and worktree constraint additions to new files. Merge best-practices-researcher with upstream platform-agnostic discovery + local FastAPI mappings. Remove Rails/Ruby skills (dhh-rails-style, andrew-kane-gem-writer, dspy-ruby) per fork's FastAPI pivot. Component counts: 36 agents, 48 skills, 7 commands. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
John Lamb
154
plugins/compound-engineering/commands/essay-edit.md
Normal file
154
plugins/compound-engineering/commands/essay-edit.md
Normal file
@@ -0,0 +1,154 @@
|
||||
---
|
||||
name: essay-edit
|
||||
description: Expert essay editor that polishes written work through granular line-level editing and structural review. Preserves the author's voice and intent — never softens or genericizes. Pairs with /essay-outline.
|
||||
argument-hint: "[path to essay file, or paste the essay]"
|
||||
---
|
||||
|
||||
# Essay Edit
|
||||
|
||||
Polish a written essay through two passes: structural integrity first, then line-level craft. This command produces a fully edited version of the essay — not a list of suggestions.
|
||||
|
||||
## Input
|
||||
|
||||
<essay_input> #$ARGUMENTS </essay_input>
|
||||
|
||||
**If the input above is empty or unclear**, ask: "Paste the essay or give me the file path."
|
||||
|
||||
If a file path is provided, read the file. Do not proceed until the essay is in context.
|
||||
|
||||
## The Editor's Creed
|
||||
|
||||
Before editing anything, internalize this:
|
||||
|
||||
**Do not be a timid scribe.**
|
||||
|
||||
A timid scribe softens language it doesn't fully understand. It rewrites the original to be cleaner according to *its own reading* — and in doing so, drains out the author's intent, edge, and specificity.
|
||||
|
||||
Examples of timid scribe behavior:
|
||||
- "Most Every subscribers don't know what they're paying for." → "Most Every subscribers may not be fully aware of what they're paying for." ✗
|
||||
- "The city ate itself." → "The city underwent significant change." ✗
|
||||
- "He was wrong about everything." → "His perspective had some notable limitations." ✗
|
||||
|
||||
The test: if the original line had teeth, the edited line must also have teeth. If the original was specific and concrete, the edited line must remain specific and concrete. Clarity is not the same as softness. Directness is not the same as aggression. Polish the language without defanging it.
|
||||
|
||||
## Phase 1: Voice Calibration
|
||||
|
||||
Load the `john-voice` skill. Read `references/core-voice.md` and `references/prose-essays.md` to calibrate the author's voice before touching a single word.
|
||||
|
||||
Note the following from the voice profile before proceeding:
|
||||
- What is the tone register of this essay? (conversational-to-deliberate ratio)
|
||||
- What is the characteristic sentence rhythm?
|
||||
- Where does the author use humor or lightness?
|
||||
- What transition devices are in play?
|
||||
|
||||
This calibration is not optional. Edits that violate the author's established voice must be rejected.
|
||||
|
||||
## Phase 2: Structural Review
|
||||
|
||||
Load the `story-lens` skill. Apply the Saunders diagnostic framework to the essay as a whole. The essay is not a story with characters — translate the framework accordingly:
|
||||
|
||||
| Saunders diagnostic | Applied to the essay |
|
||||
|---|---|
|
||||
| Beat causality | Does each paragraph cause the reader to need the next? Or do they merely follow one another? |
|
||||
| Escalation | Does the argument move up a staircase? Does each paragraph make the thesis harder to dismiss or the reader's understanding more complete? |
|
||||
| Story-yet test | If the essay ended after the introduction, would anything have changed for the reader? After each major section? |
|
||||
| Efficiency | Is every paragraph doing work? Does every sentence within each paragraph do work? Cut anything that elaborates without advancing. |
|
||||
| Expectation | Does each section land at the right level — surprising enough to be interesting, but not so left-field it loses the reader? |
|
||||
| Moral/technical unity | If something feels off — a paragraph that doesn't land, a conclusion that feels unearned — find the structural failure underneath. |
|
||||
|
||||
**Thesis check:**
|
||||
- Is there a real thesis — a specific, arguable claim — or just a topic?
|
||||
- Is the thesis earned by the conclusion, or does the conclusion simply restate what was already established?
|
||||
- Does the opening create a specific expectation that the essay fulfills or productively subverts?
|
||||
|
||||
**Paragraph audit:**
|
||||
For each paragraph, ask: does this paragraph earn its place? Identify any paragraph that:
|
||||
- Repeats what a prior paragraph already established
|
||||
- Merely elaborates without advancing the argument
|
||||
- Exists only for transition rather than substance
|
||||
|
||||
Flag structural weaknesses. Propose specific fixes. If a section must be cut entirely, say so and explain why.
|
||||
|
||||
## Phase 3: Bulletproof Audit
|
||||
|
||||
Before touching a single sentence, audit the essay's claims. The goal: every word, every phrase, and every assertion must be able to withstand a hostile, smart reader drilling into it. If you pull on a thread and the piece crumbles, the edit isn't done.
|
||||
|
||||
**What bulletproof means:**
|
||||
Each claim is underpinned by logic that holds when examined. Not language that *sounds* confident — logic that *is* sound. GenAI-generated and VC-written prose fails this test constantly: it uses terms like "value," "conviction," and "impact" as load-bearing words that carry no actual weight. Strip those away and nothing remains.
|
||||
|
||||
**The audit process — work through every claim:**
|
||||
|
||||
1. **Identify the assertion.** What is actually being claimed in this sentence or paragraph?
|
||||
2. **Apply adversarial pressure.** A skeptical reader asks: "How do you know? What's the evidence? What's the mechanism?" Can the essay answer those questions — either explicitly or by implication?
|
||||
3. **Test jargon.** Replace every abstract term ("value," "alignment," "transformation," "ecosystem," "leverage") with its literal meaning. If the sentence falls apart, the jargon was hiding a hole.
|
||||
4. **Test causality.** For every "X leads to Y" or "because of X, Y" — is the mechanism explained? Or is the causal claim assumed?
|
||||
5. **Test specificity.** Vague praise ("a powerful insight," "a fundamental shift") signals the author hasn't committed to the claim. Make it specific or cut it.
|
||||
|
||||
**Flag and fix:**
|
||||
- Mark every claim that fails the audit with a `[HOLE]` comment inline.
|
||||
- For each hole, either: (a) rewrite the claim to be defensible, (b) add the missing logic or evidence, or (c) cut the claim if it cannot be rescued.
|
||||
- Do not polish language over a logical hole. A well-written unsupported claim is worse than a clumsy honest one — it's harder to catch.
|
||||
|
||||
**The test:** After the audit, could a hostile reader pick the piece apart? If yes, the audit isn't done. Return to step 1.
|
||||
|
||||
## Phase 4: Line-Level Edit
|
||||
|
||||
Now edit the prose itself. Work sentence by sentence through the full essay.
|
||||
|
||||
**Word choice:**
|
||||
- Replace vague words with specific ones
|
||||
- Flag hedging language that weakens claims without adding nuance: "somewhat", "rather", "may", "might", "could potentially", "in some ways", "it is possible that"
|
||||
- Remove filler: "very", "really", "quite", "just", "a bit", "a little"
|
||||
- Replace abstract nouns with concrete ones where possible
|
||||
|
||||
**Grammar and mechanics:**
|
||||
- Fix subject-verb agreement, tense consistency, pronoun clarity
|
||||
- Break up sentence structures that obscure meaning
|
||||
- Eliminate passive voice where active voice is stronger — but don't apply this mechanically; passive is sometimes the right choice
|
||||
|
||||
**Sentence rhythm:**
|
||||
- Vary sentence length. Short sentences create punch. Long sentences build momentum.
|
||||
- Identify any runs of similarly-structured sentences and break the pattern
|
||||
- Ensure each paragraph opens with energy and closes with either a landing or a pull forward
|
||||
|
||||
**The kinetic test:**
|
||||
After editing each paragraph, ask: does this paragraph move? Does the last sentence create a small pull toward the next paragraph? If the prose feels like it's trudging, rewrite until it has momentum.
|
||||
|
||||
**Voice preservation:**
|
||||
At every step, check edits against the voice calibration from Phase 1. If an edit makes the prose cleaner but less recognizably *the author's*, revert it. The author's voice is not a bug to be fixed. It is the product.
|
||||
|
||||
## Phase 5: Produce the Edited Essay
|
||||
|
||||
Write the fully edited essay. Not a marked-up draft. Not a list of suggestions. The complete, polished piece.
|
||||
|
||||
**Output the edited essay to file:**
|
||||
|
||||
```
|
||||
docs/essays/YYYY-MM-DD-[slug]-edited.md
|
||||
```
|
||||
|
||||
Ensure `docs/essays/` exists before writing. The slug should be 3-5 words from the title or thesis, hyphenated.
|
||||
|
||||
If the original was from a file, note the original path.
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
```
|
||||
Edit complete.
|
||||
|
||||
File: docs/essays/YYYY-MM-DD-[slug]-edited.md
|
||||
|
||||
Structural changes:
|
||||
- [List any paragraphs reordered, cut, or significantly restructured]
|
||||
|
||||
Line-level changes:
|
||||
- [2-3 notable word/sentence-level decisions and why]
|
||||
|
||||
Voice check: [passed / adjusted — note any close calls]
|
||||
|
||||
Story verdict: [passes Saunders framework / key structural fix applied]
|
||||
|
||||
Bulletproof audit: [X holes found and fixed / all claims defensible — note any significant repairs]
|
||||
```
|
||||
114
plugins/compound-engineering/commands/essay-outline.md
Normal file
114
plugins/compound-engineering/commands/essay-outline.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: essay-outline
|
||||
description: Transform a brain dump into a story-structured essay outline. Pressure tests the idea, validates story structure using the Saunders framework, and produces a tight outline written to file.
|
||||
argument-hint: "[brain dump — your raw ideas, however loose]"
|
||||
---
|
||||
|
||||
# Essay Outline
|
||||
|
||||
Turn a brain dump into a story-structured essay outline.
|
||||
|
||||
## Brain Dump
|
||||
|
||||
<brain_dump> #$ARGUMENTS </brain_dump>
|
||||
|
||||
**If the brain dump above is empty, ask the user:** "What's the idea? Paste your brain dump — however raw or loose."
|
||||
|
||||
Do not proceed until you have a brain dump.
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Idea Triage
|
||||
|
||||
Read the brain dump and locate the potential thesis — the single thing worth saying. Ask: would a smart, skeptical reader finish this essay and think "I needed that"?
|
||||
|
||||
Play devil's advocate. This is the primary job. The standard is **bulletproof writing**: every word, every phrase, and every claim in the outline must be underpinned by logic that holds when examined. If a smart, hostile reader drills into any part of the outline and it crumbles, it hasn't earned a draft.
|
||||
|
||||
This is not a high bar — it is the minimum bar. Most writing fails it. The profligate use of terms like "value," "conviction," "impact," and "transformation" is the tell. Strip away the jargon and if nothing remains, the idea isn't real yet.
|
||||
|
||||
Look for:
|
||||
|
||||
- **Weak thesis** — Is this a real insight, or just a topic? A topic is not a thesis. "Remote work is complicated" is a topic. "Remote work didn't fail the office — the office failed remote work" is a thesis. A thesis is specific, arguable, and survives a skeptic asking "how do you know?"
|
||||
- **Jargon standing in for substance** — Replace every abstract term in the brain dump with its literal meaning. If the idea collapses without the jargon, the jargon was hiding a hole, not filling one. Flag it.
|
||||
- **Missing payoff** — What does the reader walk away with that they didn't have before? If there's no answer, say so.
|
||||
- **Broken connective tissue** — Do the ideas connect causally ("and therefore") or just sequentially ("and another thing")? Sequential ideas are a list, not an essay.
|
||||
- **Unsupported claims** — Use outside research to pressure-test assertions. For any causal claim ("X leads to Y"), ask: what is the mechanism? If the mechanism isn't in the brain dump and can't be reasoned to, flag it as a hole the draft will need to fill.
|
||||
|
||||
**If nothing survives triage:** Say directly — "There's nothing here yet." Then ask one question aimed at finding a salvageable core. Do not produce an outline for an idea that hasn't earned one.
|
||||
|
||||
**If the idea survives but has weaknesses:** Identify the weakest link and collaboratively generate a fix before moving to Phase 2.
|
||||
|
||||
### Phase 2: Story Structure Check
|
||||
|
||||
Load the `story-lens` skill. Apply the Saunders framework to the *idea* — not prose. The essay may not involve characters. That's fine. Translate the framework as follows:
|
||||
|
||||
| Saunders diagnostic | Applied to essay ideas |
|
||||
|---|---|
|
||||
| Beat causality | Does each supporting point *cause* the reader to need the next one, or do they merely follow it? |
|
||||
| Escalation | Does each beat raise the stakes of the thesis — moving the reader further from where they started? |
|
||||
| Story-yet test | If the essay ended after the hook, would anything have changed for the reader? After the first supporting point? Each beat must earn its place. |
|
||||
| Efficiency | Is every idea doing work? Cut anything that elaborates without advancing. |
|
||||
| Expectation | Does each beat land at the right level — surprising but not absurd, inevitable in hindsight? |
|
||||
| Moral/technical unity | If something feels off — a point that doesn't land, a conclusion that feels unearned — find the structural failure underneath. |
|
||||
|
||||
**The non-negotiables:**
|
||||
- The hook must create a specific expectation that the essay then fulfills or subverts
|
||||
- Supporting beats must escalate — each one should make the thesis harder to dismiss, not just add to it
|
||||
- The conclusion must deliver irreversible change in the reader's understanding — they cannot un-think what the essay showed them
|
||||
|
||||
Flag any diagnostic failures. For each failure, propose a fix. If the structure cannot be made to escalate, say so.
|
||||
|
||||
### Phase 3: Outline Construction
|
||||
|
||||
Produce the outline only after the idea has survived Phases 1 and 2.
|
||||
|
||||
**Structure:**
|
||||
- Hook — the opening move that sets an expectation
|
||||
- Supporting beats — each one causal, each one escalating
|
||||
- Conclusion — the irreversible change delivered to the reader
|
||||
|
||||
**Format rules:**
|
||||
- Bullets and sub-bullets only
|
||||
- Max 3 sub-bullets per bullet
|
||||
- No sub-sub-bullets
|
||||
- Each bullet is a *beat*, not a topic — it should imply forward motion
|
||||
- Keep it short. A good outline is a skeleton, not a draft.
|
||||
|
||||
**Bulletproof beat check — the enemy is vagueness, not argument:**
|
||||
|
||||
Bulletproof does not mean every beat must be a logical proposition. A narrative beat that creates tension, shifts the emotional register, or lands a specific image is bulletproof. What isn't bulletproof is jargon and abstraction standing in for a real idea.
|
||||
|
||||
Ask of each beat: *if someone drilled into this, is there something concrete underneath — or is it fog?*
|
||||
|
||||
- "The moment the company realized growth was masking dysfunction" → specific, defensible, narratively useful ✓
|
||||
- "Explores the tension between innovation and tradition" → fog machine — rewrite to say what actually happens ✗
|
||||
- "Value creation requires conviction" → jargon with nothing underneath — either make it concrete or cut it ✗
|
||||
|
||||
A beat that escalates tension, shifts the reader's understanding, or earns the next beat is doing its job — even if it doesn't make an explicit argument. The test is specificity, not defensibility. Can you say what this beat *does* without retreating to abstraction? If yes, it's bulletproof.
|
||||
|
||||
**Write the outline to file:**
|
||||
|
||||
```
|
||||
docs/outlines/YYYY-MM-DD-[slug].md
|
||||
```
|
||||
|
||||
Ensure `docs/outlines/` exists before writing. The slug should be 3-5 words derived from the thesis, hyphenated.
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
```
|
||||
Outline complete.
|
||||
|
||||
File: docs/outlines/YYYY-MM-DD-[slug].md
|
||||
|
||||
Thesis: [one sentence]
|
||||
Story verdict: [passes / passes with fixes / nothing here]
|
||||
Bulletproof check: [all beats concrete and specific / X beats rewritten or cut]
|
||||
|
||||
Key structural moves:
|
||||
- [Hook strategy]
|
||||
- [How the beats escalate]
|
||||
- [What the conclusion delivers]
|
||||
```
|
||||
334
plugins/compound-engineering/commands/pr-comments-to-todos.md
Normal file
334
plugins/compound-engineering/commands/pr-comments-to-todos.md
Normal file
@@ -0,0 +1,334 @@
|
||||
---
|
||||
name: pr-comments-to-todos
|
||||
description: Fetch PR comments and convert them into todo files for triage
|
||||
argument-hint: "[PR number, GitHub URL, or 'current' for current branch PR]"
|
||||
---
|
||||
|
||||
# PR Comments to Todos
|
||||
|
||||
Convert GitHub PR review comments into structured todo files compatible with `/triage`.
|
||||
|
||||
<command_purpose>Fetch all review comments from a PR and create individual todo files in the `todos/` directory, following the file-todos skill format.</command_purpose>
|
||||
|
||||
## Review Target
|
||||
|
||||
<review_target> #$ARGUMENTS </review_target>
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Identify PR and Fetch Comments
|
||||
|
||||
<task_list>
|
||||
|
||||
- [ ] Determine the PR to process:
|
||||
- If numeric: use as PR number directly
|
||||
- If GitHub URL: extract PR number from URL
|
||||
- If "current" or empty: detect from current branch with `gh pr status`
|
||||
- [ ] Fetch PR metadata: `gh pr view PR_NUMBER --json title,body,url,author,headRefName`
|
||||
- [ ] Fetch all review comments: `gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments`
|
||||
- [ ] Fetch review thread comments: `gh pr view PR_NUMBER --json reviews,reviewDecision`
|
||||
- [ ] Group comments by file/thread for context
|
||||
|
||||
</task_list>
|
||||
|
||||
### 2. Pressure Test Each Comment
|
||||
|
||||
<critical_evaluation>
|
||||
|
||||
**IMPORTANT: Treat reviewer comments as suggestions, not orders.**
|
||||
|
||||
Before creating a todo, apply engineering judgment to each comment. Not all feedback is equally valid - your job is to make the right call for the codebase, not just please the reviewer.
|
||||
|
||||
#### Step 2a: Verify Before Accepting
|
||||
|
||||
For each comment, verify:
|
||||
- [ ] **Check the code**: Does the concern actually apply to this code?
|
||||
- [ ] **Check tests**: Are there existing tests that cover this case?
|
||||
- [ ] **Check usage**: How is this code actually used? Does the concern matter in practice?
|
||||
- [ ] **Check compatibility**: Would the suggested change break anything?
|
||||
- [ ] **Check prior decisions**: Was this intentional? Is there a reason it's done this way?
|
||||
|
||||
#### Step 2b: Assess Each Comment
|
||||
|
||||
Assign an assessment to each comment:
|
||||
|
||||
| Assessment | Meaning |
|
||||
|------------|---------|
|
||||
| **Clear & Correct** | Valid concern, well-reasoned, applies to this code |
|
||||
| **Unclear** | Ambiguous, missing context, or doesn't specify what to change |
|
||||
| **Likely Incorrect** | Misunderstands the code, context, or requirements |
|
||||
| **YAGNI** | Over-engineering, premature abstraction, no clear benefit |
|
||||
|
||||
#### Step 2c: Include Assessment in Todo
|
||||
|
||||
**IMPORTANT: ALL comments become todos.** Never drop feedback - include the pressure test assessment IN the todo so `/triage` can use it to decide.
|
||||
|
||||
For each comment, the todo will include:
|
||||
- The assessment (Clear & Correct / Unclear / Likely Incorrect / YAGNI)
|
||||
- The verification results (what was checked)
|
||||
- Technical justification (why valid, or why you think it should be skipped)
|
||||
- Recommended action for triage (Fix now / Clarify / Push back / Skip)
|
||||
|
||||
The human reviews during `/triage` and makes the final call.
|
||||
|
||||
</critical_evaluation>
|
||||
|
||||
### 3. Categorize All Comments
|
||||
|
||||
<categorization>
|
||||
|
||||
For ALL comments (regardless of assessment), determine:
|
||||
|
||||
**Severity (Priority):**
|
||||
- 🔴 **P1 (Critical)**: Security issues, data loss risks, breaking changes, blocking bugs
|
||||
- 🟡 **P2 (Important)**: Performance issues, architectural concerns, significant code quality
|
||||
- 🔵 **P3 (Nice-to-have)**: Style suggestions, minor improvements, documentation
|
||||
|
||||
**Category Tags:**
|
||||
- `security` - Security vulnerabilities or concerns
|
||||
- `performance` - Performance issues or optimizations
|
||||
- `architecture` - Design or structural concerns
|
||||
- `bug` - Functional bugs or edge cases
|
||||
- `quality` - Code quality, readability, maintainability
|
||||
- `testing` - Test coverage or test quality
|
||||
- `documentation` - Missing or unclear documentation
|
||||
- `style` - Code style or formatting
|
||||
- `needs-clarification` - Comment requires clarification before implementing
|
||||
- `pushback-candidate` - Human should review before accepting
|
||||
|
||||
**Skip these (don't create todos):**
|
||||
- Simple acknowledgments ("LGTM", "Looks good")
|
||||
- Questions that were answered inline
|
||||
- Already resolved threads
|
||||
|
||||
**Note:** Comments assessed as YAGNI or Likely Incorrect still become todos with that assessment included. The human decides during `/triage` whether to accept or reject.
|
||||
|
||||
</categorization>
|
||||
|
||||
### 4. Create Todo Files Using file-todos Skill
|
||||
|
||||
<critical_instruction>Create todo files for ALL actionable comments immediately. Use the file-todos skill structure and naming convention.</critical_instruction>
|
||||
|
||||
#### Determine Next Issue ID
|
||||
|
||||
```bash
|
||||
# Find the highest existing issue ID
|
||||
ls todos/ 2>/dev/null | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'
|
||||
# If no todos exist, start with 001
|
||||
```
|
||||
|
||||
#### File Naming Convention
|
||||
|
||||
```
|
||||
{issue_id}-pending-{priority}-{brief-description}.md
|
||||
```
|
||||
|
||||
Examples:
|
||||
```
|
||||
001-pending-p1-sql-injection-vulnerability.md
|
||||
002-pending-p2-missing-error-handling.md
|
||||
003-pending-p3-rename-variable-for-clarity.md
|
||||
```
|
||||
|
||||
#### Todo File Structure
|
||||
|
||||
For each comment, create a file with this structure:
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: pending
|
||||
priority: p1 # or p2, p3 based on severity
|
||||
issue_id: "001"
|
||||
tags: [code-review, pr-feedback, {category}]
|
||||
dependencies: []
|
||||
---
|
||||
```
|
||||
|
||||
```markdown
|
||||
# [Brief Title from Comment]
|
||||
|
||||
## Problem Statement
|
||||
|
||||
[Summarize the reviewer's concern - what is wrong or needs improvement]
|
||||
|
||||
**PR Context:**
|
||||
- PR: #{PR_NUMBER} - {PR_TITLE}
|
||||
- File: {file_path}:{line_number}
|
||||
- Reviewer: @{reviewer_username}
|
||||
|
||||
## Assessment (Pressure Test)
|
||||
|
||||
| Criterion | Result |
|
||||
|-----------|--------|
|
||||
| **Assessment** | Clear & Correct / Unclear / Likely Incorrect / YAGNI |
|
||||
| **Recommended Action** | Fix now / Clarify / Push back / Skip |
|
||||
| **Verified Code?** | Yes/No - [what was checked] |
|
||||
| **Verified Tests?** | Yes/No - [existing coverage] |
|
||||
| **Verified Usage?** | Yes/No - [how code is used] |
|
||||
| **Prior Decisions?** | Yes/No - [any intentional design] |
|
||||
|
||||
**Technical Justification:**
|
||||
[If pushing back or marking YAGNI, provide specific technical reasoning. Reference codebase constraints, requirements, or trade-offs. Example: "This abstraction would be YAGNI - we only have one implementation and no plans for variants."]
|
||||
|
||||
## Findings
|
||||
|
||||
- **Original Comment:** "{exact reviewer comment}"
|
||||
- **Location:** `{file_path}:{line_number}`
|
||||
- **Code Context:**
|
||||
```{language}
|
||||
{relevant code snippet}
|
||||
```
|
||||
- **Why This Matters:** [Impact if not addressed, or why it doesn't matter]
|
||||
|
||||
## Proposed Solutions
|
||||
|
||||
### Option 1: [Primary approach based on reviewer suggestion]
|
||||
|
||||
**Approach:** [Describe the fix]
|
||||
|
||||
**Pros:**
|
||||
- Addresses reviewer concern directly
|
||||
- [Other benefits]
|
||||
|
||||
**Cons:**
|
||||
- [Any drawbacks]
|
||||
|
||||
**Effort:** Small / Medium / Large
|
||||
|
||||
**Risk:** Low / Medium / High
|
||||
|
||||
---
|
||||
|
||||
### Option 2: [Alternative if applicable]
|
||||
|
||||
[Only include if there's a meaningful alternative approach]
|
||||
|
||||
## Recommended Action
|
||||
|
||||
*(To be filled during triage)*
|
||||
|
||||
## Technical Details
|
||||
|
||||
**Affected Files:**
|
||||
- `{file_path}:{line_number}` - {what needs changing}
|
||||
|
||||
**Related Components:**
|
||||
- [Components affected by this change]
|
||||
|
||||
## Resources
|
||||
|
||||
- **PR:** #{PR_NUMBER}
|
||||
- **Comment Link:** {direct_link_to_comment}
|
||||
- **Reviewer:** @{reviewer_username}
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Reviewer concern addressed
|
||||
- [ ] Tests pass
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] PR comment resolved
|
||||
|
||||
## Work Log
|
||||
|
||||
### {today's date} - Created from PR Review
|
||||
|
||||
**By:** Claude Code
|
||||
|
||||
**Actions:**
|
||||
- Extracted comment from PR #{PR_NUMBER} review
|
||||
- Created todo for triage
|
||||
|
||||
**Learnings:**
|
||||
- Original reviewer context: {any additional context}
|
||||
```
|
||||
|
||||
### 5. Parallel Todo Creation (For Multiple Comments)
|
||||
|
||||
<parallel_processing>
|
||||
|
||||
When processing PRs with many comments (5+), create todos in parallel for efficiency:
|
||||
|
||||
1. Synthesize all comments into a categorized list
|
||||
2. Assign severity (P1/P2/P3) to each
|
||||
3. Launch parallel Write operations for all todos
|
||||
4. Each todo follows the file-todos skill template exactly
|
||||
|
||||
</parallel_processing>
|
||||
|
||||
### 6. Summary Report
|
||||
|
||||
After creating all todo files, present:
|
||||
|
||||
````markdown
|
||||
## ✅ PR Comments Converted to Todos
|
||||
|
||||
**PR:** #{PR_NUMBER} - {PR_TITLE}
|
||||
**Branch:** {branch_name}
|
||||
**Total Comments Processed:** {X}
|
||||
|
||||
### Created Todo Files:
|
||||
|
||||
**🔴 P1 - Critical:**
|
||||
- `{id}-pending-p1-{desc}.md` - {summary}
|
||||
|
||||
**🟡 P2 - Important:**
|
||||
- `{id}-pending-p2-{desc}.md` - {summary}
|
||||
|
||||
**🔵 P3 - Nice-to-Have:**
|
||||
- `{id}-pending-p3-{desc}.md` - {summary}
|
||||
|
||||
### Skipped (Not Actionable):
|
||||
- {count} comments skipped (LGTM, questions answered, resolved threads)
|
||||
|
||||
### Assessment Summary:
|
||||
|
||||
All comments were pressure tested and included in todos:
|
||||
|
||||
| Assessment | Count | Description |
|
||||
|------------|-------|-------------|
|
||||
| **Clear & Correct** | {X} | Valid concerns, recommend fixing |
|
||||
| **Unclear** | {X} | Need clarification before implementing |
|
||||
| **Likely Incorrect** | {X} | May misunderstand context - review during triage |
|
||||
| **YAGNI** | {X} | May be over-engineering - review during triage |
|
||||
|
||||
**Note:** All assessments are included in the todo files. Human judgment during `/triage` makes the final call on whether to accept, clarify, or reject each item.
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. **Triage the todos:**
|
||||
```bash
|
||||
/triage
|
||||
```
|
||||
Review each todo and approve (pending → ready) or skip
|
||||
|
||||
2. **Work on approved items:**
|
||||
```bash
|
||||
/resolve_todo_parallel
|
||||
```
|
||||
|
||||
3. **After fixes, resolve PR comments:**
|
||||
```bash
|
||||
bin/resolve-pr-thread THREAD_ID
|
||||
```
|
||||
````
|
||||
|
||||
## Important Notes
|
||||
|
||||
<requirements>
|
||||
- Ensure `todos/` directory exists before creating files
|
||||
- Each todo must have unique issue_id (never reuse)
|
||||
- All todos start with `status: pending` for triage
|
||||
- Include `code-review` and `pr-feedback` tags on all todos
|
||||
- Preserve exact reviewer quotes in Findings section
|
||||
- Link back to original PR and comment in Resources
|
||||
</requirements>
|
||||
|
||||
## Integration with /triage
|
||||
|
||||
The output of this command is designed to work seamlessly with `/triage`:
|
||||
|
||||
1. **This command** creates `todos/*-pending-*.md` files
|
||||
2. **`/triage`** reviews each pending todo and:
|
||||
- Approves → renames to `*-ready-*.md`
|
||||
- Skips → deletes the todo file
|
||||
3. **`/resolve_todo_parallel`** works on approved (ready) todos
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: resolve_todo_parallel
|
||||
description: Resolve all pending CLI todos using parallel processing
|
||||
argument-hint: "[optional: specific todo ID or pattern]"
|
||||
---
|
||||
|
||||
Resolve all TODO comments using parallel processing.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Get all unresolved TODOs from the /todos/\*.md directory
|
||||
|
||||
If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type.Make sure to look at dependencies that might occur and prioritize the ones needed by others. For example, if you need to change a name, you must wait to do the others. Output a mermaid flow diagram showing how we can do this. Can we do everything in parallel? Do we need to do one first that leads to others in parallel? I'll put the to-dos in the mermaid diagram flow‑wise so the agent knows how to proceed in order.
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a pr-comment-resolver agent for each unresolved item in parallel.
|
||||
|
||||
So if there are 3 comments, it will spawn 3 pr-comment-resolver agents in parallel. liek this
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes
|
||||
- Remove the TODO from the file, and mark it as resolved.
|
||||
571
plugins/compound-engineering/commands/workflows/plan.md
Normal file
571
plugins/compound-engineering/commands/workflows/plan.md
Normal file
@@ -0,0 +1,571 @@
|
||||
---
|
||||
name: workflows:plan
|
||||
description: Transform feature descriptions into well-structured project plans following conventions
|
||||
argument-hint: "[feature description, bug report, or improvement idea]"
|
||||
---
|
||||
|
||||
# Create a plan for a new feature or bug fix
|
||||
|
||||
## Introduction
|
||||
|
||||
**Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.
|
||||
|
||||
Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
|
||||
|
||||
## Feature Description
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."
|
||||
|
||||
Do not proceed until you have a clear feature description from the user.
|
||||
|
||||
### 0. Idea Refinement
|
||||
|
||||
**Check for brainstorm output first:**
|
||||
|
||||
Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
|
||||
|
||||
```bash
|
||||
ls -la docs/brainstorms/*.md 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**Relevance criteria:** A brainstorm is relevant if:
|
||||
- The topic (from filename or YAML frontmatter) semantically matches the feature description
|
||||
- Created within the last 14 days
|
||||
- If multiple candidates match, use the most recent one
|
||||
|
||||
**If a relevant brainstorm exists:**
|
||||
1. Read the brainstorm document
|
||||
2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
|
||||
3. Extract key decisions, chosen approach, and open questions
|
||||
4. **Skip the idea refinement questions below** - the brainstorm already answered WHAT to build
|
||||
5. Use brainstorm decisions as input to the research phase
|
||||
|
||||
**If multiple brainstorms could match:**
|
||||
Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
|
||||
|
||||
**If no brainstorm found (or not relevant), run idea refinement:**
|
||||
|
||||
Refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
|
||||
|
||||
- Ask questions one at a time to understand the idea fully
|
||||
- Prefer multiple choice questions when natural options exist
|
||||
- Focus on understanding: purpose, constraints and success criteria
|
||||
- Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
**Gather signals for research decision.** During refinement, note:
|
||||
|
||||
- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
|
||||
- **User's intent**: Speed vs thoroughness? Exploration vs execution?
|
||||
- **Topic risk**: Security, payments, external APIs warrant more caution
|
||||
- **Uncertainty level**: Is the approach clear or open-ended?
|
||||
|
||||
**Skip option:** If the feature description is already detailed, offer:
|
||||
"Your description is clear. Should I proceed with research, or would you like to refine it further?"
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Local Research (Always Runs - Parallel)
|
||||
|
||||
<thinking>
|
||||
First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
|
||||
</thinking>
|
||||
|
||||
Run these agents **in parallel** to gather local context:
|
||||
|
||||
- Task repo-research-analyst(feature_description)
|
||||
- Task learnings-researcher(feature_description)
|
||||
|
||||
**What to look for:**
|
||||
- **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
|
||||
- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
|
||||
|
||||
These findings inform the next step.
|
||||
|
||||
### 1.5. Research Decision
|
||||
|
||||
Based on signals from Step 0 and findings from Step 1, decide on external research.
|
||||
|
||||
**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
|
||||
|
||||
**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.
|
||||
|
||||
**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
|
||||
|
||||
**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
|
||||
|
||||
Examples:
|
||||
- "Your codebase has solid patterns for this. Proceeding without external research."
|
||||
- "This involves payment processing, so I'll research current best practices first."
|
||||
|
||||
### 1.5b. External Research (Conditional)
|
||||
|
||||
**Only run if Step 1.5 indicates external research is valuable.**
|
||||
|
||||
Run these agents in parallel:
|
||||
|
||||
- Task best-practices-researcher(feature_description)
|
||||
- Task framework-docs-researcher(feature_description)
|
||||
|
||||
### 1.6. Consolidate Research
|
||||
|
||||
After all research steps complete, consolidate findings:
|
||||
|
||||
- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
|
||||
- **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
|
||||
- Note external documentation URLs and best practices (if external research was done)
|
||||
- List related issues or PRs discovered
|
||||
- Capture CLAUDE.md conventions
|
||||
|
||||
**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
|
||||
|
||||
### 2. Issue Planning & Structure
|
||||
|
||||
<thinking>
|
||||
Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
|
||||
</thinking>
|
||||
|
||||
**Title & Categorization:**
|
||||
|
||||
- [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
|
||||
- [ ] Determine issue type: enhancement, bug, refactor
|
||||
- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix
|
||||
- Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md`
|
||||
- Keep it descriptive (3-5 words after prefix) so plans are findable by context
|
||||
|
||||
**Stakeholder Analysis:**
|
||||
|
||||
- [ ] Identify who will be affected by this issue (end users, developers, operations)
|
||||
- [ ] Consider implementation complexity and required expertise
|
||||
|
||||
**Content Planning:**
|
||||
|
||||
- [ ] Choose appropriate detail level based on issue complexity and audience
|
||||
- [ ] List all necessary sections for the chosen template
|
||||
- [ ] Gather supporting materials (error logs, screenshots, design mockups)
|
||||
- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
|
||||
|
||||
### 3. SpecFlow Analysis
|
||||
|
||||
After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
|
||||
|
||||
- Task spec-flow-analyzer(feature_description, research_findings)
|
||||
|
||||
**SpecFlow Analyzer Output:**
|
||||
|
||||
- [ ] Review SpecFlow analysis results
|
||||
- [ ] Incorporate any identified gaps or edge cases into the issue
|
||||
- [ ] Update acceptance criteria based on SpecFlow findings
|
||||
|
||||
### 4. Choose Implementation Detail Level
|
||||
|
||||
Select how comprehensive you want the issue to be, simpler is mostly better.
|
||||
|
||||
#### 📄 MINIMAL (Quick Issue)
|
||||
|
||||
**Best for:** Simple bugs, small improvements, clear features
|
||||
|
||||
**Includes:**
|
||||
|
||||
- Problem statement or feature description
|
||||
- Basic acceptance criteria
|
||||
- Essential context only
|
||||
|
||||
**Structure:**
|
||||
|
||||
````markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
[Brief problem/feature description]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Core requirement 1
|
||||
- [ ] Core requirement 2
|
||||
|
||||
## Context
|
||||
|
||||
[Any critical information]
|
||||
|
||||
## MVP
|
||||
|
||||
### test.rb
|
||||
|
||||
```ruby
|
||||
class Test
|
||||
def initialize
|
||||
@name = "test"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- Related issue: #[issue_number]
|
||||
- Documentation: [relevant_docs_url]
|
||||
````
|
||||
|
||||
#### 📋 MORE (Standard Issue)
|
||||
|
||||
**Best for:** Most features, complex bugs, team collaboration
|
||||
|
||||
**Includes everything from MINIMAL plus:**
|
||||
|
||||
- Detailed background and motivation
|
||||
- Technical considerations
|
||||
- Success metrics
|
||||
- Dependencies and risks
|
||||
- Basic implementation suggestions
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Comprehensive description]
|
||||
|
||||
## Problem Statement / Motivation
|
||||
|
||||
[Why this matters]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[High-level approach]
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Architecture impacts
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Detailed requirement 1
|
||||
- [ ] Detailed requirement 2
|
||||
- [ ] Testing requirements
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[How we measure success]
|
||||
|
||||
## Dependencies & Risks
|
||||
|
||||
[What could block or complicate this]
|
||||
|
||||
## References & Research
|
||||
|
||||
- Similar implementations: [file_path:line_number]
|
||||
- Best practices: [documentation_url]
|
||||
- Related PRs: #[pr_number]
|
||||
```
|
||||
|
||||
#### 📚 A LOT (Comprehensive Issue)
|
||||
|
||||
**Best for:** Major features, architectural changes, complex integrations
|
||||
|
||||
**Includes everything from MORE plus:**
|
||||
|
||||
- Detailed implementation plan with phases
|
||||
- Alternative approaches considered
|
||||
- Extensive technical specifications
|
||||
- Resource requirements and timeline
|
||||
- Future considerations and extensibility
|
||||
- Risk mitigation strategies
|
||||
- Documentation requirements
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Executive summary]
|
||||
|
||||
## Problem Statement
|
||||
|
||||
[Detailed problem analysis]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[Comprehensive solution design]
|
||||
|
||||
## Technical Approach
|
||||
|
||||
### Architecture
|
||||
|
||||
[Detailed technical design]
|
||||
|
||||
### Implementation Phases
|
||||
|
||||
#### Phase 1: [Foundation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 2: [Core Implementation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 3: [Polish & Optimization]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
## Alternative Approaches Considered
|
||||
|
||||
[Other solutions evaluated and why rejected]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- [ ] Detailed functional criteria
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- [ ] Performance targets
|
||||
- [ ] Security requirements
|
||||
- [ ] Accessibility standards
|
||||
|
||||
### Quality Gates
|
||||
|
||||
- [ ] Test coverage requirements
|
||||
- [ ] Documentation completeness
|
||||
- [ ] Code review approval
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[Detailed KPIs and measurement methods]
|
||||
|
||||
## Dependencies & Prerequisites
|
||||
|
||||
[Detailed dependency analysis]
|
||||
|
||||
## Risk Analysis & Mitigation
|
||||
|
||||
[Comprehensive risk assessment]
|
||||
|
||||
## Resource Requirements
|
||||
|
||||
[Team, time, infrastructure needs]
|
||||
|
||||
## Future Considerations
|
||||
|
||||
[Extensibility and long-term vision]
|
||||
|
||||
## Documentation Plan
|
||||
|
||||
[What docs need updating]
|
||||
|
||||
## References & Research
|
||||
|
||||
### Internal References
|
||||
|
||||
- Architecture decisions: [file_path:line_number]
|
||||
- Similar features: [file_path:line_number]
|
||||
- Configuration: [file_path:line_number]
|
||||
|
||||
### External References
|
||||
|
||||
- Framework documentation: [url]
|
||||
- Best practices guide: [url]
|
||||
- Industry standards: [url]
|
||||
|
||||
### Related Work
|
||||
|
||||
- Previous PRs: #[pr_numbers]
|
||||
- Related issues: #[issue_numbers]
|
||||
- Design documents: [links]
|
||||
```
|
||||
|
||||
### 5. Issue Creation & Formatting
|
||||
|
||||
<thinking>
|
||||
Apply best practices for clarity and actionability, making the issue easy to scan and understand
|
||||
</thinking>
|
||||
|
||||
**Content Formatting:**
|
||||
|
||||
- [ ] Use clear, descriptive headings with proper hierarchy (##, ###)
|
||||
- [ ] Include code examples in triple backticks with language syntax highlighting
|
||||
- [ ] Add screenshots/mockups if UI-related (drag & drop or use image hosting)
|
||||
- [ ] Use task lists (- [ ]) for trackable items that can be checked off
|
||||
- [ ] Add collapsible sections for lengthy logs or optional details using `<details>` tags
|
||||
- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)
|
||||
|
||||
**Cross-Referencing:**
|
||||
|
||||
- [ ] Link to related issues/PRs using #number format
|
||||
- [ ] Reference specific commits with SHA hashes when relevant
|
||||
- [ ] Link to code using GitHub's permalink feature (press 'y' for permanent link)
|
||||
- [ ] Mention relevant team members with @username if needed
|
||||
- [ ] Add links to external resources with descriptive text
|
||||
|
||||
**Code & Examples:**
|
||||
|
||||
````markdown
|
||||
# Good example with syntax highlighting and line references
|
||||
|
||||
|
||||
```ruby
|
||||
# app/services/user_service.rb:42
|
||||
def process_user(user)
|
||||
|
||||
# Implementation here
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
# Collapsible error logs
|
||||
|
||||
<details>
|
||||
<summary>Full error stacktrace</summary>
|
||||
|
||||
`Error details here...`
|
||||
|
||||
</details>
|
||||
````
|
||||
|
||||
**AI-Era Considerations:**
|
||||
|
||||
- [ ] Account for accelerated development with AI pair programming
|
||||
- [ ] Include prompts or instructions that worked well during research
|
||||
- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
|
||||
- [ ] Emphasize comprehensive testing given rapid implementation
|
||||
- [ ] Document any AI-generated code that needs human review
|
||||
|
||||
### 6. Final Review & Submission
|
||||
|
||||
**Naming Scrutiny (REQUIRED for any plan that introduces new interfaces):**
|
||||
|
||||
When the plan proposes new functions, classes, variables, modules, API fields, or database columns, scrutinize every name:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Should private helpers be private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match existing codebase conventions? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? (`data`, `manager`, `handler` = red flags) |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
Bad names in plans become bad names in code. Catching them here is cheaper than catching them in review.
|
||||
|
||||
**Pre-submission Checklist:**
|
||||
|
||||
- [ ] Title is searchable and descriptive
|
||||
- [ ] Labels accurately categorize the issue
|
||||
- [ ] All template sections are complete
|
||||
- [ ] Links and references are working
|
||||
- [ ] Acceptance criteria are measurable
|
||||
- [ ] All proposed names pass the naming scrutiny checklist above
|
||||
- [ ] Add names of files in pseudo code examples and todo lists
|
||||
- [ ] Add an ERD mermaid diagram if applicable for new model changes
|
||||
|
||||
## Output Format
|
||||
|
||||
**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.
|
||||
|
||||
```
|
||||
docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md
|
||||
```
|
||||
|
||||
Examples:
|
||||
- ✅ `docs/plans/2026-01-15-feat-user-authentication-flow-plan.md`
|
||||
- ✅ `docs/plans/2026-02-03-fix-checkout-race-condition-plan.md`
|
||||
- ✅ `docs/plans/2026-03-10-refactor-api-client-extraction-plan.md`
|
||||
- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (not descriptive - what "thing"?)
|
||||
- ❌ `docs/plans/2026-01-15-feat-new-feature-plan.md` (too vague - what feature?)
|
||||
- ❌ `docs/plans/2026-01-15-feat: user auth-plan.md` (invalid characters - colon and space)
|
||||
- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix)
|
||||
|
||||
## Post-Generation Options
|
||||
|
||||
After writing the plan file, use the **AskUserQuestion tool** to present these options:
|
||||
|
||||
**Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<name>-plan.md`. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Open plan in editor** - Open the plan file for review
|
||||
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
||||
3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (Tiangolo, Kieran-Python, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
6. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
|
||||
Based on selection:
|
||||
- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
|
||||
- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **Review and refine** → Load `document-review` skill.
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
||||
|
||||
**Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
||||
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/technical_review`.
|
||||
|
||||
## Issue Creation
|
||||
|
||||
When user selects "Create Issue", detect their project tracker from CLAUDE.md:
|
||||
|
||||
1. **Check for tracker preference** in user's CLAUDE.md (global or project):
|
||||
- Look for `project_tracker: github` or `project_tracker: linear`
|
||||
- Or look for mentions of "GitHub Issues" or "Linear" in their workflow section
|
||||
|
||||
2. **If GitHub:**
|
||||
|
||||
Use the title and type from Step 2 (already in context - no need to re-read the file):
|
||||
|
||||
```bash
|
||||
gh issue create --title "<type>: <title>" --body-file <plan_path>
|
||||
```
|
||||
|
||||
3. **If Linear:**
|
||||
|
||||
```bash
|
||||
linear issue create --title "<title>" --description "$(cat <plan_path>)"
|
||||
```
|
||||
|
||||
4. **If no tracker configured:**
|
||||
Ask user: "Which project tracker do you use? (GitHub/Linear/Other)"
|
||||
- Suggest adding `project_tracker: github` or `project_tracker: linear` to their CLAUDE.md
|
||||
|
||||
5. **After creation:**
|
||||
- Display the issue URL
|
||||
- Ask if they want to proceed to `/workflows:work` or `/technical_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
616
plugins/compound-engineering/commands/workflows/review.md
Normal file
616
plugins/compound-engineering/commands/workflows/review.md
Normal file
@@ -0,0 +1,616 @@
|
||||
---
|
||||
name: workflows:review
|
||||
description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
|
||||
argument-hint: "[PR number, GitHub URL, branch name, or latest]"
|
||||
---
|
||||
|
||||
# Review Command
|
||||
|
||||
<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>
|
||||
|
||||
## Introduction
|
||||
|
||||
<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<requirements>
|
||||
- Git repository with GitHub CLI (`gh`) installed and authenticated
|
||||
- Clean main/master branch
|
||||
- Proper permissions to create worktrees and access the repository
|
||||
- For document reviews: Path to a markdown file or document
|
||||
</requirements>
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Determine Review Target & Setup (ALWAYS FIRST)
|
||||
|
||||
<review_target> #$ARGUMENTS </review_target>
|
||||
|
||||
<thinking>
|
||||
First, I need to determine the review target type and set up the code for analysis.
|
||||
</thinking>
|
||||
|
||||
#### Immediate Actions:
|
||||
|
||||
<task_list>
|
||||
|
||||
- [ ] Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
|
||||
- [ ] Check current git branch
|
||||
- [ ] If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
|
||||
- [ ] If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call `skill: git-worktree` with branch name
|
||||
- [ ] Fetch PR metadata using `gh pr view --json` for title, body, files, linked issues
|
||||
- [ ] Set up language-specific analysis tools
|
||||
- [ ] Prepare security scanning environment
|
||||
- [ ] Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.
|
||||
|
||||
Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.
|
||||
|
||||
</task_list>
|
||||
|
||||
#### Protected Artifacts
|
||||
|
||||
<protected_artifacts>
|
||||
The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
|
||||
|
||||
- `docs/plans/*.md` — Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`).
|
||||
- `docs/solutions/*.md` — Solution documents created during the pipeline.
|
||||
|
||||
If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
|
||||
</protected_artifacts>
|
||||
|
||||
#### Load Review Agents
|
||||
|
||||
Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
|
||||
|
||||
If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
|
||||
|
||||
#### Parallel Agents to review the PR:
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list:
|
||||
|
||||
```
|
||||
Task {agent-name}(PR content + review context from settings body)
|
||||
```
|
||||
|
||||
Additionally, always run these regardless of settings:
|
||||
- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
|
||||
- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
#### Conditional Agents (Run if applicable):
|
||||
|
||||
<conditional_agents>
|
||||
|
||||
These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
|
||||
|
||||
**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
|
||||
|
||||
- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
|
||||
- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
|
||||
- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
|
||||
|
||||
**When to run:**
|
||||
- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
|
||||
- PR modifies columns that store IDs, enums, or mappings
|
||||
- PR includes data backfill scripts or rake tasks
|
||||
- PR title/body mentions: migration, backfill, data transformation, ID mapping
|
||||
|
||||
**What these agents check:**
|
||||
- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
|
||||
- `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
|
||||
- `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
|
||||
|
||||
</conditional_agents>
|
||||
|
||||
### 4. Ultra-Thinking Deep Dive Phases
|
||||
|
||||
<ultrathink_instruction> For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.</ultrathink_instruction>
|
||||
|
||||
<deliverable>
|
||||
Complete system context map with component interactions
|
||||
</deliverable>
|
||||
|
||||
#### Phase 3: Stakeholder Perspective Analysis
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>
|
||||
|
||||
<stakeholder_perspectives>
|
||||
|
||||
1. **Developer Perspective** <questions>
|
||||
|
||||
- How easy is this to understand and modify?
|
||||
- Are the APIs intuitive?
|
||||
- Is debugging straightforward?
|
||||
- Can I test this easily? </questions>
|
||||
|
||||
2. **Operations Perspective** <questions>
|
||||
|
||||
- How do I deploy this safely?
|
||||
- What metrics and logs are available?
|
||||
- How do I troubleshoot issues?
|
||||
- What are the resource requirements? </questions>
|
||||
|
||||
3. **End User Perspective** <questions>
|
||||
|
||||
- Is the feature intuitive?
|
||||
- Are error messages helpful?
|
||||
- Is performance acceptable?
|
||||
- Does it solve my problem? </questions>
|
||||
|
||||
4. **Security Team Perspective** <questions>
|
||||
|
||||
- What's the attack surface?
|
||||
- Are there compliance requirements?
|
||||
- How is data protected?
|
||||
- What are the audit capabilities? </questions>
|
||||
|
||||
5. **Business Perspective** <questions>
|
||||
- What's the ROI?
|
||||
- Are there legal/compliance risks?
|
||||
- How does this affect time-to-market?
|
||||
- What's the total cost of ownership? </questions> </stakeholder_perspectives>
|
||||
|
||||
#### Phase 4: Scenario Exploration
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>
|
||||
|
||||
<scenario_checklist>
|
||||
|
||||
- [ ] **Happy Path**: Normal operation with valid inputs
|
||||
- [ ] **Invalid Inputs**: Null, empty, malformed data
|
||||
- [ ] **Boundary Conditions**: Min/max values, empty collections
|
||||
- [ ] **Concurrent Access**: Race conditions, deadlocks
|
||||
- [ ] **Scale Testing**: 10x, 100x, 1000x normal load
|
||||
- [ ] **Network Issues**: Timeouts, partial failures
|
||||
- [ ] **Resource Exhaustion**: Memory, disk, connections
|
||||
- [ ] **Security Attacks**: Injection, overflow, DoS
|
||||
- [ ] **Data Corruption**: Partial writes, inconsistency
|
||||
- [ ] **Cascading Failures**: Downstream service issues </scenario_checklist>
|
||||
|
||||
### 6. Multi-Angle Review Perspectives
|
||||
|
||||
#### Technical Excellence Angle
|
||||
|
||||
- Code craftsmanship evaluation
|
||||
- Engineering best practices
|
||||
- Technical documentation quality
|
||||
- Tooling and automation assessment
|
||||
- **Naming accuracy** (see Naming Scrutiny below)
|
||||
|
||||
#### Naming Scrutiny (REQUIRED)
|
||||
|
||||
Every name introduced or modified in the PR must pass these checks:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Are private helpers actually private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match every other instance in the codebase? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? (`data`, `manager`, `handler` = red flags) |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? (`auth` = authentication or authorization?) |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
**Common anti-patterns to flag:**
|
||||
- False optionality: `save_with_validation()` when validation is mandatory
|
||||
- Leaked implementation: `create_batch_with_items()` when callers just need `create_batch()`
|
||||
- Type encoding: `word_string`, `new_hash` instead of domain terms
|
||||
- Structural naming: `input`, `output`, `result` instead of what they contain
|
||||
- Doppelgangers: names differing by one letter (`useProfileQuery` vs `useProfilesQuery`)
|
||||
|
||||
Include naming findings in the synthesized review. Flag as P2 (Important) unless the name is actively misleading about behavior (P1).
|
||||
|
||||
#### Business Value Angle
|
||||
|
||||
- Feature completeness validation
|
||||
- Performance impact on users
|
||||
- Cost-benefit analysis
|
||||
- Time-to-market considerations
|
||||
|
||||
#### Risk Management Angle
|
||||
|
||||
- Security risk assessment
|
||||
- Operational risk evaluation
|
||||
- Compliance risk verification
|
||||
- Technical debt accumulation
|
||||
|
||||
#### Team Dynamics Angle
|
||||
|
||||
- Code review etiquette
|
||||
- Knowledge sharing effectiveness
|
||||
- Collaboration patterns
|
||||
- Mentoring opportunities
|
||||
|
||||
### 4. Simplification and Minimalism Review
|
||||
|
||||
Run the Task code-simplicity-reviewer() to see if we can simplify the code.
|
||||
|
||||
### 5. Findings Synthesis and Todo Creation Using file-todos Skill
|
||||
|
||||
<critical_requirement> ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management. </critical_requirement>
|
||||
|
||||
#### Step 1: Synthesize All Findings
|
||||
|
||||
<thinking>
|
||||
Consolidate all agent reports into a categorized list of findings.
|
||||
Remove duplicates, prioritize by severity and impact.
|
||||
</thinking>
|
||||
|
||||
<synthesis_tasks>
|
||||
|
||||
- [ ] Collect findings from all parallel agents
|
||||
- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
|
||||
- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
|
||||
- [ ] Categorize by type: security, performance, architecture, quality, etc.
|
||||
- [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
|
||||
- [ ] Remove duplicate or overlapping findings
|
||||
- [ ] Estimate effort for each finding (Small/Medium/Large)
|
||||
|
||||
</synthesis_tasks>
|
||||
|
||||
#### Step 2: Pressure Test Each Finding
|
||||
|
||||
<critical_evaluation>
|
||||
|
||||
**IMPORTANT: Treat agent findings as suggestions, not mandates.**
|
||||
|
||||
Not all findings are equally valid. Apply engineering judgment before creating todos. The goal is to make the right call for the codebase, not rubber-stamp every suggestion.
|
||||
|
||||
**For each finding, verify:**
|
||||
|
||||
| Check | Question |
|
||||
|-------|----------|
|
||||
| **Code** | Does the concern actually apply to this specific code? |
|
||||
| **Tests** | Are there existing tests that already cover this case? |
|
||||
| **Usage** | How is this code used in practice? Does the concern matter? |
|
||||
| **Compatibility** | Would the suggested change break anything? |
|
||||
| **Prior Decisions** | Was this intentional? Is there a documented reason? |
|
||||
| **Cost vs Benefit** | Is the fix worth the effort and risk? |
|
||||
|
||||
**Assess each finding:**
|
||||
|
||||
| Assessment | Meaning |
|
||||
|------------|---------|
|
||||
| **Clear & Correct** | Valid concern, well-reasoned, applies here |
|
||||
| **Unclear** | Ambiguous or missing context |
|
||||
| **Likely Incorrect** | Agent misunderstands code, context, or requirements |
|
||||
| **YAGNI** | Over-engineering, premature abstraction, no clear benefit |
|
||||
| **Duplicate** | Already covered by another finding (merge into existing) |
|
||||
|
||||
**IMPORTANT: ALL findings become todos.** Never drop agent feedback - include the pressure test assessment IN each todo so `/triage` can use it.
|
||||
|
||||
Each todo will include:
|
||||
- The assessment (Clear & Correct / Unclear / Likely Incorrect / YAGNI)
|
||||
- The verification results (what was checked)
|
||||
- Technical justification (why valid, or why you think it should be skipped)
|
||||
- Recommended action for triage (Fix now / Clarify / Push back / Skip)
|
||||
|
||||
**Provide technical justification for all assessments:**
|
||||
- Don't just label - explain WHY with specific reasoning
|
||||
- Reference codebase constraints, requirements, or trade-offs
|
||||
- Example: "This abstraction would be YAGNI - we only have one implementation and no plans for variants. Adding it now increases complexity without clear benefit."
|
||||
|
||||
The human reviews during `/triage` and makes the final call.
|
||||
|
||||
</critical_evaluation>
|
||||
|
||||
#### Step 3: Create Todo Files Using file-todos Skill
|
||||
|
||||
<critical_instruction> Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
|
||||
|
||||
**Implementation Options:**
|
||||
|
||||
**Option A: Direct File Creation (Fast)**
|
||||
|
||||
- Create todo files directly using Write tool
|
||||
- All findings in parallel for speed
|
||||
- Invoke `Skill: "compound-engineering:file-todos"` and read the template from its assets directory
|
||||
- Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
|
||||
|
||||
**Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
|
||||
|
||||
```bash
|
||||
# Launch multiple finding-creator agents in parallel
|
||||
Task() - Create todos for first finding
|
||||
Task() - Create todos for second finding
|
||||
Task() - Create todos for third finding
|
||||
etc. for each finding.
|
||||
```
|
||||
|
||||
Sub-agents can:
|
||||
|
||||
- Process multiple findings simultaneously
|
||||
- Write detailed todo files with all sections filled
|
||||
- Organize findings by severity
|
||||
- Create comprehensive Proposed Solutions
|
||||
- Add acceptance criteria and work logs
|
||||
- Complete much faster than sequential processing
|
||||
|
||||
**Execution Strategy:**
|
||||
|
||||
1. Synthesize all findings into categories (P1/P2/P3)
|
||||
2. Group findings by severity
|
||||
3. Launch 3 parallel sub-agents (one per severity level)
|
||||
4. Each sub-agent creates its batch of todos using the file-todos skill
|
||||
5. Consolidate results and present summary
|
||||
|
||||
**Process (Using file-todos Skill):**
|
||||
|
||||
1. For each finding:
|
||||
|
||||
- Determine severity (P1/P2/P3)
|
||||
- Write detailed Problem Statement and Findings
|
||||
- Create 2-3 Proposed Solutions with pros/cons/effort/risk
|
||||
- Estimate effort (Small/Medium/Large)
|
||||
- Add acceptance criteria and work log
|
||||
|
||||
2. Use file-todos skill for structured todo management:
|
||||
|
||||
```
|
||||
Skill: "compound-engineering:file-todos"
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
|
||||
- Template at `./assets/todo-template.md` (relative to skill directory)
|
||||
- Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
|
||||
- YAML frontmatter structure: status, priority, issue_id, tags, dependencies
|
||||
- All required sections: Problem Statement, Findings, Solutions, etc.
|
||||
|
||||
3. Create todo files in parallel:
|
||||
|
||||
```bash
|
||||
{next_id}-pending-{priority}-{description}.md
|
||||
```
|
||||
|
||||
4. Examples:
|
||||
|
||||
```
|
||||
001-pending-p1-path-traversal-vulnerability.md
|
||||
002-pending-p1-api-response-validation.md
|
||||
003-pending-p2-concurrency-limit.md
|
||||
004-pending-p3-unused-parameter.md
|
||||
```
|
||||
|
||||
5. Follow template structure from file-todos skill (read `./assets/todo-template.md` from skill directory)
|
||||
|
||||
**Todo File Structure (from template):**
|
||||
|
||||
Each todo must include:
|
||||
|
||||
- **YAML frontmatter**: status, priority, issue_id, tags, dependencies
|
||||
- **Problem Statement**: What's broken/missing, why it matters
|
||||
- **Assessment (Pressure Test)**: Verification results and engineering judgment
|
||||
- Assessment: Clear & Correct / Unclear / YAGNI
|
||||
- Verified: Code, Tests, Usage, Prior Decisions
|
||||
- Technical Justification: Why this finding is valid (or why skipped)
|
||||
- **Findings**: Discoveries from agents with evidence/location
|
||||
- **Proposed Solutions**: 2-3 options, each with pros/cons/effort/risk
|
||||
- **Recommended Action**: (Filled during triage, leave blank initially)
|
||||
- **Technical Details**: Affected files, components, database changes
|
||||
- **Acceptance Criteria**: Testable checklist items
|
||||
- **Work Log**: Dated record with actions and learnings
|
||||
- **Resources**: Links to PR, issues, documentation, similar patterns
|
||||
|
||||
**File naming convention:**
|
||||
|
||||
```
|
||||
{issue_id}-{status}-{priority}-{description}.md
|
||||
|
||||
Examples:
|
||||
- 001-pending-p1-security-vulnerability.md
|
||||
- 002-pending-p2-performance-optimization.md
|
||||
- 003-pending-p3-code-cleanup.md
|
||||
```
|
||||
|
||||
**Status values:**
|
||||
|
||||
- `pending` - New findings, needs triage/decision
|
||||
- `ready` - Approved by manager, ready to work
|
||||
- `complete` - Work finished
|
||||
|
||||
**Priority values:**
|
||||
|
||||
- `p1` - Critical (blocks merge, security/data issues)
|
||||
- `p2` - Important (should fix, architectural/performance)
|
||||
- `p3` - Nice-to-have (enhancements, cleanup)
|
||||
|
||||
**Tagging:** Always add `code-review` tag, plus: `security`, `performance`, `architecture`, `rails`, `quality`, etc.
|
||||
|
||||
#### Step 4: Summary Report
|
||||
|
||||
After creating all todo files, present comprehensive summary:
|
||||
|
||||
````markdown
|
||||
## ✅ Code Review Complete
|
||||
|
||||
**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]
|
||||
|
||||
### Findings Summary:
|
||||
|
||||
- **Total Findings:** [X]
|
||||
- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
|
||||
- **🟡 IMPORTANT (P2):** [count] - Should Fix
|
||||
- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements
|
||||
|
||||
### Created Todo Files:
|
||||
|
||||
**P1 - Critical (BLOCKS MERGE):**
|
||||
|
||||
- `001-pending-p1-{finding}.md` - {description}
|
||||
- `002-pending-p1-{finding}.md` - {description}
|
||||
|
||||
**P2 - Important:**
|
||||
|
||||
- `003-pending-p2-{finding}.md` - {description}
|
||||
- `004-pending-p2-{finding}.md` - {description}
|
||||
|
||||
**P3 - Nice-to-Have:**
|
||||
|
||||
- `005-pending-p3-{finding}.md` - {description}
|
||||
|
||||
### Review Agents Used:
|
||||
|
||||
- kieran-python-reviewer
|
||||
- security-sentinel
|
||||
- performance-oracle
|
||||
- architecture-strategist
|
||||
- agent-native-reviewer
|
||||
- [other agents]
|
||||
|
||||
### Assessment Summary (Pressure Test Results):
|
||||
|
||||
All agent findings were pressure tested and included in todos:
|
||||
|
||||
| Assessment | Count | Description |
|
||||
|------------|-------|-------------|
|
||||
| **Clear & Correct** | {X} | Valid concerns, recommend fixing |
|
||||
| **Unclear** | {X} | Need clarification before implementing |
|
||||
| **Likely Incorrect** | {X} | May misunderstand context - review during triage |
|
||||
| **YAGNI** | {X} | May be over-engineering - review during triage |
|
||||
| **Duplicate** | {X} | Merged into other findings |
|
||||
|
||||
**Note:** All assessments are included in the todo files. Human judgment during `/triage` makes the final call on whether to accept, clarify, or reject each item.
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. **Address P1 Findings**: CRITICAL - must be fixed before merge
|
||||
|
||||
- Review each P1 todo in detail
|
||||
- Implement fixes or request exemption
|
||||
- Verify fixes before merging PR
|
||||
|
||||
2. **Triage All Todos**:
|
||||
```bash
|
||||
ls todos/*-pending-*.md # View all pending todos
|
||||
/triage # Use slash command for interactive triage
|
||||
```
|
||||
````
|
||||
|
||||
3. **Work on Approved Todos**:
|
||||
|
||||
```bash
|
||||
/resolve_todo_parallel # Fix all approved items efficiently
|
||||
```
|
||||
|
||||
4. **Track Progress**:
|
||||
- Rename file when status changes: pending → ready → complete
|
||||
- Update Work Log as you work
|
||||
- Commit todos: `git add todos/ && git commit -m "refactor: add code review findings"`
|
||||
|
||||
### Severity Breakdown:
|
||||
|
||||
**🔴 P1 (Critical - Blocks Merge):**
|
||||
|
||||
- Security vulnerabilities
|
||||
- Data corruption risks
|
||||
- Breaking changes
|
||||
- Critical architectural issues
|
||||
|
||||
**🟡 P2 (Important - Should Fix):**
|
||||
|
||||
- Performance issues
|
||||
- Significant architectural concerns
|
||||
- Major code quality problems
|
||||
- Reliability issues
|
||||
|
||||
**🔵 P3 (Nice-to-Have):**
|
||||
|
||||
- Minor improvements
|
||||
- Code cleanup
|
||||
- Optimization opportunities
|
||||
- Documentation updates
|
||||
|
||||
```
|
||||
|
||||
### 7. End-to-End Testing (Optional)
|
||||
|
||||
<detect_project_type>
|
||||
|
||||
**First, detect the project type from PR files:**
|
||||
|
||||
| Indicator | Project Type |
|
||||
|-----------|--------------|
|
||||
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
|
||||
| `Gemfile`, `package.json`, `app/views/*`, `*.html.*` | Web |
|
||||
| Both iOS files AND web files | Hybrid (test both) |
|
||||
|
||||
</detect_project_type>
|
||||
|
||||
<offer_testing>
|
||||
|
||||
After presenting the Summary Report, offer appropriate testing based on project type:
|
||||
|
||||
**For Web Projects:**
|
||||
```markdown
|
||||
**"Want to run browser tests on the affected pages?"**
|
||||
1. Yes - run `/test-browser`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For iOS Projects:**
|
||||
```markdown
|
||||
**"Want to run Xcode simulator tests on the app?"**
|
||||
1. Yes - run `/xcode-test`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For Hybrid Projects (e.g., Rails + Hotwire Native):**
|
||||
```markdown
|
||||
**"Want to run end-to-end tests?"**
|
||||
1. Web only - run `/test-browser`
|
||||
2. iOS only - run `/xcode-test`
|
||||
3. Both - run both commands
|
||||
4. No - skip
|
||||
```
|
||||
|
||||
</offer_testing>
|
||||
|
||||
#### If User Accepts Web Testing:
|
||||
|
||||
Spawn a subagent to run browser tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Identify pages affected by the PR
|
||||
2. Navigate to each page and capture snapshots (using Playwright MCP or agent-browser CLI)
|
||||
3. Check for console errors
|
||||
4. Test critical interactions
|
||||
5. Pause for human verification on OAuth/email/payment flows
|
||||
6. Create P1 todos for any failures
|
||||
7. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/test-browser [PR number]`
|
||||
|
||||
#### If User Accepts iOS Testing:
|
||||
|
||||
Spawn a subagent to run Xcode tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Verify XcodeBuildMCP is installed
|
||||
2. Discover project and schemes
|
||||
3. Build for iOS Simulator
|
||||
4. Install and launch app
|
||||
5. Take screenshots of key screens
|
||||
6. Capture console logs for errors
|
||||
7. Pause for human verification (Sign in with Apple, push, IAP)
|
||||
8. Create P1 todos for any failures
|
||||
9. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/xcode-test [scheme]`
|
||||
|
||||
### Important: P1 Findings Block Merge
|
||||
|
||||
Any **🔴 P1 (CRITICAL)** findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.
|
||||
```
|
||||
471
plugins/compound-engineering/commands/workflows/work.md
Normal file
471
plugins/compound-engineering/commands/workflows/work.md
Normal file
@@ -0,0 +1,471 @@
|
||||
---
|
||||
name: workflows:work
|
||||
description: Execute work plans efficiently while maintaining quality and finishing features
|
||||
argument-hint: "[plan file, specification, or todo file path]"
|
||||
---
|
||||
|
||||
# Work Plan Execution Command
|
||||
|
||||
Execute a work plan efficiently while maintaining quality and finishing features.
|
||||
|
||||
## Introduction
|
||||
|
||||
This command takes a work document (plan, specification, or todo file) and executes it systematically. The focus is on **shipping complete features** by understanding requirements quickly, following existing patterns, and maintaining quality throughout.
|
||||
|
||||
## Input Document
|
||||
|
||||
<input_document> #$ARGUMENTS </input_document>
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Phase 1: Quick Start
|
||||
|
||||
1. **Read Plan and Clarify**
|
||||
|
||||
- Read the work document completely
|
||||
- Review any references or links provided in the plan
|
||||
- If anything is unclear or ambiguous, ask clarifying questions now
|
||||
- Get user approval to proceed
|
||||
- **Do not skip this** - better to ask questions now than build the wrong thing
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
First, check the current branch:
|
||||
|
||||
```bash
|
||||
current_branch=$(git branch --show-current)
|
||||
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
|
||||
|
||||
# Fallback if remote HEAD isn't set
|
||||
if [ -z "$default_branch" ]; then
|
||||
default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
|
||||
fi
|
||||
```
|
||||
|
||||
**If already on a feature branch** (not the default branch):
|
||||
- Ask: "Continue working on `[current_branch]`, or create a new branch?"
|
||||
- If continuing, proceed to step 3
|
||||
- If creating new, follow Option A or B below
|
||||
|
||||
**If on the default branch**, choose how to proceed:
|
||||
|
||||
**Option A: Create a new branch**
|
||||
```bash
|
||||
git pull origin [default_branch]
|
||||
git checkout -b feature-branch-name
|
||||
```
|
||||
Use a meaningful name based on the work (e.g., `feat/user-authentication`, `fix/email-validation`).
|
||||
|
||||
**Option B: Use a worktree (recommended for parallel development)**
|
||||
```bash
|
||||
skill: git-worktree
|
||||
# The skill will create a new branch from the default branch in an isolated worktree
|
||||
```
|
||||
|
||||
**Option C: Continue on the default branch**
|
||||
- Requires explicit user confirmation
|
||||
- Only proceed after user explicitly says "yes, commit to [default_branch]"
|
||||
- Never commit directly to the default branch without explicit permission
|
||||
|
||||
**Recommendation**: Use worktree if:
|
||||
- You want to work on multiple features simultaneously
|
||||
- You want to keep the default branch clean while experimenting
|
||||
- You plan to switch between branches frequently
|
||||
|
||||
3. **Create Todo List**
|
||||
- Use TodoWrite to break plan into actionable tasks
|
||||
- Include dependencies between tasks
|
||||
- Prioritize based on what needs to be done first
|
||||
- Include testing and quality check tasks
|
||||
- Keep tasks specific and completable
|
||||
|
||||
### Phase 2: Execute
|
||||
|
||||
1. **Task Execution Loop**
|
||||
|
||||
For each task in priority order:
|
||||
|
||||
```
|
||||
while (tasks remain):
|
||||
- Mark task as in_progress in TodoWrite
|
||||
- Read any referenced files from the plan
|
||||
- Look for similar patterns in codebase
|
||||
- Implement following existing conventions
|
||||
- Write tests for new functionality
|
||||
- Run tests after changes
|
||||
- Mark task as completed in TodoWrite
|
||||
- Mark off the corresponding checkbox in the plan file ([ ] → [x])
|
||||
- Evaluate for incremental commit (see below)
|
||||
```
|
||||
|
||||
**IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
|
||||
|
||||
2. **Incremental Commits**
|
||||
|
||||
After completing each task, evaluate whether to create an incremental commit:
|
||||
|
||||
| Commit when... | Don't commit when... |
|
||||
|----------------|---------------------|
|
||||
| Logical unit complete (model, service, component) | Small part of a larger unit |
|
||||
| Tests pass + meaningful progress | Tests failing |
|
||||
| About to switch contexts (backend → frontend) | Purely scaffolding with no behavior |
|
||||
| About to attempt risky/uncertain changes | Would need a "WIP" commit message |
|
||||
|
||||
**Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
|
||||
|
||||
**Commit workflow:**
|
||||
```bash
|
||||
# 1. Verify tests pass (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# 2. Stage only files related to this logical unit (not `git add .`)
|
||||
git add <files related to this logical unit>
|
||||
|
||||
# 3. Commit with conventional message
|
||||
git commit -m "feat(scope): description of this unit"
|
||||
```
|
||||
|
||||
**Handling merge conflicts:** If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.
|
||||
|
||||
**Note:** Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.
|
||||
|
||||
3. **Follow Existing Patterns**
|
||||
|
||||
- The plan should reference similar code - read those files first
|
||||
- Match naming conventions exactly
|
||||
- Reuse existing components where possible
|
||||
- Follow project coding standards (see CLAUDE.md)
|
||||
- When in doubt, grep for similar implementations
|
||||
|
||||
4. **Naming Scrutiny (Apply to every new name)**
|
||||
|
||||
Before committing any new function, class, variable, module, or field name:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Are private helpers actually private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match every other instance in the codebase? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
**Quick validation:** Search the codebase for the naming pattern you're using. If your convention doesn't match existing instances, align with the codebase.
|
||||
|
||||
5. **Test Continuously**
|
||||
|
||||
- Run relevant tests after each significant change
|
||||
- Don't wait until the end to test
|
||||
- Fix failures immediately
|
||||
- Add new tests for new functionality
|
||||
|
||||
6. **Figma Design Sync** (if applicable)
|
||||
|
||||
For UI work with Figma designs:
|
||||
|
||||
- Implement components following design specs
|
||||
- Use figma-design-sync agent iteratively to compare
|
||||
- Fix visual differences identified
|
||||
- Repeat until implementation matches design
|
||||
|
||||
7. **Track Progress**
|
||||
- Keep TodoWrite updated as you complete tasks
|
||||
- Note any blockers or unexpected discoveries
|
||||
- Create new tasks if scope expands
|
||||
- Keep user informed of major milestones
|
||||
|
||||
### Phase 3: Quality Check
|
||||
|
||||
1. **Run Core Quality Checks**
|
||||
|
||||
Always run before submitting:
|
||||
|
||||
```bash
|
||||
# Run full test suite (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# Run linting (per CLAUDE.md)
|
||||
# Use linting-agent before pushing to origin
|
||||
```
|
||||
|
||||
2. **Consider Reviewer Agents** (Optional)
|
||||
|
||||
Use for complex, risky, or large changes. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
|
||||
|
||||
Run configured agents in parallel with Task tool. Present findings and address critical issues.
|
||||
|
||||
3. **Final Validation**
|
||||
- All TodoWrite tasks marked completed
|
||||
- All tests pass
|
||||
- Linting passes
|
||||
- Code follows existing patterns
|
||||
- Figma designs match (if applicable)
|
||||
- No console errors or warnings
|
||||
|
||||
4. **Prepare Operational Validation Plan** (REQUIRED)
|
||||
- Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
|
||||
- Include concrete:
|
||||
- Log queries/search terms
|
||||
- Metrics or dashboards to watch
|
||||
- Expected healthy signals
|
||||
- Failure signals and rollback/mitigation trigger
|
||||
- Validation window and owner
|
||||
- If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
|
||||
|
||||
### Phase 4: Ship It
|
||||
|
||||
1. **Create Commit**
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git status # Review what's being committed
|
||||
git diff --staged # Check the changes
|
||||
|
||||
# Commit with conventional format
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(scope): description of what and why
|
||||
|
||||
Brief explanation if needed.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
2. **Capture and Upload Screenshots for UI Changes** (REQUIRED for any UI work)
|
||||
|
||||
For **any** design changes, new views, or UI modifications, you MUST capture and upload screenshots:
|
||||
|
||||
**Step 1: Start dev server** (if not running)
|
||||
```bash
|
||||
bin/dev # Run in background
|
||||
```
|
||||
|
||||
**Step 2: Capture screenshots with agent-browser CLI**
|
||||
```bash
|
||||
agent-browser open http://localhost:3000/[route]
|
||||
agent-browser snapshot -i
|
||||
agent-browser screenshot output.png
|
||||
```
|
||||
See the `agent-browser` skill for detailed usage.
|
||||
|
||||
**Step 3: Upload using imgup skill**
|
||||
```bash
|
||||
skill: imgup
|
||||
# Then upload each screenshot:
|
||||
imgup -h pixhost screenshot.png # pixhost works without API key
|
||||
# Alternative hosts: catbox, imagebin, beeimg
|
||||
```
|
||||
|
||||
**What to capture:**
|
||||
- **New screens**: Screenshot of the new UI
|
||||
- **Modified screens**: Before AND after screenshots
|
||||
- **Design implementation**: Screenshot showing Figma design match
|
||||
|
||||
**IMPORTANT**: Always include uploaded image URLs in PR description. This provides visual context for reviewers and documents the change.
|
||||
|
||||
3. **Create Pull Request**
|
||||
|
||||
```bash
|
||||
git push -u origin feature-branch-name
|
||||
|
||||
gh pr create --title "Feature: [Description]" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
- What was built
|
||||
- Why it was needed
|
||||
- Key decisions made
|
||||
|
||||
## Testing
|
||||
- Tests added/modified
|
||||
- Manual testing performed
|
||||
|
||||
## Post-Deploy Monitoring & Validation
|
||||
- **What to monitor/search**
|
||||
- Logs:
|
||||
- Metrics/Dashboards:
|
||||
- **Validation checks (queries/commands)**
|
||||
- `command or query here`
|
||||
- **Expected healthy behavior**
|
||||
- Expected signal(s)
|
||||
- **Failure signal(s) / rollback trigger**
|
||||
- Trigger + immediate action
|
||||
- **Validation window & owner**
|
||||
- Window:
|
||||
- Owner:
|
||||
- **If no operational impact**
|
||||
- `No additional operational monitoring required: <reason>`
|
||||
|
||||
## Before / After Screenshots
|
||||
| Before | After |
|
||||
|--------|-------|
|
||||
|  |  |
|
||||
|
||||
## Figma Design
|
||||
[Link if applicable]
|
||||
|
||||
---
|
||||
|
||||
[](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
4. **Update Plan Status**
|
||||
|
||||
If the input document has YAML frontmatter with a `status` field, update it to `completed`:
|
||||
```
|
||||
status: active → status: completed
|
||||
```
|
||||
|
||||
5. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR
|
||||
- Note any follow-up work needed
|
||||
- Suggest next steps if applicable
|
||||
|
||||
---
|
||||
|
||||
## Swarm Mode (Optional)
|
||||
|
||||
For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
|
||||
|
||||
### When to Use Swarm Mode
|
||||
|
||||
| Use Swarm Mode when... | Use Standard Mode when... |
|
||||
|------------------------|---------------------------|
|
||||
| Plan has 5+ independent tasks | Plan is linear/sequential |
|
||||
| Multiple specialists needed (review + test + implement) | Single-focus work |
|
||||
| Want maximum parallelism | Simpler mental model preferred |
|
||||
| Large feature with clear phases | Small feature or bug fix |
|
||||
|
||||
### Enabling Swarm Mode
|
||||
|
||||
To trigger swarm execution, say:
|
||||
|
||||
> "Make a Task list and launch an army of agent swarm subagents to build the plan"
|
||||
|
||||
Or explicitly request: "Use swarm mode for this work"
|
||||
|
||||
### Swarm Workflow
|
||||
|
||||
When swarm mode is enabled, the workflow changes:
|
||||
|
||||
1. **Create Team**
|
||||
```
|
||||
Teammate({ operation: "spawnTeam", team_name: "work-{timestamp}" })
|
||||
```
|
||||
|
||||
2. **Create Task List with Dependencies**
|
||||
- Parse plan into TaskCreate items
|
||||
- Set up blockedBy relationships for sequential dependencies
|
||||
- Independent tasks have no blockers (can run in parallel)
|
||||
|
||||
3. **Spawn Specialized Teammates**
|
||||
```
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "implementer",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim implementation tasks, execute, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "tester",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim testing tasks, run tests, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
4. **Coordinate and Monitor**
|
||||
- Team lead monitors task completion
|
||||
- Spawn additional workers as phases unblock
|
||||
- Handle plan approval if required
|
||||
|
||||
5. **Cleanup**
|
||||
```
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "implementer" })
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "tester" })
|
||||
Teammate({ operation: "cleanup" })
|
||||
```
|
||||
|
||||
See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### Start Fast, Execute Faster
|
||||
|
||||
- Get clarification once at the start, then execute
|
||||
- Don't wait for perfect understanding - ask questions and move
|
||||
- The goal is to **finish the feature**, not create perfect process
|
||||
|
||||
### The Plan is Your Guide
|
||||
|
||||
- Work documents should reference similar code and patterns
|
||||
- Load those references and follow them
|
||||
- Don't reinvent - match what exists
|
||||
|
||||
### Test As You Go
|
||||
|
||||
- Run tests after each change, not at the end
|
||||
- Fix failures immediately
|
||||
- Continuous testing prevents big surprises
|
||||
|
||||
### Quality is Built In
|
||||
|
||||
- Follow existing patterns
|
||||
- Write tests for new code
|
||||
- Run linting before pushing
|
||||
- Use reviewer agents for complex/risky changes only
|
||||
|
||||
### Ship Complete Features
|
||||
|
||||
- Mark all tasks completed before moving on
|
||||
- Don't leave features 80% done
|
||||
- A finished feature that ships beats a perfect feature that doesn't
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before creating PR, verify:
|
||||
|
||||
- [ ] All clarifying questions asked and answered
|
||||
- [ ] All TodoWrite tasks marked completed
|
||||
- [ ] Tests pass (run project's test command)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] All new names pass naming scrutiny (caller's perspective, no false qualifiers, correct visibility, consistent conventions, precise, complete words, correct part of speech)
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Before/after screenshots captured and uploaded (for UI changes)
|
||||
- [ ] Commit messages follow conventional format
|
||||
- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
|
||||
- [ ] PR description includes summary, testing notes, and screenshots
|
||||
- [ ] PR description includes Compound Engineered badge
|
||||
|
||||
## When to Use Reviewer Agents
|
||||
|
||||
**Don't use by default.** Use reviewer agents only when:
|
||||
|
||||
- Large refactor affecting many files (10+)
|
||||
- Security-sensitive changes (authentication, permissions, data access)
|
||||
- Performance-critical code paths
|
||||
- Complex algorithms or business logic
|
||||
- User explicitly requests thorough review
|
||||
|
||||
For most features: tests + linting + following patterns is sufficient.
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- **Analysis paralysis** - Don't overthink, read the plan and execute
|
||||
- **Skipping clarifying questions** - Ask now, not after building wrong thing
|
||||
- **Ignoring plan references** - The plan has links for a reason
|
||||
- **Testing at the end** - Test continuously or suffer later
|
||||
- **Forgetting TodoWrite** - Track progress or lose track of what's done
|
||||
- **80% done syndrome** - Finish the feature, don't move on early
|
||||
- **Over-reviewing simple changes** - Save reviewer agents for complex work
|
||||
Reference in New Issue
Block a user