autojanet/skills/writing-plans/SKILL.md

name	description
writing-plans	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):

# [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.

### 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/
• Vikunja: https://tasks.ctz.fyi/projects/

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