96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
---
|
|
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).
|