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.

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

Completed items can be archived to reduce board clutter using /archive-kanban.

How it works:

• Adds archived: true and archived_date: YYYY-MM-DD to YAML frontmatter
• Files stay in place — no moves or deletions
• All workflows skip items where archived: true
• Only epics and features (with ALL children Done) are archivable
• Archiving a parent archives all descendants recursively
• Fully reversible by removing the archived fields

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

When blocking, always add blocked_reason:

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