@phuthuycoding/kanban-flow 0.3.0

package/skills/kanban-flow/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: kanban-flow
+description: Drive a kanban feature or bug through brainstorm, planning approval, start-or-backlog decision, implementation, testing, review and archive using the kf CLI. Use when the user requests the kanban workflow or resumes a work item managed in .works. Delegates each phase to its dedicated skill.
+---
+
+# Kanban Flow — Orchestrator
+
+**The user describes the idea; the agent decides the rest.** One command runs the whole lifecycle; each phase runs a dedicated skill.
+
+**ARGUMENTS:** `<context> <feature_name>` — e.g. `kanban auth user-login` or `kanban billing payment-timeout --type bug`
+
+State is enforced by the `kf` CLI: artifact gates, approval fingerprints, execution ids, report statuses and traceability. The agent authors and verifies the content; file presence alone cannot prove that code was tested.
+
+**Human boundary:** user participates in **Phase 1 (brainstorm/bug triage)**, **Phase 2 (approval)** and the explicit **start-now vs backlog** decision. After the user chooses start, run everything autonomously within the approved scope. Stop and ask only for a decision on backlog start, REQUIREMENT_BUG or a scope change; do not ask "continue?" between normal phases.
+
+**Preflight:** if the project has no `.works/`, run `kf init --defaults` first (full bootstrap without prompts; use `kf init -i` when the user should answer the setup questions). Detect project stack/tooling by READING the repository — never assume.
+
+---
+
+## Phase model & artifact contract
+
+```
+brainstorm → planning → implementation → testing → review → dones
+                 ↘ backlog ↗
+```
+
+Folder name: `{feature_name}_{timestamp}` (created by `kf new`). Artifacts follow `phase-{x}-{name}.md`.
+
+| Phase | Skill | Gate artifacts (filled to LEAVE) | Notes |
+|-------|-------|----------------------------------|-------|
+| 1. Brainstorm / Bug triage | `kanban-brainstorm` or `kanban-bug` | `phase-1-spec-requirement.md` (`status: confirmed`) | Human + agent refine requirement or reproduce bug |
+| 2. Planning | `kanban-plan` | Feature: four phase-2 files + `use-cases/UC-###.md`; bug: confirmed bug report | **Human approval, then start/backlog decision** |
+| Backlog | — | Approved planning contract remains intact | Waiting for explicit user decision to start |
+| 3. Implement | `kanban-implement` | — (tasks.md tracks) | Autonomous |
+| 4. Testing | `kanban-test` | `phase-4-testing-result.md` (`status: PASS`) | FAIL/REJECT → loop to implementation |
+| 5. Review | `kanban-review` | `phase-5-review-report.md` (`status: PASS`) | FAIL/REJECT → loop; REQUIREMENT_BUG → STOP |
+| 6. Closure | `kanban-archive` | Feature: `phase-6-feature-report.md`; bug: current test/review evidence | Feature canonical docs or affected bug docs, then archive |
+
+**Two gate layers on every move:**
+1. **Artifact gate** — files exist and contain no template placeholders.
+2. **Directional gate** — report `status` semantics: FAIL/REJECT blocks forward motion and forces a loop back to implementation; REQUIREMENT_BUG blocks **all** motion (STOP FEATURE — never silently rewrite the requirement).
+
+For features, `kf validate` checks each `## TC-###` for FR references and matching individual UC files. Approval fingerprints the requirement, four planning artifacts and individual UC files. For bugs, approval fingerprints only the bug report; feature planning artifacts and feature report are not required. A changed contract must return to planning for human approval. Each entry to testing creates a new execution id; testing and review reports must carry that id in `execution:`. Read templates with `kf instruct <artifact> --change <feature>` to obtain the current id and exact output path.
+
+Feature canonical docs are synced by the CLI on archive:
+- Requirement: `docs/requirement/{context}/{feature_name}.md`
+- Use cases: `docs/use-cases/{context}/{feature_name}/README.md`, one `UC-###.md` per use case and `diagram.md`
+- Test plan/result: `docs/testplan/{context}/{feature_name}.md` and `{feature_name}-result.md`
+
+Work item type is stored in `.kfw.json` as `kind: feature|bug`. Create a bug with `kf new <name> --type bug`; route it to `kanban-bug` for reproduction and triage before planning.
+
+Bug closure updates the existing related feature docs only if needed. Do not auto-create feature docs for a bug or overwrite a feature requirement with bug-report content.
+
+---
+
+## How to delegate phases
+
+The pipeline is ONE run but each phase has a specialist skill. Drive it like this:
+
+```bash
+kf status --all                # which phase is each feature in?
+kf status --change {feature}   # current phase + artifact checklist + Next: + Approval
+```
+
+Then **load the skill for the feature's CURRENT phase** and follow it to its endpoint (each skill ends pointing at the next one). Do not re-read old phase instructions you've already executed; go straight at the target.
+
+If planning is already approved and its fingerprint is unchanged, ask whether to start now or keep the item in backlog. If an item is in backlog, do not start implementation without an explicit user decision. If review has a current PASS report, hand off to kanban-archive. If already in dones, validate and finish only missing closure work; never implement again. Resume existing artifacts and tasks instead of recreating the item or approved plan. `kf status --all` includes backlog and dones.
+
+## Multi-agent harness
+
+If `.kf/config.json` has `harness.stages`, some stages are assigned to **roles** (writer, coder, tester…), each backed by a runner CLI. Before doing a stage's work yourself, read `kf status --change {feature} --json`: when `assignedRoles` is non-empty, you are the orchestrator for that stage — do not do the work, hand it off:
+
+```bash
+kf run {feature}            # blocking; runs the stage's whole role chain in order
+kf run {feature} --detach   # long stages (implementation): returns a chain id
+kf runs {feature}           # poll until the runs are done, then read their STATUS
+kf run {feature} --role writer   # re-run one role of the chain
+```
+
+A stage can list several roles (`brainstorm: ["researcher", "writer"]`); they run one after another and each gets told where the previous one wrote. If a role does not finish `DONE`/`DONE_WITH_CONCERNS`, the chain stops there and the later roles never run — read the log of the role that stopped, do not simply re-run the chain.
+
+When polling a detached chain, check the chain column in `kf runs` (`1/2`, `2/2`): a run marked `chain stopped 1/2` means the later roles never ran, so the stage is **not** done even though nothing is running. Treat it like a stopped chain: read that role's log before deciding.
+
+Then act on the worker's `STATUS:`: `DONE` → `kf validate --change {feature}` and decide the transition as usual (gates, not the worker's word, decide); `DONE_WITH_CONCERNS` → read the concerns in the run log, then decide; `BLOCKED` / `NEEDS_CONTEXT` → stop and ask the user. A run without a `STATUS:` line or with a non-zero exit is not done. Never do an assigned stage yourself unless the user says so. Human gates stay with you.
+
+If you are resuming mid-pipeline (the feature already exists), skip straight to the phase skill for its current phase. **Never trust a folder location alone — a stage folder is not "done"; artifact + report completeness is.**
+
+---
+
+## Interaction policy
+
+- User gives ONE command. Agent does everything else automatically.
+- Brainstorm asks about **material ambiguity** only (missing scope, unclear behavior, conflicting acceptance criteria). Minor details → reasonable assumption + record it in the spec.
+- Confirm the requirement in Phase 1, then obtain execution-contract approval in Phase 2. Present a tight summary + implementation plan and ask for approval. On approval run `kf approve`. Without approval, do not start autonomous execution.
+- If scope must change after approval, stop implementation and explain the change. On the user's direction run `kf stage <feature> planning`, revise the contract and obtain fresh approval. REQUIREMENT_BUG blocks this route too; report it and await a human decision.
+- Auto-fix benign blockers once. Stop + ask only when genuinely stuck.
+- Never bypass a failed gate with `--force` unless the user explicitly approves.
+
+---
+
+## CLI reference
+
+```text
+kf init                        # scaffold .works/ + hooks + docs
+kf doctor [--json]             # diagnose the project (stage dirs, config, metadata, skills); exit 1 when broken
+kf contexts [--json]           # declared contexts + counts, or a survey brief when none
+kf new {feature} --context {ctx} [--type feature|bug]   # Phase 1: create feature/bug + seed spec
+kf status --change {feature}   # artefact checklist + Next: + approval state
+kf instruct {artifact} --change {feature}   # current execution id + exact output path
+kf approve {feature}           # Phase 2 HITL gate
+kf validate --change {feature}  # gate + traceability issues
+kf stage {feature} {phase}     # move (gates + hooks run; planning → backlog/implementation)
+kf run {feature} [--detach]    # run the roles assigned to the current stage (harness.stages), in order
+kf runs {feature}              # worker run history (role, runner) + STATUS lines
+kf archive {feature}           # review(PASS) → dones + copy canonical docs
+```
+
+Contexts: a project may declare the ones it uses in `.kf/config.json`, and the first entry is the default. `kf new` refuses a context outside that list and names the nearest declared one; a case-only variant is refused too. Run `kf contexts --json` before `kf new` and use a declared name exactly. When `restricted` is false nothing is declared and any valid name works. Never add a context to the config to get past a refusal — naming a business domain is the human's call.
+
+Phase hooks: `<project>/.kf/hooks/{phase}.sh` run automatically before entering a phase (project → user `~/.kf/hooks` → package precedence). Exit non-zero blocks the transition (`--skip-hooks` bypasses). The agent does NOT run hooks manually — `kf stage` does.
+
+---
+
+## Hard rules
+
+- Do NOT ask "continue to next step?" — autonomous after the user chooses start at the Phase 2 decision gate.
+- Obtain requirement confirmation and planning approval; after approval continue within the approved scope.
+- After planning approval, explicitly ask whether to start implementation now or move to backlog. Never infer this choice.
+- Never `mv` feature folders manually — always `kf stage` / `kf archive`.
+- Never bypass a failed gate with `--force` unless the user explicitly approves. Every real bypass (`--force` on a failing gate, `--skip-hooks` on an existing hook) is recorded in `.kfw.json` and reported by `kf status`/`kf validate`.
+- Always write `phase-4-testing-result.md` and `phase-5-review-report.md` — gates enforce it.
+- FAIL/REJECT loops back to implementation and re-testing before review. REQUIREMENT_BUG → STOP, never rewrite the requirement. When the item should be dropped for good (requirement wrong at the root, work superseded, user says stop), **propose** `kf cancel {feature} --reason "<why>"` and let the user decide; never cancel on your own. Reopening later is `kf stage {feature} <the stage it was cancelled from>`.
+- No scope creep beyond the approved plan.
+- Follow the project's AGENTS.md and the user's permissions. Autonomous execution does not authorize unrelated changes, database operations, deployment or messages to others.
+- Never silently swallow errors. If a step can't complete and can't be auto-fixed, STOP and report.
+- The user's single command IS authorization for the full pipeline — up to the Phase 2 approval gate.

package/skills/kanban-implement/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: kanban-implement
+description: 'Implement an approved kanban feature or bug, track tasks and verify the build. Use in implementation, or after an explicit start decision from planning/backlog or a FAIL/REJECT repair loop.'
+---
+
+# Kanban Phase 3 — Implement (Autonomous)
+
+Argument: `<feature_name>`.
+
+Execute the approved implementation plan for a feature, or the approved bug report's fix scope and regression strategy for a bug. If implementation requires a scope change, explain it and obtain the user's decision before revising the contract.
+
+**Invoked through `kf run`?** If your prompt starts with `kf-run:`, you are a worker for this stage only: skip the "move to stage" step below, never run `kf stage` / `kf approve` / `kf archive` / `kf run`, never edit approved contract artifacts, do not commit, and end your final message with two lines exactly: `STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and `Summary: <one or two sentences>`. The main agent reads them and decides the transition.
+
+---
+
+## 1. Move to implementation
+
+Read `kf status --change {feature_name}`. Move only when coming from planning or backlog with a valid approval, or when a FAIL/REJECT report requires a loop. If already in implementation, skip the move and resume existing tasks. If approval changed, stop and return to planning on the user's direction. Entering implementation from backlog requires the user's explicit start decision.
+
+```bash
+kf stage {feature_name} implementation
+```
+
+Create tasks.md if missing: `- [ ] 1. ...` checkboxes mapping tasks to the approved test cases for a feature, or reproduction/acceptance/regression scope in the bug report for a bug. Preserve completed tasks on resume; add the required fix tasks when looping. Record the starting HEAD and pre-existing working-tree changes in a `## Baseline` section at the top of `tasks.md` so review can distinguish this work item's changes.
+
+## 2. Work by dependency order
+
+- Independent tasks → **parallelize via subagents**.
+- Sequential / dependent tasks → main agent.
+
+**Subagent prompt contract** — every subagent prompt must state:
+
+- Task: the exact task + the TC it must satisfy
+- Files to read: plan excerpt, reference files, repo conventions
+- Files it may modify: explicit allowlist — nothing else
+- Acceptance criteria: what "done" means, verifiable
+- Constraints: no contract changes, no unrelated edits
+- Context: `.works/implementation/{feature}/` path (and reports path when applicable)
+
+**Subagent status protocol** — require every subagent to end with:
+
+```text
+Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+Summary: one or two sentences
+Concerns/Blockers: (optional)
+```
+
+Treat `DONE_WITH_CONCERNS` and `BLOCKED` as not-done: resolve the concern or unblock before ticking the task.
+
+## 3. Tick tasks as they land; gate on build
+
+```bash
+{build_command}
+```
+
+- PASS → continue.
+- FAIL → analyze, fix, re-run.
+- Failed again → STOP, show error, ask.
+
+When all tasks ticked, run the FULL build (not just the touched module).
+
+Do not modify the approved requirement, plan or test-case contract. Project-specific permissions for database operations and other external actions still apply.
+
+---
+
+## Done
+
+All tasks done, build green, no test regressions. Hand off:
+
+```text
+Load the kanban-test skill and move the feature to testing.
+```

package/skills/kanban-plan/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: kanban-plan
+description: '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.'
+---
+
+# Kanban 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
+
+```bash
+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.
+
+Print each template and fill the file at its path:
+
+```bash
+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
+```
+
+### implementation-plan
+- Scope: now / supporting / future / not-in-scope
+- `TASK-###` breakdown, complexity, impact analysis (backend / frontend / DB / API / infra / security / performance / regression / deps)
+- 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.md` only as an index and coverage summary.
+- Write **one file per use case** under `use-cases/UC-###.md`, using `kf instruct use-case --id UC-###`.
+- Each file contains one `UC-###`: goal, actors, preconditions, trigger, main / alternative / exception flows, postconditions, business rules, data and acceptance criteria.
+- The file name and 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` → `Unit` cases only, one per acceptance criterion and per edge case, each tied to an FR and a UC.
+  - `unit+integration` → add `Integration` cases wherever the change meets another system, the database or an API.
+  - `full` → add **`UI / E2E`** cases for the user-facing flows: what is clicked, what is typed, what appears on screen, following the `UI Tests` scope (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 referencing `FR-###` (spec) and `UC-###` (the matching individual use-case file). `kf validate` blocks 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.md` before generating the cases, and say so when you present the contract for approval.
+
+## 3. Human approval gate
+
+```bash
+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:
+
+```bash
+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:
+
+```text
+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.
+```

package/skills/kanban-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: kanban-review
+description: 'Review a kanban feature or bug against its approved scope, current testing evidence and layered review rules. Write PASS/FAIL/REJECT/REQUIREMENT_BUG for the current execution. Use in review.'
+---
+
+# Kanban Phase 5 — Review (Autonomous)
+
+Argument: `<feature_name>`.
+
+Stand on quality, not survivor. Load layered review rules, audit the changes, and write a report whose `status:` is the truth `kf` trusts.
+
+**Invoked through `kf run`?** If your prompt starts with `kf-run:`, you are a worker for this stage only: skip the "move to stage" step below, never run `kf stage` / `kf approve` / `kf archive` / `kf run`, never edit approved contract artifacts, do not commit, and end your final message with two lines exactly: `STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and `Summary: <one or two sentences>`. The main agent reads them and decides the transition.
+
+---
+
+## 1. Move to review
+
+```bash
+kf stage {feature_name} review
+```
+
+(Already there → skip. If the move is refused, run `kf validate --change {feature_name}` — a missing/stale or non-PASS testing report blocks this direction; loop back through kanban-test.)
+
+## 2. Load review rules
+
+- Resolve rules per filename in project → user → package order. Include general, security and performance plus the project's stack rule when available.
+- Project: `{project_root}/.kf/review/rules/*.md`; user: `~/.kf/review/rules/*.md`; package: `kanban-flow/review/rules/*.md` beside the installed CLI's package.json. If no rule source is available, report the missing rules instead of silently skipping review.
+- Stack packs (`node`, `go`, `rust`, `python`, `php`, `ruby`, `java`) are opt-in: if the project's stack has no `{stack}.md`, suggest `kf rules` (auto-detect) or `kf rules --stack <id>` to install it — they are not auto-loaded from `kanban-flow/review/stacks/`.
+
+Review **only files actually changed**. Record findings with severity HIGH / MEDIUM / LOW. Reproduce plausible failures — don't infer.
+
+**AI-assisted code risk lens** — hunt for the failure modes AI-generated code produces most:
+
+- Phantom tests: tests that execute code but never assert the behavior the spec requires
+- Catch-and-swallow: catches that hide errors instead of handling or rethrowing with context
+- Generic helpers without a domain anchor: abstractions invented for one call site
+- Scope drift: changes outside the approved contract and task list
+- Unrelated broad rewrites: reformatting or refactoring files beyond the diff's purpose
+- Polished comments/commits that describe the change but never explain intent or risk
+
+Preserve decisions: do not reopen verified findings or silently undo user-chosen scope, libraries, or thresholds. Before applying a security finding, threat-model it — state what the code stores, protects, and exposes; a finding without a reachable attack path is LOW.
+
+Use the `## Baseline` recorded at the top of `tasks.md` (starting HEAD + pre-existing working-tree changes) to include committed, staged, unstaged and new untracked feature files. Preserve unrelated pre-existing changes. Verify the testing report is PASS for the current execution id. After any implementation fix, loop through testing again before writing a new review result.
+
+## 3. Write review-report
+
+For `kind: bug`, review against the bug report and existing feature behavior. Check reproduction evidence, regression tests and fix scope; do not demand feature planning artifacts. Record the verified root cause and whether related feature docs need an update. If no documentation changes are needed, say why.
+
+A bug fix is reviewed adversarially, because a narrow fix is the most common way a bug comes back wearing different clothes. Two things go in every bug review report, and "none" is a valid answer only when you say what you looked at:
+
+- **Reachable regressions.** Name what else calls the code you changed, and what a plausible caller passes that the fix did not consider. A guard added for one entry point rarely covers the others — list the sibling paths and say, for each, whether you checked it or not. Do not write "no regressions"; write what you reached for.
+- **Claims you disproved.** State at least one thing the implementer asserted that you tried to break and could not — the root cause, the blast radius, a "this cannot happen" in a comment. Re-run the reproduction yourself rather than trusting the report, and if an explanation in a comment is load-bearing, verify it instead of reading it. Comments that justify a fix have been wrong in exactly the direction that made the fix look correct.
+
+A test that passes proves the code does something; it does not prove the test would fail if the fix were removed. When a fix turns on one predicate, delete or invert it and confirm a test goes red. A test that stays green under that is not protecting anything, and should be reported as a finding.
+
+```bash
+kf instruct review-report --change {feature_name}
+```
+
+Fill `phase-5-review-report.md`, set frontmatter `status:` to exactly one of:
+
+- `PASS` — no HIGH blockers; change is shippable
+- `FAIL` — HIGH blockers / broken tests
+- `REJECT` — does not meet DoD / acceptance criteria
+- `REQUIREMENT_BUG` — the requirement itself is wrong vs. real product need
+
+Set `execution:` to the current id from instruct and keep Review Status/Final Decision consistent with frontmatter. Assess MEDIUM findings against acceptance and DoD; do not declare PASS merely because there are no HIGH findings.
+
+## 4. The directional gate decides
+
+- `PASS` → load kanban-archive for the applicable feature/bug closure before running `kf archive`.
+- `FAIL`/`REJECT` → **structural fix needed**: loop back, re-implement, then the feature must be **re-tested before review again** (kanban-test skill).
+
+```bash
+kf stage {feature_name} implementation
+```
+
+- `REQUIREMENT_BUG` → **STOP FEATURE.** Do not silently rewrite the requirement — report back to the user what the review found and ask how to proceed. `kf stage` blocks all movement here by design.
+
+---
+
+## Done
+
+A decisive report written. Hand off:
+
+```text
+If PASS: load the kanban-archive skill.
+If FAIL/REJECT: load kanban-implement (then kanban-test before returning here).
+If REQUIREMENT_BUG: stop and report to the user.
+```

package/skills/kanban-test/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: kanban-test
+description: 'Test a kanban feature against its approved test plan or a bug against reproduction and regression scope. Write current-execution results with PASS/FAIL/REJECT/BLOCKED. Use in testing.'
+---
+
+# Kanban Phase 4 — Testing (Autonomous)
+
+Argument: `<feature_name>`.
+
+Prove the feature against the plan's test cases. The report's `status:` IS the decision — `kf stage` reads it and blocks the wrong direction.
+
+**Invoked through `kf run`?** If your prompt starts with `kf-run:`, you are a worker for this stage only: skip the "move to stage" step below, never run `kf stage` / `kf approve` / `kf archive` / `kf run`, never edit approved contract artifacts, do not commit, and end your final message with two lines exactly: `STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` and `Summary: <one or two sentences>`. The main agent reads them and decides the transition.
+
+---
+
+## 1. Move to testing
+
+```bash
+kf stage {feature_name} testing
+```
+
+(Already there → skip.)
+
+If `kf stage` refuses the move, run `kf validate --change {feature_name}` to see what is missing — unfinished `tasks.md` checkboxes block entry to testing (DoD), so tick them in implementation first.
+
+Every entry to testing creates a new execution id. Keep old reports as evidence, but never reuse them as proof for the current implementation. Read the current id from `kf status` or `kf instruct ... --change`.
+
+## 2. Run against the plan's test cases
+
+Read the Test Strategy from `phase-1-spec-requirement.md` (Test Level / UI Tests / Tools / Coverage Target) — it was committed in the approved plan. Detect the real test tooling from the repo. Execute exactly what the level promises: `unit` → unit suite; `unit+integration` → + integration; `full` → + UI/E2E suite (Playwright/Cypress/...). If `full` and the UI tests are missing or skipped, that's a gap — report it, don't fake coverage.
+
+Track TC-by-TC: Status / Actual / Expected / Tool / Evidence.
+
+For `kind: bug`, use the bug report's reproduction, expected result, acceptance criteria and regression strategy instead of a phase-2 test plan. Verify the defect is fixed and run the affected regression suite; use descriptive test IDs or actual test names in the results table. Do not require FR/UC/TC artifacts for a bug.
+
+## 3. Write testing-result
+
+```bash
+kf instruct testing-result --change {feature_name}
+```
+
+Fill `phase-4-testing-result.md`, set frontmatter `status:` to exactly one of:
+
+- `PASS` — all tests pass, coverage target met
+- `FAIL` — tests failing
+- `REJECT` — feature does not meet acceptance criteria
+- `BLOCKED` — cannot test (env/tooling)
+
+Always write the report, including `execution:` from the current template. Include per-TC results, actual commands, evidence and coverage against the approved target. In the "Commands and Evidence" table the Exit code column must be the real numeric exit code of each command you ran; `kf validate` rejects a `PASS` report that has no command row or any exit code other than `0` (`testing_exit_code`). Keep status and conclusion consistent. Missing tooling, skipped required tests or unmeasured required coverage cannot count as PASS. Write outcomes here; keep phase-2-test-case.md unchanged.
+
+## 4. The directional gate decides
+
+- `PASS` → `kf stage {feature_name} review`
+- `FAIL`/`REJECT` → loop to implementation, apply the fix, then enter testing again and write a result for the new execution id:
+
+```bash
+kf stage {feature_name} implementation
+```
+
+...then return here and re-test before attempting review again.
+
+- `BLOCKED` → stop and report the environment/tooling blocker. Do not advance or substitute a known issue for required passing tests.
+
+Still failing after one fix cycle → STOP, show failing tests, ask: fix deeper / record as known issue / abort.
+
+---
+
+## Done
+
+Report written with a decisive status. Hand off:
+
+```text
+If PASS: load the kanban-review skill.
+If FAIL/REJECT: kanban-implement first, then testing with a new execution id.
+If BLOCKED: stop and report the blocker.
+```