feat(pi): add skills and improve AGENTS.md reading guidelines
- Add 'create-skill' skill for scaffolding new skill directories - Add 'planning' skill for structured implementation workflows - Add search-then-read pattern guidance to AGENTS.md
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: planning
|
||||
description: 'Create a structured plan before implementing broad or non-trivial changes. Use when user requests a new feature spanning multiple areas, significant refactoring, or explicitly asks to "plan this out". Produces a plan document in _scratch/, waits for user approval, then tracks progress as tasks are completed.'
|
||||
---
|
||||
|
||||
# Planning Workflow Skill
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger this workflow when:
|
||||
- A user requests a **broad or non-trivial change** (e.g. new feature spanning frontend/backend, significant refactoring)
|
||||
- A user says things like "plan this out", "create a plan", or "do this properly"
|
||||
|
||||
Don't trigger for routine multi-file changes like renames, simple bug fixes, or mechanical refactors.
|
||||
|
||||
## Rules
|
||||
|
||||
### 1. Always Start with a Plan
|
||||
|
||||
**Before touching any code**, create a markdown plan in `_scratch/plan-[short-name].md` with:
|
||||
- A clear title and status
|
||||
- Clarifications section (if any unknowns)
|
||||
- Phased tasks as checkboxes (`- [ ]`)
|
||||
|
||||
### 2. Ask Clarifying Questions First
|
||||
|
||||
When a requirement is **ambiguous or has multiple valid interpretations**:
|
||||
- List your interpretations
|
||||
- Ask the user to confirm
|
||||
- Document answers in the plan's "Clarifications" section
|
||||
|
||||
### 3. Wait for User Approval
|
||||
|
||||
Present the plan and wait for the user to confirm before implementing. If the user requests changes, update the plan first.
|
||||
|
||||
### 4. Update the Plan as You Work
|
||||
|
||||
- Change `- [ ]` to `- [x]` for completed items
|
||||
- Note any deviations from the original plan
|
||||
- If you discover new tasks, add them with a note explaining why
|
||||
|
||||
### 5. Plan Document Format
|
||||
|
||||
```markdown
|
||||
# Plan: [Feature Name]
|
||||
|
||||
> **Status**: ⏳ In Progress | ✅ Complete | ❌ Blocked
|
||||
|
||||
## Clarifications
|
||||
|
||||
- ~~Question?~~ **Answer**
|
||||
|
||||
## Tasks
|
||||
|
||||
### Phase 1: [Name]
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
### Phase 2: [Name]
|
||||
- [ ] Task 3
|
||||
|
||||
## Rollback Plan (if destructive/irreversible)
|
||||
[How to undo if needed]
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- ❌ Coding before the user approves the plan
|
||||
- ❌ Making assumptions about ambiguous requirements
|
||||
- ❌ Plans that are too vague ("update code")
|
||||
- ❌ Forgetting to update the plan as you work
|
||||
Reference in New Issue
Block a user