---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---

# Writing Plans

## Overview

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:** If working in an isolated worktree, it should have been created via the `using-git-worktrees` skill at execution time.

## Vikunja Project Setup

Before writing the plan, determine where tasks will live:

1. Call `litellm_vikunja-vikunja_api` with operation `get_projects` to list all projects
2. Present the list to the user and ask: "Which Vikunja project should I create tasks in? Or I can create a new one cloned from the Template."
3. If creating a new project:
   - Ask the user what to name it
   - Call `litellm_vikunja-vikunja_api` with operation `put_projects_projectid_duplicate`, `projectID: 5`, body `{ "name": "<chosen name>" }`
   - This clones the Template project (ID 5) including its Kanban board and buckets
4. Note the project ID for task creation below

### Kanban Buckets

After identifying or creating the project, look up its Kanban bucket IDs — these are project-specific:

1. Call `get_projects_project_views` with the project ID to find the Kanban view ID
2. Call `get_projects_id_views_view_buckets` with that view ID to get buckets
3. Note bucket IDs for: **Backlog**, **Todo**, **In Progress**, **Done**

Tasks are created in **Backlog** by default. When a task begins execution it moves to **In Progress**; when complete it moves to **Done** (see Kanban Lifecycle below).

## Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

## File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- Prefer smaller, focused files over large ones that do too much.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

## Bite-Sized Task Granularity

**Each step is one action (2-5 minutes):**
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step

## Plan Document Header

**Every plan MUST start with this header (mentally — this becomes the first parent task description):**

```markdown
# [Feature Name] Implementation Plan

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Spec:** [BookStack spec URL if available]
```

## Task Structure

Each **Task N** block becomes a **parent Vikunja task**. Each **step** within it becomes a **subtask** linked to that parent.

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

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

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

## Saving the Plan to BookStack

After composing the plan (before creating Vikunja tasks), save it to BookStack:

1. The **Plans** book already exists (book ID 159) under the Superpowers shelf at https://wiki.ctz.fyi
2. Create the plan page via `bookstack_pages_create`:
   - `book_id`: 159
   - `name`: `[Plan] YYYY-MM-DD: <feature name>`
   - `markdown`: the full plan document
3. Note the page URL to share with the user

> If a spec page already exists in BookStack, link to it in the plan header under **Spec:**.

## Creating Tasks in Vikunja

After saving to BookStack, create the plan in Vikunja:

For each **Task N** block:
1. Create a parent task via `litellm_vikunja-vikunja_api` operation `put_projects_id_tasks`:
   - `id`: the project ID chosen above
   - body: `{ "title": "Task N: [Component Name]", "description": "<Files section + architecture notes for this task>" }`

2. For each **step** within that task:
   - Create the step task via `put_projects_id_tasks` (same project):
     `{ "title": "Step M: [step description]", "description": "<full step content including code blocks, commands, expected output>" }`
   - Link it as a subtask of the parent via `put_tasks_taskid_relations` on the **parent** task:
     `{ "kind": "subtask", "other_task_id": <step_task_id> }`

3. Place each parent task in the **Backlog** bucket using `post_projects_project_views_view_buckets_bucket_tasks`:
   - `project`: project ID
   - `view`: Kanban view ID
   - `bucket`: Backlog bucket ID
   - body: `{ "task_id": <parent_task_id> }`

After all tasks are created, share both:
- BookStack plan URL: `https://wiki.ctz.fyi/books/plans-A64/page/<slug>`
- Vikunja project URL: `https://tasks.ctz.fyi/projects/<id>`

## Kanban Lifecycle

Tasks must be moved through the board as work progresses:

| Stage | Action | Vikunja operation |
|-------|--------|-------------------|
| Task created | → Backlog | `post_projects_project_views_view_buckets_bucket_tasks` with Backlog bucket ID |
| Work starts | → In Progress | same operation, In Progress bucket ID |
| Work complete | → Done | same operation, Done bucket ID |
| Mark done | Set `done: true` | `post_tasks_id` with `{ "done": true }` |

**When working on the tasks**
1. make sure to make comits that are linked to the tasks in the comment message

**When finishing any task or step:**
1. Move it to the Done bucket
2. Call `post_tasks_id` with `{ "done": true }` to mark it complete

If you are executing tasks directly (not delegating to subagents), you are responsible for keeping the board up to date as each task progresses.

## No Placeholders

Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
- Steps that describe what to do without showing how (code blocks required for code steps)
- References to types, functions, or methods not defined in any task

## Remember
- Exact file paths always
- Complete code in every step — if a step changes code, show the code
- Exact commands with expected output
- DRY, YAGNI, TDD, frequent commits

## Self-Review

After composing the complete plan (before saving to BookStack or creating Vikunja tasks), check it against the spec:

1. **Spec coverage:** Can you point to a task for every requirement? List any gaps.
2. **Placeholder scan:** Search for any patterns from the "No Placeholders" section. Fix them.
3. **Type consistency:** Do type names, method signatures, and property names stay consistent across tasks?

Fix any issues inline before saving and creating tasks.

## Execution Handoff

After creating all Vikunja tasks and saving the plan to BookStack, offer execution choice:

**"Plan complete.**
- **BookStack:** https://wiki.ctz.fyi/books/plans-A64/page/<slug>
- **Vikunja:** https://tasks.ctz.fyi/projects/<id>

**Two execution options:**

**1. Subagent-Driven (recommended)** — I dispatch a fresh subagent per task, review between tasks, fast iteration

**2. Inline Execution** — Execute tasks in this session using executing-plans, batch execution with checkpoints

**Which approach?"**

**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use `subagent-driven-development`
- Fresh subagent per task + two-stage review
- Each subagent must move tasks through the kanban board as they work

**If Inline Execution chosen:**
- **REQUIRED SUB-SKILL:** Use `executing-plans`
- Batch execution with checkpoints
- Move tasks through kanban board as each task starts and completes