Plankit

plankit

Turn a rough idea (a feature, a project, a spec, a PRD) into a structured plan document you can act on. plankit is generative: it brainstorms the approach, settles the decisions needed for a coherent draft, and writes a plan-<slug>-YYYY-MM-DD.md grounded in the real codebase (not a guess). It is the front of a flow, plankit drafts → grillkit hardens → issuekit files where a project tracks work in GitHub Issues, and plankit drafts → grillkit hardens → implementkit builds where it doesn't. Either way the plan it writes is the exact input the next step expects. plankit plans only: it never writes application code and never creates issues.

When this fires

The user wants to think a piece of work through before building it: "plan this feature", "brainstorm a plan / PRD / spec", "write a plan doc", "help me think through X first", "/plankit". One distinction matters:

• It is not the adversarial interrogator. That's grillkit. plankit asks enough to draft a coherent plan and records the thin spots as open questions; grillkit is what pressure-tests them one decision at a time.

Procedure

1. Capture the idea

Get the concept, the problem it solves, who it's for, and the outcome that means success. If the input is a one-liner, ask a few scoping questions (use AskUserQuestion when available). Those are generative "what are we building and why", not adversarial "what did you miss". Enough to draft, no more.

2. Ground it in reality

Research before proposing, so the plan reuses what exists instead of reinventing it.

• In an existing repo: read the relevant code, docs, and config to find the patterns, utilities, and conventions the plan should build on. Look up facts yourself (Read, Grep, Glob); reserve questions for genuine decisions. Never propose new code where a suitable implementation already exists; name the existing thing in the plan instead.
• Greenfield (no repo yet): skip the code research; ground the plan in the user's stated goals and constraints.

3. Diverge, explore approaches

Brainstorm the real options and recommend one, something concrete to accept or redirect, not a naked menu. This is the generative half: don't settle for the first idea, and consider the unconstrained version of the work before narrowing to the practical one.

When more than one credible path exists, default to a spread that is genuinely different rather than variants of one idea: a minimal viable (the smallest diff that ships and is useful), an ideal (the shape you'd choose with time to do it properly), and where one exists a lateral (a reframe that dissolves the problem instead of solving it). Name what each option reuses from the research above, so the plan stays anchored to the code you just read. Collapsing to a single approach is fine when the work warrants it, since "no credible alternative" beats an invented Option B.

The failure mode is options that only look plural:

Variants (avoid): cache the response · cache it with a shorter TTL · cache it behind a flag we can tune later. One idea in three hats, so there's no real choice to make.

Distinct (aim for): cache the response (smallest diff, ships this week, goes stale on writes) · denormalize the read path so there's nothing to cache (a migration, but the whole staleness class disappears) · don't fix it here at all, because it's only slow when called in a loop, so batch upstream and the endpoint stops mattering.

4. Converge, settle the structure

Resolve the structural decisions a coherent draft needs (the architecture, the phases, the scope boundary) one at a time, each with a recommended answer. Then stop: deliberately leave the deeper, thin, or still-uncertain spots for grillkit rather than grinding every edge case here. Record those under Open questions in the doc so the hardening step has a target.

5. Write the plan document

Write docs/plans/plan-<slug>-YYYY-MM-DD.md, where <slug> is a short lowercase kebab-case name for the feature and the suffix is the plan's ISO creation date (plan-sso-login-2026-07-23.md). Keep that date stable on later edits; record an updated date inside the document when useful. Use the plan-doc format below, which is the contract grillkit and issuekit both read, so keep the body phase/task-shaped. Create docs/plans/ if it doesn't exist. If a plan for this work already exists, update it in place rather than writing a second file. For a genuine same-day collision between distinct plans, make the slug more specific; only as a last resort insert a sequence immediately before the date (plan-sso-login-02-2026-07-23.md).

6. Hand off

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

Report where the plan landed and offer the next step, in order, naming a sibling kit only when it is installed and otherwise describing the action in plain language:

• grillkit. Pressure-test and harden the draft (it can update this same file in place).
• issuekit, when the project tracks work in GitHub Issues. Turn the hardened plan into issues.
• implementkit, when it does not. Build straight from the plan, one phase at a time.

Name the second or the third, not both, when you can tell which applies. The prompt or the repo's agent-guide file says which; open issues on the repo are the weaker signal. Name both when nothing settles it, and never assume a project files GitHub issues just because it is hosted on GitHub.

If the planning surfaced project vocabulary worth pinning down or a hard-to-reverse trade-off decision, offer domainkit when installed; otherwise offer to record a glossary entry or ADR directly.

Do not start either yourself.

Plan-doc format

The canonical structure plankit owns. Keep it lean, so every section earns its place, and keep the body organized as phases/tasks so issuekit can decompose it into issues:

# Plan: <title>

## Context
The problem, why it matters now, and the outcome that means success.

## Design decisions (settled)
| Decision | Resolution |
|----------|-----------|
| <the choice> | <what we picked and, briefly, why> |

## Approach
The chosen approach and what it **reuses** from the existing codebase, then the plan body as phases/milestones/tasks, each a concrete, verifiable unit of work. This is the structure issuekit reads to propose an issue breakdown. When the alternatives were close, keep the rejected ones to a line each so the choice stays legible later.

## Open questions
Unresolved or thin spots, written as targets for grillkit to interrogate.

## Non-goals
Explicit scope boundaries, meaning what this plan deliberately does not cover.

A hardened plan additionally carries a Grilled: YYYY-MM-DD line directly under the title. grillkit writes it when the plan survives a grill session, and issuekit reads it as the gate for filing issues ready. plankit never writes the stamp itself; a fresh draft is ungrilled by definition.

The phase-heading annotation slot

A phase heading ends in an optional annotation, and downstream skills write into it. plankit writes a bare heading (### Phase 2: auth) and never annotates one itself, because a fresh plan has neither been filed nor built. Two vocabularies share the slot:

• (#41), written by issuekit when it files that phase as an issue. It says where the phase is tracked.
• (built YYYY-MM-DD), written by implementkit when it finishes building that phase. It says the phase is done.

They coexist, so ### Phase 2: auth (#41) (built 2026-08-20) is a tracked phase that shipped. Keeping both in one slot is what lets a reader and a survey tool answer "what is left in this plan?" from the plan alone, with no tracker to consult, which is the only way that question has an answer on a project that files no issues.

The stamp is opt-in per plan. A plan with no annotation anywhere makes no claim about itself, so nothing may read its phases as unbuilt. That is what lets the convention arrive without a migration: plans written before it stay silent and correct, and a plan starts making claims the first time something stamps it.

Match the heading loosely. A phase heading begins Phase <n> and the separator that follows varies across real plan sets, so anything reading these headings accepts a colon, a dash, or nothing.

Notes

• Plan only. No application code, no issues; those are separate steps (implementkit, issuekit). plankit hands off; it doesn't cross into them.
• Fewest honest sections. Prefer a short, sharp plan over a padded one; drop a section rather than fill it with filler. Scale the doc to the work's real surface area.
• Defer the grilling. Leaving open questions is fine and expected. Draft a coherent plan and let grillkit harden it; don't try to be both.
• Follow the repo's conventions. If the codebase has its own plan/RFC/PRD location or template, follow that and say you did, rather than forcing docs/plans.
• No filesystem or shell (e.g. a browser-based agent)? Then you can't write the file. Instead print the finished plan document as a codeblock and give the user the canonical plan-<slug>-YYYY-MM-DD.md filename to save wherever they keep plans.