Using Kanban

Using Kanban

Overview

Kanban is an Agile/SCRUM work item management system using a hierarchical folder structure with markdown files. Each work item has YAML frontmatter for metadata and markdown content for details.

Core principle: Break large initiatives into smaller deliverable units, track state through ToDo → InProgress → InReview → Done.

When to Use

• Planning new development initiatives
• Creating work items (epics, features, stories, bugfixes, tasks)
• Starting work from the backlog
• Tracking progress across multiple items
• Organizing work into sprints or iterations

Not for: Ad-hoc fixes (use /fix-errors), quick tasks without tracking needs.

Folder Structure

<PROJECT_ROOT>/.kanban/
├── epics/
│   └── epic-<id>-<slug>/
│       ├── _epic.md
│       └── features/
│           └── feature-<id>-<slug>/
│               ├── _feature.md
│               └── items/
│                   ├── story-<id>.md
│                   ├── bugfix-<id>.md
│                   └── task-<id>.md
└── standalone/
    ├── stories/
    ├── bugfixes/
    └── tasks/

CRITICAL: Kanban files go in the project root, not in the workflow files location.

Work Item Types

States

File Format

Each item uses YAML frontmatter + markdown:

---
id: story-001
title: User can log in with email
type: story
parent: feature-001
state: ToDo
priority: High
effort: 3
tags: [auth, security]
assignee: ""
created: 2026-01-15
updated: 2026-01-15
acceptance_criteria:
  - User can enter email and password
  - Invalid credentials show error message
  - Successful login redirects to dashboard
---

# User can log in with email

## Description
As a registered user, I want to log in with my email and password, so that I can access my account.

## Acceptance Criteria
- [ ] User can enter email and password
- [ ] Invalid credentials show error message
- [ ] Successful login redirects to dashboard

## Technical Notes
Use existing auth service. Follow OAuth 2.0 patterns.

YAML Frontmatter Safety (Parser-Proof)

Kanban scanners depend on strict YAML parsing. One frontmatter parse error can hide the parent item and cascade into skipped children.

Critical scalar rule

If a list item contains embedded quotes and extra text, quote the entire scalar:

# ✅ Good
acceptance_criteria:
  - '"Voeg melk en eieren toe aan de boodschappenlijst" results in exactly 2 AddToList actions'

# ❌ Bad (partially quoted scalar)
acceptance_criteria:
  - "Voeg melk en eieren toe aan de boodschappenlijst" results in exactly 2 AddToList actions

Additional YAML guardrails

• Use spaces, never tabs, for indentation.
• Keep list indentation consistent (two spaces + "- ").
• Quote full values when they include YAML-significant characters (:, #, [, ], {, }) or mixed quoting.
• Keep frontmatter strictly between opening and closing ---.

Safe frontmatter template snippet

---
id: story-001
title: Example story
type: story
parent: feature-001
state: ToDo
priority: High
acceptance_criteria:
  - User can start voice input from FAB
  - '"Voeg melk en eieren toe aan de boodschappenlijst" results in exactly 2 AddToList actions'
---

Pre-save parser checklist (30 seconds)

1. Confirm frontmatter starts and ends with ---.
2. Check required fields (id, title, type, state, priority, parent where applicable).
3. Validate any complex acceptance_criteria lines are fully quoted scalars.
4. Verify parent references an existing item ID.
5. Rescan board and fix the first parse error before investigating skipped descendants.

Quick Input Shortcuts

When prompted, use these shortcuts:

Workflow Integration

Starting Work

/start-kanban-work              # List all incomplete items
/start-kanban-work features     # List incomplete features
/start-kanban-work todo         # List items in ToDo state
/start-kanban-work feature-001  # Start specific item

Creating Items

• /create-epic - Large initiatives with 1-3-1 decomposition
• /create-feature - Features with story/task generation
• /create-story - User stories with acceptance criteria
• /create-bugfix - Planned fixes with root cause
• /create-task - Small technical tasks

1-3-1 Decision Method

Used in epics and features to structure decisions:

1. 1 Core Problem - Clear statement of what to solve
2. 3 Options - Quick/Simple, Balanced, Comprehensive approaches
3. 1 Recommendation - Best approach with reasoning

Pre-Creation Checklist

BEFORE creating ANY kanban items, complete these steps:

Step 1: Read or Create Counter File

# Check if counter file exists
cat .kanban/_counters.yaml

If file doesn't exist:

1. Scan ALL existing items to find highest IDs
2. Create counter file with discovered values

# Find highest IDs (example grep commands)
grep -r "^id: epic-" .kanban/ | sort -t'-' -k2 -n | tail -1
grep -r "^id: feature-" .kanban/ | sort -t'-' -k2 -n | tail -1
grep -r "^id: story-" .kanban/ | sort -t'-' -k2 -n | tail -1
grep -r "^id: task-" .kanban/ | sort -t'-' -k2 -n | tail -1

Step 2: Reserve ID Range

Before creating files, plan all IDs upfront:

Step 3: Update Counter BEFORE Creating Files

Update _counters.yaml to the END of your reserved range before creating any files. This prevents collisions if the process is interrupted.

ID Generation

CRITICAL: Use the ID counter file to ensure unique numbering.

Counter File: .kanban/_counters.yaml

This file tracks the last used ID for each work item type:

# .kanban/_counters.yaml
# Last assigned ID numbers - DO NOT manually edit
epic: 3
feature: 12
story: 45
bugfix: 8
task: 67

Process

1. Read .kanban/_counters.yaml (create if missing with all zeros)
2. Increment the counter for the item type
3. Generate ID using format <type>-<number> (zero-padded to 3 digits)
4. Update the counter file with new value
5. Create the work item with the new ID

ID format: <type>-<number> (e.g., epic-001, feature-012, story-046)

Initialize Counter File

If .kanban/_counters.yaml doesn't exist, create it:

# .kanban/_counters.yaml
# Last assigned ID numbers - DO NOT manually edit
epic: 0
feature: 0
story: 0
bugfix: 0
task: 0

Best Practices

1. Use _counters.yaml to get next ID (never manually assign)
2. Start with Epic for large initiatives
3. Break down epics into features before implementation
4. Keep tasks small (< 1 day)
5. Document acceptance criteria for stories/bugfixes
6. Update states to reflect actual progress
7. Use tags for cross-cutting concerns (security, performance)

File Separation Rules

CRITICAL: Each work item type lives in its own file. Never embed child items.

Why?

• UI parses individual files to build hierarchy
• Embedded lists are not tracked as work items
• State changes require separate files

Feature files (_feature.md):

• Contain overview, acceptance criteria, technical approach
• Do NOT contain story or task definitions
• Reference stories/tasks by ID if needed

Story files (story-XXX.md):

• Contain user story, acceptance criteria, technical notes
• Do NOT contain task definitions
• Tasks are separate files with parent: story-XXX

Task-Story Relationship

Tasks should be children of stories (or features for cross-cutting work):

Correct hierarchy:

Feature → Stories → Tasks
task.parent: story-XXX  (appears under story in UI)

Cross-cutting tasks:

task.parent: feature-XXX  (testing, registration, integration)

Wrong:

task.parent: feature-XXX for story-specific work
→ Task won't appear under its story in UI

ID Generation - CRITICAL

IDs are GLOBAL across all features, not per-feature.

ALWAYS read _counters.yaml BEFORE creating ANY item.

Minimum Item Requirements

CRITICAL: Every parent must have at least one child item.

Why?

• Features define WHAT to build; stories define WHO benefits and WHY
• Stories define user value; tasks define HOW to implement
• Empty parents create orphan work items in the kanban board
• Tasks are the atomic unit of work that gets done

When creating features: Always create at least one story, even for small features.

When creating stories: Always create at least one task, even if it's a single implementation task.

Post-Creation Verification

AFTER creating stories, verify task coverage:

Acceptance Criteria → Task Mapping

For each story, create a mapping table:

Verification Steps

1. List all acceptance criteria from the story
2. Map each criterion to one or more tasks
3. Identify gaps - any unmapped criteria need new tasks
4. Create missing tasks before marking story as ready

Red Flags

Common Mistakes

Archiving

Items can be archived to reduce board clutter. There are two strategies:

1. Soft Archive (Reversible)

Use when: You want to hide items from the board but keep the file structure intact.

• Adds archived: true and archived_date: YYYY-MM-DD to YAML frontmatter
• Files stay in place — no moves or deletions
• Fully reversible by removing the archived fields
• Command: /archive-kanban

2. Hard Archive (Permanent Cleanup)

Use when: A feature is long-completed and you want to physically declutter the file system.

• Goal: Consolidate a feature folder into a single read-only file.
• Location: .kanban/archive/<feature-name>.md
• Process:
  1. Create a single markdown file in .kanban/archive/
  2. Append content of _feature.md
  3. Append content of all child items/*.md separated by ---
  4. Delete the original feature folder
• Result: One flat file per feature, zero folder clutter.

Archivable criteria:

When scanning items, always skip archived: true items — treat them as if they don't exist on the active board.

State Transitions

ToDo → InProgress   # Start working
InProgress → InReview  # Submit for review
InReview → Done     # Approved
InProgress → Blocked   # Cannot proceed
Blocked → InProgress   # Blocker resolved

Transition timing: State changes must reflect CURRENT reality, not be applied retroactively. Mark InProgress when you START work, not when you're already done. Never skip ToDo → Done directly — always go through InProgress.

When blocking, always add blocked_reason:

state: Blocked
blocked_reason: "Waiting for API access credentials"