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:
2026-05-01 23:26:53 -04:00
parent e4d40d89d9
commit ba30222962
3 changed files with 141 additions and 0 deletions

View File

@@ -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