171 lines
6.4 KiB
Markdown
171 lines
6.4 KiB
Markdown
---
|
|
name: writing-plans
|
|
description: |
|
|
Creates comprehensive implementation plans with exact file paths, complete code
|
|
examples, and verification steps for engineers with zero codebase context.
|
|
|
|
trigger: |
|
|
- Design phase complete (brainstorming/PRD/TRD validated)
|
|
- Need to create executable task breakdown
|
|
- Creating work for other engineers or AI agents
|
|
|
|
skip_when: |
|
|
- Design not validated → use brainstorming first
|
|
- Requirements still unclear → use pre-dev-prd-creation first
|
|
- Already have a plan → use executing-plans
|
|
|
|
sequence:
|
|
after: [brainstorming, pre-dev-trd-creation]
|
|
before: [executing-plans, subagent-driven-development]
|
|
|
|
related:
|
|
similar: [brainstorming]
|
|
---
|
|
|
|
# Writing Plans
|
|
|
|
## Overview
|
|
|
|
This skill dispatches a specialized agent to write comprehensive implementation plans for engineers with zero codebase context.
|
|
|
|
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
|
|
|
|
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
|
|
|
|
## The Process
|
|
|
|
**Step 1: Dispatch the write-plan agent**
|
|
|
|
Use the Task tool to launch the specialized planning agent:
|
|
|
|
```
|
|
Task(
|
|
subagent_type: "general-purpose",
|
|
description: "Write implementation plan",
|
|
prompt: "Use the write-plan agent to create a comprehensive implementation plan.
|
|
|
|
Load agents/write-plan.md and follow all instructions to:
|
|
- Understand the feature scope
|
|
- Read relevant codebase files
|
|
- Create bite-sized tasks (2-5 min each)
|
|
- Include exact file paths, complete code, and verification steps
|
|
- Add code review checkpoints
|
|
- Pass the Zero-Context Test
|
|
|
|
Save the plan to docs/plans/YYYY-MM-DD-<feature-name>.md and report back with execution options.",
|
|
model: "opus"
|
|
)
|
|
```
|
|
|
|
**Step 2: Ask user about execution**
|
|
|
|
After the agent completes and saves the plan, use `AskUserQuestion` to determine next steps:
|
|
|
|
```
|
|
AskUserQuestion(
|
|
questions: [{
|
|
header: "Execution",
|
|
question: "The plan is ready. Would you like to execute it now or save it for later?",
|
|
options: [
|
|
{ label: "Execute now", description: "Start implementation in current session using subagent-driven development" },
|
|
{ label: "Execute in parallel session", description: "Open a new agent session in the worktree for batch execution" },
|
|
{ label: "Save for later", description: "Keep the plan for manual review before execution" }
|
|
],
|
|
multiSelect: false
|
|
}]
|
|
)
|
|
```
|
|
|
|
**Based on response:**
|
|
- **Execute now** → Use `ring-default:subagent-driven-development` skill
|
|
- **Execute in parallel session** → Instruct user to open new session and use `ring-default:executing-plans`
|
|
- **Save for later** → Report plan location and end workflow
|
|
|
|
## Why Use an Agent?
|
|
|
|
**Context preservation:** Plan writing requires reading many files and analyzing architecture. Using a dedicated agent keeps the main supervisor's context clean.
|
|
|
|
**Model power:** The agent runs on Opus for comprehensive planning and attention to detail.
|
|
|
|
**Separation of concerns:** The supervisor orchestrates workflows, the agent focuses on deep planning work.
|
|
|
|
## What the Agent Does
|
|
|
|
The write-plan agent will:
|
|
1. Explore the codebase to understand architecture
|
|
2. Identify all files that need modification
|
|
3. Break the feature into bite-sized tasks (2-5 minutes each)
|
|
4. Write complete, copy-paste ready code for each task
|
|
5. Include exact commands with expected output
|
|
6. Add code review checkpoints after task batches
|
|
7. Verify the plan passes the Zero-Context Test
|
|
8. Save to `docs/plans/YYYY-MM-DD-<feature-name>.md`
|
|
9. Report back (supervisor then uses `AskUserQuestion` for execution choice)
|
|
|
|
## Requirements for Plans
|
|
|
|
The agent ensures every plan includes:
|
|
- ✅ Header with goal, architecture, tech stack, prerequisites
|
|
- ✅ Verification commands with expected output
|
|
- ✅ Exact file paths (never "somewhere in src")
|
|
- ✅ Complete code (never "add validation here")
|
|
- ✅ Bite-sized steps separated by verification
|
|
- ✅ Failure recovery steps
|
|
- ✅ Code review checkpoints with severity-based handling
|
|
- ✅ Passes Zero-Context Test (executable with only the document)
|
|
- ✅ **Recommended agents per task** (see Agent Selection below)
|
|
|
|
## Agent Selection for Execution
|
|
|
|
Plans should specify which specialized agents to use for each task type. During execution, prefer specialized agents over general-purpose when available.
|
|
|
|
**Pattern matching for agent selection:**
|
|
|
|
| Task Type | Agent Pattern | Examples |
|
|
|-----------|---------------|----------|
|
|
| Backend API/services | `ring-dev-team:backend-engineer-*` | `backend-engineer-golang`, `backend-engineer-python`, `backend-engineer-typescript` |
|
|
| Frontend UI/components | `ring-dev-team:frontend-engineer-*` | `frontend-engineer`, `frontend-engineer-typescript` |
|
|
| Infrastructure/CI/CD | `ring-dev-team:devops-engineer` | Single agent |
|
|
| Testing strategy | `ring-dev-team:qa-analyst` | Single agent |
|
|
| Monitoring/reliability | `ring-dev-team:sre` | Single agent |
|
|
|
|
**Plan header should include:**
|
|
```markdown
|
|
## Recommended Agents
|
|
- Backend tasks: `ring-dev-team:backend-engineer-golang` (or language variant: `-python`, `-typescript`)
|
|
- Frontend tasks: `ring-dev-team:frontend-engineer-typescript` (or generic `frontend-engineer`)
|
|
- Fallback: `general-purpose` if specialized agent unavailable
|
|
```
|
|
|
|
**Agent availability check:** If `ring-dev-team` plugin is not installed, execution falls back to `general-purpose` Task agents automatically.
|
|
|
|
## Execution Options Reference
|
|
|
|
When user selects an execution mode via `AskUserQuestion`:
|
|
|
|
**1. Execute now (Subagent-Driven)**
|
|
- Dispatches fresh subagent per task in current session
|
|
- Code review between tasks
|
|
- Fast iteration with quality gates
|
|
- Uses `ring-default:subagent-driven-development`
|
|
|
|
**2. Execute in parallel session**
|
|
- User opens new agent session in the worktree
|
|
- Batch execution with human review checkpoints
|
|
- Uses `ring-default:executing-plans`
|
|
|
|
**3. Save for later**
|
|
- Plan saved to `docs/plans/YYYY-MM-DD-<feature-name>.md`
|
|
- User reviews plan manually before deciding on execution
|
|
- Can invoke `ring-default:executing-plans` later with the plan file
|
|
|
|
## Required Patterns
|
|
|
|
This skill uses these universal patterns:
|
|
- **State Tracking:** See `skills/shared-patterns/state-tracking.md`
|
|
- **Failure Recovery:** See `skills/shared-patterns/failure-recovery.md`
|
|
- **Exit Criteria:** See `skills/shared-patterns/exit-criteria.md`
|
|
- **TodoWrite:** See `skills/shared-patterns/todowrite-integration.md`
|
|
|
|
Apply ALL patterns when using this skill.
|