Creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps for engineers with zero codebase context.
This skill dispatches a specialized agent to write comprehensive implementation plans for engineers with zero codebase context.
Announce at start: "I'm using the ring:writing-plans skill to create the implementation plan."
Context: This should be run in a dedicated worktree (created by ring:brainstorming skill).
Step 1: Dispatch Write-Plan Agent
Dispatch via Task(subagent_type: "ring:write-plan") with:
docs/plans/YYYY-MM-DD-<feature-name>.mdStep 2: Validate Plan
After the plan is saved, validate it:
python3 default/lib/validate-plan-precedent.py docs/plans/YYYY-MM-DD-<feature>.md
Interpretation:
PASS → Plan is safe to executeWARNING → Plan has issues to address
Step 3: Ask User About Execution
Ask via AskUserQuestion: "Execute now?" Options:
ring:subagent-driven-developmentring:executing-plansContext preservation (reading many files keeps supervisor clean) | Model power (comprehensive planning) | Separation of concerns (supervisor orchestrates, agent plans)
Explore codebase → identify files → break into bite-sized tasks (2-5 min) → write complete code → include exact commands → add review checkpoints → verify Zero-Context Test → save to docs/plans/YYYY-MM-DD-<feature>.md → report back
Every plan: Header (goal, architecture, tech stack) | Verification commands with expected output | Exact file paths (never "somewhere in src") | Complete code (never "add validation here") | Bite-sized steps with verification | Failure recovery | Review checkpoints | Zero-Context Test | Recommended agents per task
If TopologyConfig exists (from pre-dev research.md frontmatter or user input):
Each task MUST include:
backend | frontend | sharedTask Format with Target:
## Task 3: Create User Login API
**Target:** backend
**Working Directory:** packages/api
**Agent:** ring:backend-engineer-golang
**Files to Create/Modify:**
- `packages/api/internal/handlers/auth.go`
- `packages/api/internal/services/auth_service.go`
...rest of task...
Target Assignment Rules:
| Target | When | Agent |
|---|---|---|
backend | API endpoints, services, data layer, CLI | ring:backend-engineer-{golang,typescript} |
frontend | UI components, pages, BFF routes | See Frontend Tasks (api_pattern aware) |
shared | CI/CD, configs, docs, cross-module | ring:devops-engineer or ring:general-purpose |
Working Directory Resolution:
| Topology Structure | Backend Path | Frontend Path |
|---|---|---|
single-repo | . | . |
monorepo | topology.modules.backend.path | topology.modules.frontend.path |
multi-repo | topology.modules.backend.path (absolute) | topology.modules.frontend.path (absolute) |
| Task Type | Agent |
|---|---|
| Go backend API/services | ring:backend-engineer-golang |
| TypeScript backend API/services | ring:backend-engineer-typescript |
Read api_pattern from topology configuration to determine correct agent:
| API Pattern | Task Type | Agent |
|---|---|---|
direct | UI components, pages, forms | ring:frontend-engineer |
direct | Server Actions, data fetching | ring:frontend-engineer |
direct | Server Components with data loading | ring:frontend-engineer |
bff | API routes (/api/*) | ring:frontend-bff-engineer-typescript |
bff | Data aggregation, transformation | ring:frontend-bff-engineer-typescript |
bff | External service integration | ring:frontend-bff-engineer-typescript |
bff | UI components, pages, forms | ring:frontend-engineer |
other | Depends on pattern | Ask user or use ring:frontend-engineer default |
def get_frontend_agent(task, topology):
api_pattern = topology.get('api_pattern', 'direct')
if api_pattern == 'direct':
return 'ring:frontend-engineer'
if api_pattern == 'bff':
if is_bff_task(task): # API routes, aggregation, transformation
return 'ring:frontend-bff-engineer-typescript'
else: # UI components, pages
return 'ring:frontend-engineer'
return 'ring:frontend-engineer' # Default for 'other'
def is_bff_task(task):
bff_indicators = [
'API route', 'api route', '/api/',
'aggregat', 'transform', 'BFF',
'external service', 'backend service',
'data layer', 'HTTP client'
]
return any(ind in task.description for ind in bff_indicators)
| Task Type | Agent |
|---|---|
| Infra/CI/CD | ring:devops-engineer |
| Testing | ring:qa-analyst |
| Reliability | ring:sre |
| Fallback | ring:general-purpose |
When TopologyConfig includes api_pattern, include it in task metadata:
## Task 3: Aggregate Dashboard Data
**Target:** frontend
**Working Directory:** packages/web
**API Pattern:** bff
**Agent:** ring:frontend-bff-engineer-typescript
**Files to Create/Modify:**
- `packages/web/app/api/dashboard/route.ts`
- `packages/web/lib/services/dashboard-aggregator.ts`
...rest of task...
| Option | Description |
|---|---|
| Execute now | Fresh subagent per task, code review between tasks → ring:subagent-driven-development |
| Parallel session | User opens new session, batch execution with human review → ring:executing-plans |
| Save for later | Plan at docs/plans/YYYY-MM-DD-<feature>.md, manual review before execution |
This skill uses these universal patterns:
skills/shared-patterns/state-tracking.mdskills/shared-patterns/failure-recovery.mdskills/shared-patterns/exit-criteria.mdskills/shared-patterns/todowrite-integration.mdApply ALL patterns when using this skill.
STOP and report if:
| Decision Type | Blocker Condition | Required Action |
|---|---|---|
| Design Validation | Design phase not complete (brainstorming/PRD/TRD not validated) | STOP and report |
| Plan Validation | Plan fails validate-plan-precedent.py check | STOP and report |
| Zero-Context Test | Plan contains vague instructions ("add validation here") | STOP and report |
| Agent Assignment | Tasks missing recommended agent specification | STOP and report |
The following requirements CANNOT be waived:
| Severity | Condition | Required Action |
|---|---|---|
| CRITICAL | Plan created without validated design | MUST complete design phase first |
| CRITICAL | Tasks contain placeholder code ("add logic here") | MUST write complete code examples |
| HIGH | Plan fails validation script | MUST address warnings and re-validate |
| HIGH | Missing exact file paths in tasks | MUST specify complete paths |
| MEDIUM | Missing verification commands in tasks | Should add expected output verification |
| LOW | Missing review checkpoints between tasks | Fix in next iteration |
| User Says | Your Response |
|---|---|
| "Skip design validation, we know what to build" | "CANNOT skip design validation. Plans without validated design lead to rework. Design phase MUST be complete first." |
| "Add the code later, just outline the tasks" | "CANNOT use placeholder code. Zero-Context Test requires complete code so engineers can execute without codebase knowledge." |
| "Approximate file paths are fine" | "CANNOT use vague paths. Tasks MUST include exact file paths - never 'somewhere in src'." |
| "Skip plan validation, we're in a hurry" | "CANNOT skip validation. Plan validation catches issues before they become implementation blockers." |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Design is obvious, skip to planning" | Obvious ≠ validated. Unvalidated designs cause plan rework. | MUST complete design phase first |
| "Engineer will figure out the details" | Zero-Context Test: engineer has NO codebase context. Plan must be complete. | MUST include complete code and paths |
| "Validation warnings are minor" | Warnings indicate issues that become blockers during execution. | MUST address all warnings |
| "Agent assignment is flexible" | Wrong agent = wrong standards applied. Each task needs correct specialist. | MUST specify recommended agent |
| "Plan is good enough, validation is overkill" | "Good enough" plans fail Zero-Context Test. Validation ensures completeness. | MUST run and pass validation |