[2.9.0] Rename plugin to compound-engineering
BREAKING: Plugin renamed from compounding-engineering to compound-engineering. Users will need to reinstall with the new name: claude /plugin install compound-engineering Changes: - Renamed plugin directory and all references - Updated documentation counts (24 agents, 19 commands) - Added julik-frontend-races-reviewer to docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
137
plugins/compound-engineering/commands/changelog.md
Normal file
137
plugins/compound-engineering/commands/changelog.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
name: changelog
|
||||
description: Create engaging changelogs for recent merges to main branch
|
||||
argument-hint: "[optional: daily|weekly, or time period in days]"
|
||||
---
|
||||
|
||||
You are a witty and enthusiastic product marketer tasked with creating a fun, engaging change log for an internal development team. Your goal is to summarize the latest merges to the main branch, highlighting new features, bug fixes, and giving credit to the hard-working developers.
|
||||
|
||||
## Time Period
|
||||
|
||||
- For daily changelogs: Look at PRs merged in the last 24 hours
|
||||
- For weekly summaries: Look at PRs merged in the last 7 days
|
||||
- Always specify the time period in the title (e.g., "Daily" vs "Weekly")
|
||||
- Default: Get the latest changes from the last day from the main branch of the repository
|
||||
|
||||
## PR Analysis
|
||||
|
||||
Analyze the provided GitHub changes and related issues. Look for:
|
||||
|
||||
1. New features that have been added
|
||||
2. Bug fixes that have been implemented
|
||||
3. Any other significant changes or improvements
|
||||
4. References to specific issues and their details
|
||||
5. Names of contributors who made the changes
|
||||
6. Use gh cli to lookup the PRs as well and the description of the PRs
|
||||
7. Check PR labels to identify feature type (feature, bug, chore, etc.)
|
||||
8. Look for breaking changes and highlight them prominently
|
||||
9. Include PR numbers for traceability
|
||||
10. Check if PRs are linked to issues and include issue context
|
||||
|
||||
## Content Priorities
|
||||
|
||||
1. Breaking changes (if any) - MUST be at the top
|
||||
2. User-facing features
|
||||
3. Critical bug fixes
|
||||
4. Performance improvements
|
||||
5. Developer experience improvements
|
||||
6. Documentation updates
|
||||
|
||||
## Formatting Guidelines
|
||||
|
||||
Now, create a change log summary with the following guidelines:
|
||||
|
||||
1. Keep it concise and to the point
|
||||
2. Highlight the most important changes first
|
||||
3. Group similar changes together (e.g., all new features, all bug fixes)
|
||||
4. Include issue references where applicable
|
||||
5. Mention the names of contributors, giving them credit for their work
|
||||
6. Add a touch of humor or playfulness to make it engaging
|
||||
7. Use emojis sparingly to add visual interest
|
||||
8. Keep total message under 2000 characters for Discord
|
||||
9. Use consistent emoji for each section
|
||||
10. Format code/technical terms in backticks
|
||||
11. Include PR numbers in parentheses (e.g., "Fixed login bug (#123)")
|
||||
|
||||
## Deployment Notes
|
||||
|
||||
When relevant, include:
|
||||
|
||||
- Database migrations required
|
||||
- Environment variable updates needed
|
||||
- Manual intervention steps post-deploy
|
||||
- Dependencies that need updating
|
||||
|
||||
Your final output should be formatted as follows:
|
||||
|
||||
<change_log>
|
||||
|
||||
# 🚀 [Daily/Weekly] Change Log: [Current Date]
|
||||
|
||||
## 🚨 Breaking Changes (if any)
|
||||
|
||||
[List any breaking changes that require immediate attention]
|
||||
|
||||
## 🌟 New Features
|
||||
|
||||
[List new features here with PR numbers]
|
||||
|
||||
## 🐛 Bug Fixes
|
||||
|
||||
[List bug fixes here with PR numbers]
|
||||
|
||||
## 🛠️ Other Improvements
|
||||
|
||||
[List other significant changes or improvements]
|
||||
|
||||
## 🙌 Shoutouts
|
||||
|
||||
[Mention contributors and their contributions]
|
||||
|
||||
## 🎉 Fun Fact of the Day
|
||||
|
||||
[Include a brief, work-related fun fact or joke]
|
||||
|
||||
</change_log>
|
||||
|
||||
## Style Guide Review
|
||||
|
||||
Now review the changelog using the EVERY_WRITE_STYLE.md file and go one by one to make sure you are following the style guide. Use multiple agents, run in parallel to make it faster.
|
||||
|
||||
Remember, your final output should only include the content within the <change_log> tags. Do not include any of your thought process or the original data in the output.
|
||||
|
||||
## Discord Posting (Optional)
|
||||
|
||||
You can post changelogs to Discord by adding your own webhook URL:
|
||||
|
||||
```
|
||||
# Set your Discord webhook URL
|
||||
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
|
||||
|
||||
# Post using curl
|
||||
curl -H "Content-Type: application/json" \
|
||||
-d "{\"content\": \"{{CHANGELOG}}\"}" \
|
||||
$DISCORD_WEBHOOK_URL
|
||||
```
|
||||
|
||||
To get a webhook URL, go to your Discord server → Server Settings → Integrations → Webhooks → New Webhook.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If no changes in the time period, post a "quiet day" message: "🌤️ Quiet day! No new changes merged."
|
||||
- If unable to fetch PR details, list the PR numbers for manual review
|
||||
- Always validate message length before posting to Discord (max 2000 chars)
|
||||
|
||||
## Schedule Recommendations
|
||||
|
||||
- Run daily at 6 AM NY time for previous day's changes
|
||||
- Run weekly summary on Mondays for the previous week
|
||||
- Special runs after major releases or deployments
|
||||
|
||||
## Audience Considerations
|
||||
|
||||
Adjust the tone and detail level based on the channel:
|
||||
|
||||
- **Dev team channels**: Include technical details, performance metrics, code snippets
|
||||
- **Product team channels**: Focus on user-facing changes and business impact
|
||||
- **Leadership channels**: Highlight progress on key initiatives and blockers
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
description: Create or edit Claude Code skills with expert guidance on structure and best practices
|
||||
allowed-tools: Skill(create-agent-skills)
|
||||
argument-hint: [skill description or requirements]
|
||||
---
|
||||
|
||||
Invoke the create-agent-skills skill for: $ARGUMENTS
|
||||
112
plugins/compound-engineering/commands/deploy-docs.md
Normal file
112
plugins/compound-engineering/commands/deploy-docs.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: deploy-docs
|
||||
description: Validate and prepare documentation for GitHub Pages deployment
|
||||
---
|
||||
|
||||
# Deploy Documentation Command
|
||||
|
||||
Validate the documentation site and prepare it for GitHub Pages deployment.
|
||||
|
||||
## Step 1: Validate Documentation
|
||||
|
||||
Run these checks:
|
||||
|
||||
```bash
|
||||
# Count components
|
||||
echo "Agents: $(ls plugins/compound-engineering/agents/*.md | wc -l)"
|
||||
echo "Commands: $(ls plugins/compound-engineering/commands/*.md | wc -l)"
|
||||
echo "Skills: $(ls -d plugins/compound-engineering/skills/*/ 2>/dev/null | wc -l)"
|
||||
|
||||
# Validate JSON
|
||||
cat .claude-plugin/marketplace.json | jq . > /dev/null && echo "✓ marketplace.json valid"
|
||||
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq . > /dev/null && echo "✓ plugin.json valid"
|
||||
|
||||
# Check all HTML files exist
|
||||
for page in index agents commands skills mcp-servers changelog getting-started; do
|
||||
if [ -f "plugins/compound-engineering/docs/pages/${page}.html" ] || [ -f "plugins/compound-engineering/docs/${page}.html" ]; then
|
||||
echo "✓ ${page}.html exists"
|
||||
else
|
||||
echo "✗ ${page}.html MISSING"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Step 2: Check for Uncommitted Changes
|
||||
|
||||
```bash
|
||||
git status --porcelain plugins/compound-engineering/docs/
|
||||
```
|
||||
|
||||
If there are uncommitted changes, warn the user to commit first.
|
||||
|
||||
## Step 3: Deployment Instructions
|
||||
|
||||
Since GitHub Pages deployment requires a workflow file with special permissions, provide these instructions:
|
||||
|
||||
### First-time Setup
|
||||
|
||||
1. Create `.github/workflows/deploy-docs.yml` with the GitHub Pages workflow
|
||||
2. Go to repository Settings > Pages
|
||||
3. Set Source to "GitHub Actions"
|
||||
|
||||
### Deploying
|
||||
|
||||
After merging to `main`, the docs will auto-deploy. Or:
|
||||
|
||||
1. Go to Actions tab
|
||||
2. Select "Deploy Documentation to GitHub Pages"
|
||||
3. Click "Run workflow"
|
||||
|
||||
### Workflow File Content
|
||||
|
||||
```yaml
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'plugins/compound-engineering/docs/**'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/configure-pages@v4
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: 'plugins/compound-engineering/docs'
|
||||
- uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
## Step 4: Report Status
|
||||
|
||||
Provide a summary:
|
||||
|
||||
```
|
||||
## Deployment Readiness
|
||||
|
||||
✓ All HTML pages present
|
||||
✓ JSON files valid
|
||||
✓ Component counts match
|
||||
|
||||
### Next Steps
|
||||
- [ ] Commit any pending changes
|
||||
- [ ] Push to main branch
|
||||
- [ ] Verify GitHub Pages workflow exists
|
||||
- [ ] Check deployment at https://everyinc.github.io/every-marketplace/
|
||||
```
|
||||
162
plugins/compound-engineering/commands/generate_command.md
Normal file
162
plugins/compound-engineering/commands/generate_command.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
name: generate_command
|
||||
description: Create a new custom slash command following conventions and best practices
|
||||
argument-hint: "[command purpose and requirements]"
|
||||
---
|
||||
|
||||
# Create a Custom Claude Code Command
|
||||
|
||||
Create a new slash command in `.claude/commands/` for the requested task.
|
||||
|
||||
## Goal
|
||||
|
||||
#$ARGUMENTS
|
||||
|
||||
## Key Capabilities to Leverage
|
||||
|
||||
**File Operations:**
|
||||
- Read, Edit, Write - modify files precisely
|
||||
- Glob, Grep - search codebase
|
||||
- MultiEdit - atomic multi-part changes
|
||||
|
||||
**Development:**
|
||||
- Bash - run commands (git, tests, linters)
|
||||
- Task - launch specialized agents for complex tasks
|
||||
- TodoWrite - track progress with todo lists
|
||||
|
||||
**Web & APIs:**
|
||||
- WebFetch, WebSearch - research documentation
|
||||
- GitHub (gh cli) - PRs, issues, reviews
|
||||
- Playwright - browser automation, screenshots
|
||||
|
||||
**Integrations:**
|
||||
- AppSignal - logs and monitoring
|
||||
- Context7 - framework docs
|
||||
- Stripe, Todoist, Featurebase (if relevant)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be specific and clear** - detailed instructions yield better results
|
||||
2. **Break down complex tasks** - use step-by-step plans
|
||||
3. **Use examples** - reference existing code patterns
|
||||
4. **Include success criteria** - tests pass, linting clean, etc.
|
||||
5. **Think first** - use "think hard" or "plan" keywords for complex problems
|
||||
6. **Iterate** - guide the process step by step
|
||||
|
||||
## Required: YAML Frontmatter
|
||||
|
||||
**EVERY command MUST start with YAML frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: command-name
|
||||
description: Brief description of what this command does (max 100 chars)
|
||||
argument-hint: "[what arguments the command accepts]"
|
||||
---
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `name`: Lowercase command identifier (used internally)
|
||||
- `description`: Clear, concise summary of command purpose
|
||||
- `argument-hint`: Shows user what arguments are expected (e.g., `[file path]`, `[PR number]`, `[optional: format]`)
|
||||
|
||||
## Structure Your Command
|
||||
|
||||
```markdown
|
||||
# [Command Name]
|
||||
|
||||
[Brief description of what this command does]
|
||||
|
||||
## Steps
|
||||
|
||||
1. [First step with specific details]
|
||||
- Include file paths, patterns, or constraints
|
||||
- Reference existing code if applicable
|
||||
|
||||
2. [Second step]
|
||||
- Use parallel tool calls when possible
|
||||
- Check/verify results
|
||||
|
||||
3. [Final steps]
|
||||
- Run tests
|
||||
- Lint code
|
||||
- Commit changes (if appropriate)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Tests pass
|
||||
- [ ] Code follows style guide
|
||||
- [ ] Documentation updated (if needed)
|
||||
```
|
||||
|
||||
## Tips for Effective Commands
|
||||
|
||||
- **Use $ARGUMENTS** placeholder for dynamic inputs
|
||||
- **Reference CLAUDE.md** patterns and conventions
|
||||
- **Include verification steps** - tests, linting, visual checks
|
||||
- **Be explicit about constraints** - don't modify X, use pattern Y
|
||||
- **Use XML tags** for structured prompts: `<task>`, `<requirements>`, `<constraints>`
|
||||
|
||||
## Example Pattern
|
||||
|
||||
```markdown
|
||||
Implement #$ARGUMENTS following these steps:
|
||||
|
||||
1. Research existing patterns
|
||||
- Search for similar code using Grep
|
||||
- Read relevant files to understand approach
|
||||
|
||||
2. Plan the implementation
|
||||
- Think through edge cases and requirements
|
||||
- Consider test cases needed
|
||||
|
||||
3. Implement
|
||||
- Follow existing code patterns (reference specific files)
|
||||
- Write tests first if doing TDD
|
||||
- Ensure code follows CLAUDE.md conventions
|
||||
|
||||
4. Verify
|
||||
- Run tests: `bin/rails test`
|
||||
- Run linter: `bundle exec standardrb`
|
||||
- Check changes with git diff
|
||||
|
||||
5. Commit (optional)
|
||||
- Stage changes
|
||||
- Write clear commit message
|
||||
```
|
||||
|
||||
## Creating the Command File
|
||||
|
||||
1. **Create the file** at `.claude/commands/[name].md` (subdirectories like `workflows/` supported)
|
||||
2. **Start with YAML frontmatter** (see section above)
|
||||
3. **Structure the command** using the template above
|
||||
4. **Test the command** by using it with appropriate arguments
|
||||
|
||||
## Command File Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: command-name
|
||||
description: What this command does
|
||||
argument-hint: "[expected arguments]"
|
||||
---
|
||||
|
||||
# Command Title
|
||||
|
||||
Brief introduction of what the command does and when to use it.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: [First Major Step]
|
||||
|
||||
Details about what to do.
|
||||
|
||||
### Step 2: [Second Major Step]
|
||||
|
||||
Details about what to do.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Expected outcome 1
|
||||
- [ ] Expected outcome 2
|
||||
```
|
||||
141
plugins/compound-engineering/commands/heal-skill.md
Normal file
141
plugins/compound-engineering/commands/heal-skill.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
description: Heal skill documentation by applying corrections discovered during execution with approval workflow
|
||||
argument-hint: [optional: specific issue to fix]
|
||||
allowed-tools: [Read, Edit, Bash(ls:*), Bash(git:*)]
|
||||
---
|
||||
|
||||
<objective>
|
||||
Update a skill's SKILL.md and related files based on corrections discovered during execution.
|
||||
|
||||
Analyze the conversation to detect which skill is running, reflect on what went wrong, propose specific fixes, get user approval, then apply changes with optional commit.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
Skill detection: !`ls -1 ./skills/*/SKILL.md | head -5`
|
||||
</context>
|
||||
|
||||
<quick_start>
|
||||
<workflow>
|
||||
1. **Detect skill** from conversation context (invocation messages, recent SKILL.md references)
|
||||
2. **Reflect** on what went wrong and how you discovered the fix
|
||||
3. **Present** proposed changes with before/after diffs
|
||||
4. **Get approval** before making any edits
|
||||
5. **Apply** changes and optionally commit
|
||||
</workflow>
|
||||
</quick_start>
|
||||
|
||||
<process>
|
||||
<step_1 name="detect_skill">
|
||||
Identify the skill from conversation context:
|
||||
|
||||
- Look for skill invocation messages
|
||||
- Check which SKILL.md was recently referenced
|
||||
- Examine current task context
|
||||
|
||||
Set: `SKILL_NAME=[skill-name]` and `SKILL_DIR=./skills/$SKILL_NAME`
|
||||
|
||||
If unclear, ask the user.
|
||||
</step_1>
|
||||
|
||||
<step_2 name="reflection_and_analysis">
|
||||
Focus on $ARGUMENTS if provided, otherwise analyze broader context.
|
||||
|
||||
Determine:
|
||||
- **What was wrong**: Quote specific sections from SKILL.md that are incorrect
|
||||
- **Discovery method**: Context7, error messages, trial and error, documentation lookup
|
||||
- **Root cause**: Outdated API, incorrect parameters, wrong endpoint, missing context
|
||||
- **Scope of impact**: Single section or multiple? Related files affected?
|
||||
- **Proposed fix**: Which files, which sections, before/after for each
|
||||
</step_2>
|
||||
|
||||
<step_3 name="scan_affected_files">
|
||||
```bash
|
||||
ls -la $SKILL_DIR/
|
||||
ls -la $SKILL_DIR/references/ 2>/dev/null
|
||||
ls -la $SKILL_DIR/scripts/ 2>/dev/null
|
||||
```
|
||||
</step_3>
|
||||
|
||||
<step_4 name="present_proposed_changes">
|
||||
Present changes in this format:
|
||||
|
||||
```
|
||||
**Skill being healed:** [skill-name]
|
||||
**Issue discovered:** [1-2 sentence summary]
|
||||
**Root cause:** [brief explanation]
|
||||
|
||||
**Files to be modified:**
|
||||
- [ ] SKILL.md
|
||||
- [ ] references/[file].md
|
||||
- [ ] scripts/[file].py
|
||||
|
||||
**Proposed changes:**
|
||||
|
||||
### Change 1: SKILL.md - [Section name]
|
||||
**Location:** Line [X] in SKILL.md
|
||||
|
||||
**Current (incorrect):**
|
||||
```
|
||||
[exact text from current file]
|
||||
```
|
||||
|
||||
**Corrected:**
|
||||
```
|
||||
[new text]
|
||||
```
|
||||
|
||||
**Reason:** [why this fixes the issue]
|
||||
|
||||
[repeat for each change across all files]
|
||||
|
||||
**Impact assessment:**
|
||||
- Affects: [authentication/API endpoints/parameters/examples/etc.]
|
||||
|
||||
**Verification:**
|
||||
These changes will prevent: [specific error that prompted this]
|
||||
```
|
||||
</step_4>
|
||||
|
||||
<step_5 name="request_approval">
|
||||
```
|
||||
Should I apply these changes?
|
||||
|
||||
1. Yes, apply and commit all changes
|
||||
2. Apply but don't commit (let me review first)
|
||||
3. Revise the changes (I'll provide feedback)
|
||||
4. Cancel (don't make changes)
|
||||
|
||||
Choose (1-4):
|
||||
```
|
||||
|
||||
**Wait for user response. Do not proceed without approval.**
|
||||
</step_5>
|
||||
|
||||
<step_6 name="apply_changes">
|
||||
Only after approval (option 1 or 2):
|
||||
|
||||
1. Use Edit tool for each correction across all files
|
||||
2. Read back modified sections to verify
|
||||
3. If option 1, commit with structured message showing what was healed
|
||||
4. Confirm completion with file list
|
||||
</step_6>
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- Skill correctly detected from conversation context
|
||||
- All incorrect sections identified with before/after
|
||||
- User approved changes before application
|
||||
- All edits applied across SKILL.md and related files
|
||||
- Changes verified by reading back
|
||||
- Commit created if user chose option 1
|
||||
- Completion confirmed with file list
|
||||
</success_criteria>
|
||||
|
||||
<verification>
|
||||
Before completing:
|
||||
|
||||
- Read back each modified section to confirm changes applied
|
||||
- Ensure cross-file consistency (SKILL.md examples match references/)
|
||||
- Verify git commit created if option 1 was selected
|
||||
- Check no unintended files were modified
|
||||
</verification>
|
||||
7
plugins/compound-engineering/commands/plan_review.md
Normal file
7
plugins/compound-engineering/commands/plan_review.md
Normal file
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: plan_review
|
||||
description: Have multiple specialized agents review a plan in parallel
|
||||
argument-hint: "[plan file path or plan content]"
|
||||
---
|
||||
|
||||
Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review this plan in parallel.
|
||||
3
plugins/compound-engineering/commands/prime.md
Normal file
3
plugins/compound-engineering/commands/prime.md
Normal file
@@ -0,0 +1,3 @@
|
||||
Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused. Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code. Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.
|
||||
|
||||
ALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions.
|
||||
211
plugins/compound-engineering/commands/release-docs.md
Normal file
211
plugins/compound-engineering/commands/release-docs.md
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
name: release-docs
|
||||
description: Build and update the documentation site with current plugin components
|
||||
argument-hint: "[optional: --dry-run to preview changes without writing]"
|
||||
---
|
||||
|
||||
# Release Documentation Command
|
||||
|
||||
You are a documentation generator for the compound-engineering plugin. Your job is to ensure the documentation site at `plugins/compound-engineering/docs/` is always up-to-date with the actual plugin components.
|
||||
|
||||
## Overview
|
||||
|
||||
The documentation site is a static HTML/CSS/JS site based on the Evil Martians LaunchKit template. It needs to be regenerated whenever:
|
||||
|
||||
- Agents are added, removed, or modified
|
||||
- Commands are added, removed, or modified
|
||||
- Skills are added, removed, or modified
|
||||
- MCP servers are added, removed, or modified
|
||||
|
||||
## Step 1: Inventory Current Components
|
||||
|
||||
First, count and list all current components:
|
||||
|
||||
```bash
|
||||
# Count agents
|
||||
ls plugins/compound-engineering/agents/*.md | wc -l
|
||||
|
||||
# Count commands
|
||||
ls plugins/compound-engineering/commands/*.md | wc -l
|
||||
|
||||
# Count skills
|
||||
ls -d plugins/compound-engineering/skills/*/ 2>/dev/null | wc -l
|
||||
|
||||
# Count MCP servers
|
||||
ls -d plugins/compound-engineering/mcp-servers/*/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
Read all component files to get their metadata:
|
||||
|
||||
### Agents
|
||||
For each agent file in `plugins/compound-engineering/agents/*.md`:
|
||||
- Extract the frontmatter (name, description)
|
||||
- Note the category (Review, Research, Workflow, Design, Docs)
|
||||
- Get key responsibilities from the content
|
||||
|
||||
### Commands
|
||||
For each command file in `plugins/compound-engineering/commands/*.md`:
|
||||
- Extract the frontmatter (name, description, argument-hint)
|
||||
- Categorize as Workflow or Utility command
|
||||
|
||||
### Skills
|
||||
For each skill directory in `plugins/compound-engineering/skills/*/`:
|
||||
- Read the SKILL.md file for frontmatter (name, description)
|
||||
- Note any scripts or supporting files
|
||||
|
||||
### MCP Servers
|
||||
For each MCP server in `plugins/compound-engineering/mcp-servers/*/`:
|
||||
- Read the configuration and README
|
||||
- List the tools provided
|
||||
|
||||
## Step 2: Update Documentation Pages
|
||||
|
||||
### 2a. Update `docs/index.html`
|
||||
|
||||
Update the stats section with accurate counts:
|
||||
```html
|
||||
<div class="stats-grid">
|
||||
<div class="stat-card">
|
||||
<span class="stat-number">[AGENT_COUNT]</span>
|
||||
<span class="stat-label">Specialized Agents</span>
|
||||
</div>
|
||||
<!-- Update all stat cards -->
|
||||
</div>
|
||||
```
|
||||
|
||||
Ensure the component summary sections list key components accurately.
|
||||
|
||||
### 2b. Update `docs/pages/agents.html`
|
||||
|
||||
Regenerate the complete agents reference page:
|
||||
- Group agents by category (Review, Research, Workflow, Design, Docs)
|
||||
- Include for each agent:
|
||||
- Name and description
|
||||
- Key responsibilities (bullet list)
|
||||
- Usage example: `claude agent [agent-name] "your message"`
|
||||
- Use cases
|
||||
|
||||
### 2c. Update `docs/pages/commands.html`
|
||||
|
||||
Regenerate the complete commands reference page:
|
||||
- Group commands by type (Workflow, Utility)
|
||||
- Include for each command:
|
||||
- Name and description
|
||||
- Arguments (if any)
|
||||
- Process/workflow steps
|
||||
- Example usage
|
||||
|
||||
### 2d. Update `docs/pages/skills.html`
|
||||
|
||||
Regenerate the complete skills reference page:
|
||||
- Group skills by category (Development Tools, Content & Workflow, Image Generation)
|
||||
- Include for each skill:
|
||||
- Name and description
|
||||
- Usage: `claude skill [skill-name]`
|
||||
- Features and capabilities
|
||||
|
||||
### 2e. Update `docs/pages/mcp-servers.html`
|
||||
|
||||
Regenerate the MCP servers reference page:
|
||||
- For each server:
|
||||
- Name and purpose
|
||||
- Tools provided
|
||||
- Configuration details
|
||||
- Supported frameworks/services
|
||||
|
||||
## Step 3: Update Metadata Files
|
||||
|
||||
Ensure counts are consistent across:
|
||||
|
||||
1. **`plugins/compound-engineering/.claude-plugin/plugin.json`**
|
||||
- Update `description` with correct counts
|
||||
- Update `components` object with counts
|
||||
- Update `agents`, `commands` arrays with current items
|
||||
|
||||
2. **`.claude-plugin/marketplace.json`**
|
||||
- Update plugin `description` with correct counts
|
||||
|
||||
3. **`plugins/compound-engineering/README.md`**
|
||||
- Update intro paragraph with counts
|
||||
- Update component lists
|
||||
|
||||
## Step 4: Validate
|
||||
|
||||
Run validation checks:
|
||||
|
||||
```bash
|
||||
# Validate JSON files
|
||||
cat .claude-plugin/marketplace.json | jq .
|
||||
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .
|
||||
|
||||
# Verify counts match
|
||||
echo "Agents in files: $(ls plugins/compound-engineering/agents/*.md | wc -l)"
|
||||
grep -o "[0-9]* specialized agents" plugins/compound-engineering/docs/index.html
|
||||
|
||||
echo "Commands in files: $(ls plugins/compound-engineering/commands/*.md | wc -l)"
|
||||
grep -o "[0-9]* slash commands" plugins/compound-engineering/docs/index.html
|
||||
```
|
||||
|
||||
## Step 5: Report Changes
|
||||
|
||||
Provide a summary of what was updated:
|
||||
|
||||
```
|
||||
## Documentation Release Summary
|
||||
|
||||
### Component Counts
|
||||
- Agents: X (previously Y)
|
||||
- Commands: X (previously Y)
|
||||
- Skills: X (previously Y)
|
||||
- MCP Servers: X (previously Y)
|
||||
|
||||
### Files Updated
|
||||
- docs/index.html - Updated stats and component summaries
|
||||
- docs/pages/agents.html - Regenerated with X agents
|
||||
- docs/pages/commands.html - Regenerated with X commands
|
||||
- docs/pages/skills.html - Regenerated with X skills
|
||||
- docs/pages/mcp-servers.html - Regenerated with X servers
|
||||
- plugin.json - Updated counts and component lists
|
||||
- marketplace.json - Updated description
|
||||
- README.md - Updated component lists
|
||||
|
||||
### New Components Added
|
||||
- [List any new agents/commands/skills]
|
||||
|
||||
### Components Removed
|
||||
- [List any removed agents/commands/skills]
|
||||
```
|
||||
|
||||
## Dry Run Mode
|
||||
|
||||
If `--dry-run` is specified:
|
||||
- Perform all inventory and validation steps
|
||||
- Report what WOULD be updated
|
||||
- Do NOT write any files
|
||||
- Show diff previews of proposed changes
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If component files have invalid frontmatter, report the error and skip
|
||||
- If JSON validation fails, report and abort
|
||||
- Always maintain a valid state - don't partially update
|
||||
|
||||
## Post-Release
|
||||
|
||||
After successful release:
|
||||
1. Suggest updating CHANGELOG.md with documentation changes
|
||||
2. Remind to commit with message: `docs: Update documentation site to match plugin components`
|
||||
3. Remind to push changes
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full documentation release
|
||||
claude /release-docs
|
||||
|
||||
# Preview changes without writing
|
||||
claude /release-docs --dry-run
|
||||
|
||||
# After adding new agents
|
||||
claude /release-docs
|
||||
```
|
||||
150
plugins/compound-engineering/commands/report-bug.md
Normal file
150
plugins/compound-engineering/commands/report-bug.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: report-bug
|
||||
description: Report a bug in the compound-engineering plugin
|
||||
argument-hint: "[optional: brief description of the bug]"
|
||||
---
|
||||
|
||||
# Report a Compounding Engineering Plugin Bug
|
||||
|
||||
Report bugs encountered while using the compound-engineering plugin. This command gathers structured information and creates a GitHub issue for the maintainer.
|
||||
|
||||
## Step 1: Gather Bug Information
|
||||
|
||||
Use the AskUserQuestion tool to collect the following information:
|
||||
|
||||
**Question 1: Bug Category**
|
||||
- What type of issue are you experiencing?
|
||||
- Options: Agent not working, Command not working, Skill not working, MCP server issue, Installation problem, Other
|
||||
|
||||
**Question 2: Specific Component**
|
||||
- Which specific component is affected?
|
||||
- Ask for the name of the agent, command, skill, or MCP server
|
||||
|
||||
**Question 3: What Happened (Actual Behavior)**
|
||||
- Ask: "What happened when you used this component?"
|
||||
- Get a clear description of the actual behavior
|
||||
|
||||
**Question 4: What Should Have Happened (Expected Behavior)**
|
||||
- Ask: "What did you expect to happen instead?"
|
||||
- Get a clear description of expected behavior
|
||||
|
||||
**Question 5: Steps to Reproduce**
|
||||
- Ask: "What steps did you take before the bug occurred?"
|
||||
- Get reproduction steps
|
||||
|
||||
**Question 6: Error Messages**
|
||||
- Ask: "Did you see any error messages? If so, please share them."
|
||||
- Capture any error output
|
||||
|
||||
## Step 2: Collect Environment Information
|
||||
|
||||
Automatically gather:
|
||||
```bash
|
||||
# Get plugin version
|
||||
cat ~/.claude/plugins/installed_plugins.json 2>/dev/null | grep -A5 "compound-engineering" | head -10 || echo "Plugin info not found"
|
||||
|
||||
# Get Claude Code version
|
||||
claude --version 2>/dev/null || echo "Claude CLI version unknown"
|
||||
|
||||
# Get OS info
|
||||
uname -a
|
||||
```
|
||||
|
||||
## Step 3: Format the Bug Report
|
||||
|
||||
Create a well-structured bug report with:
|
||||
|
||||
```markdown
|
||||
## Bug Description
|
||||
|
||||
**Component:** [Type] - [Name]
|
||||
**Summary:** [Brief description from argument or collected info]
|
||||
|
||||
## Environment
|
||||
|
||||
- **Plugin Version:** [from installed_plugins.json]
|
||||
- **Claude Code Version:** [from claude --version]
|
||||
- **OS:** [from uname]
|
||||
|
||||
## What Happened
|
||||
|
||||
[Actual behavior description]
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
[Expected behavior description]
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Error Messages
|
||||
|
||||
```
|
||||
[Any error output]
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
|
||||
[Any other relevant information]
|
||||
|
||||
---
|
||||
*Reported via `/report-bug` command*
|
||||
```
|
||||
|
||||
## Step 4: Create GitHub Issue
|
||||
|
||||
Use the GitHub CLI to create the issue:
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo EveryInc/every-marketplace \
|
||||
--title "[compound-engineering] Bug: [Brief description]" \
|
||||
--body "[Formatted bug report from Step 3]" \
|
||||
--label "bug,compound-engineering"
|
||||
```
|
||||
|
||||
**Note:** If labels don't exist, create without labels:
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo EveryInc/every-marketplace \
|
||||
--title "[compound-engineering] Bug: [Brief description]" \
|
||||
--body "[Formatted bug report]"
|
||||
```
|
||||
|
||||
## Step 5: Confirm Submission
|
||||
|
||||
After the issue is created:
|
||||
1. Display the issue URL to the user
|
||||
2. Thank them for reporting the bug
|
||||
3. Let them know the maintainer (Kieran Klaassen) will be notified
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
✅ Bug report submitted successfully!
|
||||
|
||||
Issue: https://github.com/EveryInc/every-marketplace/issues/[NUMBER]
|
||||
Title: [compound-engineering] Bug: [description]
|
||||
|
||||
Thank you for helping improve the compound-engineering plugin!
|
||||
The maintainer will review your report and respond as soon as possible.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If `gh` CLI is not authenticated: Prompt user to run `gh auth login` first
|
||||
- If issue creation fails: Display the formatted report so user can manually create the issue
|
||||
- If required information is missing: Re-prompt for that specific field
|
||||
|
||||
## Privacy Notice
|
||||
|
||||
This command does NOT collect:
|
||||
- Personal information
|
||||
- API keys or credentials
|
||||
- Private code from your projects
|
||||
- File paths beyond basic OS info
|
||||
|
||||
Only technical information about the bug is included in the report.
|
||||
27
plugins/compound-engineering/commands/reproduce-bug.md
Normal file
27
plugins/compound-engineering/commands/reproduce-bug.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: reproduce-bug
|
||||
description: Reproduce and investigate a bug using logs and console inspection
|
||||
argument-hint: "[GitHub issue number]"
|
||||
---
|
||||
|
||||
Look at github issue #$ARGUMENTS and read the issue description and comments.
|
||||
|
||||
Then, run the following agents in parallel to reproduce the bug:
|
||||
|
||||
1. Task rails-console-explorer(issue_description)
|
||||
2. Task appsignal-log-investigator (issue_description)
|
||||
|
||||
Then think about the places it could go wrong looking at the codebase. Look for loggin output we can look for.
|
||||
|
||||
Then, run the following agents in parallel again to find any logs that could help us reproduce the bug.
|
||||
|
||||
1. Task rails-console-explorer(issue_description)
|
||||
2. Task appsignal-log-investigator (issue_description)
|
||||
|
||||
Keep running these agents until you have a good idea of what is going on.
|
||||
|
||||
**Reference Collection:**
|
||||
|
||||
- [ ] Document all research findings with specific file paths (e.g., `app/services/example_service.rb:42`)
|
||||
|
||||
Then, add a comment to the issue with the findings and how to reproduce the bug.
|
||||
34
plugins/compound-engineering/commands/resolve_parallel.md
Normal file
34
plugins/compound-engineering/commands/resolve_parallel.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: resolve_parallel
|
||||
description: Resolve all TODO comments using parallel processing
|
||||
argument-hint: "[optional: specific TODO pattern or file]"
|
||||
---
|
||||
|
||||
Resolve all TODO comments using parallel processing.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Gather the things todo from above.
|
||||
|
||||
### 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
|
||||
- Push to remote
|
||||
49
plugins/compound-engineering/commands/resolve_pr_parallel.md
Normal file
49
plugins/compound-engineering/commands/resolve_pr_parallel.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
---
|
||||
|
||||
Resolve all PR comments using parallel processing.
|
||||
|
||||
Claude Code automatically detects and understands your git context:
|
||||
|
||||
- Current branch detection
|
||||
- Associated PR context
|
||||
- All PR comments and review threads
|
||||
- Can work with any PR by specifying the PR number, or ask it.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Get all unresolved comments for PR
|
||||
|
||||
```bash
|
||||
gh pr status
|
||||
bin/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type.
|
||||
|
||||
### 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
|
||||
- Run bin/resolve-pr-thread THREAD_ID_1
|
||||
- Push to remote
|
||||
|
||||
Last, check bin/get-pr-comments PR_NUMBER again to see if all comments are resolved. They should be, if not, repeat the process from 1.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
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
|
||||
|
||||
### 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.
|
||||
- Push to remote
|
||||
310
plugins/compound-engineering/commands/triage.md
Normal file
310
plugins/compound-engineering/commands/triage.md
Normal file
@@ -0,0 +1,310 @@
|
||||
---
|
||||
name: triage
|
||||
description: Triage and categorize findings for the CLI todo system
|
||||
argument-hint: "[findings list or source type]"
|
||||
---
|
||||
|
||||
- First set the /model to Haiku
|
||||
- Then read all pending todos in the todos/ directory
|
||||
|
||||
Present all findings, decisions, or issues here one by one for triage. The goal is to go through each item and decide whether to add it to the CLI todo system.
|
||||
|
||||
**IMPORTANT: DO NOT CODE ANYTHING DURING TRIAGE!**
|
||||
|
||||
This command is for:
|
||||
|
||||
- Triaging code review findings
|
||||
- Processing security audit results
|
||||
- Reviewing performance analysis
|
||||
- Handling any other categorized findings that need tracking
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Present Each Finding
|
||||
|
||||
For each finding, present in this format:
|
||||
|
||||
```
|
||||
---
|
||||
Issue #X: [Brief Title]
|
||||
|
||||
Severity: 🔴 P1 (CRITICAL) / 🟡 P2 (IMPORTANT) / 🔵 P3 (NICE-TO-HAVE)
|
||||
|
||||
Category: [Security/Performance/Architecture/Bug/Feature/etc.]
|
||||
|
||||
Description:
|
||||
[Detailed explanation of the issue or improvement]
|
||||
|
||||
Location: [file_path:line_number]
|
||||
|
||||
Problem Scenario:
|
||||
[Step by step what's wrong or could happen]
|
||||
|
||||
Proposed Solution:
|
||||
[How to fix it]
|
||||
|
||||
Estimated Effort: [Small (< 2 hours) / Medium (2-8 hours) / Large (> 8 hours)]
|
||||
|
||||
---
|
||||
Do you want to add this to the todo list?
|
||||
1. yes - create todo file
|
||||
2. next - skip this item
|
||||
3. custom - modify before creating
|
||||
```
|
||||
|
||||
### Step 2: Handle User Decision
|
||||
|
||||
**When user says "yes":**
|
||||
|
||||
1. **Update existing todo file** (if it exists) or **Create new filename:**
|
||||
|
||||
If todo already exists (from code review):
|
||||
|
||||
- Rename file from `{id}-pending-{priority}-{desc}.md` → `{id}-ready-{priority}-{desc}.md`
|
||||
- Update YAML frontmatter: `status: pending` → `status: ready`
|
||||
- Keep issue_id, priority, and description unchanged
|
||||
|
||||
If creating new todo:
|
||||
|
||||
```
|
||||
{next_id}-ready-{priority}-{brief-description}.md
|
||||
```
|
||||
|
||||
Priority mapping:
|
||||
|
||||
- 🔴 P1 (CRITICAL) → `p1`
|
||||
- 🟡 P2 (IMPORTANT) → `p2`
|
||||
- 🔵 P3 (NICE-TO-HAVE) → `p3`
|
||||
|
||||
Example: `042-ready-p1-transaction-boundaries.md`
|
||||
|
||||
2. **Update YAML frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: ready # IMPORTANT: Change from "pending" to "ready"
|
||||
priority: p1 # or p2, p3 based on severity
|
||||
issue_id: "042"
|
||||
tags: [category, relevant-tags]
|
||||
dependencies: []
|
||||
---
|
||||
```
|
||||
|
||||
3. **Populate or update the file:**
|
||||
|
||||
```yaml
|
||||
# [Issue Title]
|
||||
|
||||
## Problem Statement
|
||||
[Description from finding]
|
||||
|
||||
## Findings
|
||||
- [Key discoveries]
|
||||
- Location: [file_path:line_number]
|
||||
- [Scenario details]
|
||||
|
||||
## Proposed Solutions
|
||||
|
||||
### Option 1: [Primary solution]
|
||||
- **Pros**: [Benefits]
|
||||
- **Cons**: [Drawbacks if any]
|
||||
- **Effort**: [Small/Medium/Large]
|
||||
- **Risk**: [Low/Medium/High]
|
||||
|
||||
## Recommended Action
|
||||
[Filled during triage - specific action plan]
|
||||
|
||||
## Technical Details
|
||||
- **Affected Files**: [List files]
|
||||
- **Related Components**: [Components affected]
|
||||
- **Database Changes**: [Yes/No - describe if yes]
|
||||
|
||||
## Resources
|
||||
- Original finding: [Source of this issue]
|
||||
- Related issues: [If any]
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] [Specific success criteria]
|
||||
- [ ] Tests pass
|
||||
- [ ] Code reviewed
|
||||
|
||||
## Work Log
|
||||
|
||||
### {date} - Approved for Work
|
||||
**By:** Claude Triage System
|
||||
**Actions:**
|
||||
- Issue approved during triage session
|
||||
- Status changed from pending → ready
|
||||
- Ready to be picked up and worked on
|
||||
|
||||
**Learnings:**
|
||||
- [Context and insights]
|
||||
|
||||
## Notes
|
||||
Source: Triage session on {date}
|
||||
```
|
||||
|
||||
4. **Confirm approval:** "✅ Approved: `{new_filename}` (Issue #{issue_id}) - Status: **ready** → Ready to work on"
|
||||
|
||||
**When user says "next":**
|
||||
|
||||
- **Delete the todo file** - Remove it from todos/ directory since it's not relevant
|
||||
- Skip to the next item
|
||||
- Track skipped items for summary
|
||||
|
||||
**When user says "custom":**
|
||||
|
||||
- Ask what to modify (priority, description, details)
|
||||
- Update the information
|
||||
- Present revised version
|
||||
- Ask again: yes/next/custom
|
||||
|
||||
### Step 3: Continue Until All Processed
|
||||
|
||||
- Process all items one by one
|
||||
- Track using TodoWrite for visibility
|
||||
- Don't wait for approval between items - keep moving
|
||||
|
||||
### Step 4: Final Summary
|
||||
|
||||
After all items processed:
|
||||
|
||||
````markdown
|
||||
## Triage Complete
|
||||
|
||||
**Total Items:** [X] **Todos Approved (ready):** [Y] **Skipped:** [Z]
|
||||
|
||||
### Approved Todos (Ready for Work):
|
||||
|
||||
- `042-ready-p1-transaction-boundaries.md` - Transaction boundary issue
|
||||
- `043-ready-p2-cache-optimization.md` - Cache performance improvement ...
|
||||
|
||||
### Skipped Items (Deleted):
|
||||
|
||||
- Item #5: [reason] - Removed from todos/
|
||||
- Item #12: [reason] - Removed from todos/
|
||||
|
||||
### Summary of Changes Made:
|
||||
|
||||
During triage, the following status updates occurred:
|
||||
|
||||
- **Pending → Ready:** Filenames and frontmatter updated to reflect approved status
|
||||
- **Deleted:** Todo files for skipped findings removed from todos/ directory
|
||||
- Each approved file now has `status: ready` in YAML frontmatter
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. View approved todos ready for work:
|
||||
```bash
|
||||
ls todos/*-ready-*.md
|
||||
```
|
||||
````
|
||||
|
||||
2. Start work on approved items:
|
||||
|
||||
```bash
|
||||
/resolve_todo_parallel # Work on multiple approved items efficiently
|
||||
```
|
||||
|
||||
3. Or pick individual items to work on
|
||||
|
||||
4. As you work, update todo status:
|
||||
- Ready → In Progress (in your local context as you work)
|
||||
- In Progress → Complete (rename file: ready → complete, update frontmatter)
|
||||
|
||||
```
|
||||
|
||||
## Example Response Format
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Issue #5: Missing Transaction Boundaries for Multi-Step Operations
|
||||
|
||||
Severity: 🔴 P1 (CRITICAL)
|
||||
|
||||
Category: Data Integrity / Security
|
||||
|
||||
Description: The google_oauth2_connected callback in GoogleOauthCallbacks concern performs multiple database operations without transaction protection. If any step fails midway, the database is left in an inconsistent state.
|
||||
|
||||
Location: app/controllers/concerns/google_oauth_callbacks.rb:13-50
|
||||
|
||||
Problem Scenario:
|
||||
|
||||
1. User.update succeeds (email changed)
|
||||
2. Account.save! fails (validation error)
|
||||
3. Result: User has changed email but no associated Account
|
||||
4. Next login attempt fails completely
|
||||
|
||||
Operations Without Transaction:
|
||||
|
||||
- User confirmation (line 13)
|
||||
- Waitlist removal (line 14)
|
||||
- User profile update (line 21-23)
|
||||
- Account creation (line 28-37)
|
||||
- Avatar attachment (line 39-45)
|
||||
- Journey creation (line 47)
|
||||
|
||||
Proposed Solution: Wrap all operations in ApplicationRecord.transaction do ... end block
|
||||
|
||||
Estimated Effort: Small (30 minutes)
|
||||
|
||||
---
|
||||
|
||||
Do you want to add this to the todo list?
|
||||
|
||||
1. yes - create todo file
|
||||
2. next - skip this item
|
||||
3. custom - modify before creating
|
||||
|
||||
```
|
||||
|
||||
## Important Implementation Details
|
||||
|
||||
### Status Transitions During Triage
|
||||
|
||||
**When "yes" is selected:**
|
||||
1. Rename file: `{id}-pending-{priority}-{desc}.md` → `{id}-ready-{priority}-{desc}.md`
|
||||
2. Update YAML frontmatter: `status: pending` → `status: ready`
|
||||
3. Update Work Log with triage approval entry
|
||||
4. Confirm: "✅ Approved: `{filename}` (Issue #{issue_id}) - Status: **ready**"
|
||||
|
||||
**When "next" is selected:**
|
||||
1. Delete the todo file from todos/ directory
|
||||
2. Skip to next item
|
||||
3. No file remains in the system
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
Every time you present a todo as a header, include:
|
||||
- **Progress:** X/Y completed (e.g., "3/10 completed")
|
||||
- **Estimated time remaining:** Based on how quickly you're progressing
|
||||
- **Pacing:** Monitor time per finding and adjust estimate accordingly
|
||||
|
||||
Example:
|
||||
```
|
||||
|
||||
Progress: 3/10 completed | Estimated time: ~2 minutes remaining
|
||||
|
||||
```
|
||||
|
||||
### Do Not Code During Triage
|
||||
|
||||
- ✅ Present findings
|
||||
- ✅ Make yes/next/custom decisions
|
||||
- ✅ Update todo files (rename, frontmatter, work log)
|
||||
- ❌ Do NOT implement fixes or write code
|
||||
- ❌ Do NOT add detailed implementation details
|
||||
- ❌ That's for /resolve_todo_parallel phase
|
||||
```
|
||||
|
||||
When done give these options
|
||||
|
||||
```markdown
|
||||
What would you like to do next?
|
||||
|
||||
1. run /resolve_todo_parallel to resolve the todos
|
||||
2. commit the todos
|
||||
3. nothing, go chill
|
||||
```
|
||||
17
plugins/compound-engineering/commands/workflows/codify.md
Normal file
17
plugins/compound-engineering/commands/workflows/codify.md
Normal file
@@ -0,0 +1,17 @@
|
||||
---
|
||||
name: codify
|
||||
description: "[DEPRECATED] Use /compound instead - Document solved problems"
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
---
|
||||
|
||||
# /codify is deprecated
|
||||
|
||||
**This command has been renamed to `/compound`.**
|
||||
|
||||
The new name better reflects the compounding engineering philosophy: each documented solution compounds your team's knowledge.
|
||||
|
||||
---
|
||||
|
||||
Tell the user: "Note: `/codify` has been renamed to `/compound`. Please use `/compound` going forward."
|
||||
|
||||
Now run the `/compound` command with the same arguments: #$ARGUMENTS
|
||||
202
plugins/compound-engineering/commands/workflows/compound.md
Normal file
202
plugins/compound-engineering/commands/workflows/compound.md
Normal file
@@ -0,0 +1,202 @@
|
||||
---
|
||||
name: compound
|
||||
description: Document a recently solved problem to compound your team's knowledge
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
---
|
||||
|
||||
# /compound
|
||||
|
||||
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
|
||||
/compound # Document the most recent fix
|
||||
/compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Parallel Subagents
|
||||
|
||||
This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
|
||||
|
||||
### 1. **Context Analyzer** (Parallel)
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against CORA schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
### 2. **Solution Extractor** (Parallel)
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
### 3. **Related Docs Finder** (Parallel)
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
### 4. **Prevention Strategist** (Parallel)
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
### 5. **Category Classifier** (Parallel)
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
### 6. **Documentation Writer** (Parallel)
|
||||
- Assembles complete markdown file
|
||||
- Validates YAML frontmatter
|
||||
- Formats content for readability
|
||||
- Creates the file in correct location
|
||||
|
||||
### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
|
||||
Based on problem type detected, automatically invoke applicable agents:
|
||||
- **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`
|
||||
|
||||
## 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/
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Parallel documentation generation complete
|
||||
|
||||
Primary Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: Extracted 3 code fixes
|
||||
✓ Related Docs Finder: Found 2 related issues
|
||||
✓ Prevention Strategist: Generated test cases
|
||||
✓ Category Classifier: docs/solutions/performance-issues/
|
||||
✓ Documentation Writer: Created complete markdown
|
||||
|
||||
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 /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 /compound completes for deeper review
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/plan` - Planning workflow (references documented solutions)
|
||||
424
plugins/compound-engineering/commands/workflows/plan.md
Normal file
424
plugins/compound-engineering/commands/workflows/plan.md
Normal file
@@ -0,0 +1,424 @@
|
||||
---
|
||||
name: 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 2025.** 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.
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Repository Research & Context Gathering
|
||||
|
||||
<thinking>
|
||||
First, I need to understand the project's conventions and existing patterns, leveraging all available resources and use paralel subagents to do this.
|
||||
</thinking>
|
||||
|
||||
Runn these three agents in paralel at the same time:
|
||||
|
||||
- Task repo-research-analyst(feature_description)
|
||||
- Task best-practices-researcher(feature_description)
|
||||
- Task framework-docs-researcher(feature_description)
|
||||
|
||||
**Reference Collection:**
|
||||
|
||||
- [ ] Document all research findings with specific file paths (e.g., `app/services/example_service.rb:42`)
|
||||
- [ ] Include URLs to external documentation and best practices guides
|
||||
- [ ] Create a reference list of similar issues or PRs (e.g., `#123`, `#456`)
|
||||
- [ ] Note any team conventions discovered in `CLAUDE.md` or team documentation
|
||||
|
||||
### 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:`, `fix:`, `docs:`)
|
||||
- [ ] Determine issue type: enhancement, bug, refactor
|
||||
|
||||
**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
|
||||
[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
|
||||
## 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
|
||||
## 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
|
||||
|
||||
**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
|
||||
|
||||
## Output Format
|
||||
|
||||
Write the plan to `plans/<issue_title>.md`
|
||||
|
||||
## Post-Generation Options
|
||||
|
||||
After writing the plan file, use the **AskUserQuestion tool** to present these options:
|
||||
|
||||
**Question:** "Plan ready at `plans/<issue_title>.md`. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Start `/work`** - Begin implementing this plan
|
||||
2. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity)
|
||||
3. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
4. **Simplify** - Reduce detail level
|
||||
5. **Rework** - Change approach or request specific changes
|
||||
|
||||
Based on selection:
|
||||
- **`/work`** → Call the /work command with the plan file path
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
|
||||
- **Rework** → Ask "What would you like changed?" then regenerate with changes
|
||||
- **Other** (automatically provided) → Accept free text, act on it
|
||||
|
||||
Loop back to options after Simplify/Rework until user selects `/work` or `/plan_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:**
|
||||
```bash
|
||||
# Extract title from plan filename (kebab-case to Title Case)
|
||||
# Read plan content for body
|
||||
gh issue create --title "feat: [Plan Title]" --body-file plans/<issue_title>.md
|
||||
```
|
||||
|
||||
3. **If Linear:**
|
||||
```bash
|
||||
# Use linear CLI if available, or provide instructions
|
||||
# linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.md)"
|
||||
```
|
||||
|
||||
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 `/work` or `/plan_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
405
plugins/compound-engineering/commands/workflows/review.md
Normal file
405
plugins/compound-engineering/commands/workflows/review.md
Normal file
@@ -0,0 +1,405 @@
|
||||
---
|
||||
name: 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 PR branch → proceed with analysis on current branch
|
||||
- [ ] If DIFFERENT branch → 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>
|
||||
|
||||
#### Parallel Agents to review the PR:
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Run ALL or most of these agents at the same time:
|
||||
|
||||
1. Task kieran-rails-reviewer(PR content)
|
||||
2. Task dhh-rails-reviewer(PR title)
|
||||
3. If turbo is used: Task rails-turbo-expert(PR content)
|
||||
4. Task git-history-analyzer(PR content)
|
||||
5. Task dependency-detective(PR content)
|
||||
6. Task pattern-recognition-specialist(PR content)
|
||||
7. Task architecture-strategist(PR content)
|
||||
8. Task code-philosopher(PR content)
|
||||
9. Task security-sentinel(PR content)
|
||||
10. Task performance-oracle(PR content)
|
||||
11. Task devops-harmony-analyst(PR content)
|
||||
12. Task data-integrity-guardian(PR content)
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
### 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
|
||||
|
||||
#### 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
|
||||
- [ ] 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
|
||||
- [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
|
||||
|
||||
```
|
||||
|
||||
### 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.
|
||||
```
|
||||
275
plugins/compound-engineering/commands/workflows/work.md
Normal file
275
plugins/compound-engineering/commands/workflows/work.md
Normal file
@@ -0,0 +1,275 @@
|
||||
---
|
||||
name: 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**
|
||||
|
||||
Choose your work style:
|
||||
|
||||
**Option A: Live work on current branch**
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
git checkout -b feature-branch-name
|
||||
```
|
||||
|
||||
**Option B: Parallel work with worktree (recommended for parallel development)**
|
||||
```bash
|
||||
# Ask user first: "Work in parallel with worktree or on current branch?"
|
||||
# If worktree:
|
||||
skill: git-worktree
|
||||
# The skill will create a new branch from main in an isolated worktree
|
||||
```
|
||||
|
||||
**Recommendation**: Use worktree if:
|
||||
- You want to work on multiple features simultaneously
|
||||
- You want to keep main clean while experimenting
|
||||
- You plan to switch between branches frequently
|
||||
|
||||
Use live branch if:
|
||||
- You're working on a single feature
|
||||
- You prefer staying in the main repository
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
2. **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
|
||||
|
||||
3. **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
|
||||
|
||||
4. **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
|
||||
|
||||
5. **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
|
||||
bin/rails test
|
||||
|
||||
# Run linting (per CLAUDE.md)
|
||||
# Use linting-agent before pushing to origin
|
||||
```
|
||||
|
||||
2. **Consider Reviewer Agents** (Optional)
|
||||
|
||||
Use for complex, risky, or large changes:
|
||||
|
||||
- **code-simplicity-reviewer**: Check for unnecessary complexity
|
||||
- **kieran-rails-reviewer**: Verify Rails conventions (Rails projects)
|
||||
- **performance-oracle**: Check for performance issues
|
||||
- **security-sentinel**: Scan for security vulnerabilities
|
||||
- **cora-test-reviewer**: Review test quality (CORA projects)
|
||||
|
||||
Run reviewers in parallel with Task tool:
|
||||
|
||||
```
|
||||
Task(code-simplicity-reviewer): "Review changes for simplicity"
|
||||
Task(kieran-rails-reviewer): "Check Rails conventions"
|
||||
```
|
||||
|
||||
Present findings to user 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
|
||||
|
||||
### 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. **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
|
||||
|
||||
## Screenshots/Videos
|
||||
[If UI changes]
|
||||
|
||||
## Figma Design
|
||||
[Link if applicable]
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR
|
||||
- Note any follow-up work needed
|
||||
- Suggest next steps if applicable
|
||||
|
||||
---
|
||||
|
||||
## 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 `bin/rails test`)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Commit messages follow conventional format
|
||||
- [ ] PR description includes summary and testing notes
|
||||
|
||||
## 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