The Lifecycle of a Swamp Issue

2026-05-15 · page · source summary

Paul Stack's field report on how the Swamp team dogfoods their own agent workflow framework. An issue isn't a GitHub thread — it's a state machine instance (@swamp/issue-lifecycle) that enforces five phases: triage, planning, adversarial review, iteration, and implementation. The agent physically cannot skip steps. No plan is auto-approved; no issue is auto-triaged. The model is the guardrail.

Key Quotes

"The real state lived in the swamp datastore and GitHub was just a reflection of it."

When the issue lifecycle grew to include structured plan versions, adversarial findings, and feedback rounds, GitHub issues became a sync problem. Swamp-club became the source of truth — itself a swamp model where each method call posts a structured lifecycle entry. This is Long Live Systems of Record in practice: "where does the truth live" is the only question that matters.

"The agent physically cannot skip steps."

Methods like approve, implement, and triage are guarded by model-level checks. Approving a plan requires it to exist, to have gone through adversarial review, and to have no unresolved critical or high findings. Call a method in the wrong phase and it bounces. This is claude-ctrl's "an instruction in context is not a constraint" applied to workflow state — the model is the enforcement mechanism, not a suggestion in a prompt.

"If the tool can't handle its own process, it isn't ready to handle yours."

The issue lifecycle model runs on Swamp infrastructure. When the team wants to change triage behavior, they edit the issue-lifecycle extension, and the upgrade system carries old instances forward. Conventions change via agent-constraints/ files. This is dogfooding as engineering discipline, not marketing.

"The human reads it and either gives feedback... or says to proceed."

No auto-approval of plans. The agent generates, reviews, and presents — but a human who will live with the outcome must approve. Operator-driven triage serves double duty: it prevents prompt injection via issue bodies and ensures the human frames the context.

Key Themes

#tool #workflow #state-machine #adversarial-review #dogfooding

Critical Analysis

The adversarial review phase is the most important idea here and the least discussed. Most agent workflows have planning then implementation. Adding a dedicated adversarial review phase — where the plan is systematically attacked before any code is written — addresses the core failure mode of agentic development: the agent confidently executing a bad plan. This is cheaper than fixing bad code and catches problems at the level of intent rather than syntax. It's the same insight as Specifications as the Product (invest in the spec, not the code) but operationalized as a state machine phase.

The GitHub divorce is honest about something most agent tools dance around. Claude Code, Codex, Aider — they all integrate with GitHub Issues as the task source. Swamp argues that as soon as your issue has structured state (plan versions, findings, feedback rounds), GitHub becomes a liability, not an asset. The sync problem between a rich data model and GitHub's flat issue format is real. Whether Swamp's answer (replace GitHub entirely) or Kata's answer (local-first SQLite issue tracker) is better depends on whether you need GitHub's collaboration surface.

Operator-driven triage as prompt injection defense is clever but incomplete. Stack mentions it almost in passing, but it's a genuine architectural insight: if an attacker can file an issue with a prompt injection payload, automatic triage means the agent processes attacker-controlled text without human oversight. Requiring a human to initiate triage closes this vector. But it's a speed bump, not a wall — the human might not notice the injection either, and the payload could be subtle enough to survive triage and affect planning or implementation.

The "agent physically cannot skip steps" claim depends on the model being correct. If the state machine model has a bug, the agent can skip steps. This is the same trust-the-compiler argument — the guard is only as strong as the guard's implementation. Stack acknowledges this implicitly by dogfooding: the issue lifecycle model is itself built and maintained through the issue lifecycle. That's recursive validation, which is stronger than testing alone but not immune to systemic failure.

What's conspicuously absent: error recovery. What happens when adversarial review finds a critical flaw in phase 3? Does the plan go back to phase 2 (planning) or phase 4 (iteration)? The state machine presumably encodes these transitions, but Stack doesn't describe them. Also missing: the implementation verification process, which is promised as a follow-up post. Without that piece, we see the gate but not the verification on the other side.

The relationship to The Plan Is the Program is direct. Swamp's lifecycle makes the plan the atomic unit of work: triage produces classification, planning produces the plan, adversarial review attacks the plan, iteration refines the plan, and only then does implementation render the plan into code. The plan is literally the thing that moves through the state machine. Code doesn't appear until phase 5.

Cross-Links

Sources: The Lifecycle of a Swamp Issue Last updated: 2026-05-15