Roles
Huddle has two roles. They are about people, not about the AI: every person has their own Claude Code session.
AI Manager
One person per repo. They install Huddle, write the Issues, answer decisions, review pull requests and merge. Only they merge into the default branch, and only they touch production, settings and secrets.
Developer
Takes an Issue, works on its own branch and answers what the session asks. Their session never merges, never touches the default branch or secrets, and touches only the files the Issue allows.
Why one AI Manager: decisions that nobody owns get answered in a rush, or twice in two ways. One owner keeps the answers consistent and keeps production in a single pair of hands. Each person runs one or two Issues at a time.
Labels
The status of an Issue lives in its labels. Nobody sets them by hand: a job does, from each Issue's «Depends on» section and from its comments.
| Label | Meaning |
|---|---|
ready | Everything it depends on is merged. Waiting for someone. |
assigned | A developer has it. Not started. |
in progress | A session is working on it. |
in review | A pull request is open and waits for the AI Manager. |
blocked | It depends on an Issue that is not merged yet. |
needs decision | The session asked the AI Manager and waits. |
changes requested from AI Manager | The AI Manager asked for changes and nobody has taken the request yet. |
An Issue lists what it needs under «Depends on». A dependency counts as merged only when the Issue is closed and a merged pull request closed it. An Issue closed by hand unblocks nothing.
Two labels are stop labels: needs decision and changes requested from AI Manager. The work waits for someone else, so they stand alone: in progress and in review are taken off while one of them is on, and come back by themselves once the request is taken or the question is answered.
Areas and progress
A team sees how far each part of its project has come, as a percentage, and the total. Areas are milestones, on GitHub and on GitLab alike, and a project has as many as it needs. The AI Manager keeps an estimate of the Issues not written yet in each milestone, so the percentage is honest about the work still to come.
Progress shows in three places: a pinned «Huddle progress» Issue that rewrites itself, the huddle progress command, and one line when a Claude Code session opens. The skill /huddle-areas proposes the areas and puts Issues in them, and it changes nothing until the AI Manager says yes.
Decisions
Nothing is dropped silently. Everything an Issue asks for ends up done, or written under «What was NOT done» with the reason. When a session cannot go on without a decision, it does not guess:
- It pushes what is done.
- It comments on the Issue with the question, the options with their trade-offs and a recommendation, and adds the
needs decisionlabel. - It stops. The AI Manager answers with
/huddle-decide, and the session continues on the same branch.
Reviews
The session works test first: the failing test, then the code, touching only the allowed files. It opens the pull request with the real test counts and «What was NOT done», and ends with a message that starts with «Issue #N finished». CI runs the tests. The AI Manager reviews with /huddle-review and either merges or asks for changes.
A request for changes is a comment with a «Prompt for Claude Code» heading. The session waiting in the background picks it up, pushes the fix and answers «Ready for review again». If Claude Code was closed meanwhile, a hook says on the next start that a request is pending. Either way, /huddle-play <n> picks the Issue up again after the AI Manager answered a review or a decision.
The AI Manager can also let their session do the checking: /huddle-watch looks every few minutes at what waits and reviews it (/huddle-watch status and /huddle-watch off do what they say). Turning it on is the order to merge what it approves. Decisions and bug triage stay with the person, and huddle queue lists what waits.
«Only you» steps
The AI Manager's own Claude Code session does every step it can: merging an approved pull request, tagging a release, running the smoke test on the sandboxes. It hands a step to a person only when it needs something the session cannot have:
- a second person's account;
- a payment;
- a secret, such as creating or pasting a token;
- a phone or another device;
- a legal or business decision;
- a paid action the person must approve;
- a permission that was denied.
What such a step looks like
It is numbered, with one action per step and exactly where to click. Whatever is typed or pasted sits in a copy block. Each step ends with «You should see:» and «If you see something else:», and every technical word is explained once.
Want to try it? Get started, or read the full team guide (opens in a new tab) and the design (opens in a new tab).