| name | kanbanzai-workflow |
| description | Use this skill whenever you are making progress decisions: deciding what to build, whether to proceed to the next stage, whether a state transition is valid, or whether to create new entities. Also activates when resolving entity lifecycle errors, determining human vs. agent responsibilities, or deciding whether to stop and ask.
|
Purpose
This skill defines the workflow stage gates, human/agent ownership boundary, and the
conditions that require you to stop and ask the human.
Stage Gates
Work progresses through seven stages. Each stage has a gate that must pass before
proceeding to the next.
| Stage | Who leads | Output | Gate to pass |
|---|
| Planning | Human | Agreed scope | Human signals readiness to design |
| Design | Human + Agent | Approved design document | Document approved |
| Features | Agent | Plan + Feature entities | Design document approved |
| Specification | Human + Agent | Approved spec document | Features exist |
| Dev plan & tasks | Agent | Task entities + dev plan | Spec approved |
| Implementation | Agent | Working code, passing tests | Tasks exist |
| Review | Agent | Review report, verdict | Implementation complete; feature in reviewing |
Implementation does not proceed directly to merge. After implementation is complete,
the feature must pass through the Review stage. See Feature Lifecycle States below
and read kanbanzai-review for the full review procedure.
Bug fixes and small improvements follow a lighter path — no design document or
specification needed unless the fix involves a significant architectural change.
Feature Lifecycle States
Feature entities move through an enforced set of lifecycle states. The complete
path from creation to merge is:
proposed → designing → specifying → dev-planning → developing → reviewing → done
There is no shortcut from developing directly to done. Every feature must pass
through reviewing before it may be marked done or merged.
reviewing
- Entered from:
developing, when the implementing agent has completed all tasks
and the implementation is ready for review.
- Meaning: Implementation is complete; a code review is in progress. The feature
may not be merged until the review concludes with an
approved or
approved-with-notes verdict.
- Who transitions to this state: The implementing agent, after all tasks are
done
or cancelled.
- Exit transitions: →
done (review approved) or → needs-rework (review found
blocking issues).
To transition into reviewing:
entity(action: "transition", id: "FEAT-...", status: "reviewing")
For the full review procedure, read kanbanzai-review.
needs-rework
- Entered from:
reviewing, when the reviewer finds one or more blocking findings
that prevent merge.
- Meaning: The feature has blocking findings that must be addressed before it can
be re-reviewed and merged.
- Who transitions to this state: The reviewing agent, after writing the review
report with a
changes-required verdict.
- Exit transitions:
- →
reviewing, after the implementing agent has addressed all blocking findings
and the feature is ready for re-review.
- →
developing, if the required changes are substantial enough to warrant
reopening tasks and resuming full implementation work.
To address rework and return to review:
entity(action: "transition", id: "FEAT-...", status: "reviewing")
The knowledge base will contain a rework-findings entry contributed by the reviewer.
Read it before beginning rework.
Human vs. Agent Ownership
Humans own: intent, priorities, approvals, and product direction. Humans make
technology choices, approve design documents, and accept completed work.
Agents own: execution — decomposing work, implementing, reviewing, verifying,
tracking status, and maintaining consistency — within the guardrails set by humans.
Agents never:
- Approve their own work
- Make final architecture or technology decisions
- Proceed past a stage gate without human approval
- Create design content without an approved design document
- Merge a feature that has not passed the Review stage
Emergency Brake
Stop and ask the human before proceeding if any of the following are true:
- You are about to write design content (data models, API shapes, technology choices)
without an approved design document
- You are about to create Plan, Feature, or Task entities without an approved design
- You are about to make a technology or architecture choice without explicit human approval
- You are unsure which workflow stage the current work belongs to
- Work has drifted beyond the scope of the current task, feature, or plan
- A review has returned
changes-required and the scope of rework is unclear
When in doubt, surface the question rather than guessing.
Entity Lifecycle
Entity lifecycle transitions are enforced. Invalid transitions are rejected with an error
that names the valid transitions from the current state.
Load references/lifecycle.md for transition diagrams covering feature, task, bug, and
plan entities.
Gotchas
Tool call failures: Read the error message. It names the valid transitions from the
current state. Do not retry with the same arguments — identify the correct transition first.
Stage gates apply by entity type, not work size: A one-line bug fix and a major feature
both follow the same lifecycle for their entity type. The size of the work does not change
the rules.
Implementation does not merge directly: After all tasks are done, transition the feature
to reviewing and follow the review procedure in kanbanzai-review. Do not call
merge until a review report with an approved verdict exists.
Verbal approval must be recorded immediately: When a human approves a document in
conversation, call doc with action: approve immediately. Verbal approval that is not
recorded does not satisfy the stage gate — the next operation will fail.
Related
kanbanzai-getting-started — session orientationkanbanzai-documents — registration, approval, drift, supersessionkanbanzai-agents — context assembly, task dispatch, commit formatkanbanzai-review — code review procedurereferences/lifecycle.md — entity lifecycle transition diagrams
