feat: Convert workflows:* commands to deprecation wrappers
Each wrapper forwards to the new ce:* equivalent with a deprecation notice. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -1,145 +1,10 @@
|
||||
---
|
||||
name: workflows:brainstorm
|
||||
description: Explore requirements and approaches through collaborative dialogue before planning implementation
|
||||
description: "[DEPRECATED] Use /ce:brainstorm instead — renamed for clarity."
|
||||
argument-hint: "[feature idea or problem to explore]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Brainstorm a Feature or Improvement
|
||||
NOTE: /workflows:brainstorm is deprecated. Please use /ce:brainstorm instead. This alias will be removed in a future version.
|
||||
|
||||
**Note: The current year is 2026.** Use this when dating brainstorm documents.
|
||||
|
||||
Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/workflows:plan`, which answers **HOW** to build it.
|
||||
|
||||
**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
|
||||
|
||||
## Feature Description
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
|
||||
|
||||
Do not proceed until you have a feature description from the user.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 0: Assess Requirements Clarity
|
||||
|
||||
Evaluate whether brainstorming is needed based on the feature description.
|
||||
|
||||
**Clear requirements indicators:**
|
||||
- Specific acceptance criteria provided
|
||||
- Referenced existing patterns to follow
|
||||
- Described exact expected behavior
|
||||
- Constrained, well-defined scope
|
||||
|
||||
**If requirements are already clear:**
|
||||
Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
|
||||
|
||||
### Phase 1: Understand the Idea
|
||||
|
||||
#### 1.1 Repository Research (Lightweight)
|
||||
|
||||
Run a quick repo scan to understand existing patterns:
|
||||
|
||||
- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
|
||||
|
||||
Focus on: similar features, established patterns, CLAUDE.md guidance.
|
||||
|
||||
#### 1.2 Collaborative Dialogue
|
||||
|
||||
Use the **AskUserQuestion tool** to ask questions **one at a time**.
|
||||
|
||||
**Guidelines (see `brainstorming` skill for detailed techniques):**
|
||||
- Prefer multiple choice when natural options exist
|
||||
- Start broad (purpose, users) then narrow (constraints, edge cases)
|
||||
- Validate assumptions explicitly
|
||||
- Ask about success criteria
|
||||
|
||||
**Exit condition:** Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
### Phase 2: Explore Approaches
|
||||
|
||||
Propose **2-3 concrete approaches** based on research and conversation.
|
||||
|
||||
For each approach, provide:
|
||||
- Brief description (2-3 sentences)
|
||||
- Pros and cons
|
||||
- When it's best suited
|
||||
|
||||
Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
|
||||
|
||||
Use **AskUserQuestion tool** to ask which approach the user prefers.
|
||||
|
||||
### Phase 3: Capture the Design
|
||||
|
||||
Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`.
|
||||
|
||||
**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.
|
||||
|
||||
### Phase 4: Handoff
|
||||
|
||||
Use **AskUserQuestion tool** to present next steps:
|
||||
|
||||
**Question:** "Brainstorm captured. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Review and refine** - Improve the document through structured self-review
|
||||
2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
3. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
4. **Ask more questions** - I have more questions to clarify before moving on
|
||||
5. **Done for now** - Return later
|
||||
|
||||
**If user selects "Share to Proof":**
|
||||
|
||||
```bash
|
||||
CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md)
|
||||
TITLE="Brainstorm: <topic title>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
|
||||
Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
|
||||
|
||||
If the curl fails, skip silently. Then return to the Phase 4 options.
|
||||
|
||||
**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4.
|
||||
|
||||
**If user selects "Review and refine":**
|
||||
|
||||
Load the `document-review` skill and apply it to the brainstorm document.
|
||||
|
||||
When document-review returns "Review complete", present next steps:
|
||||
|
||||
1. **Move to planning** - Continue to `/workflows:plan` with this document
|
||||
2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
```
|
||||
Brainstorm complete!
|
||||
|
||||
Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
|
||||
|
||||
Key decisions:
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
Next: Run `/workflows:plan` when ready to implement.
|
||||
```
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
|
||||
- **Ask one question at a time** - Don't overwhelm
|
||||
- **Apply YAGNI** - Prefer simpler approaches
|
||||
- **Keep outputs concise** - 200-300 words per section max
|
||||
|
||||
NEVER CODE! Just explore and document decisions.
|
||||
/ce:brainstorm $ARGUMENTS
|
||||
|
||||
@@ -1,240 +1,10 @@
|
||||
---
|
||||
name: workflows:compound
|
||||
description: Document a recently solved problem to compound your team's knowledge
|
||||
description: "[DEPRECATED] Use /ce:compound instead — renamed for clarity."
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# /compound
|
||||
NOTE: /workflows:compound is deprecated. Please use /ce:compound instead. This alias will be removed in a future version.
|
||||
|
||||
Coordinate multiple subagents working in parallel to document a recently solved problem.
|
||||
|
||||
## Purpose
|
||||
|
||||
Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
|
||||
|
||||
**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/workflows:compound # Document the most recent fix
|
||||
/workflows:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Two-Phase Orchestration
|
||||
|
||||
<critical_requirement>
|
||||
**Only ONE file gets written - the final documentation.**
|
||||
|
||||
Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
|
||||
</critical_requirement>
|
||||
|
||||
### Phase 1: Parallel Research
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
|
||||
#### 1. **Context Analyzer**
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
#### 3. **Related Docs Finder**
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
#### 4. **Prevention Strategist**
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
#### 5. **Category Classifier**
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
### Phase 2: Assembly & Write
|
||||
|
||||
<sequential_tasks>
|
||||
|
||||
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
||||
|
||||
The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
1. Collect all text results from Phase 1 subagents
|
||||
2. Assemble complete markdown file from the collected pieces
|
||||
3. Validate YAML frontmatter against schema
|
||||
4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 3: Optional Enhancement
|
||||
|
||||
**WAIT for Phase 2 to complete before proceeding.**
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Based on problem type, optionally invoke specialized agents to review the documentation:
|
||||
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
## What It Captures
|
||||
|
||||
- **Problem symptom**: Exact error messages, observable behavior
|
||||
- **Investigation steps tried**: What didn't work and why
|
||||
- **Root cause analysis**: Technical explanation
|
||||
- **Working solution**: Step-by-step fix with code examples
|
||||
- **Prevention strategies**: How to avoid in future
|
||||
- **Cross-references**: Links to related issues and docs
|
||||
|
||||
## Preconditions
|
||||
|
||||
<preconditions enforcement="advisory">
|
||||
<check condition="problem_solved">
|
||||
Problem has been solved (not in-progress)
|
||||
</check>
|
||||
<check condition="solution_verified">
|
||||
Solution has been verified working
|
||||
</check>
|
||||
<check condition="non_trivial">
|
||||
Non-trivial problem (not simple typo or obvious error)
|
||||
</check>
|
||||
</preconditions>
|
||||
|
||||
## What It Creates
|
||||
|
||||
**Organized documentation:**
|
||||
|
||||
- File: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
**Categories auto-detected from problem:**
|
||||
|
||||
- build-errors/
|
||||
- test-failures/
|
||||
- runtime-errors/
|
||||
- performance-issues/
|
||||
- database-issues/
|
||||
- security-issues/
|
||||
- ui-bugs/
|
||||
- integration-issues/
|
||||
- logic-errors/
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| ❌ Wrong | ✅ Correct |
|
||||
|----------|-----------|
|
||||
| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
|
||||
| Research and assembly run in parallel | Research completes → then assembly runs |
|
||||
| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Documentation complete
|
||||
|
||||
Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: 3 code fixes
|
||||
✓ Related Docs Finder: 2 related issues
|
||||
✓ Prevention Strategist: Prevention strategies, test suggestions
|
||||
✓ Category Classifier: `performance-issues`
|
||||
|
||||
Specialized Agent Reviews (Auto-Triggered):
|
||||
✓ performance-oracle: Validated query optimization approach
|
||||
✓ kieran-rails-reviewer: Code examples meet Rails standards
|
||||
✓ code-simplicity-reviewer: Solution is appropriately minimal
|
||||
✓ every-style-editor: Documentation style verified
|
||||
|
||||
File created:
|
||||
- docs/solutions/performance-issues/n-plus-one-brief-generation.md
|
||||
|
||||
This documentation will be searchable for future reference when similar
|
||||
issues occur in the Email Processing or Brief System modules.
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Link related documentation
|
||||
3. Update other references
|
||||
4. View documentation
|
||||
5. Other
|
||||
```
|
||||
|
||||
## The Compounding Philosophy
|
||||
|
||||
This creates a compounding knowledge system:
|
||||
|
||||
1. First time you solve "N+1 query in brief generation" → Research (30 min)
|
||||
2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
|
||||
3. Next time similar issue occurs → Quick lookup (2 min)
|
||||
4. Knowledge compounds → Team gets smarter
|
||||
|
||||
The feedback loop:
|
||||
|
||||
```
|
||||
Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
|
||||
↑ ↓
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Each unit of engineering work should make subsequent units of work easier—not harder.**
|
||||
|
||||
## Auto-Invoke
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /workflows:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## Routes To
|
||||
|
||||
`compound-docs` skill
|
||||
|
||||
## Applicable Specialized Agents
|
||||
|
||||
Based on problem type, these agents can enhance documentation:
|
||||
|
||||
### Code Quality & Review
|
||||
- **kieran-rails-reviewer**: Reviews code examples for Rails best practices
|
||||
- **code-simplicity-reviewer**: Ensures solution code is minimal and clear
|
||||
- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues
|
||||
|
||||
### Specific Domain Experts
|
||||
- **performance-oracle**: Analyzes performance_issue category solutions
|
||||
- **security-sentinel**: Reviews security_issue solutions for vulnerabilities
|
||||
- **cora-test-reviewer**: Creates test cases for prevention strategies
|
||||
- **data-integrity-guardian**: Reviews database_issue migrations and queries
|
||||
|
||||
### Enhancement & Documentation
|
||||
- **best-practices-researcher**: Enriches solution with industry best practices
|
||||
- **every-style-editor**: Reviews documentation style and clarity
|
||||
- **framework-docs-researcher**: Links to Rails/gem documentation references
|
||||
|
||||
### When to Invoke
|
||||
- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
|
||||
- **Manual trigger**: User can invoke agents after /workflows:compound completes for deeper review
|
||||
- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/workflows:plan` - Planning workflow (references documented solutions)
|
||||
/ce:compound $ARGUMENTS
|
||||
|
||||
@@ -1,636 +1,10 @@
|
||||
---
|
||||
name: workflows:plan
|
||||
description: Transform feature descriptions into well-structured project plans following conventions
|
||||
description: "[DEPRECATED] Use /ce:plan instead — renamed for clarity."
|
||||
argument-hint: "[feature description, bug report, or improvement idea]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Create a plan for a new feature or bug fix
|
||||
NOTE: /workflows:plan is deprecated. Please use /ce:plan instead. This alias will be removed in a future version.
|
||||
|
||||
## 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 **thoroughly** — every section matters
|
||||
2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
|
||||
3. Extract and carry forward **ALL** of the following into the plan:
|
||||
- Key decisions and their rationale
|
||||
- Chosen approach and why alternatives were rejected
|
||||
- Constraints and requirements discovered during brainstorming
|
||||
- Open questions (flag these for resolution during planning)
|
||||
- Success criteria and scope boundaries
|
||||
- Any specific technical choices or patterns discussed
|
||||
4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build
|
||||
5. Use brainstorm content as the **primary input** to research and planning phases
|
||||
6. **Critical: The brainstorm is the origin document.** Throughout the plan, reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
|
||||
7. **Do not omit brainstorm content** — if the brainstorm discussed it, the plan must address it (even if briefly). Scan each brainstorm section before finalizing the plan to verify nothing was dropped.
|
||||
|
||||
**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 compound-engineering:workflow: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
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [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
|
||||
```
|
||||
|
||||
## Sources
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- 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
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Comprehensive description]
|
||||
|
||||
## Problem Statement / Motivation
|
||||
|
||||
[Why this matters]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[High-level approach]
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Architecture impacts
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph**: [What callbacks/middleware/observers fire when this runs?]
|
||||
- **Error propagation**: [How do errors flow across layers? Do retry strategies align?]
|
||||
- **State lifecycle risks**: [Can partial failure leave orphaned/inconsistent state?]
|
||||
- **API surface parity**: [What other interfaces expose similar functionality and need the same change?]
|
||||
- **Integration test scenarios**: [Cross-layer scenarios that unit tests won't catch]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Detailed requirement 1
|
||||
- [ ] Detailed requirement 2
|
||||
- [ ] Testing requirements
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[How we measure success]
|
||||
|
||||
## Dependencies & Risks
|
||||
|
||||
[What could block or complicate this]
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- 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
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [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]
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
### Interaction Graph
|
||||
|
||||
[Map the chain reaction: what callbacks, middleware, observers, and event handlers fire when this code runs? Trace at least two levels deep. Document: "Action X triggers Y, which calls Z, which persists W."]
|
||||
|
||||
### Error & Failure Propagation
|
||||
|
||||
[Trace errors from lowest layer up. List specific error classes and where they're handled. Identify retry conflicts, unhandled error types, and silent failure swallowing.]
|
||||
|
||||
### State Lifecycle Risks
|
||||
|
||||
[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.]
|
||||
|
||||
### API Surface Parity
|
||||
|
||||
[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.]
|
||||
|
||||
### Integration Test Scenarios
|
||||
|
||||
[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.]
|
||||
|
||||
## 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]
|
||||
|
||||
## Sources & References
|
||||
|
||||
### Origin
|
||||
|
||||
- **Brainstorm document:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm. Key decisions carried forward: [list 2-3 major decisions from brainstorm]
|
||||
|
||||
### 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
|
||||
|
||||
**Brainstorm cross-check (if plan originated from a brainstorm):**
|
||||
|
||||
Before finalizing, re-read the brainstorm document and verify:
|
||||
- [ ] Every key decision from the brainstorm is reflected in the plan
|
||||
- [ ] The chosen approach matches what was decided in the brainstorm
|
||||
- [ ] Constraints and requirements from the brainstorm are captured in acceptance criteria
|
||||
- [ ] Open questions from the brainstorm are either resolved or flagged
|
||||
- [ ] The `origin:` frontmatter field points to the brainstorm file
|
||||
- [ ] The Sources section includes the brainstorm with a summary of carried-forward decisions
|
||||
|
||||
**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
|
||||
- [ ] Add names of files in pseudo code examples and todo lists
|
||||
- [ ] Add an ERD mermaid diagram if applicable for new model changes
|
||||
|
||||
## Write Plan File
|
||||
|
||||
**REQUIRED: Write the plan file to disk before presenting any options.**
|
||||
|
||||
```bash
|
||||
mkdir -p docs/plans/
|
||||
```
|
||||
|
||||
Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
|
||||
|
||||
Confirm: "Plan written to docs/plans/[filename]"
|
||||
|
||||
**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
|
||||
|
||||
## 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 (DHH, Kieran, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
6. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
7. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
8. **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.
|
||||
- **Share to Proof** → Upload the plan to Proof:
|
||||
```bash
|
||||
CONTENT=$(cat docs/plans/<plan_filename>.md)
|
||||
TITLE="Plan: <plan title from frontmatter>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
Display: `View & collaborate in Proof: <PROOF_URL>` — skip silently if curl fails. Then return to options.
|
||||
- **`/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.
|
||||
/ce:plan $ARGUMENTS
|
||||
|
||||
@@ -1,525 +1,10 @@
|
||||
---
|
||||
name: workflows:review
|
||||
description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
|
||||
description: "[DEPRECATED] Use /ce:review instead — renamed for clarity."
|
||||
argument-hint: "[PR number, GitHub URL, branch name, or latest]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Review Command
|
||||
NOTE: /workflows:review is deprecated. Please use /ce:review instead. This alias will be removed in a future version.
|
||||
|
||||
<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>
|
||||
|
||||
### 2. 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 1: 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 2: 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>
|
||||
|
||||
### 3. Multi-Angle Review Perspectives
|
||||
|
||||
#### Technical Excellence Angle
|
||||
|
||||
- Code craftsmanship evaluation
|
||||
- Engineering best practices
|
||||
- Technical documentation quality
|
||||
- Tooling and automation assessment
|
||||
|
||||
#### 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: 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
|
||||
- Use standard template from `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- 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:
|
||||
|
||||
```bash
|
||||
skill: file-todos
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
|
||||
- Template location: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- 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: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
|
||||
**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
|
||||
- **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 3: 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-rails-reviewer
|
||||
- security-sentinel
|
||||
- performance-oracle
|
||||
- architecture-strategist
|
||||
- agent-native-reviewer
|
||||
- [other agents]
|
||||
|
||||
### 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
|
||||
````
|
||||
|
||||
### 6. 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.
|
||||
/ce:review $ARGUMENTS
|
||||
|
||||
@@ -1,470 +1,10 @@
|
||||
---
|
||||
name: workflows:work
|
||||
description: Execute work plans efficiently while maintaining quality and finishing features
|
||||
description: "[DEPRECATED] Use /ce:work instead — renamed for clarity."
|
||||
argument-hint: "[plan file, specification, or todo file path]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Work Plan Execution Command
|
||||
NOTE: /workflows:work is deprecated. Please use /ce:work instead. This alias will be removed in a future version.
|
||||
|
||||
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 System-Wide Test Check (see below)
|
||||
- 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)
|
||||
```
|
||||
|
||||
**System-Wide Test Check** — Before marking a task done, pause and ask:
|
||||
|
||||
| Question | What to do |
|
||||
|----------|------------|
|
||||
| **What fires when this runs?** Callbacks, middleware, observers, event handlers — trace two levels out from your change. | Read the actual code (not docs) for callbacks on models you touch, middleware in the request chain, `after_*` hooks. |
|
||||
| **Do my tests exercise the real chain?** If every dependency is mocked, the test proves your logic works *in isolation* — it says nothing about the interaction. | Write at least one integration test that uses real objects through the full callback/middleware chain. No mocks for the layers that interact. |
|
||||
| **Can failure leave orphaned state?** If your code persists state (DB row, cache, file) before calling an external service, what happens when the service fails? Does retry create duplicates? | Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent. |
|
||||
| **What other interfaces expose this?** Mixins, DSLs, alternative entry points (Agent vs Chat vs ChatMethods). | Grep for the method/behavior in related classes. If parity is needed, add it now — not as a follow-up. |
|
||||
| **Do error strategies align across layers?** Retry middleware + application fallback + framework error handling — do they conflict or create double execution? | List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises. |
|
||||
|
||||
**When to skip:** Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."
|
||||
|
||||
**When this matters most:** Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
|
||||
|
||||
**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. **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
|
||||
- **Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together.** If your change touches callbacks, middleware, or error handling — you need both.
|
||||
|
||||
5. **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
|
||||
|
||||
6. **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
|
||||
- [ ] 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
|
||||
/ce:work $ARGUMENTS
|
||||
|
||||
Reference in New Issue
Block a user