---
name: writing-plans
description: Create implementation plans detailed enough for an executor with little project context
permalink: opencode-config/skills/writing-plans/skill
---

# Writing Plans

## When to Use

Use this skill when you have requirements for a non-trivial implementation and need a clear plan before editing code.

## Core Goal

Write a comprehensive implementation plan that assumes the executor lacks prior context. The plan must include exact tasks, file paths, expected code shape, and verification commands.

## Scope Check

If requirements contain multiple independent features/subsystems, split into separate plans so each can be implemented and verified independently.

## Plan Storage (basic-memory)

Store plans as basic-memory notes in the repo project under `plans/`.

- Project: `opencode-config` (or current repo project)
- Note path: `plans/<feature-or-workstream-name>`
- Use only basic-memory `plans/` notes for plan storage.

## Plan Header Template

```markdown
# [Feature Name] Implementation Plan

> For implementation: use `subagent-driven-development` when subagents are available; otherwise use `executing-plans`.

**Goal:** [one sentence]

**Architecture:** [2-3 concise sentences]

**Tech Stack:** [languages, frameworks, tools]
```

## Build the Plan in This Order

1. **Map file structure first**
   - List files to create/modify/test using exact paths.
   - State each file's responsibility.
   - Prefer small, focused files and clear interfaces.

2. **Decompose into small actionable tasks**
   - Tasks should be independently understandable and testable.
   - Use checkbox syntax for steps: `- [ ]`.
   - Keep each step concrete (write test, run command, implement minimal code, re-run checks).

3. **Include code shape guidance**
   - Show function/class signatures, data flow, and key logic constraints.
   - Avoid vague instructions like "add validation" without describing expected behavior.

4. **Include exact verification commands (when known)**
   - Provide commands with scope and expected result.
   - Example: `pytest tests/path/test_file.py::test_case -v` → expected FAIL before implementation, PASS after.
   - If exact commands are unknown, state how to discover them from repo scripts/docs.

## Task Template

````markdown
### Task N: [Name]

**Files:**
- Create: `path/to/new_file.ts`
- Modify: `path/to/existing_file.ts`
- Test: `path/to/test_file.ts`

- [ ] Step 1: Write/extend failing test for [specific behavior]
- [ ] Step 2: Run: `<exact command>` and confirm expected failure
- [ ] Step 3: Implement minimal code for [specific behavior]
- [ ] Step 4: Run: `<exact command>` and confirm pass
- [ ] Step 5: Run broader verification: `<exact command>`
````

## Plan Review Loop (required)

After each plan chunk:

1. Review for completeness, scope alignment, actionable decomposition, and verification quality.
2. Fix identified issues in the same chunk.
3. Re-review until the chunk is implementation-ready.

Suggested chunking: use `## Chunk N: <name>` headings for large plans.

## Completion Handoff

When done, state where the plan is stored in basic-memory (for example `plans/<name>`) and whether execution should proceed via:
- `subagent-driven-development` (preferred when available), or
- `executing-plans` (single-agent execution).