playbooks

home / skills / lerianstudio / ring / writing-plans

writing-plans skill

/default/skills/writing-plans

This skill creates complete implementation plans with exact file paths, code, and verification steps to enable zero-context engineers to execute quickly.

npx playbooks add skill lerianstudio/ring --skill writing-plans

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
7.4 KB
---
name: ring: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 ring:pre-dev-prd-creation first
  - Already have a plan → use ring:executing-plans

sequence:
  after: [brainstorming, ring:pre-dev-trd-creation]
  before: [ring:executing-plans, ring: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 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", model: "opus")` 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:

```bash
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:
1. Execute now → `ring:subagent-driven-development`
2. Parallel session → user opens new session with `ring:executing-plans`
3. Save for later → report location and end

## Why Use an Agent?

**Context preservation** (reading many files keeps supervisor clean) | **Model power** (Opus for 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

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

### 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:**

```markdown
## 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)](#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:

```markdown
## 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.

Overview

This skill dispatches a specialized agent to produce complete, executable implementation plans for engineers with zero codebase context. It announces usage at start, writes bite-sized tasks with exact file paths and full code examples, and saves the plan to a dated markdown in docs/plans. Plans include verification steps, failure recovery, and recommended agents per task.

How this skill works

The skill dispatches a write-plan subagent (Task(subagent_type: "ring:write-plan", model: "opus")) that explores the codebase, identifies affected files, and breaks work into 2–5 minute tasks. The agent writes exact file paths, complete code snippets, verification commands with expected outputs, and review checkpoints, then saves the result to docs/plans/YYYY-MM-DD-<feature-name>.md. After saving, run the provided validation script and ask the user whether to execute, run in parallel, or save for later.

When to use it

  • You need a developer-ready implementation plan when no engineer has context of the repo.
  • Preparing work for distributed teams or contractors who must follow exact file edits and verification.
  • Converting research or feature specs into step-by-step actionable tasks with recovery steps.
  • Before starting automated execution or orchestrated subagent-driven development.
  • When multi-module/topology-aware plans must assign targets, working directories, and agents.

Best practices

  • Run the skill in a dedicated worktree created for planning to avoid polluting main branches.
  • Always include the announce string at the start: "I'm using the ring:writing-plans skill to create the implementation plan."
  • Validate the saved plan with python3 default/lib/validate-plan-precedent.py and iterate until PASS.
  • Provide TopologyConfig or pre-dev frontmatter so the agent can resolve working directories and assign targets correctly.
  • Apply required shared patterns: state-tracking, failure-recovery, exit-criteria, and TodoWrite to every plan.

Example use cases

  • Create a zero-context plan to add a new Go API endpoint with exact file edits, full code, and tests.
  • Generate a multi-module feature plan that assigns backend/frontend/shared targets and recommends agents per task.
  • Produce a CI/CD change plan that lists modified config files, verification commands, and rollback steps.
  • Prepare an execution-ready plan to integrate an external service, including BFF or direct API pattern decisions.

FAQ

What announcement does the skill require?

Begin the session with: "I'm using the ring:writing-plans skill to create the implementation plan."

How do I know a plan is safe to execute?

Run python3 default/lib/validate-plan-precedent.py docs/plans/YYYY-MM-DD-<feature>.md — PASS means safe, WARNING means address issues and revalidate.