jitsusama/planning-guide

Planning

Planning is where you think a problem through and debate it before touching code. It is a conversation, not an intake form. You dig hard, you argue for the best shape, and you leave with a living document that captures the spirit of the work and tracks its own progress.

The quest tool drives planning, as one of the four document kinds (plan, research, brief, report) that live under a loaded quest. The plan document is the single source of truth: it survives reloads, resumes and cold starts, and the workflow rehydrates from it. The tool is a tracker, not a gate. It never prompts the user; it only reflects where the work is and reminds you of the posture for each stage.

A plan exists under a quest. If no quest is loaded when you start planning, the agent loads or creates one first. Plans are scaffolded into the quest's plans/ subdirectory and tied back to the quest via the document's quest front-matter field.

The Stages

A plan moves through three working stages and two terminal ones.

• think (read-only): dig and debate. No implementing.
• draft (read-only except the plan document): write the document.
• build (writes allowed): implement against the plan.
• concluded / retired: terminal. The document is the record.

You drive transitions with the quest tool's stage verbs:

• quest({action: "think", note, kind: "plan"}) opens a fresh plan loop from idle with a note on what it is about. The same action reopens the focused plan from draft or build when discovery sends you back to the drawing board (replan).
• quest({action: "draft", title}) moves think to draft and creates the document, with a title that becomes its H1.
• quest({action: "build"}) moves draft to build once the document is written.
• quest({action: "conclude"}) closes a finished plan; quest({action: "retire", reason}) abandons one with a reason. Both default to the focused document when one is set; pass scope: "quest" to act on the loaded quest itself.
• quest({action: "focus", id}) switches the focused document, and quest({action: "unfocus"}) clears it. Switching focus does not change the document's stage.

A refused transition hands back guidance and changes nothing. There is no approval prompt.

Think: Dig, Then Debate

Investigate before you form a view. Read the code, trace the flow, understand the current state. Only once you have dug should you start shaping an approach.

Then debate. Surface tradeoffs. Float alternatives and say which you prefer and why. Push back where you disagree. Work the problem high level first, because a change up top invalidates the detail below it. Take one thread at a time rather than a wall of parallel points.

Ask the user only when something genuinely blocks you, and ask in plain conversation, one question at a time. There is no interview tool and no batch of questions. If you are explaining, analyzing or proposing, that is conversation, not a question.

The Plan Document

The document is what you carry out of planning. Aim for a proper markdown file that reads well on its own, with just enough structure that the workflow can parse it.

The parsed contract

Only two things are ever parsed, so only two things are load bearing. Everything else is your prose.

1. Front-matter: a small YAML block at the top.

---
id: PLAN-20260530-a3f
stage: build
updated: 2026-05-31
sessions:
  - 019e7a4b-516e-7911-a1ff-6d5383f7fa64
---

The id is stable and assigned once; the H1 is the friendly name and can change freely. stage, updated and sessions are maintained by the workflow as you transition, so you rarely touch them by hand.

2. Checkboxes: standard GitHub task-list items (- [ ] and - [x]) anywhere in the body. These are the progress.

Recommended sections

These are a starting shape, not a cage. Reshape them to fit the work; the parser never reads section headings.

# A Readable Title

## Spirit
The stable north star: why this work exists and what good looks
like. This is the part that must survive every deviation.

## Context
What framing the problem surfaced. Constraints. What is in and
out of scope.

## Approach
The shape you settled on and the decisions behind it, each with
its rationale.

## Work
- [ ] First increment, sequenced so each step forces the least
- [ ] Next increment

## Open Questions
- [ ] Anything still unresolved

## Discovery & Deviations
An append-only, dated log. When the work surfaces something that
changes the plan, it lands here with the decision and the consent
behind it.

Progress and Keeping It Current

The document must always reflect reality, because the work may resume in a different session days later. While building, check off - [ ] to - [x] as you finish each increment, and write what you discover into Discovery & Deviations. Updating the document is not bookkeeping you do at the end; it is how the workflow knows where the work stands, and the scoreboard tracks it live, so progress climbs as you check items off rather than waiting on a stage change.

When resuming, trust the checkboxes: the checked items are done, the unchecked are what remain. To find a plan in a fresh session, load the relevant quest with quest({action: "load", id}) (or let the workflow auto-load it from the session's cwd), then focus the document by its id. quest({action: "list"}) shows the quests under the questsRoot, and quest({action: "show"}) renders the loaded quest's documents with their kinds and stages.

Deviating From the Plan

When build surfaces something the plan did not foresee, the response depends on what changes.

• A change to the spirit or the approach needs the user's consent. Stop, explain what you found and what you would change, and get their agreement before proceeding.
• Anything smaller, you just do, and record it in Discovery & Deviations so the document stays honest.

If the plan is genuinely wrong, reopen it: transition back to think with a note on what changed, rework the approach, then draft again.

Where Plans Live

Plans live under their parent quest, in the quest's plans/ subdirectory, as PLAN-DATE-XXX.md. The quest itself lives under the questsRoot (default ~/.local/share/pi/agentic-harness.pi/quest-workflow/quests/, override with questsRoot in the quest-workflow section of the package config at ~/.config/pi/agentic-harness.pi/config.json).

When you start a plan without a loaded quest, the agent loads or creates one first. There is no longer a notion of a free-standing plan: every plan belongs to a quest.

Granularity

Size each Work item so it is:

• Small enough for one increment or one commit.
• Independently verifiable.
• Clear enough that someone reading only that line knows what to do.

For Code Plans

A plan gives context and direction, not implementation. It explains what to build and why; the how is decided while building, under TDD. So a code plan is most useful when it captures:

• Skills to follow: name them rather than restating them (for example code-tdd-guide, code-style-standard, the prose standard). The implementer loads them.
• Interfaces: the exported surface and how it is called, with signatures and what it returns.
• Data shapes: what flows through the system and why it is shaped that way.
• Test scenarios: a flat coverage checklist of behaviours to verify, not full test code and not a TDD order. More scenarios emerge while building.

Keep complete implementation code, complete test code and step-by-step procedures out of the plan. If you are writing the body of a method, you have stopped planning and started coding.