Work Unit Roadmap — a Claude Code Plugin
Turn a coding agent workflow into a disciplined project wiki and execution contract system: atomic Work Units, verification evidence, client-confirmed closeout, and a recoverable project memory.
Small task, verify, report, receive. Repeat.
What is this?
Most AI coding sessions fail because the agent mixes planning, execution, status updates, and self-approval in one context window. WUR separates those concerns.
agents/ is the project second brain: roadmap, research, decisions, design, tech stack, specialist registry, reports, and graph state. It is the source of truth.
contracts/rule.md stores shared WUR execution rules. contracts/PHASE_{n}_CONTRACT.md is one phase contract per phase: task brief, pending Work Units, explicit Allowed Read References, and the report ledger. The executor reads only the listed agents/ paths when deeper context is needed, follows contracts/rule.md, may update only touched WU Status/Commit cells in the active contract's Pending Work table, and appends evidence under ## Execution Rounds And Reports. WUR receives the report before updating agents/.
There is no Codex App Server integration, no MCP runtime coordinator, and no required subagent platform. WUR is a wiki + contract + receive workflow.
Software projects should also keep agents/project/DESIGN.md and agents/project/TECH_STACK.md. DESIGN.md is the AI-readable Design Contract. TECH_STACK.md records stack choices and verification commands. Defaults are recommendations, not mandates: common web apps prefer Vite/React/TypeScript/Tailwind/shadcn; SEO sites prefer Next.js App Router; mobile prefers Expo + TypeScript + NativeWind; browser games prefer Vite + TypeScript with Phaser or Three.js.
Scope boundary
Canonical scope contract lives in skills/wur-guidelines/SKILL.md (## Scope Boundary). This README is package/user documentation; runtime agent behavior is defined by the skills/ and commands/ files.
Short form:
- Wiki = plan
- Contracts = execution boundary
- Checks = deterministic local scripts
- No hosted CI/CD, deployment pipelines, cloud services, or platform-specific runtime orchestration inside WUR.
Why use it
WUR prevents common AI drift:
- editing roadmap state directly during execution
- creating many noisy executor handoff/fix files
- marking Work Units done without client review
- losing project context when the agent hits context limits
- making the executor ask too many questions because the task lacks a clear contract
The contract keeps the executor focused. The wiki stays clean.
Control model
/wur:init creates agents/ once./wur:wiki:* enriches and queries the wiki./wur:start {n} creates or refreshes contracts/rule.md and contracts/PHASE_{n}_CONTRACT.md.- The executor follows that contract. It must not edit
agents/; it may update touched Pending Work Status/Commit cells and append reports in the active phase contract.
- Reports are appended to the same contract file.
/wur:test records pass/waive/fail state. Failed work stays in the same contract ledger; the executor may add or update a fix round there, not a Phase Fix file./wur:done closes a phase only when the current client request explicitly invokes it.
Installation
Claude Code — marketplace (recommended)
/plugin marketplace add truong170201/work-unit-roadmap
/plugin install wur@work-unit-roadmap
/reload-plugins
Claude Code — local clone
git clone https://github.com/truong170201/work-unit-roadmap.git
/plugin install .
/reload-plugins
Quick start
1. Bootstrap the project wiki
/wur:init "Build an internal inventory app for warehouse operators."
This creates:
agents/project/PHILOSOPHY.md, USAGE.md, plus DESIGN.md / TECH_STACK.md for software projectsagents/roadmap/ALL.md and agents/roadmap/log.mdagents/SCHEMA.md and agents/index.mdagents/raw/, research/, docs/, reports/, references/- optional
agents/departments/ and agents/specialists/ when project context is clear
2. Optional graph layer
/wur:wiki:upgrade
/wur:wiki:graph extract
Markdown under agents/ remains canonical. Derived graph artifacts can be rebuilt.
3. Enrich wiki from an idea
/wur:wiki:ima "Older warehouse operators need a faster picking flow with fewer screen taps."
IMA writes durable knowledge into agents/ and may update roadmap planning when the user's natural language calls for it. It never starts execution, marks WUs done, closes phases, or touches application code.
4. Create the phase contract
/wur:start 1
This creates or refreshes:
contracts/rule.md
contracts/PHASE_1_CONTRACT.md
The contract skips WUs already accepted or done. Re-running /wur:start 1 updates the task section but keeps existing reports.
5. Execute outside WUR state
