Self-Perpetuating Implementation Workflow

A scalable, context-efficient workflow system for multi-phase implementation projects with AI agents.

Built on beads — a Git-native issue tracker designed for AI agents.

What We Built on Top of Beads

Beads is excellent for issue tracking and basic memory (bd remember), but we found AI agents needed more structure to truly learn from their work. We didn't fork the Go codebase — instead, we built a shell script extension layer that adds:

Why We Extended Beads

| Gap in vanilla beads | What we added | |---------------------|---------------| | Flat memory (key-value only) | Structured categories — lessons/, decisions/, goals/ with templates | | Manual memory capture | Automatic capture — Agents self-document mistakes and decisions without prompting | | Single context injection | Tiered context — bd-prime-minimal (~500 bytes) vs bd prime (~4KB) | | No self-validation | Memory health checks — bd-check-memories reports category coverage | | No session-end protocol | Self-review prompts — Agents ask themselves "what did I learn?" before closing | | Parallel agents collide on same files | Epic conflict-guard workflow — cross-epic blocks edges keep bd ready conflict-safe |

The Result

AI agents now learn from their mistakes automatically. Each session:

1. Starts with past lessons injected (via hooks)
2. Captures new learnings as work happens (via CLAUDE.md instructions)
3. Ends with a self-check for uncaptured insights

No user prompting required. The system runs in the background.

For multi-agent execution, epic setup now includes a mandatory conflict-guard pass so overlapping tasks are dependency-gated and agents can pick the next safe task directly from bd ready.

Extensions Added

# Install to ~/bin
bash ./beads/extensions/install.sh

| Command | Purpose | |---------|---------| | bd-lesson <topic> "desc" | Capture a mistake/fix with structured template | | bd-decision <topic> "choice" "why" | Record a decision with rationale | | bd-goal <scope> "vision" | Set project direction | | bd-review | See all lessons and decisions | | bd-check-memories | Memory health report (category counts, warnings) | | bd-prime-minimal | Lightweight context injection for session start |

See Memory Protocol for full documentation, or use BOOTSTRAP_PROMPT.md to set up another project.

Parallel agents + PM orchestration

• MULTI_AGENT_PM_PROTOCOL.md — Roles (PM vs worker), handoff templates, bd-first queue, max-3 parallel cap, IDE-neutral dashboard + optional Cursor SDK automation.

• workflow-pm CLI (root package.json, binary wfpm): run PM tools against any target repo without copying scripts.

  • Install: npm install -D workflow-pm (or npm install -D github:pwhermanson/workflow-protocol), then npm exec wfpm -- dashboard / wfpm from node_modules/.bin.
  • wfpm dashboard — same as node scripts/bd-pm-dashboard.mjs with cwd = current directory (or wfpm -w /path/to/repo dashboard).
  • wfpm parallel-check — enforces MAX_PARALLEL_AGENTS.
  • wfpm control-center — starts PM Control Center (postinstall installs pm-control-center deps on first install).
  • Env: WORKFLOW_PM_WORKSPACE or WFP_WORKSPACE for default -w.

Publish to npm (maintainers): from repo root, npm login then npm publish --access public. Requires an npm account and an available unscoped name (workflow-pm) or switch name in package.json to a scoped package (@scope/workflow-pm).

• scripts/bd-pm-parallel-check.sh / scripts/bd-pm-parallel-check.ps1 — Same parallel-cap check, for callers that already have this repo cloned (runs pm-parallel-check.mjs from your cwd).

• PM dashboard (low-level) — scripts/bd-pm-dashboard.mjs: or use wfpm dashboard which spawns this with the chosen workspace. Flags: --prompt-only, --strict, --target=generic|cursor|claude|all, -h. Env: PM_READY_LIMIT, MAX_PARALLEL_AGENTS.

• PM Control Center (operator UI) — pm-control-center/: localhost dashboard (beads read via bd, copy-paste prompts, QC helpers, optional gh). Development: cd pm-control-center && npm run dev. Production-like: npm run build && npm start. Default http://127.0.0.1:5275; env PM_CONTROL_CENTER_HOST, PM_CONTROL_CENTER_PORT. Operator persistence under %LOCALAPPDATA%/workflow-protocol/pm-cc (Windows) or ~/.cache/workflow-protocol/pm-cc. Shared core: scripts/lib/pm-dashboard-core.mjs. Programmatic import: import "workflow-pm/pm-dashboard-core" from the published package.

Future: Native Go Implementation

If the shell script layer hits limitations, we'll fork beads to add native support. Tracked in issue workflow-protocol-0ej. Planned features:

• bd lesson as native command (no shell scripts)
• bd prime --minimal flag (tiered loading)
• First-class memory categories in the schema

The Problem This Solves

When working on complex, multi-phase projects with AI agents (Claude, GPT, etc.):

• Context drift — Agents lose track of what's done vs. pending across sessions
• Context bloat — Loading entire roadmaps (100KB+) wastes context window
• Session handoff failures — No clear "where to pick up" when starting new sessions
• Documentation rot — Progress tracking falls out of sync with actual state
• Duplicate work — Agents redo completed tasks or miss incomplete ones

The Solution

A chunked roadmap system with:

• Index file (~10KB) — Progress tracking, next task pointer, key decisions
• Chunk files (~10-30KB each) — All task details, micro-steps, completion notes
• Self-perpetuating prompts — Each task ends with a ready-to-paste prompt for the next session
• Beads integration — Persistent memory and issue tracking across sessions

Result: ~30KB typical context load (vs 100KB+), clear session handoffs, zero drift.

Quick Start

For New Repositories

# 1. Copy this protocol to your repo
cp -r workflow-protocol/templates/* your-repo/docs/

# 2. Set up beads (optional but recommended)
cd your-repo
bd init

# 3. Add protocol memory
bd remember --key roadmap-protocol "Implementation Roadmap Protocol: See docs/IMPLEMENTATION_ROADMAP_PROTOCOL.md"

# 4. Create your first roadmap
# See SETUP.md for detailed instructions

For Existing Repositories

# 1. Copy the protocol document
cp workflow-protocol/IMPLEMENTATION_ROADMAP_PROTOCOL.md your-repo/docs/

# 2. Add to CLAUDE.md (if using Claude Code)
# See templates/CLAUDE-md-snippet.md

# 3. Convert existing roadmaps to chunked structure
# See SETUP.md § Converting Existing Roadmaps

What's Included

| File/Folder | Purpose | |-------------|---------| | CHANGELOG.md | Notable workflow-protocol changes | | SETUP.md | Step-by-step setup instructions | | IMPLEMENTATION_ROADMAP_PROTOCOL.md | The core protocol document | | MULTI_AGENT_PM_PROTOCOL.md | PM vs worker agents, beads handoffs, parallel cap (max 3 default) | | templates/ | Roadmaps, chunks, changelog, PM/worker paste prompts | | scripts/ | bd-pm-dashboard, lib/pm-dashboard-core.mjs (shared CLI + UI), pm-parallel-check.mjs (parallel cap via Node), bd-pm-parallel-check shell wrappers | | pm-control-center/ | Local PM operator UI (Express + React + Vite); reads bd/git/gh in a chosen workspace; default port 5275 | | beads/ | Beads setup, memories, and integration guide | | gitignore/ | .gitignore options (with/without beads) | | examples/ | Sample chunked roadmap for reference |

Core Concepts

1. Chunked Roadmap Structure

docs/<project>/
├── <Name>_Roadmap-v1.md          # INDEX (progress, next task, decisions)
└── <name>-roadmap/                # CHUNKS
    ├── project-a-<name>.md        # All Project A tasks
    ├── project-b-<name>.md        # All Project B tasks
    └── ...

2. Context Loading Rules

Always load:

1. Index file (~10KB)
2. Active chunk only (~10-30KB)
3. CHANGELOG.md

Never load:

• All chunks at once
• Specs not needed for current task

3. One Task Per Context Window

Each context window should:

• Execute exactly ONE task
• Complete all micro-steps
• Update chunk file (completion notes)
• Update index file (progress table)
• Update CHANGELOG.md
• Prepare Next Prompt for next session

4. Self-Perpetuating Prompts

Every completed task includes:

Continue <Project> roadmap task <X.Y>.

Load:
- <path/to/index.md>
- <path/to/active-chunk.md>
- CHANGELOG.md

Execute Task <X.Y>, then update docs and return next prompt.

5. Beads Integration (Optional)

Beads provides:

• Persistent memories — Context that survives across sessions
• Issue tracking — Task management with bd create, bd close
• Session hooks — Auto-inject context on session start

Why This Works

Scalability

• Works for 5 tasks or 500 tasks
• Chunk files grow independently
• Index stays lean (~10KB)

Session Independence

• Any agent can pick up where the last left off
• No "catch up" reading required
• Next Prompt contains everything needed

Context Efficiency

• 30KB typical load vs 100KB+
• More room for code, specs, and conversation
• Faster agent response times

Drift Prevention

• Progress tracked in index (single source of truth)
• Completion notes in chunks (audit trail)
• Beads memories persist key decisions

Getting Started

1. Read SETUP.md for detailed setup instructions
2. Copy IMPLEMENTATION_ROADMAP_PROTOCOL.md to your repo
3. Use templates to create your first chunked roadmap
4. Optionally set up beads for persistent memory

License

MIT — Use freely, modify as needed, no attribution required.

Contributing

This is a living system. Improvements welcome:

• Better templates
• Additional examples
• Integration guides for other AI tools
• Workflow optimizations