voku/agent-kanban

Markdown TODO Kanban parser, renderer, and verifier for coding-agent workflows.

0.0.1 2026-06-09 21:44 UTC

Requires

• php: ^8.3

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.5

MIT

• Lars Moelleken

README

A lightweight, strict PHP library designed to parse, render, verify, and synchronize Markdown-based Kanban boards tailored for coding-agent workflows.

We provide here a CLI utility and programmatic API to handle split-file Kanban setups.

Features

• Split-File Board Management: Aggregates a directory of individual Jira cards (todo/jira/ITPNG-*.md) and a metadata file (todo/board.md) into a single consolidated board markdown document.
• Strict Verifier (TodoBoardVerifier): Validates the integrity of the board against a set of robust constraints (WIP limits, status mappings, ticket uniqueness, task briefs, matching counts).
• Flexible Rendering (TodoBoardCli render): Outputs a clean Markdown board representation with query options to filter by lane, assignee, domain, status, search string, and limit.
• Jira Synchronization (TodoBoardCli jira-sync): Syncs local card metadata with remote Jira issue states.
• Zero-Dependency Core Helpers: Uses package-local, byte-safe string utilities to run reliably in generic PHP environments.

Directory Structure

vendor/
├── bin/
│   └── agent-kanban             # Standalone CLI binary
├── src/
│   ├── Composer/                # Composer integration
│   ├── JiraIssueProvider.php    # Interface for remote Jira integration
│   ├── TodoBoardCard.php        # Immutable card representation
│   ├── TodoBoardCli.php         # CLI command router and output formatter
│   ├── TodoBoardRenderOptions.php # Value object for render filtering
│   ├── TodoBoardSource.php      # Board assembler & markdown parser
│   └── TodoBoardVerifier.php    # Integrity checking engine
├── tests/
│   ├── fixtures/                # Mock project structures for testing
│   └── *Test.php                # Package test cases
├── composer.json                # Composer package config
├── phpstan.neon.dist            # Static analysis configuration
└── phpunit.xml                  # PHPUnit test runner settings

The Markdown Kanban Architecture

The board operates on a split-file architecture to avoid git conflicts during concurrent agent execution:

1. Board Metadata (todo/board.md)

Maintains board-wide variables:

# Board Metadata

- **Source:** `todo/jira/*.md`
- **Done count:** 301

2. Card Source Files (todo/jira/ITPNG-*.md)

Each ticket has its own Markdown file with frontmatter metadata:

# ITPNG-123: Implement secure form validation

- **Ticket:** ITPNG-123
- **Lane:** READY
- **Status:** Selected
- **Domain:** Security
- **Assignee:** Lars Moelleken
- **Updated:** 2026-06-09 11:32:00
- **Fit:** (Recommended) Task has clear inputs and target files.
- **Summary:** Short summary of the work.
- **Next:** Write unit tests for the validator.
- **Validation:** Run make test_unit.
- **Wave:** Wave 1
- **Next pull rank:** 1

## Handoff / Context
Additional context notes go here...

CLI Usage

Run the package binary from the project root directory:

./vendor/bin/agent-kanban <command> [options]

Supported Commands

• summary Prints an overview of lane sizes, WIP health, and status counters:

  ./vendor/bin/agent-kanban summary

• render Renders the board representation. Supports optional filters:

  ./vendor/bin/agent-kanban render --lanes=READY,DOING --assignee=moellekenl --limit=5

  Available filters: --lanes, --domain, --assignee, --status, --search, --limit.

• lane <LANE> Prints the tickets and details for a specific lane (e.g. READY, DOING, VERIFY, BLOCKED, BACKLOG):

  ./vendor/bin/agent-kanban lane READY

• next-pull Shows recommended cards ready to be pulled by agents.

• ticket <TICKET_KEY> (or context <TICKET_KEY>) Renders the compiled context and brief for a specific ticket:

  ./vendor/bin/agent-kanban ticket ITPNG-123

• brief <TICKET_KEY> Extracts and displays only the Agent Task Brief section of the card.

• jira-sync Syncs local Markdown card statuses against the Jira API using the provided issue provider interface.

Board Verification Rules

The TodoBoardVerifier executes the following checks:

1. Entrypoint Integrity: TODO.md in the workspace root must point to todo/jira/ and must not contain raw lane tables directly.
2. Required Sections: The compiled board must contain sections like # TODO for Coding Agents, ## ITPNG Markdown Board, ### WIP Health, etc.
3. Count Verification: Lane headers (e.g. #### READY (Count: 3)) must match the actual number of files in that lane.
4. Valid Status Mapping:
   • READY $\rightarrow$ Selected, In Planung
   • DOING $\rightarrow$ In Progress
   • VERIFY $\rightarrow$ In Test
   • BLOCKED $\rightarrow$ Warten
   • BACKLOG $\rightarrow$ Backlog
5. No Duplicates: A ticket key can only exist in a single lane.
6. Task Brief Existence: All cards in the READY lane must include an Agent Task Brief.
7. WIP Constraints: Validates that active WIP fits within the limit (maximum 3 active implementation cards).

Development

Run development commands within the vendor/ directory:

# Install package dependencies
composer install

# Run static analysis (PHPStan)
composer phpstan

# Run unit tests
composer test

# Run all CI verification checks
composer ci