kanban-plan
Plan and obtain human approval for a kanban feature contract or lightweight bug triage contract, then ask whether to start or defer to backlog. Use when a work item is in planning.
SKILL.mdskills/kanban-plan/SKILL.md
GitHubKanban Phase 2 — Planning → Execution Contract (Human + Agent)
Argument: <feature_name>.
Phase 2 turns the confirmed requirement into a binding execution contract that the human approves. Everything written here is law for the rest of the pipeline — no silent scope creep afterwards.
1. Verify stage
kf status --change {feature_name} # must show stage = planning
If approval is already valid, keep the contract unchanged and go to the start/backlog decision in section 4. If the approval is changed or pending, finish the applicable contract and obtain fresh human approval.
Read work item kind from kf status --change {feature_name} --json. For kind: bug, use the confirmed bug report as the contract: reproduction, expected fix, scope, regression strategy and docs impact. Skip section 2; present this concise contract, run approval in section 3 and ask start/backlog in section 4. Do not create feature planning artifacts for a bug. If the request introduces behavior beyond correcting the defect, explain the scope change and follow the user's decision before creating a related feature.
2. Write the four plan artifacts (in order)
Read the confirmed Test Strategy from phase-1-spec-requirement.md (Level in a feature spec, Test Level in a bug report, plus UI Tests, Tools, Coverage Target) — it was agreed with the human in Phase 1. Everything below must honour it.
Who writes what
The four artifacts depend on each other: the UC list drives the diagram and the test cases, and every TC-### must cite a real FR-### and UC-###. So the skeleton stays with you, and subagents only take the work that is independent once the skeleton is fixed:
| Step | Who | Output |
|---|---|---|
| a. Impact survey | 1-3 subagents in parallel, one per area (backend, frontend, DB/API/infra, existing tests) | Findings returned to you, never written to artifacts |
| b. Skeleton | You | implementation-plan, the use-case-specification index with the final UC IDs, slugs and one-line goals |
| c. UC files | One subagent per UC-###, in parallel |
use-cases/UC-###-<slug>.md |
| d. Diagram + test cases | You | use-case-diagram, test-cases |
| e. Contract review | 1 subagent with a fresh context | Findings returned to you before section 3 |
Skip the subagents and do every step yourself when the change is small (two UCs or fewer, or a survey that fits in a few files): each handover re-reads the spec and the code, which costs more than it saves at that size. If your runtime has no subagent tool, do the same steps yourself in the same order.
Subagent prompt contract — every subagent prompt must state:
- Task: its step (a, c or e), and for step c the exact
UC-###, slug and goal from the index - Files to read:
phase-1-spec-requirement.md, the skeleton artifacts, the relevant source paths - Files it may write: step c only, exactly its one
use-cases/UC-###-<slug>.md; steps a and e write nothing - Constraints: never rename or renumber a
UC-###/FR-###, never add scope beyond the confirmed requirement, never edit another artifact, never runkf approve,kf stage,kf archiveorkf run - Context:
.works/planning/{feature_name}/(fromkf status --change {feature_name})
Subagent status protocol — require every subagent to end with:
Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
Summary: one or two sentences
Concerns/Blockers: (optional)
Treat DONE_WITH_CONCERNS, BLOCKED and NEEDS_CONTEXT as not-done: resolve it before moving on. A missing Status: line is not done either.
a. Impact survey
kf stage <feature> planning already fetched and fast-forwarded the base checkout to its upstream — survey the files as they are; if the transition output carried a ⚠ base is N commit(s) behind warning, surface it to the user before writing the contract instead of pulling yourself.
Before writing the plan, dispatch the survey subagents in one batch. Each answers for its area: which modules, endpoints, tables and components the change touches, who depends on them, which existing tests cover them, and any risk to regression, security or performance. Ask for file:line references and conclusions, not file dumps. Feed the findings into the impact analysis of the implementation plan; do not paste them as-is.
b-d. Skeleton, UC files, diagram and test cases
Write the implementation plan and the use-case index first (step b). Once the UC IDs are fixed, dispatch one subagent per UC file (step c), all in one batch. When they return, read each UC file and check that its ID, goal and acceptance criteria match the index, then write the diagram and the test cases yourself (step d).
Print each template and fill the file at its path:
kf instruct implementation-plan --change {feature_name}
kf instruct use-case-specification --change {feature_name}
kf instruct use-case-diagram --change {feature_name}
kf instruct test-cases --change {feature_name}
kf instruct use-case --change {feature_name} --id UC-001-create-task
implementation-plan
- Scope: now / supporting / future / not-in-scope
TASK-###breakdown, complexity, impact analysis (backend / frontend / DB / API / infra / security / performance / regression / deps)- Read the spec's
## Affected surfacesfirst: every declared surface gets a task row or a## Documentation Impactentry —kf validatewarns on any surface the plan never mentions.N/Ameans none owed. - Testing strategy incl. coverage target from the spec's Test Strategy (default >= 80%) and Definition of Done
- When Test Level is
full: name the UI/E2E framework you will use (Playwright, Cypress and so on) and say which suite covers the critical flows and which covers everything.
use-case-specification
- Use
phase-2-use-case-specification.mdonly as an index and coverage summary. - Write one file per use case under
use-cases/, namedUC-###-<slug>.md(e.g.UC-001-create-task.md), usingkf instruct use-case --id UC-###-<slug>. The slug makes a file listing readable; plainUC-###.mdstays valid. - Each file contains one
UC-###: goal, actors, preconditions, trigger, main / alternative / exception flows, postconditions, business rules, data and acceptance criteria. - The
UC-###prefix of the file name and the declared ID must match exactly. Do not put multiple UC narratives in one file.
use-case-diagram
- Mermaid
graph TD/flowchart: actors → use cases (one box per UC-###)
test-cases
- Generate test cases from the spec's Test Level (unit | unit+integration | full):
unit→Unitcases only, one per acceptance criterion and per edge case, each tied to an FR and a UC.unit+integration→ addIntegrationcases wherever the change meets another system, the database or an API.full→ addUI / E2Ecases for the user-facing flows: what is clicked, what is typed, what appears on screen, following theUI Testsscope (critical or all). Add the matching## TC-###sections from the detailed template, with references that match that scope.
- Keep the plan table-driven: fill overall totals, per-type counts, use-case coverage matrix and requirement coverage matrix before the detailed
## TC-###tables. - Define each test in a
## TC-###section referencingFR-###(spec) andUC-###(the matching individual use-case file).kf validateblocks missing or unknown references before approval. - If the user wants to change the test level during Phase 2, which is rare: update the Test Strategy in
phase-1-spec-requirement.mdbefore generating the cases, and say so when you present the contract for approval.
e. Contract review
Before section 3, dispatch one review subagent with a fresh context. It reads the requirement and every planning artifact and reports: an FR-### with no test case, an acceptance criterion that cannot be tested, a UC or task outside the confirmed scope, an ID that differs between files, and an impact the plan misses. It edits nothing. Fix what it finds yourself, or record why a finding does not apply.
3. Human approval gate
kf validate --change {feature_name}
Before approval, approval_required is expected; approval_changed is expected when revising an old contract. Fix all other errors and assess warnings before presenting the contract. kf approve validates the artifacts without requiring an existing approval. Present a tight summary to the user:
- what the feature does (2-3 lines)
- implementation plan headlines (tasks, approach, risks)
- test strategy + coverage target (as agreed in the spec's Test Strategy: unit / unit+integration / full + UI scope)
- Definition of Done
Ask once: "approve?" On approval:
kf approve {feature_name}
kf approve fingerprints the requirement, four planning artifacts and all individual UC files for a feature; for a bug it fingerprints only the bug report. kf stage requires the approved contents to remain unchanged. Progress and test outcomes belong in tasks.md and the testing report; do not rewrite the approved contract during execution.
4. Start/backlog decision gate
Approval means the contract is valid; it does not mean implementation must start immediately. Ask the user once:
"The plan is ready. Start implementation now, or put it in the backlog?"
- Start now →
kf stage {feature_name} implementation - Defer →
kf stage {feature_name} backlog
Do not choose on the user's behalf. A deferred item keeps its approved contract in backlog and can resume to implementation later after the user chooses to start.
Done
Approval and the start/defer decision are recorded. Hand off:
If the user chose start, load kanban-implement and move the feature to implementation. If the user chose defer, leave it in backlog and resume only after an explicit start decision.