agent-workflow

A board-driven, multi-agent development workflow with Claude Code or Codex executors — works with Trello (via MCP) or GitHub Issues (via gh, no MCP needed); other trackers are one provider descriptor away. A meta-agent triages cards into reviewable plans, a human approves by dragging a card, and an orchestrator executes: isolated git worktree → (TDD gate: failing specs → adversarial test critic) → worker implements → two-verdict acceptance audit → auto-merge or human review. Every step leaves an audit trail on the card.

Synthesized from studied methodologies plus production experience: github/spec-kit (constitution, clarify-before-plan, WHAT/HOW separation), obra/superpowers (two-stage review, evidence-before-claims, TDD iron law), garrytan/gstack (the quote-the-evidence verification gate and file-anchored project learnings are adapted from its review/learnings mechanics), Fission-AI/OpenSpec (numbered WHEN/THEN acceptance scenarios as the TDD gate's coverage contract), the MECE principle from Minto's Pyramid Principle (split proposals and scenario lists must be mutually exclusive, collectively exhaustive), and an adversarial-critics TDD process (refute-framed test critic, mutation-resistance checks).

Extracted from a live project and used in production by its two original repos (a Rails web app and a Rust/Tauri desktop app) — every mechanism here was earned by a real failure, and docs/design-notes.md records which one.

The flow

        [/flow-card] ↘
Icebox → Backlog → [/flow-check] → Plan Proposed ─(human drags)→ Ready for AI
                       ↓ questions                                     ↓ [/flow-run]
                  Human Questions                              In Progress
                                                                    ↓
                                        worktree + guardrail hooks + branch
                                                                    ↓
                                     TDD gate (M/L or risky cards): specs-only worker
                                        → test critic (job: REJECT the specs)
                                        → implementation resumes same session
                                                                    ↓
                                     acceptance subagent: 8 checks, severity triage,
                                     two verdicts (spec compliance + code quality),
                                     constitution re-check against the DIFF
                                                                    ↓
                            gaps → retry (≤3 iterations) │ minor → ledger comment
                                                                    ↓
                        auto-merge (confidence/risk/CI gates) → Done │ else → Review

Key properties:

• Cards are authored, not dashed off: /flow-card <rough intention> grounds the sentence in the repo and asks — at most three questions — only the gaps triage could not safely default, then writes a card carrying a completion contract (goal / done-when / out-of-scope / stop-if). Optional: a card written by hand works exactly as before, it just pays for the QUESTIONS → /flow-questions → re-triage round-trip when it's underspecified.
• Humans gate twice: approving the plan (drag to Ready) and, when auto-merge criteria fail, reviewing the PR. Everything else is agents.
• Constitution: project non-negotiables live in .claude/constitution.md; every plan carries a per-article gate and the acceptance check re-verifies the diff. See constitution-template.md and examples/constitution-rodnik-web.md.
• Executors are configurable: choose Claude or Codex globally, or use different executors for workers and audits. Claude uses its existing scope/git hooks; Codex uses an explicit sandbox and does not run Claude hooks. Acceptance rechecks scope, source identity and complete coverage for either executor. See executor configuration and "Threat model" below for capability differences.
• Verdicts require evidence: no "should pass" anywhere in the chain — fresh command output or it didn't happen. Acceptance findings must quote the motivating line (unquotable → demoted to minor), and every finding carries a stable fingerprint that meta tracks across iterations: repeats are marked, ledgered minors aren't re-litigated, and two identical gap sets in a row block the card early instead of burning the last iteration.
• Review coverage is explicit: a Git-derived manifest accounts for every changed file, including renames/deletions/binaries. Missing or failed coverage cannot approve a PR. Project rules are additive by path; bounded groups organize related files without losing unmatched ones. Source quotes are checked against frozen blobs. Plan, base/head, config and kit changes invalidate old review results. See review manifests.
• Project memory compounds: acceptance and the test critic surface non-obvious, file-anchored discoveries into .claude/learnings.jsonl (meta is the single writer — dedup by key, staleness via anchored files); triage reads them when drafting PLANs and workers get the relevant ones injected before touching code, so the same pitfall isn't rediscovered on card 30.

Repository layout

kit/                    → copy into your repo's .claude/
  commands/             /flow-card, /flow-check, /flow-run (+ helpers) — the orchestrators
  prompts/              plan format, card triage, worker bodies (iter1/specs/impl/iterN),
                        test-critic, acceptance-check, roles/
  hooks/                scope-guard.sh, git-guard.sh, worker-settings.json
  bin/                  parse-verdict, harvest-learnings, render-learnings —
                        the tested mechanical halves of /flow-run
constitution-template.md → seed for your .claude/constitution.md
examples/               a real, incident-driven project constitution
  providers/            tracker descriptors: trello.md, github.md — how meta
                        performs the semantic ops on each tracker
scripts/                copied into a consumer's bin/ at adoption:
                        workflow-kit-sync, kit-digest, kit-verify
docs/                   design-notes.md + tracker.example.*.json +
                        ci-kit-intact.example.yml
tests/                  static contracts and behavioral checks, run in CI

Requirements

• The configured executor CLI(s), authenticated: Claude Code (claude) and/or Codex (codex). A Codex-only configuration does not require Claude. See executors for permissions and session requirements.
• gh (authenticated), git, jq, Python 3.8+, rsync, and coreutils (sha256sum, for bin/kit-verify).
• A task tracker, one of:
  • Trello — an MCP server exposing mcp__trello__* tools, e.g. @delorenj/mcp-server-trello; a board with the ten pipeline lists (Icebox, Backlog, Triage in progress, Human Questions, Plan Proposed, Ready for AI, In Progress, Review, Blocked, Done).
  • GitHub Issues — no MCP: the kit drives gh directly; pipeline states are flow:* labels (one-time setup in kit/providers/github.md). Everything provider-specific lives in kit/providers/<name>.md — adding a tracker is one descriptor file, not a fork of the commands.

Threat model (read before adopting)

What the kit defends against, and what it deliberately does not:

• Defended: honest-mistake drift. The scope/git hooks, the file manifest, the acceptance re-check and the two-verdict audit exist to catch a well-meaning worker going off-plan. That is the designed failure mode, and the layers are redundant on purpose.
• NOT defended: a malicious card. Card text, PLAN comments and PR bodies are injected into worker/acceptance prompts. Claude workers run with --permission-mode bypassPermissions; Codex workers default to workspace-write, or explicitly configured danger-full-access. A card authored by an attacker is a prompt injection with shell access. The tracker is a trusted input — restrict board/repo write access to people you'd give a shell.
• NOT defended: a malicious worker. Codex's filesystem sandbox is not a plan-path/git-intent guard; Claude hooks do not run in Codex. External tools and inherited credentials remain part of the execution environment. git-guard/scope-guard are regex/manifest checks on tool-call arguments, and real bypasses are trivial (verified): scope-guard matches only the edit tools, so a Bash echo hacked > file writes anywhere unchecked; git-guard greps the raw command string, so quote-splitting the flag (git push --for''ce) walks past it. Treat the hooks as guardrails, not containment. If you need containment, run /flow-run itself inside a VM/container with a repo-scoped token.
• Blast radius: a worker holds whatever credentials the worktree environment exposes (gh token, env vars). Scope the token to the target repos; never export unrelated secrets into the meta session that spawns workers.

Canonical source & staying in sync

This repo is the canonical source of the kit. Consumers do not edit kit files in their own repo — they edit HERE (PR to this repo), then pull:

1. Copy scripts/workflow-kit-sync, scripts/kit-digest and scripts/kit-verify into your repo's bin/ once, during adoption. They live there rather than in .claude/bin/ on purpose: that tree is one of the ones the sync deletes, and a check the sync can delete is not a check. (They are copied, never synced — workflow-kit-sync reports when your copies have fallen behind this repo.)
2. Run bin/workflow-kit-sync to pull the latest kit (or use KIT_REF=<full-40-character-commit> bin/workflow-kit-sync to pin it). It overwrites .claude/{commands,prompts,hooks,bin,providers} (deletions propagate), never touches project-owned files (tracker.json, constitution.md, project-context.md, settings.local.json, the committed learnings.jsonl memory, optional prompts/ui-design.md), and records the kit SHA and a digest of the kit-owned trees in .claude/KIT_REVISION.
3. Review the diff, commit.
4. Wire bin/kit-verify into CI (docs/ci-kit-intact.example.yml). The rule above — consumers don't edit kit files in their own repo — is otherwise just prose: the sync's rsync --delete erases a local edit with no diff to notice it by, so you learn about it when it vanishes. kit-verify recomputes the digest and fails the pull request while the edit still exists, naming the three ways out (send it upstream, move the file out of the kit-owned trees, or re-sync deliberately). bin/kit-verify --selftest proves on every run that the check can go red — it tampers with a synthetic kit and asserts the failure.

First production consumers: two private repos of the original project (a Rails web app and a Rust/Tauri desktop app), synced through this exact mechanism.

Contributing (humans AND agents): main is PR-only by convention. The org plan has no enforced branch protection, so this is a standing rule, not a technical gate: never push to main directly — branch, open a PR with a rationale, merge after review (self-merge is acceptable for trivial doc fixes; prompt/behavior changes wait for a human or a second agent). Direct pushes to main are treated as incidents.

Before opening a PR, run all five suites in CONTRIBUTING.md (requires bash, jq, Python 3 and Git). CI runs the same suites. The static suite pins the invariants that break silently: dangling file references, placeholders a prompt body uses but doesn't declare, verdict-contract keys drifting between a prompt and the meta code that parses it, invalid JSON artifacts, and prompt size budgets (raising a budget is allowed, but it's a conscious diff in the test file, not silent growth).

Adoption (human or agent — ~15 minutes)

1. Copy kit/ into the target repo as .claude/ (commands/, prompts/, hooks/, bin/, providers/ — keep paths) and scripts/workflow-kit-sync as bin/workflow-kit-sync. chmod +x .claude/hooks/*.sh .claude/bin/* bin/workflow-kit-sync.
2. Create .claude/constitution.md from constitution-template.md. Keep the universal articles; write 3–7 PROJECT articles — each earned by a real incident/constraint (see examples/).
3. Create .claude/tracker.json from the example for your tracker (docs/tracker.example.trello.json / docs/tracker.example.github.json): provider + board/repo, state ids or labels, card_prefix (e.g. ACME), targets (repo_root + toolchain + test_cmd/lint_cmd per repo), default_target, tdd_gate thresholds, auto_merge_criteria.
4. Create the session log file (default .gilb/session-log.md, path is configurable in tracker.json). The learnings file (default .claude/learnings.jsonl, key learnings) is created lazily by meta on first harvest — nothing to do here.
5. Write .claude/project-context.md: stack, language conventions, commit format — workers read it before touching code.
6. Smoke-test: put one small card in Backlog (by hand, or via /flow-card <one sentence>) → run /flow-check → review the PLAN it posts → drag to Ready for AI → run /flow-run → watch the card land in Done/Review with an audit trail.

Giving this workflow to an agent (e.g. an autonomous cofounder agent)

Grant the agent read access to this repo and say:

Adopt the development workflow from in project X: follow README "Adoption" steps 1–6. Ask me for: the tracker (Trello board / GitHub repo) to use, the card prefix, and the project articles for the constitution (propose a draft from the incidents you know). Do not modify kit files themselves — configuration lives in tracker.json / constitution.md / project-context.md.

The kit is agent-agnostic on the meta side: any agent that can call the tracker (MCP or gh) and call the kit scripts can act as the orchestrator. run-agent launches the configured Claude or Codex worker/critic/acceptance processes with one normalized result contract. Codex can read the command Markdown explicitly; .claude/commands are not automatically Codex slash commands. See the Codex entry instructions.

Tuning

• tdd_gate (tracker.json): enabled, min_size (S/M/L), min_risk — which cards get the specs-first + test-critic path. Below the gate, workers still follow inline test-first discipline.
• auto_merge_criteria: min_confidence, max_risk, require_ci_green, strategy. CI must contain at least one check and all reported checks must pass; absent/skipped/pending checks route to Review. Setting require_ci_green: false is the explicit opt-out. Acceptance is bound to the full PR head SHA, enforced again at merge. Research cards never auto-merge.
• executor: default claude or codex, a wall-clock timeout, and Codex worker sandbox. worker.executor / acceptance.executor override the default; the test critic follows acceptance. All stages retain the same review gates.
• worker.model / acceptance.model: per-stage model override (e.g. a cheaper model for acceptance).
• targets[<name>].arch_cmd (optional): an architecture-contract gate (import-linter, packwerk, cargo-deny). When defined it joins the mandatory PLAN gates next to test_cmd/lint_cmd, and /flow-refactor uses it as a scan signal. Absent = skipped.
• review (tracker.json): path rules, related-file groups, explicit exclusions with reasons, and group limits. All language/provider-specific choices stay in consumer config; defaults review every changed file.
• --parallel N on /flow-run: up to 4 cards in flight.
• /flow-run --resume <card>: continue a card whose meta session died mid-run — per-card state is journaled to <worker_log_dir>/<card-short>-state.json at every phase boundary. Each executor attempt has a durable, non-reusable directory: resume waits for a live process or consumes its recorded result instead of launching it again. Incomplete claims require inspection; failed journal writes stop new side effects. See docs/design-notes.md for recovery limits.
• /flow-clean: the sanctioned worktree cleanup — lists finished-card worktrees (card Done + PR merged/closed + clean tree) and removes only what the human confirms. /flow-run itself never deletes worktrees.
• /flow-refactor [target] [path]: the complexity-removal loop — scans a target repo for boundary decay (module cycles, internals-reaching imports), co-change coupling, dead code and complexity hotspots, and proposes ≤5 evidence-anchored refactor cards into Backlog; the human picks which get created, and they ride the normal contour from there. Reads the target's optional arch_cmd (an architecture-contract gate like import-linter/packwerk/cargo-deny) when configured.

Known origins

The kit was extracted from a live project (card prefix RDK, earlier GILB). The example constitution's filename and the default state directory .gilb/ (configurable per target in tracker.json) still carry the original names — historical, not functional; they have no effect on behavior.

Contributing

See CONTRIBUTING.md — the short version: run all five test suites before every PR, main is PR-only, prompt growth is budgeted, and mechanical logic belongs in kit/bin/ with behavioral pins.

License

MIT. The methodologies credited above have their own licenses in their own repos; nothing from them is copied verbatim here — the mechanisms are re-implementations adapted to this kit's tracker/PLAN architecture.