chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,582 @@
|
||||
# Command Examples
|
||||
|
||||
This document provides complete, real-world examples of slash commands from the erk project. Use these as references when creating new commands.
|
||||
|
||||
## Example 1: submit-stack (Workflow Automation Pattern)
|
||||
|
||||
**Pattern:** Workflow Automation (Analyze → Act → Report)
|
||||
|
||||
**Full source:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create git commit and submit stack with Graphite
|
||||
argument-hint: <description>
|
||||
---
|
||||
|
||||
# Submit Stack
|
||||
|
||||
Automatically create a git commit with a helpful summary message and submit the entire Graphite stack as pull requests.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Analyze changes**: First checks for .PLAN.md file to understand context, otherwise reviews git status and diff
|
||||
2. **Create commit**: Generates a concise single-sentence commit message summarizing the changes
|
||||
3. **Restack**: Runs `gt restack` to ensure all branches in the stack are properly rebased
|
||||
4. **Submit stack**: Runs `gt submit --stack --publish --no-edit` to create/update PRs for the entire stack
|
||||
5. **Report results**: Shows the submitted PRs and their URLs
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# With description argument
|
||||
|
||||
/submit-stack "Add user authentication feature"
|
||||
|
||||
# Without argument (will analyze changes automatically)
|
||||
|
||||
/submit-stack
|
||||
\`\`\`
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
When this command is invoked:
|
||||
|
||||
### 1. Analyze Current Changes
|
||||
|
||||
**FIRST**: Check if `.PLAN.md` exists in the repository root:
|
||||
|
||||
\`\`\`bash
|
||||
if [ -f .PLAN.md ]; then
|
||||
|
||||
# Use .PLAN.md for context
|
||||
|
||||
else
|
||||
|
||||
# Fall back to git analysis
|
||||
|
||||
fi
|
||||
\`\`\`
|
||||
|
||||
If `.PLAN.md` exists:
|
||||
|
||||
- Read the plan file to understand what was implemented
|
||||
- Use the plan's summary and goals to create the commit message
|
||||
|
||||
If no `.PLAN.md`:
|
||||
|
||||
- Run `git status` and `git diff HEAD` to see changes
|
||||
- Review the changes to create an accurate summary
|
||||
|
||||
### 2. Create Git Commit
|
||||
|
||||
Based on the analysis:
|
||||
|
||||
- If user provided an argument, use it as the basis for the commit message
|
||||
- If `.PLAN.md` exists, summarize what was implemented from the plan
|
||||
- Otherwise, analyze the git changes and create a descriptive single-sentence summary
|
||||
- Ensure the commit message follows the repository's commit style (check `git log` for patterns)
|
||||
- **DO NOT include any Claude Code footer or co-authorship attribution**
|
||||
|
||||
\`\`\`bash
|
||||
git add .
|
||||
git commit -m "[Single sentence summary of what was done]"
|
||||
\`\`\`
|
||||
|
||||
### 3. Restack the Stack
|
||||
|
||||
Ensure all branches in the stack are properly rebased:
|
||||
|
||||
\`\`\`bash
|
||||
gt restack
|
||||
\`\`\`
|
||||
|
||||
### 4. Submit Stack
|
||||
|
||||
Submit all PRs in the stack without interactive prompts:
|
||||
|
||||
\`\`\`bash
|
||||
gt submit --stack --publish --no-edit --restack
|
||||
\`\`\`
|
||||
|
||||
Flags explained:
|
||||
|
||||
- `--stack`: Submit entire stack (upstack + downstack)
|
||||
- `--publish`: Publish any draft PRs
|
||||
- `--no-edit`: Use commit messages as PR titles/descriptions without prompting
|
||||
- `--restack`: Restack branches before submitting (if needed)
|
||||
|
||||
### 5. Show Results
|
||||
|
||||
After submission, show:
|
||||
|
||||
- Number of PRs created/updated
|
||||
- PR URLs (extract from `gt` output)
|
||||
- Current stack status with `gt log short`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Check for .PLAN.md FIRST** before analyzing git changes
|
||||
- **NEVER run additional exploration commands** beyond checking .PLAN.md, git status/diff/log
|
||||
- **Stage all changes** with `git add .` before committing
|
||||
- **Single sentence summary**: Keep commit message concise and focused
|
||||
- **Follow repo patterns**: Check recent commits with `git log` to match style
|
||||
- **NO Claude footer**: Do not add any attribution or generated-by footer
|
||||
- If there are no staged or unstaged changes, report to the user and exit
|
||||
|
||||
## Error Handling
|
||||
|
||||
If any step fails:
|
||||
|
||||
- Report the specific command that failed
|
||||
- Show the error message
|
||||
- Ask the user how to proceed (don't retry automatically)
|
||||
|
||||
## Example Output
|
||||
|
||||
\`\`\`
|
||||
Analyzing changes...
|
||||
✓ Found .PLAN.md - using plan context
|
||||
✓ Found changes in 3 files
|
||||
|
||||
Creating commit: "Add dot-agent submit-stack command for automated PR workflow"
|
||||
✓ Commit created
|
||||
|
||||
Restacking branches...
|
||||
✓ Stack restacked successfully
|
||||
|
||||
Submitting stack...
|
||||
✓ 2 PRs created/updated:
|
||||
|
||||
- PR #123: dot-agent-claude-folder-support (new)
|
||||
- PR #122: base-branch (updated)
|
||||
|
||||
Current stack:
|
||||
◯ dot-agent-claude-folder-support (current)
|
||||
◯ base-branch
|
||||
◉ main
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Key features of this example:**
|
||||
|
||||
- Argument handling (optional `<description>`)
|
||||
- Context file priority check (`.PLAN.md` first)
|
||||
- Conditional logic based on file existence
|
||||
- Specific command flags explained
|
||||
- Clear anti-patterns ("NEVER run additional exploration")
|
||||
- Expected output format shown
|
||||
|
||||
## Example 2: ensure-ci (Iterative Fixing Pattern)
|
||||
|
||||
**Pattern:** Iterative Fixing (Run → Parse → Fix → Repeat)
|
||||
|
||||
**Full source:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Run make all-ci and iteratively fix issues until all checks pass
|
||||
---
|
||||
|
||||
You are an implementation finalizer. Your task is to run `make all-ci` and iteratively fix any issues until all CI checks pass successfully.
|
||||
|
||||
## Your Mission
|
||||
|
||||
Run the full CI pipeline (`make all-ci`) and automatically fix any failures. Keep iterating until all checks pass or you get stuck on an issue that requires human intervention.
|
||||
|
||||
## CI Pipeline (make all-ci)
|
||||
|
||||
The `make all-ci` target runs these checks in order:
|
||||
|
||||
1. **lint** - Ruff linting checks
|
||||
2. **format** - Ruff code formatting checks
|
||||
3. **prettier-check** - Markdown formatting checks
|
||||
4. **pyright** - Type checking
|
||||
5. **test** - Pytest test suite
|
||||
|
||||
## Iteration Process
|
||||
|
||||
### 1. Initial Run
|
||||
|
||||
Start by running `make all-ci` to see the current state:
|
||||
|
||||
\`\`\`bash
|
||||
make all-ci
|
||||
\`\`\`
|
||||
|
||||
### 2. Parse Failures
|
||||
|
||||
Analyze the output to identify which check(s) failed. Common failure patterns:
|
||||
|
||||
- **Ruff lint failures**: Look for "ruff check" errors
|
||||
- **Format failures**: Look for "ruff format --check" or files that would be reformatted
|
||||
- **Prettier failures**: Look for markdown files that need formatting
|
||||
- **Pyright failures**: Look for type errors with file paths and line numbers
|
||||
- **Test failures**: Look for pytest failures with test names and assertion errors
|
||||
|
||||
### 3. Apply Targeted Fixes
|
||||
|
||||
Based on the failure type, apply appropriate fixes:
|
||||
|
||||
#### Ruff Lint Failures
|
||||
|
||||
\`\`\`bash
|
||||
make fix # Runs: uv run ruff check --fix --unsafe-fixes
|
||||
\`\`\`
|
||||
|
||||
#### Ruff Format Failures
|
||||
|
||||
\`\`\`bash
|
||||
make format # Runs: uv run ruff format
|
||||
\`\`\`
|
||||
|
||||
#### Prettier Failures
|
||||
|
||||
\`\`\`bash
|
||||
make prettier # Runs: prettier --write '\*_/_.md'
|
||||
\`\`\`
|
||||
|
||||
#### Pyright Type Errors
|
||||
|
||||
- Use Read tool to examine the file at the reported line number
|
||||
- Use Edit tool to fix type annotations, add type hints, or fix type mismatches
|
||||
- Follow the coding standards in AGENTS.md (use `list[...]` not `List[...]`, etc.)
|
||||
|
||||
#### Test Failures
|
||||
|
||||
- Read the test file and source file involved
|
||||
- Analyze the assertion error or exception
|
||||
- Edit the source code or test to fix the issue
|
||||
- Consider if the test is validating correct behavior
|
||||
|
||||
### 4. Verify Fix
|
||||
|
||||
After applying fixes, run `make all-ci` again to verify:
|
||||
|
||||
\`\`\`bash
|
||||
make all-ci
|
||||
\`\`\`
|
||||
|
||||
### 5. Repeat Until Success
|
||||
|
||||
Continue the cycle: run → identify failures → fix → verify
|
||||
|
||||
## Iteration Control
|
||||
|
||||
**Safety Limits:**
|
||||
|
||||
- **Maximum iterations**: 10 attempts
|
||||
- **Stuck detection**: If the same error appears 3 times in a row, stop
|
||||
- **Progress tracking**: Use TodoWrite to show iteration progress
|
||||
|
||||
## Progress Reporting
|
||||
|
||||
Use TodoWrite to track your progress:
|
||||
|
||||
\`\`\`
|
||||
Iteration 1: Fixing lint errors
|
||||
Iteration 2: Fixing format errors
|
||||
Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py
|
||||
Iteration 4: All checks passed
|
||||
\`\`\`
|
||||
|
||||
Update the status as you work through each iteration.
|
||||
|
||||
## When to Stop
|
||||
|
||||
**SUCCESS**: Stop when `make all-ci` exits with code 0 (all checks passed)
|
||||
|
||||
**STUCK**: Stop and report to user if:
|
||||
|
||||
1. You've completed 10 iterations without success
|
||||
2. The same error persists after 3 fix attempts
|
||||
3. You encounter an error you cannot automatically fix
|
||||
|
||||
## Stuck Reporting Format
|
||||
|
||||
If you get stuck, report clearly:
|
||||
|
||||
\`\`\`markdown
|
||||
|
||||
## Finalization Status: STUCK
|
||||
|
||||
I was unable to resolve the following issue after N attempts:
|
||||
|
||||
**Check**: [lint/format/prettier/pyright/test]
|
||||
|
||||
**Error**:
|
||||
[Exact error message]
|
||||
|
||||
**File**: [file path if applicable]
|
||||
|
||||
**Attempted Fixes**:
|
||||
|
||||
1. [What you tried first]
|
||||
2. [What you tried second]
|
||||
3. [What you tried third]
|
||||
|
||||
**Next Steps**:
|
||||
[Suggest what needs to be done manually]
|
||||
\`\`\`
|
||||
|
||||
## Success Reporting Format
|
||||
|
||||
When all checks pass:
|
||||
|
||||
\`\`\`markdown
|
||||
|
||||
## Finalization Status: SUCCESS
|
||||
|
||||
All CI checks passed after N iteration(s):
|
||||
|
||||
- Lint: PASSED
|
||||
- Format: PASSED
|
||||
- Prettier: PASSED
|
||||
- Pyright: PASSED
|
||||
- Tests: PASSED
|
||||
|
||||
The code is ready for commit/PR.
|
||||
\`\`\`
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
1. **Be systematic**: Fix one type of error at a time
|
||||
2. **Run full CI**: Always run full `make all-ci`, not individual checks
|
||||
3. **Track progress**: Use TodoWrite for every iteration
|
||||
4. **Don't guess**: Read files before making changes
|
||||
5. **Follow standards**: Adhere to AGENTS.md coding standards
|
||||
6. **Fail gracefully**: Report clearly when stuck
|
||||
7. **Be efficient**: Use targeted fixes (don't reformat everything for one lint error)
|
||||
|
||||
## Example Flow
|
||||
|
||||
\`\`\`
|
||||
Iteration 1:
|
||||
|
||||
- Run make all-ci
|
||||
- Found: 5 lint errors, 2 files need formatting
|
||||
- Fix: Run make fix && make format
|
||||
- Result: 3 lint errors remain
|
||||
|
||||
Iteration 2:
|
||||
|
||||
- Run make all-ci
|
||||
- Found: 3 lint errors (imports)
|
||||
- Fix: Edit files to fix import issues
|
||||
- Result: All lint/format pass, 2 type errors
|
||||
|
||||
Iteration 3:
|
||||
|
||||
- Run make all-ci
|
||||
- Found: 2 pyright errors in switch.py:45 and switch.py:67
|
||||
- Fix: Add type annotations
|
||||
- Result: All checks pass
|
||||
|
||||
SUCCESS
|
||||
\`\`\`
|
||||
|
||||
## Begin Now
|
||||
|
||||
Start by running `make all-ci` and begin the iterative fix process. Track your progress with TodoWrite and report your final status clearly.
|
||||
```
|
||||
|
||||
**Key features of this example:**
|
||||
|
||||
- Maximum iteration limit (10 attempts)
|
||||
- Stuck detection (same error 3 times)
|
||||
- Per-error-type fix instructions
|
||||
- TodoWrite progress tracking requirement
|
||||
- Clear success/failure reporting formats
|
||||
- Detailed example flow showing iterations
|
||||
|
||||
## Example 3: create-implementation-plan (Agent Delegation Pattern)
|
||||
|
||||
**Pattern:** Agent Delegation (Context → Delegate → Iterate)
|
||||
|
||||
**Full source:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create an implementation plan using the subagent agent
|
||||
---
|
||||
|
||||
## ⚠️ PLANNING-ONLY MODE ACTIVE
|
||||
|
||||
I'll help you create an implementation plan using the specialized planning agent. This workflow is designed for **planning only** - no code will be written until the plan is finalized and saved to disk.
|
||||
|
||||
### How This Works
|
||||
|
||||
1. **You provide context** about what needs to be built
|
||||
2. **The agent creates a plan** (displayed in terminal for review)
|
||||
3. **We iterate together** until the plan is perfect
|
||||
4. **Plan is saved to disk** as a markdown file
|
||||
5. **Then (and only then)** implementation can begin
|
||||
|
||||
### Provide Your Planning Context
|
||||
|
||||
You can share:
|
||||
|
||||
- A feature you want to implement
|
||||
- An error message or bug to fix
|
||||
- Performance issues to optimize
|
||||
- A refactoring goal
|
||||
- Any relevant context or requirements
|
||||
|
||||
**What would you like to plan?**
|
||||
|
||||
---
|
||||
|
||||
**IMPORTANT AGENT INSTRUCTIONS:**
|
||||
|
||||
When invoking the subagent agent:
|
||||
|
||||
1. **DO NOT write any code during planning phase**
|
||||
2. **DO NOT use Edit, Write, or any modification tools**
|
||||
3. **ONLY output the plan to terminal for iterative review**
|
||||
4. **ONLY persist to disk after explicit user approval**
|
||||
5. The agent should remain in "Phase 1: Human-Readable Planning" mode until the user explicitly approves with signals like "looks good", "approved", or "ready to implement"
|
||||
|
||||
The goal is to create a comprehensive implementation plan that will be saved as a `.md` file at the repository root, which can then guide future implementation work.
|
||||
```
|
||||
|
||||
**Key features of this example:**
|
||||
|
||||
- User-facing explanation of the workflow
|
||||
- Clear phase boundaries (planning vs implementation)
|
||||
- Explicit anti-patterns ("DO NOT write code")
|
||||
- User approval trigger ("looks good", "approved")
|
||||
- Tells agent which specialized agent to invoke
|
||||
- Specifies where to save output (`.md` at root)
|
||||
|
||||
## Example 4: codex-review (Simple Execution Pattern)
|
||||
|
||||
**Pattern:** Simple Execution (Parse Arguments → Execute → Return Output)
|
||||
|
||||
**Minimal example structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Perform a local code review using repository standards and best practices
|
||||
argument-hint: [base-branch]
|
||||
---
|
||||
|
||||
# Codex Review
|
||||
|
||||
Performs a thorough code review of changes between the current branch and the base branch.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. Determines base branch (uses provided argument or defaults to main/master)
|
||||
2. Runs codex-review script with the base branch
|
||||
3. Displays review findings and suggestions
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`bash
|
||||
|
||||
# With explicit base branch
|
||||
|
||||
/codex-review develop
|
||||
|
||||
# Without argument (auto-detects main/master)
|
||||
|
||||
/codex-review
|
||||
\`\`\`
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### 1. Determine Base Branch
|
||||
|
||||
If `[base-branch]` argument is provided:
|
||||
|
||||
- Use the specified branch
|
||||
|
||||
If no argument:
|
||||
|
||||
- Check if `main` branch exists: `git rev-parse --verify main`
|
||||
- If yes, use `main`
|
||||
- If no, use `master`
|
||||
|
||||
### 2. Run Review Script
|
||||
|
||||
Execute the review script with the determined base branch:
|
||||
|
||||
\`\`\`bash
|
||||
scripts/codex-review.py [base-branch]
|
||||
\`\`\`
|
||||
|
||||
### 3. Display Results
|
||||
|
||||
Show the script output directly to the user, including:
|
||||
|
||||
- Files reviewed
|
||||
- Issues found
|
||||
- Suggestions for improvements
|
||||
- Compliance with coding standards
|
||||
|
||||
## Error Handling
|
||||
|
||||
If the script fails:
|
||||
|
||||
- Show the error message
|
||||
- Check if the base branch exists
|
||||
- Verify the script is executable
|
||||
|
||||
## Notes
|
||||
|
||||
- Square brackets `[base-branch]` indicate optional argument
|
||||
- Script handles actual review logic
|
||||
- Command is a simple wrapper for convenience
|
||||
```
|
||||
|
||||
**Key features of this example:**
|
||||
|
||||
- Optional argument handling (square brackets)
|
||||
- Argument defaulting logic
|
||||
- Direct script invocation
|
||||
- Minimal additional logic
|
||||
- Clear output pass-through
|
||||
|
||||
## Pattern Comparison
|
||||
|
||||
| Feature | submit-stack | ensure-ci | create-implementation-plan | codex-review |
|
||||
| --------------------- | ------------------------ | ------------------ | -------------------------- | ------------------------ |
|
||||
| **Pattern** | Workflow Automation | Iterative Fixing | Agent Delegation | Simple Execution |
|
||||
| **Arguments** | Optional `<description>` | None | None | Optional `[base-branch]` |
|
||||
| **Context Files** | Checks `.PLAN.md` | Checks `AGENTS.md` | None | None |
|
||||
| **Iterations** | Single pass | Up to 10 | Iterative (user-driven) | Single pass |
|
||||
| **Tool Usage** | Git, Graphite | Make, Edit tools | Task tool (agent) | Script execution |
|
||||
| **Progress Tracking** | Inline reporting | TodoWrite required | None (user reviews) | None |
|
||||
| **Error Handling** | Ask user | Stop if stuck | None specified | Show error message |
|
||||
| **Success Criteria** | PRs submitted | Exit code 0 | User approves plan | Script completes |
|
||||
|
||||
## Usage Guidance
|
||||
|
||||
**Use submit-stack as a reference when:**
|
||||
|
||||
- Command needs to check context files first
|
||||
- Workflow has clear sequential steps
|
||||
- Git operations are involved
|
||||
- Results need clear reporting
|
||||
|
||||
**Use ensure-ci as a reference when:**
|
||||
|
||||
- Command needs to iterate until success
|
||||
- Multiple error types need different fixes
|
||||
- Progress tracking is important
|
||||
- Stuck detection is needed
|
||||
|
||||
**Use create-implementation-plan as a reference when:**
|
||||
|
||||
- Command delegates to specialized agent
|
||||
- User review/approval is required
|
||||
- No direct code modification should happen
|
||||
- Output is saved to specific location
|
||||
|
||||
**Use codex-review as a reference when:**
|
||||
|
||||
- Command is a simple wrapper
|
||||
- Main logic is in external script
|
||||
- Argument handling is straightforward
|
||||
- Output is passed through directly
|
||||
Reference in New Issue
Block a user