pal-e-docs

Convention: Kanban Over Plans

convention-kanban-over-plans Convention

active convention
Project

Convention: Kanban Over Plans

Axioms

A kanban implements a collection of user story and architecture notes. User stories define why the work exists. Architecture notes define what the system looks like. The kanban is where stories become working software through architecture. Without stories and architecture, a board is just a task list.
A project houses kanbans together for the purpose of an overarching goal. The goal is the Vision. User stories express the goal as needs. Architecture expresses the goal as a system. Kanbans execute the goal by implementing stories through architecture. Everything in a project serves the goal.

Principle

Kanban boards are the work execution tool. Plans are historical artifacts. Architecture diagrams and user stories are the project anchors — they give the kanban its purpose and its definition of done.

Why

Plans create rigid plan→phase→subphase hierarchies that duplicate what kanban provides natively. A ticket with children IS a phase. A sub-board IS a plan. The board is both the planning tool and the execution view. No separate document needed.
But a kanban without stories or architecture is incomplete by definition. Stories provide the acceptance criteria — how you know the work is done. Architecture provides the system map — how you know where the work goes. The traceability triangle (story ↔ architecture ↔ board item) isn't overhead, it's the mechanism that turns a task list into purposeful execution.

The Traceability Model

Every board item carries three labels:
  • story:X — which user story this serves (references a story-{project}-{key} note)
  • arch:X — which architecture component this touches (references an arch-{facet}-{project} note)
  • type:X — what kind of work (feature, bug, infra, etc.)
This creates the traceability triangle: User Story ↔ Architecture ↔ Board Item. The story note defines why. The architecture note defines where. The board item tracks when. No plan note needed as an intermediary.
Foundational work (infra, devops) may omit the story: label — the absence communicates that the work enables stories without being one.

Project Structure

A project page (see template-project-page) defines:
  • Vision — the overarching goal (stable, rarely changes)
  • User Stories — index table linking to user-story notes. The needs the project serves.
  • Architecture — three architecture notes (domain, dataflow, deployment). The system that serves the needs.
  • Board — the primary kanban. Implements the stories through the architecture.
  • Status — what's true right now (derivable from board state)
  • Milestones — significant completions
  • Repos — what code lives where
A project has one primary board plus decomposition boards as needed (see template-board). All boards in a project serve the same overarching goal.

What Happens to Existing Plans

  • Existing plan notes remain as historical reference
  • Plan items removed from boards — they inflate WIP
  • Active phase notes continue as board items but don't need a parent plan
  • New work starts as a Forgejo issue on the board

Supersedes

  • template-plan — no longer required for new work
  • feedback_one_plan_per_project — one primary BOARD per project (not one plan)
  • feedback_todos_plan_pipeline — all work goes through the board

Cross-Repo Pipeline Boards

Some work spans multiple repos and follows a defined pipeline (e.g., Capacitor mobile lifecycle). These get a cross-repo pipeline board — a single board that tracks items across repo boundaries through pipeline stages.
Board items on cross-repo boards carry an additional label:
  • consumer:X — which consuming project this item belongs to (e.g., consumer:westside, consumer:mcd-tracker). Enables filtering a shared pipeline board by project.
The full label set for cross-repo board items becomes: story:X, arch:X, type:X, consumer:X.
Rules:
  • Cross-repo boards are owned by the pipeline SOP, not by any single project (e.g., board-capacitor-mobile is owned by sop-capacitor-mobile-lifecycle).
  • Column flow still follows sop-board-workflow — backlog, todo, next_up, in_progress, done.
  • The consumer:X label is required on every item. Items without a consumer label are malformed.
  • Pipeline stages (from the SOP) map to board items, not board columns. Columns remain kanban state, not pipeline position.
  • sop-board-workflow — column flow SOP
  • template-project-page — project page structure
  • template-ticket — board item conventions (traceability triangle)
  • template-user-story — user story note format (the WHY)
  • template-architecture — architecture note format (the WHAT/WHERE)
  • template-board — fractal decomposition boards. When a ticket is too big (>5 min), it gets a board note with scoped user stories + architecture + kanban. Same structure at every level. "A sub-board IS a plan" — formalized.
  • sop-capacitor-mobile-lifecycle — first cross-repo pipeline board consumer.