The Problem

Agents without structure

Free-form sessions. Re-explaining context every time. No idea what each agent did or didn't do.

Non-determinism compounds

The more agents, the more drift. Mistakes are silent. Babysitting required.

Skills don't scale

LLMs follow ~150-200 instructions. Claude Code already uses ~50. Every rule competes for attention. Lost in the Middle — context position matters.

🤖 🤖 🤖

5-6 agents running simultaneously

each needs full context from scratch

each can silently go off-track


Brain Fry

The Harness

Issue Viewer = web app + issue-cli. Issues are markdown files. Agents are first-class citizens.

Web App

Kanban board, issue detail, workflow designer. Human approvals, agent dispatch — one click to spin up Claude or Codex.

issue-cli

Agent-first CLI. Agents use it instead of touching files directly. Every output contains next steps.

workflow.yaml

Per-project rules: statuses, transitions, validations, prompts, subsystem overlays. Fully configurable.

$ issue-cli next --version 0.1 → pathfinding.md [backlog · high] $ issue-cli start pathfinding ✓ claimed · status → in progress Next: implement, check off items Then: issue-cli transition pathfinding $ issue-cli done pathfinding ✗ unchecked items remain: [ ] add unit tests $ issue-cli check pathfinding "add unit tests" ✓ checked off $ issue-cli done pathfinding ✓ done · assignee cleared

JIRA + CMT but for agents

Composed, Just-in-Time Prompt

Every agent dispatch assembles a fresh, precise context from its parts.

Base Prompt
who, rules, tooling
+
Status Prompt
what to do now
+
Subsystem Overlay
domain expertise
+
Inject Prompt
extra actions
+
Issue Content
the actual task
↓
Composed Context
Precise · minimal · assembled at dispatch time
Agent knows exactly what to do, in this project, at this status, for this issue.

No re-explaining. No guessing. No babysitting.

Example

How It Actually Works

👤 1. Human
clicks dispatch in web UI
↓
⚙️ 2. tmux session
claude / codex launched in alacritty
↓
⚙️ 3. Composed prompt
base + status + subsystem + issue
↓
🤖 4. issue-cli start
claims issue, status → in progress
loop
🤖 5. Agent works
implements, checks off items
↓
🤖 6. issue-cli transition
attempts to advance status
↓
⚙️ 7. Validation
blocked → error returned → self-correct → retry
↓
👤 8. Human approval gate
hard stop — human reviews & approves
↓
✅ 9. Done
assignee cleared · retro filed

Control + Feedback Loop

Validations

Block transitions when agent misses something. CLI returns a clear error — agent self-corrects and retries. No human needed.

Human Approval Gates

Hard stops at backlog and human-testing. Catches non-deterministic drift before it compounds.

Retros & Bug Reports

issue-cli retrospective · issue-cli report-bug
Agent files its own feedback. Bot reviews it. Workflow improves.

🤖 agent works
↓
🐛 📓 files bugs & retros
↓
🤖 bot reviews
↓
⚙️ workflow improves
↓
🤖 agent improves

Control Feedback Examples

Agent receives structured validation errors and self-corrects:

$ issue-cli transition pathfinding done ✗ transition blocked rule: section_checkboxes_checked: Testing unchecked items in Testing: [ ] All relevant automated tests passing [ ] Test results logged with "tests:" prefix $ issue-cli comment pathfinding \ "tests: all passing, 42 assertions" ✓ comment added $ issue-cli check pathfinding \ "All relevant automated tests passing" ✓ checked off $ issue-cli transition pathfinding done ✓ transitioned → done