Intake → Delivery Flow

The pipeline processes work items through a deterministic sequence of stages. Each stage has explicit entry conditions, a defined executor, and clear exit criteria. Labels on GitHub issues and PRs encode the current state — no external database required.

The State Machine

Stage 1: Intake

Work enters the pipeline as a GitHub issue. Issues can originate from bug reports, feature requests, or automated triage (e.g., Sentry alerts, user feedback channels).

Entry conditions

• Issue exists in the project backlog column
• Issue has no classification label yet (agent, human, or needs-info)

What happens

• PM agent detects the issue during its periodic dispatch cycle
• Issue is queued for research within concurrency limits

Stage 2: Research

A coding agent analyzes the issue to determine scope, complexity, and whether it can be automated. This runs in cloud mode — the agent reads the codebase but doesn't modify it.

Entry conditions

• Issue in backlog column
• No classification label present
• Under concurrency limit (default: 3 concurrent research agents)

What happens

1. Agent reads issue details and searches the codebase for relevant files
2. Analyzes complexity and scope
3. Classifies: agent (automatable), human (needs judgment), or needs-info
4. Posts structured research comment to the issue
5. Applies classification and scope labels

Exit criteria

Classification label applied. Research tracking label added.

Output labels

Timeout

30 minutes. If no classification label after timeout, the session is flagged as zombie and cleaned up.

Stage 3: Build

A coding agent implements the fix in an isolated git worktree, runs tests, and opens a PR. This is the core execution stage — where code gets written.

Entry conditions

• Issue has agent label (classified as automatable)
• Research complete (tracking label present)
• Issue is open
• No PR already exists for this issue
• Under concurrency limit (default: 2 concurrent builds)

What happens

1. Create git worktree — never modify the main clone
2. Spawn coding agent in the worktree
3. Agent implements the fix
4. Runs lint, typecheck, and tests
5. Creates PR with Closes #N in the body
6. Syncs labels from issue to PR

Exit criteria

PR exists for the issue.

Isolation model

~/project/                      # Main clone — NEVER touched
~/project/worktrees/
  └── issue-<num>/              # Isolated worktree per issue
      ├── branch: fix/issue-N   # Dedicated branch
      └── (full repo checkout)  # Independent working tree

Stage 4: Review

Automated code review via a GitHub Action. The PM agent triggers this by adding a label — no coding agent is spawned for review.

Entry conditions

• PR exists
• No review label present

What happens

1. PM agent adds the review-trigger label to the PR
2. GitHub Action fires automatically
3. Action reviews code and posts findings as PR comments
4. Action adds review-complete label

Exit criteria

Review-complete label applied.

Stage 5: Fix Comments

A coding agent reads review comments, categorizes them, and implements fixes. This stage has a built-in circuit breaker.

Entry conditions

• PR has review-complete label
• No comments-fixed label
• No agent-stuck label
• Fix attempts < 3 (circuit breaker threshold)

What happens

1. Agent reads all review comments (inline and PR-level)
2. Categorizes each: must-fix, should-fix, nitpick
3. Implements fixes for must-fix and should-fix items
4. Commits, pushes, and posts a summary comment
5. Adds comments-fixed label

Circuit breaker

After 3 failed fix attempts, the pipeline adds agent-stuck and stops retrying. A human must triage. This prevents infinite loops and wasted compute.

Stage 6: E2E Test

Browser-based end-to-end testing using the PR's preview deployment.

Entry conditions

• Review complete and comments addressed
• No test result label present
• No agent-stuck label

What happens

1. Agent retrieves the preview deployment URL
2. Extracts test criteria from the PR description
3. Uses browser automation to test the deployment
4. Captures screenshots as evidence
5. Posts results as a PR comment
6. Adds pass or fail label

Stage 7: Deliver

The only mandatory human touchpoint. A human reviews the PR and merges it.

What happens

1. Human reviews the PR (code, review comments, test results)
2. Human approves and merges
3. Labels sync from PR back to issue
4. Issue auto-closes via Closes #N in the PR body

Auto-merge (optional)

For low-risk repositories, auto-merge can be enabled when all conditions are met: architecture review approved, QA approved or tests passing, CI green, no unresolved comments. This is opt-in per repository.

Concurrency Management

Each stage has configurable concurrency limits to prevent resource exhaustion:

Label Sync

Labels automatically sync between issues and PRs at key transitions:

• PR created: issue labels → PR (scope, complexity, area)
• PR merged: PR labels → issue (completion status)
• Daily reconciliation: catch any drift

Pipeline-internal labels (stage tracking) do not sync — they belong to their respective object.