// Use when you have a spec or requirements for a multi-step task, before touching code
| name | writing-plans |
| description | Use when you have a spec or requirements for a multi-step task, before touching code |
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
Announce at start: "I'm using the writing-plans skill to create the implementation plan."
Context: Planning is read-only. Use hive_feature_create + hive_plan_write and keep implementation out of the planning session.
Save plans to: hive_plan_write (writes to .hive/features/<feature>/plan.md)
hive_status() to confirm the active feature, current task IDs, and any blocked or runnable work before revising the plan.todo only when shaping a multi-task plan or review response needs an active checklist.vscode/memory only for durable planning decisions or blocker history that future turns need.Each step is one action (2-5 minutes):
Every plan MUST follow this structure:
# [Feature Name]
## Discovery
### Original Request
- "{User's exact words}"
### Interview Summary
- {Point}: {Decision}
### Research Findings
- `{file:lines}`: {Finding}
---
## Non-Goals (What we're NOT building)
- {Explicit exclusion}
---
## Design Summary
{Concise human-facing summary of the feature before task details. Optional Mermaid is allowed here for dependency or sequence overview only.}
---
## Tasks
### 1. Task Name
Use the Task Structure template below for every task.
The Depends on annotation declares task execution order:
Always include Depends on for each task. Use none to enable parallel starts.
### N. Task Name
**Depends on**: none
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
**What to do**:
- Step 1: Write the failing test
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- Step 2: Run test to verify it fails
- Run: `pytest tests/path/test.py::test_name -v`
- Expected: FAIL with "function not defined"
- Step 3: Write minimal implementation
```python
def function(input):
return expected
```
- Step 4: Run test to verify it passes
- Run: `pytest tests/path/test.py::test_name -v`
- Expected: PASS
- Step 5: Commit
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
**Must NOT do**:
- {Task guardrail}
**References**:
- `{file:lines}` — {Why this reference matters}
**Verify**:
- [ ] Run: `{command}` → {expected}
- [ ] {Additional acceptance criteria}
All verification MUST be agent-executable (no human intervention):
✅ `bun test` → all pass
✅ `curl -X POST /api/x` → 201
❌ "User manually tests..."
❌ "Visually confirm..."
plan.md as the human-facing review surface and execution truthDesign Summary before ## Tasks## TasksAfter saving the plan, ask whether to consult Hygienic (Consultant/Reviewer/Debugger) before offering execution choice.
Plan complete and saved to .hive/features/<feature>/plan.md.
Two execution options:
Which approach?
If Agent-Driven chosen:
If Parallel Session chosen:
Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when you need parallel, read-only exploration with the agent tool (Scout fan-out)
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes