@phuthuycoding/kanban-flow 0.3.0

package/kanban-flow/templates/phase-5-review-report.md

@@ -0,0 +1,68 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+execution: "{execution_id}"
+status: REJECT
+---
+
+# Review Report
+
+## Feature
+{feature_name}
+
+## Review Status
+- {review_status}
+
+## Review Overview
+
+| Field | Result |
+|---|---|
+| Reviewed scope / diff | {reviewed_scope} |
+| Execution | {execution_id} |
+| Open blocking findings | {blocking_findings} |
+| Overall decision | {review_status} |
+
+## Requirement Compliance
+{requirement_compliance}
+
+## Scope Compliance
+{scope_compliance}
+
+## Code Convention
+{code_convention}
+
+## Architecture
+{architecture}
+
+## Logic
+{logic}
+
+## Tests
+{tests}
+
+## Test Coverage
+{test_coverage}
+
+## Linter / Formatter / Prettier
+{linter}
+
+## Type Check / Static Analysis
+{type_check}
+
+## Findings
+
+| ID | Severity | Area / location | Finding | Evidence | Required action | Status |
+|---|---|---|---|---|---|---|
+| FINDING-001 | {severity} | {area} | {description} | {evidence} | {required_action} | {finding_status} |
+
+If no findings remain, replace the sample row with `None` and record the review evidence. PASS requires all blocking findings to be resolved.
+
+## Documentation Impact
+
+| Update needed? | Related feature / docs | Reason / update |
+|---|---|---|
+| {docs_update_needed} | {related_docs} | {docs_update_reason} |
+
+## Final Decision
+{final_decision}

package/kanban-flow/templates/phase-6-feature-report.md

@@ -0,0 +1,78 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: DONE
+---
+
+# Feature Report
+
+## Feature
+{feature_name}
+
+## Completion Overview
+
+| Field | Result |
+|---|---|
+| Context | {context} |
+| Delivery summary | {delivery_summary} |
+| Reviewed execution | {execution_id} |
+| Testing / review status | PASS / PASS |
+
+## Requirement Summary
+{requirement_summary}
+
+## Scope
+{scope}
+
+## Implementation Summary
+{implementation_summary}
+
+## Changed Areas
+
+| Area / files | Change | Requirement / use case |
+|---|---|---|
+| {changed_area} | {change_summary} | {requirement_reference} |
+
+## Use Cases
+
+| Use case | Delivered behavior | Evidence |
+|---|---|---|
+| UC-001 {use_case_name} | {delivered_behavior} | {use_case_evidence} |
+
+## Test Summary
+| Metric | Result |
+|---|---:|
+| Test cases | {total_cases} |
+| Passed | {passed} |
+| Failed | {failed} |
+| Coverage | {overall_coverage}% |
+
+## Review Summary
+{review_summary}
+
+## Documentation Updated
+
+| Document | Update / purpose | Delivery |
+|---|---|---|
+| `docs/requirement/{context}/{feature_name}.md` | Confirmed requirement | CLI copies on archive |
+| `docs/use-cases/{context}/{feature_name}/README.md` | UC index and coverage | CLI copies on archive |
+| `docs/use-cases/{context}/{feature_name}/UC-###.md` | Individual UC narratives | CLI copies on archive |
+| `docs/use-cases/{context}/{feature_name}/diagram.md` | Actor/use-case diagram | CLI copies on archive |
+| `docs/testplan/{context}/{feature_name}.md` | Test contract | CLI copies on archive |
+| `docs/testplan/{context}/{feature_name}-result.md` | Current execution evidence | CLI copies on archive |
+| {other_document} | {documentation_updated} | {documentation_status} |
+
+Replace the UC wildcard row with the actual files. Record `N/A` with a reason if no other documents need updates.
+
+## Known Limitations
+- {known_limitation}
+
+## Accepted Follow-ups
+
+| Item | Reason deferred | Backlog reference |
+|---|---|---|
+| {follow_up} | {deferred_reason} | {backlog_reference} |
+
+## Final Status
+DONE

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@phuthuycoding/kanban-flow",
+  "version": "0.3.0",
+  "description": "Kanban workflow CLI — artifact-gated feature pipeline (brainstorm → plan → implement → test → review → archive)",
+  "type": "module",
+  "license": "MIT",
+  "author": "Quyen (phuthuycoding)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phuthuycoding/kanban-flow.git"
+  },
+  "homepage": "https://github.com/phuthuycoding/kanban-flow#readme",
+  "bugs": {
+    "url": "https://github.com/phuthuycoding/kanban-flow/issues"
+  },
+  "keywords": [
+    "kanban",
+    "workflow",
+    "cli",
+    "ai-agents",
+    "spec-driven",
+    "traceability",
+    "agentic",
+    "code-review",
+    "requirements",
+    "test-plan"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kf": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "docs/workflow",
+    "kanban-flow/templates",
+    "kanban-flow/review"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "chmod +x dist/index.js",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "oxlint": "^1.81.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/skills/kanban-archive/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: kanban-archive
+description: 'Close a PASS-reviewed feature or bug with kf archive. Features require a completion report and canonical docs; bugs update related docs only when needed. Use at review with current PASS reports or when completing closure in dones.'
+---
+
+# Kanban Phase 6 — Artifact (Autonomous)
+
+Argument: `<feature_name>`.
+
+Close the work item with traceable results and the appropriate documentation.
+
+---
+
+## 1. Prepare closure artifacts
+
+```bash
+kf status --change {feature_name}
+kf status --change {feature_name} --json
+```
+
+Require current PASS testing and review reports. Read `kind` before choosing closure work:
+
+- Feature: use `kf instruct feature-report --change {feature_name}` and write `phase-6-feature-report.md` in the review folder. Include actual changes, test/review evidence, documentation manifest, limitations and accepted follow-ups.
+- Bug: no feature report or feature planning artifacts are required. Read the bug report and review result; confirm the verified fix, regression evidence and docs impact.
+
+If already in dones, complete only missing closure work and validate; never reimplement.
+
+## 2. Sync docs
+
+For a feature, let `kf archive` copy requirement, UC index/files/diagram and test plan/current result into canonical docs. The requirement mirror under `docs/requirement/` was already written in Phase 1 — `kf archive` refreshes it and stamps `status: archived`. Do not manually copy the UC index/files, diagram or test plan before archive, and do not change approved source artifacts during closure. Update other affected docs from the plan's documentation impact as needed.
+
+For a bug, update existing related feature docs only when the fix changes documented behavior or reveals inaccurate documentation. Use the feature/context named in the bug report; do not overwrite feature docs with bug-report content. Record bug ID, fix summary and regression reference in the project's changelog or change-history section (e.g. CHANGELOG.md) when one exists. If behavior is already documented correctly, leave docs as-is and record “No documentation update required” with the reason in the review report. Bug archive does not automatically create canonical feature docs.
+
+## 3. Archive and validate
+
+```bash
+kf archive {feature_name}
+kf validate --change {feature_name}
+```
+
+`kf archive` requires current PASS reports, runs the dones hook, moves review → dones and marks metadata archived. Features additionally require the feature report and receive canonical copies; bugs do not. `kf stage ... dones` uses the same archive path. Validate after archive and check reported canonical destinations for a feature. Do not report completion if validation fails.
+
+When refreshing an item already in dones, canonical docs may include later bug fixes. If the CLI reports changed canonical docs, preserve them with `--skip-specs`; do not use `--force` to restore an older snapshot without explicit user direction.
+
+## 4. Git handoff
+
+```bash
+git status
+```
+
+Commit when the user requested it or project instructions explicitly require it. Use conventional commits: `feat({context}): ...` for features and `fix({context}): ...` for bugs. Include only this work item's changes, respect ignored .works directories and preserve unrelated working-tree changes. Otherwise report that changes are uncommitted.
+
+---
+
+## Done
+
+Pipeline complete. Deliver the final report:
+
+```text
+## Pipeline Complete: {context}/{feature_name}
+1. ✓ Confirm — requirement or bug triage
+2. ✓ Plan — approved feature contract or lightweight bug contract
+3. ✓ Implement — {M}/{M} tasks
+4. ✓ Test — {N}/{N} passed
+5. ✓ Review — PASS
+6. ✓ Archive — kf archive, docs sync/update status
+
+Artifacts: .works/dones/{feature_name}_{timestamp}/
+Feature canonical docs:
+- docs/requirement/{context}/{feature_name}.md
+- docs/use-cases/{context}/{feature_name}/README.md
+- docs/use-cases/{context}/{feature_name}/UC-###.md (one file per use case)
+- docs/use-cases/{context}/{feature_name}/diagram.md
+- docs/testplan/{context}/{feature_name}.md
+- docs/testplan/{context}/{feature_name}-result.md
+```
+
+For bugs, list only related docs actually updated, or state why none were needed. Report the commit SHA only if a commit was made.

package/skills/kanban-brainstorm/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: kanban-brainstorm
+description: 'Kanban Phase 1 — brainstorm the feature requirement with the user, create the feature via `kf new`, and author phase-1-spec-requirement.md with FR-### anchors. Use when a kanban feature is at the brainstorm stage, or right after "kanban {context} {feature}" starts a brand-new feature.'
+---
+
+# Kanban Phase 1 — Brainstorm (Human + Agent)
+
+Arguments: `<context> <feature_name>`.
+
+The user's idea is at its coarsest here. Your job is to convert a rough idea into a **precise, testable requirement** with `FR-###` anchors — everything downstream (UC, TC, traceability) hangs off them.
+
+Brainstorming is **divergence then convergence**: first open the problem up from every useful angle (ideas, users, edge cases, alternatives), then shut it down into a bounded, agreed requirement. Do not rush. The quality of Phase 1 decides how many questions the rest of the pipeline has to re-ask.
+
+**Run via orchestrator:** normally invoked by `kanban-flow`. Call this skill directly when a feature is (or should be) at the `brainstorm` stage.
+
+---
+
+## 1. Understand the challenge
+
+Orientation before ideation. Cheap questions here prevent expensive ones later.
+
+1. **Read the repository.** Structure, stack, tooling, data model, conventions. Reading code beats asking — never make the user explain what the code already answers.
+2. **Read one similar existing feature** (if any) for house patterns.
+3. **Restate the challenge.** In one or two sentences, play the user's idea back: *"You want X in order to achieve Y, in the context of Z — is that right?"*. Fix misunderstandings before generating ideas against the wrong target.
+4. **If no `.works/` → `kf init --defaults`** (full bootstrap without prompts: config, seeded `.kf` overrides, `.gitignore`).
+
+Rules of engagement:
+- **Material ambiguity** (missing scope, unclear behavior, conflicting acceptance criteria) → ask **up to 3 focused questions**, then proceed. Each question names the decision it feeds.
+- **Minor details** → make a reasonable assumption and record it in the spec under *Assumptions*.
+- The user is the *brief*, not the implementer. Do not trouble them with mechanics.
+
+---
+
+## 2. Diverge — open the problem (framework phase)
+
+A `kanban` launch can arrive with the idea fully formed or as a vague half-thought. **If the requirement is not already crystal clear, run a brainstorming framework** to widen the view before committing to a shape.
+
+Pick the framework that fits the situation. Ask yourself (or the user, if genuinely uncertain) which angle is weak:
+
+| Angle you need | Framework |
+|---|---|
+| Challenge the premise / rebuild from fundamentals | **First Principles** |
+| Improve / stretch an existing product or flow | **SCAMPER** |
+| User-centric problem shaping | **Design Thinking** |
+| New product / new market / launch narrative | **Working Backwards** |
+| Diagnose *why* something is broken | **5 Whys** |
+| Break a creative block / surface many options fast | **Rapid Fire** |
+
+When ambiguity warrants divergence, run one suitable framework and record the outcome in the spec. For an already precise requirement, proceed to authoring and confirmation.
+
+### Framework 1: First Principles Thinking
+
+1. **Identify the problem** — what are we actually trying to solve?
+2. **Break it down** — the fundamental truths/components that cannot be argued away.
+3. **Question assumptions** — for every "we need X", ask *do we really? what if we...*.
+4. **Rebuild** — if we started fresh with the truths as the only constraint, what would we build?
+
+```
+PROBLEM: [challenge]
+
+CURRENT APPROACH:
+- How it's typically done: ...
+- Assumptions baked in: ...
+
+FUNDAMENTAL TRUTHS:
+1. [core requirement that cannot change]
+2. [physical/logical constraint]
+3. [user need at the deepest level]
+
+QUESTIONED ASSUMPTIONS:
+- "We need X" -> Do we really? What if...?
+- "It must be Y" -> Why? Alternative...?
+
+REBUILT SOLUTION:
+- [the shape that survives]
+
+WHAT CHANGES IN THE SPEC:
+- Scope in / out decisions this surfed (only if it genuinely informs the requirement)
+```
+
+### Framework 2: SCAMPER
+
+Apply each lens to the feature. Generate at least one idea per letter.
+
+```
+CHALLENGE: [feature/flow being designed]
+
+[S] Substitute — other tech/approach/component?
+[C] Combine — which features/systems can merge?
+[A] Adapt — what's similar elsewhere, what can we copy across domains?
+[M] Modify — bigger/smaller/faster/slower? exaggerate what?
+[P] Put to other uses — who else could use this, for what?
+[E] Eliminate — what can be removed without killing the value?
+[R] Reverse — opposite ordering, roles, or flow?
+
+TOP 3 IDEAS:
+1. ... (why)
+2. ... (why)
+3. ... (why)
+
+WHICH ONES LAND IN THE SPEC:
+- [idea] -> FR/orientation; [idea] -> explicitly out of scope (recorded)
+```
+
+### Framework 3: Design Thinking
+
+1. **Empathize** — who is the user, what is their current journey, what do they *really* need (not just what they say)?
+2. **Define** — problem statement in the form: *"[User] needs [need] because [insight]"*.
+3. **Ideate** — 10+ ideas, no judgment, quantity first, build on each other.
+4. **Prototype** — the cheapest thing that validates the direction.
+5. **Test** — what feedback do we need, what metric proves it works?
+
+```
+EMPATHIZE:
+- User: [who]
+- Pain points: [...]
+- Current journey: [steps]
+
+DEFINE:
+- Problem statement: [user] needs [need] because [insight]
+- How Might We: [question]
+
+IDEATE (10+):
+1..10+
+
+PROTOTYPE:
+- MVP concept: ...
+- Cheapest validation: ...
+
+TEST:
+- Success metric: ...
+- Feedback needed: ...
+```
+
+### Framework 4: Working Backwards (Amazon-style)
+
+Start from the end experience and work back to what we must build.
+
+1. **Press release** — announce the finished feature.
+2. **FAQ** — answer the customer + internal questions.
+3. **Customer experience** — the detailed user journey.
+4. **Work back to requirements** — what must exist for that journey.
+
+```
+PRESS RELEASE:
+- Headline: [name] helps [user] [benefit]
+- Problem: [2-3 sentences]
+- Solution: [2-3 sentences]
+- How it works: [plain explanation]
+
+FAQ:
+- Q(A): what is it / how different / how to start / cost
+
+REQUIREMENTS THAT MUST EXIST:
+1. ... 2. ... 3. ...
+```
+
+### Framework 5: 5 Whys
+
+Use when the feature exists to fix a *problem* whose true cause is unclear. Iterate "why" until the root cause surfaces (5 is the rule of thumb; stop early if a real cause appears).
+
+```
+PROBLEM: [initial symptom]
+
+Why #1 -> Because: ...
+Why #2 -> Because: ...
+Why #3 -> Because: ...
+Why #4 -> Because: ...
+Why #5 -> Because: [root cause]
+
+ROOT CAUSE: [summary]
+
+WHAT THE FEATURE MUST ACTUALLY DO: [solution targeting the root cause, not the symptom]
+```
+
+### Framework 6: Rapid Fire
+
+Generate 15+ options in one pass, no filtering during generation.
+
+```
+CHALLENGE: [feature]
+
+IDEAS (15+):
+1..15+
+
+CATEGORIES:
+- Quick wins / Big bets / Experiments / Parking lot
+
+TOP 3 TO PURSUE:
+1. ... (why)
+2. ... (why)
+3. ... (why)
+```
+
+### Synthesis (always, whichever framework)
+
+End divergence by answering three questions in the spec's language:
+
+```
+IDEAS SURFACED: [what changed the shape]
+SCOPE DECISION: [what's in, what's explicitly out — and why]
+REMAINING BLIND SPOTS: [what we could not evaluate cheaply at Phase 1]
+```
+
+---
+
+## 3. Create the feature
+
+Check `kf list --json` first. If the feature already exists, resume its requirement; do not run `kf new` again. Feature and context names use letters, digits, hyphens or underscores and start with a letter or digit.
+
+**Pick the context before you run `kf new`.** A project may declare the contexts it uses in `.kf/config.json`, and `kf new` refuses anything outside that list:
+
+```bash
+kf contexts --json   # declared: [...], restricted: true|false
+```
+
+- `restricted: true` — use one of the declared names, spelled exactly. `Auth` is refused next to `auth`, because accepting both is how a second docs tree appears.
+- `restricted: false` — nothing is declared; any valid name works, and the `brief` field tells you how to propose a list. Proposing one is a suggestion for the human to confirm, never something to write into the config yourself.
+
+If `kf new` refuses the name, it prints the nearest declared one. Take that suggestion or ask the human — do not invent a new context to get past the refusal, and do not add one to `.kf/config.json`.
+
+```bash
+kf new {feature_name} --context {context}
+```
+
+Scaffolds `.works/brainstorm/{feature}_{ts}/` + metadata + seeded `phase-1-spec-requirement.md`.
+
+---
+
+## 4. Author the requirement
+
+Print the template and instructions:
+
+```bash
+kf instruct spec-requirement --change {feature_name}
+```
+
+Fill **every section** of `phase-1-spec-requirement.md`. Mapping from divergence to sections:
+
+- **Objective / Problem Statement** — the restated challenge (sharpened by the framework).
+- **Scope (in & out)** — the SCOPE DECISION from synthesis. Explicit "out" items are valuable: they stop Phase 2-3 from drifting.
+- **Actors** — humans and systems touching the feature.
+- **Functional Requirements `FR-###`** — **the traceability anchor.** One behavior per FR, phrased so a test could pass/fail on it. Include the priority (must/should/could) and a note carrying any framework rationale.
+- **Non-Functional Requirements** — performance, security, UX, accessibility, compliance.
+- **Main Use Cases** — one line each with `UC-###` ids (full narratives live in Phase 2).
+- **Constraints / Assumptions / Edge Cases / Open Questions** — edge cases should feel adversarial: empty states, concurrency, permissions, partial failure, boundary values.
+- **Test Strategy** — onboard the user on how deep to test (this locks what Phase 2 must produce):
+  - Ask: *"How far do you want this feature tested?"* with concrete options:
+    - `unit` — unit tests only, for logic and state. The default for a pure backend or utility feature.
+    - `unit+integration` — unit tests plus tests where the change meets another system, the database or an API. The default for an API or a datastore.
+    - `full` — unit, integration and **UI/E2E** (Playwright, Cypress, Detox and so on). The default for anything with a user interface or a critical flow, such as a web todo list, a login or a checkout.
+  - When the user picks `full`, ask how wide the UI coverage goes: *"UI tests for every flow, or only the critical ones?"* → `{test_level}: full`, `{ui_test_scope}: critical|all`.
+  - Record it in the spec under the labels that template actually uses: `Level` in the feature template, `Test Level` in the bug template, plus `UI Tests`, `Tools` (the framework name and the file that runs it) and `Coverage Target` (80% by default).
+  - **Let the nature of the feature set the default.** Do not ask again when the answer is obvious: a CRUD API is `unit+integration`, an app with a UI is `full`. Ask only when you genuinely cannot decide.
+- **Acceptance Criteria** — each `[ ]` must be independently verifiable by a human or a test. Under `full`, at least one criterion per FR must read as a UI action: what is clicked, what is typed, what appears on screen.
+
+Set `status: pending` → `status: confirmed` in the spec frontmatter when the human signs off (Phase 1 ends on this confirmation).
+
+Mirror the requirement to `docs/requirement/{context}/{feature_name}.md` (canonical, human-readable; create the context dir if missing — `kf archive` refreshes it later).
+
+```bash
+kf status --change {feature_name}
+```
+
+The checklist reports content completion; human confirmation is still required before advancing.
+
+---
+
+## 5. Confirm with the human
+
+Present a tight summary (do not dump the whole file):
+
+```text
+FEATURE: {name}  ({context})
+STATUS: pending
+
+OBJECTIVE: {one line}
+
+FR SUMMARY:
+- FR-001 | must | {behavior}
+- ...
+UC SUMMARY:
+- UC-001 {name}
+- ...
+
+ACCEPTANCE (sample):
+- [ ] {criterion}
+
+DECISIONS RECORDED:
+- {scope decision / assumption}
+- ...
+
+SCOPE OUT (explicit):
+- {item} — because {reason}
+
+Please confirm the requirement.
+```
+
+- On confirmation → set `status: confirmed`, mirror canonical requirement, run `kf stage {feature_name} planning`, then load kanban-plan.
+- If the user pushes back → update the spec, re-confirm. This is normal; the spec exists to absorb disagreement cheaply here, not in implementation.
+
+---
+
+## Done
+
+The requirement is confirmed and mirrored. Hand off to **Phase 2 — Planning**:
+
+```text
+Load the kanban-plan skill and write the four plan artifacts (implementation-plan, use-case-specification, use-case-diagram, test-cases). The one-line use-case summaries and the FR/UC ids from phase-1-spec-requirement.md are the input — the full narratives are written in Phase 2, not carried over from Phase 1. Do not re-derive the ids from scratch.
+```

package/skills/kanban-bug/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: kanban-bug
+description: 'Kanban bug workflow — triage and document a defect with reproduction, expected/actual result, severity, root cause and regression coverage before handing off to kanban-plan. Use when a work item has kind: bug.'
+---
+
+# Kanban Bug — Triage and fix a defect
+
+Argument: `<bug_name>`.
+
+A bug goes through the same state machine and approval gate as a feature, but Phase 1 must record enough to reproduce it and to stop it coming back.
+
+## 1. Verify
+
+```bash
+kf status --change {bug_name}
+kf show {bug_name}
+```
+
+Only use this skill when the metadata says `kind: bug` and the work item is in `brainstorm`. If the bug is already in `planning`, `backlog`, `implementation`, `testing` or `review`, resume the matching skill; do not recreate artifacts.
+
+## 2. Triage contract
+
+Read and fill `phase-1-spec-requirement.md` using the bug template (`kf instruct spec-requirement --change {bug_name}`):
+
+- Severity and the affected environments.
+- Reproduction steps that are deterministic enough to follow.
+- Actual result and expected result.
+- What the fix covers and what it does not, plus acceptance criteria for the behaviour a regression must protect.
+- Suspected root cause when there is evidence for one; when there is not, say it is undetermined.
+- Regression test strategy and acceptance criteria that can be checked.
+- The related feature when you can identify it, and the docs impact: which file needs changing and why, or that no docs change is needed.
+
+- **Sibling entry points**: list what else reaches the broken code. Review will ask which of them the fix covers, so naming them here is cheaper than discovering them later.
+
+Do not guess a root cause to make the report look finished. If you cannot reproduce it, report the blocker plainly and never assume the bug is PASS.
+
+Write the reproduction so someone else can run it and watch it fail. Review re-runs it rather than trusting the report, so steps that only work on your machine come back as a finding.
+
+## 3. Human confirmation
+
+Summarise the bug, its severity, the reproduction, the impact, the expected fix and the regression test for the user. Only once the user confirms do you set the frontmatter to `status: confirmed` and run:
+
+```bash
+kf stage {bug_name} planning
+```
+
+Then load `kanban-plan` on its bug branch. The bug report is the execution contract: do not create an implementation plan, a use-case index, narratives, a diagram, a test plan or a feature report. Planning still needs human approval, and the user still chooses start or backlog.
+
+## 4. Handoff
+
+```text
+Bug report confirmed. Load kanban-plan on the bug branch to approve the triage contract and ask start or backlog; keep the reproduction and the regression test inside the approved scope.
+```
+
+A FAIL or a REJECT, in testing or in review, sends the item back to implementation. `REQUIREMENT_BUG` still stops for the user to decide; do not use it in place of a bug report.