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 ring:writing-plans skill to create the implementation plan."

Context: This should be run in a dedicated worktree (created by ring:brainstorming skill).

The Process

Step 1: Dispatch Write-Plan Agent

Dispatch via Task(subagent_type: "ring:write-plan") with:

Instructions to create bite-sized tasks (2-5 min each)
Include exact file paths, complete code, verification steps
Save to docs/plans/YYYY-MM-DD-<feature-name>.md

Step 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 execute
WARNING → Plan has issues to address
- Review the warnings in the output
- Update plan to address the issues
- Re-run validation until PASS

Step 3: Ask User About Execution

Ask via AskUserQuestion: "Execute now?" Options:

Execute now → ring:subagent-driven-development
Parallel session → user opens new session with ring:executing-plans
Save for later → report location and end

Why Use an Agent?

Context preservation (reading many files keeps supervisor clean) | Model power (comprehensive planning) | Separation of concerns (supervisor orchestrates, agent plans)

What the Agent Does

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

Requirements for Plans

Multi-Module Task Requirements

If TopologyConfig exists (from pre-dev research.md frontmatter or user input):

Each task MUST include:

Target: backend | frontend | shared
Working Directory: Resolved path from topology configuration
Agent: Recommended agent matching the target

Task 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)

Agent Selection

Backend Tasks

Task Type	Agent
Go backend API/services	`ring:backend-engineer-golang`
TypeScript backend API/services	`ring:backend-engineer-typescript`

Frontend Tasks (api_pattern aware)

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

Decision Logic for Frontend Tasks

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)

Infrastructure and Other Tasks

Task Type	Agent
Infra/CI/CD	`ring:devops-engineer`
Testing	`ring:qa-analyst`
Reliability	`ring:sre`
Fallback	`ring:general-purpose`

Task Format with api_pattern

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

Execution Options Reference

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

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.

Blocker Criteria

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

Cannot Be Overridden

The following requirements CANNOT be waived:

Design phase MUST be complete before creating implementation plan
Plan validation script MUST pass before execution
All tasks MUST include exact file paths, never "somewhere in src"
All tasks MUST include complete code examples, never placeholders
Each task MUST specify recommended agent

Severity Calibration

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

Pressure Resistance

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."

Anti-Rationalization Table

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