TL;DR: Instead of building yet another orchestration layer, use the labels in your existing issue tracker (GitHub, GitLab, Jira) as a distributed state machine. Each AI agent watches for its label, does its job, and swaps the label to hand off to the next agent. The pipeline runs itself.
Glossary
Before diving in, here are a few terms I'll use throughout:
| Term | What It Means (Plain English) |
|---|---|
| Agent | An AI-powered program that can read code, write code, run tests, and interact with tools — autonomously. Think of it as a junior developer that never sleeps. |
| Agentic Loop | The infinite watch-work-hand off cycle an agent runs. It polls for tasks, executes them, and transitions to the next state. Like a factory worker at a station on an assembly line. |
| Label | A tag on a GitHub/GitLab/Jira issue (e.g., ai-backend, ai-review). In this architecture, labels serve as both the task queue and the workflow state. |
| MCP (Model Context Protocol) | A standard way for AI agents to talk to external tools (GitHub, Slack, databases). Instead of writing custom API integrations, agents use MCP servers as universal adapters. |
| Hook | A script that runs automatically before or after an agent takes an action. Used for validation, permission checks, and state transitions. |
| Human-in-the-Loop (HITL) | Any point where a human can step in, override, or take over from the AI. In this system, it's as simple as changing a label. |
| Rollback | When something fails, the agent reverts the issue to a previous state (label) instead of moving forward. |
| Idempotent | An operation that produces the same result no matter how many times you run it. Important when agents might retry failed tasks. |
1. The Problem I Kept Running Into
Over the past year, I've been working with AI agents that can write code, run tests, create pull requests, and generate documentation. Individually, they're impressive. But the moment I tried to chain them together — analysis, then backend, then frontend, then review, then QA — everything fell apart.
The questions piled up fast:
- How does the backend agent know the analysis phase is done?
- Who triggers the frontend agent after the backend ships?
- What happens when the reviewer rejects the code? Who gets it back?
- If the QA agent finds a regression, how do we restart the cycle?
- How can a human jump in at any point without breaking the pipeline?
The obvious answer was to build an orchestrator. Maybe use Temporal, or Airflow, or write a custom state machine with a database behind it. But every time I started down that path, it felt like I was solving the wrong problem. I was building infrastructure to manage infrastructure.
Then I realized something embarrassingly obvious: I already had a workflow engine. It was called GitHub Issues.
Every development team already tracks tasks in an issue tracker. Every issue already has labels. Every label change is already logged. Every comment is already timestamped. The entire audit trail is already there.
What if labels weren't just metadata? What if each label was a state in a distributed state machine, and each AI agent was a worker that watched for its specific label?
That's the core idea behind Label-Driven Agentic Workflows.
2. The Core Idea: Issue = Task, Label = State
The mapping is clean:
| What You Need | What You Already Have |
|---|---|
| Task / work item | The GitHub Issue |
| Task context | Issue body, comments, linked branches |
| Workflow state | Labels (ai-backend, ai-review, ai-qe) |
| Work queue | Issue list filtered by a label |
| State transition | Agent removes its label, adds the next one |
| Audit log | Issue activity timeline |
No separate database. No message queue. No orchestrator process.
An agent doesn't get "called" by another agent. It pulls work by polling the issue tracker: "Are there any issues with my label? No? Sleep. Yes? Let me work on it."
3. The Puzzle Metaphor
The best way I've found to explain this to people is through a puzzle analogy.
Each agent is a self-contained puzzle piece. It has four components:
- System Prompt — its identity and behavioral rules ("You are the Backend Agent. Never touch frontend files.")
- Skills — what it can actually do (write APIs, run tests, generate migrations)
- MCP Connections — the external tools it can reach (GitHub for issues, Slack for notifications, a database for schema checks)
- Transition Rules — which label triggers it, which label it applies when done, which label it applies on failure
Snap these pieces together and you get a pipeline. The beauty is:
- Swap a piece: Replace the Claude backend agent with a Gemini one. Nothing else changes.
- Add a piece: Insert a security audit between review and QA. Just add a label and an agent.
- Remove a piece: Skip design for a hotfix. Change one transition rule.
- Different infrastructure: PO runs on a laptop, backend on a cloud VM, QA inside CI/CD.
Agents never call each other. A puzzle piece doesn't reach into the next piece and move it. It finishes its own shape, and the next piece recognizes the connection point (the label) on its own.
4. The Agentic Loop: A System That Runs Itself
Here's where it gets interesting. Once you start the agents, the system runs itself. Nobody triggers anything manually. It's like a factory assembly line that operates 24/7.
Each agent runs a simple infinite loop with six phases:
- Watch — Poll the tracker for issues with my label.
- Grab — Lock the issue (assign to self), read all context: description, previous agent comments, code state.
- Think — Use the system prompt + context to formulate a plan.
- Work — Write code, create files, run commands via tools and MCP connections.
- Check — Run tests, linters, builds. Did it work?
-
Hand off — If yes: remove my label, add the next. If no: remove my label, add the previous (or
needs-human). Write a summary comment. Go back to step 1.
That's it. Each agent is a while(true) loop with a label filter. The issue tracker is the message broker. The label is the message. The loop is the consumer.
5. The Self-Driving Kanban Board
Here's the mental model that clicked for me: this is a Kanban board that drives itself.
Every team already uses Kanban. Cards move through columns: Backlog → In Progress → Review → Done. A human reads a card, does the work, drags it to the next column.
In Label-Driven Agentic Workflows, the same thing happens — except the "human" is an AI agent, the "column" is a label, and the "drag" is an API call. The board moves itself. When you check in the morning, work has progressed overnight.
Why this works better than building a custom orchestrator:
- No infrastructure to maintain. GitHub already handles concurrency, persistence, and access control. You don't need Redis or RabbitMQ.
- Survives failures gracefully. If an agent crashes, the label stays on the issue. When the agent restarts, it picks up where it left off.
- Full visibility for free. Open any issue and read the entire agent conversation — what was tried, what failed, what succeeded. It's like reading a team chat history.
- Human override is trivial. Remove a label. That's it. The agent stops. Do the work yourself. Add the next label when you're done.
- Reconfigure in minutes. Want to add a security scan step? Create a label, deploy an agent, update one transition rule.
6. State Machine: A Full SDLC Pipeline
For a real software development lifecycle, the state machine looks like this:
Each label maps to an agent with a single responsibility:
| Label | Agent Role | What It Does |
|---|---|---|
ai-po |
Product Owner | Writes acceptance criteria, validates feasibility |
ai-analysis |
Analyst | Maps criteria to codebase, identifies files to change |
ai-design |
Architect | API contracts, DB schemas, component designs |
ai-backend |
Backend Dev | Server code, APIs, database logic, backend tests |
ai-frontend |
Frontend Dev | UI components, API binding, frontend tests |
ai-review |
Reviewer | Code review, security audit, quality checks |
ai-qe |
QA Engineer | E2E tests, regression suites, edge cases |
needs-human |
Human | Anything the agents can't resolve |
7. Prompt Design: The Shape of Each Puzzle Piece
The system prompt is the most critical part of each agent. It's what prevents a backend agent from writing CSS or a reviewer from rewriting the implementation.
A good prompt answers four questions:
- Who am I? — Identity and domain expertise.
- What can I do? — Available skills, tools, and MCP connections.
- What must I never do? — Hard boundaries that prevent scope creep.
- How do I hand off? — Exact label transition rules.
Backend Agent (example)
You are the Backend Agent.
Implement server-side logic, APIs, and database schemas.
BOUNDARIES:
- ONLY work on issues labeled 'ai-backend'.
- NEVER modify files in /src/components, /public, or /styles.
- If UI changes are needed, document the API endpoints and leave it to the Frontend Agent.
TRANSITIONS:
- Success: Remove 'ai-backend', add 'ai-frontend'. Comment with a summary of changes and new endpoints.
- Failure: Remove 'ai-backend', add 'ai-analysis'. Comment explaining the blocker.
- Critical: Remove 'ai-backend', add 'needs-human'. Comment with full error context.
Review Agent (example)
You are the Review Agent.
Audit code changes against acceptance criteria.
BOUNDARIES:
- ONLY process issues labeled 'ai-review'.
- NEVER write implementation code. You are an auditor, not a builder.
- Check: code quality, security, test coverage, documentation.
TRANSITIONS:
- Approved: Remove 'ai-review', add 'ai-qe'. Post approval comment.
- Rejected: Remove 'ai-review', add 'ai-backend' or 'ai-frontend'. Post inline review comments.
8. Hooks: Guardrails for Autonomous Agents
When an agent runs inside a CLI tool (Claude Code, Gemini CLI, Codex), hooks act as guardrails — scripts that run before and after the agent does anything.
Before the agent works (Pre-Hook):
- Check: does the issue still have my label? (A human might have removed it while the agent was starting.)
- If not: halt immediately. Don't waste tokens or write unauthorized code.
After the agent finishes (Post-Hook):
- Run the test suite. Did everything pass?
- If yes: swap labels via the API.
- If no: rollback the label to the previous agent.
This keeps agents honest even when running unsupervised at 3 AM.
9. Human-in-the-Loop: Humans and Agents on the Same Board
This is, honestly, my favorite part of the whole architecture. Humans and agents share the same workspace — the issue tracker. Same comments, same labels, same history. There's no separate "override console."
Four patterns I've found useful:
1. Take Over
A developer sees the backend agent about to tackle a tricky database migration. They remove ai-backend, do it manually, then add ai-frontend to resume the pipeline.
2. Review Gate
For security-critical code, add a mandatory needs-human-review step. The review agent transitions there instead of ai-qe. A human approves and manually swaps to ai-qe.
3. Course Correction
A PM reads the PO agent's acceptance criteria and disagrees. They remove the current label, add a correction comment, and re-apply ai-po to restart from scratch.
4. Selective Automation
Not every stage needs AI. Automate backend, review, and QA. Keep product ownership and frontend fully human. Labels flow between human and agent columns seamlessly.
The label system doesn't care who processes the work. It only tracks what state the task is in.
10. Error Recovery Without Complexity
Failures are guaranteed in autonomous systems. LLMs hallucinate. Tests flake. APIs rate-limit. Here's how labels handle it without a dedicated error recovery framework:
Retry with limits: The agent tracks attempt count via issue comments. After 3 failures, it stops trying and transitions to needs-human with a full error log.
No double-processing: Before starting, the agent assigns the issue to its service account. If already assigned, it skips the issue. Simple mutex via the tracker's native assignee field.
Graceful degradation: If an agent encounters a logic contradiction (e.g., conflicting requirements), it doesn't guess. It writes a detailed comment explaining the conflict and rolls back to ai-analysis or escalates to needs-human.
11. Tool Independence
One thing I want to emphasize: this architecture doesn't lock you into any specific AI tool. The agents communicate through the issue tracker, not through each other.
| CLI / Tool | Hooks | MCP | Fit |
|---|---|---|---|
| Claude Code | ✅ Full | ✅ Native | Excellent |
| Gemini CLI | ✅ Scriptable | ✅ Native | Excellent |
| Codex CLI | ✅ Native | ✅ Integrated | Excellent |
| OpenCode | ⚠️ Custom wrapper | ✅ Standard | Good |
| Cursor | ❌ Limited | ✅ Custom | Fair |
You could run the backend agent with Claude, the reviewer with Gemini, and the QA with Codex. They'd never know. Labels are the universal interface.
12. What I'd Do Differently Next Time
After experimenting with this approach across several projects, a few hard-learned lessons:
- Keep prompts short. Long prompts cause context drift. Each agent should have a prompt under 500 words with crystal-clear boundaries.
- One agent, one job. The moment you ask a backend agent to also handle documentation, quality drops. Single responsibility isn't just good OOP — it's essential for agents.
- Comments are context. Every agent should post a detailed handoff comment. This becomes the primary input for the next agent, reducing redundant codebase scanning.
- Labels must be mutually exclusive. Never let two agent labels coexist on the same issue. One owner at a time.
- Start small. Don't automate the entire SDLC on day one. Start with one agent (e.g., code review) and expand the pipeline as you build confidence.
- Hooks are non-negotiable. Without pre-hooks checking label validity, you'll get agents working on tasks that humans already took over.
13. Conclusion
The insight behind Label-Driven Agentic Workflows is almost embarrassingly simple: your issue tracker is already a workflow engine. Your Kanban board is already a state machine. Your labels are already a queue.
You don't need Temporal. You don't need Airflow. You don't need a custom orchestrator with a PostgreSQL backend and a Redis cache.
You need labels, agents, and the discipline to treat each agent as a self-contained puzzle piece — with its own prompt, skills, MCP connections, and transition rules.
The pipeline runs itself. Humans step in whenever they want by changing a label. The audit trail writes itself through issue comments. And the whole thing works on infrastructure your team already pays for and already understands.
That's the pitch. No new platform to learn. No new database to maintain. Just labels.
Top comments (0)