Workflows

A workflow is the path an initiative takes from idea to completion. It is not just a set of labels — it is a contract about who does what, when, and what evidence is required before moving forward.

Why workflows exist

Without a workflow, a feature request is just a note. With a workflow, it becomes a tracked piece of work with clear phases, assigned agents, and gates that enforce quality. You cannot move from planning to implementation until the planning gate is satisfied. You cannot mark an initiative done until review is complete.

This prevents the common failure mode where work skips steps — designs that were never reviewed, code that was never tested, bugs that were patched without understanding the root cause.

Choosing an initiative workflow

• FEAT is for product or user capabilities: new behavior, user-visible enhancements, onboarding/customer-facing changes, or work that needs product discovery.
• TECH is for technical or system capabilities: platform changes, refactors, migrations, infrastructure/internal tooling, security hardening, performance work, dependency upgrades, and system capability improvements.
• FIX is for bug and root-cause repair: reproduce the failure, choose a patch or structural correction, then prove the regression is gone.
• CHORE is for routine maintenance: low-risk upkeep that does not need product discovery, architecture decisions, or implementation-heavy planning.

The feature workflow

backlog → design → planning → ready → in_progress → review → done → archived

Backlog

The initiative exists but no work has started. It is a captured idea, waiting to be picked up.

Design

This is where the product and architecture are defined. kpm leads product discovery, closing requirements with you one at a time via questionnaire. karch reads the approved requirements and drafts an architecture decision record. kui creates mockups if there are UI decisions.

The design phase is iterative. kpm does not propose a full feature spec in one shot. Each requirement is closed individually — proposed, confirmed or corrected, then moved on from. This prevents the common problem where an agent confidently designs the wrong thing because it misunderstood the goal early on.

Gate to planning: A PRD and ADR must be approved via document review.

Planning

klead translates the approved design into a story tree. One epic per major component, stories inside each epic as vertical slices. Every story names the files to touch, cites the relevant ADR section, and lists measurable acceptance criteria.

ktest reviews each acceptance criterion for testability. If an AC says "handles auth correctly," ktest rewrites it to "returns 401 on invalid token" — one condition, verifiable.

Gate to ready: At least one epic and one story with acceptance criteria must exist.

Ready

Planning is complete. The initiative waits in queue for a developer to begin.

Gate to in_progress: At least one story with acceptance criteria.

In progress

kdev implements the stories. For each story, kdev reads the story description, the cited ADR section, and the named files, then implements and verifies each acceptance criterion with concrete proof.

Other agents support as needed: ktest when tests are unclear, ksec when security paths are touched, kreviewer when early review helps.

Gate to review: All epics must be complete.

Review

Round one runs kreviewer and ktest in parallel. kreviewer reads changed files in context and compares against the PRD and ADR. ktest runs the full test suite and linter.

If either flags issues outside their domain — architectural deviation, scope drift, security concerns — round two brings in karch, kpm, klead, or ksec.

This iterates until all findings are resolved. You confirm before marking done.

Done and archived

Done means all work is finished and verified. Archived means the initiative is filed away — completed, cancelled, or superseded.

The fix workflow

backlog → triage → planning → ready → in_progress → review → done → archived

Fixes are similar to features but start with triage instead of design. kdev reproduces the bug, identifies the root cause, and presents two options:

• A short-term patch — what changes, how fast, what risk remains
• A long-term structural fix — broader changes, what recurrence class it prevents

You pick the approach. Then planning breaks it into stories.

Every fix story requires a regression-test acceptance criterion. The test that reproduced the bug must now pass.

The chore workflow

backlog → ready → in_progress → done → archived

Chores skip design and triage. Use this for maintenance tasks that don't need product or architecture decisions — dependency updates, configuration changes, cleanup.

The TECH workflow

backlog → technical_discovery → architecture → planning → ready → in_progress → review → done → archived

TECH is a first-class workflow for direct technical initiatives: platform work, architecture-led refactors, developer-experience improvements, infrastructure changes, migrations, and other engineering work where the primary question is technical execution rather than product definition.

TECH follows the feature-style rigor where needed, but it does not default to product or UI phases. karch leads technical discovery and architecture. klead turns the approved technical discovery and ADR decisions into maximum-detail implementation stories. kdev, kinfra, ksec, kdevex, and ktest participate according to the technical surface area.

kpm and kui are opt-in for TECH. Bring in kpm only when product policy, user-facing value, pricing, positioning, or requirement trade-offs need product ownership. Bring in kui only when the technical change creates or changes user-visible flows, layouts, interaction patterns, or visual design. Otherwise, TECH stays on the direct technical path.

TECH planning stories must be executable from the story alone: resolved objectives and constraints inline, explicit contracts, file paths, verify gates, migration and rollback notes where applicable, out-of-scope, and measurable Given/When/Then acceptance criteria.

Epic and story lifecycles

An epic moves through: todo → ready → in_progress → done → archived. It cannot be done until all its stories are done, archived, or rejected.

A story moves through: todo → doing → done → rejected → archived. It cannot be done until its acceptance criteria are verified.

Where you see workflows

• Plan (Mod+3) shows initiatives in board and list views, with their current state
• Work (Mod+2) shows active sessions and initiatives
• Tools (Mod+7) has a Workflows tab where you can browse and edit workflow definitions

Related pages

• Plan a feature — the full feature planning flow
• Fix a bug — the bug fix flow
• Agents — which agents run in each phase

Gate configuration enforcement

Malformed or empty configured gates fail closed and block the transition with an actionable message — a gate with no operands, blank operands, or an expression that does not parse never silently passes a transition.