Issue Lifecycle¶

States¶

┌──────────┐    sync     ┌──────────┐   unblocked   ┌──────────┐
│  GitHub   │───────────▶│  Queued   │──────────────▶│  Ready   │
│  (open)   │            │          │               │          │
└──────────┘            └──────────┘               └────┬─────┘
                                                        │
                                                   assign│
                                                        ▼
┌──────────┐   merged    ┌──────────┐  pr_created  ┌──────────┐
│  Done    │◀────────────│In Review │◀─────────────│  Claimed  │
│          │            │          │               │          │
└──────────┘            └─────┬────┘               └──────────┘
                              │
                         changes│requested
                              ▼
                        ┌──────────┐
                        │Iterating │──── max 3 iterations
                        │          │     then → Failed
                        └──────────┘
                              │
                         2nd failure
                              ▼
                        ┌──────────┐
                        │  Failed  │──── escalate to human
                        │          │     via Discord #admin
                        └──────────┘

Labels¶

Label	Meaning	Set By
`agent-ready`	Issue is ready for automation	Human / Conductor-E
`agent-claimed`	Dev-E has claimed this issue	Dev-E
`agent-failed`	Dev-E failed after 2 attempts	Conductor-E
`requires-human-review`	Human gate triggered	Conductor-E
`requires-macos`	Needs Xcode/simulators (skip Dev-E)	Human
`high-priority`	Higher in queue	Human
`critical`	Production bug, interrupts current work	Human

Dependencies¶

Issues can declare dependencies in the body:

depends-on: #123
depends-on: #124, #125

Conductor-E parses these and blocks the issue until all dependencies are closed.

Example Flow¶

Issue #547: Add Firestore rules CI check

Created — PM creates issue with acceptance criteria
Synced — Conductor-E polls GitHub, adds to PostgreSQL queue
Queued — Priority: normal, no dependencies, no human gate
Ready — Available for assignment
Assigned — Conductor-E assigns to Dev-E, posts to Discord #tasks
Claimed — Dev-E labels agent-claimed, creates feature/issue-547-firestore-ci
In Progress — Dev-E runs Claude Code headless
PR Created — Dev-E pushes branch, creates PR Closes #547
In Review — Review-E reviews, Copilot reviews, CI runs
Changes Requested — Review-E requests changes on test coverage
Iterating — Dev-E reads comments, runs claude --continue, pushes fix
Approved — Review-E approves, CI passes
Merged — Auto-merge squash merges to main
Done — Conductor-E detects merge, marks complete, picks next issue

Timing Expectations¶

Phase	Expected Duration
Sync → Ready	< 5 minutes (poll interval)
Ready → Claimed	< 1 minute (Dev-E poll)
Claimed → PR Created	5–30 minutes (Claude Code)
PR → Review	< 5 minutes (Review-E + Copilot)
Review → Merge	2–10 minutes (CI + auto-merge)
Total	~15–50 minutes per issue

Production Bugs (Critical)¶

When a critical label is added:

Conductor-E moves issue to top of queue immediately
If Dev-E is working on something, it finishes current task first (no interrupt mid-Claude)
Critical issue is next assignment
Discord #admin gets immediate notification