The life of a task
A task goes from pickup to acceptance through a few states, and each step has a matching ph bandum command. This page spells out who does what at each step. You need to set up Phillip in the project's repo first. See Dev and Test.
A task id looks like GH-12, which is the issue number. On GitLab, you still use the GH- prefix with the issue number in the project.
Swipe sideways to see the whole diagram.
Task states
The state lives in the status: ... label on the issue. Bandum and Phillip set this label for you, so you don't need to add it.
| State | Label | When |
|---|---|---|
| Todo | (no status: label yet) | The issue is created and nobody has picked it up |
| In progress | status: in progress | A dev has picked up the task and is working on it |
| Review | status: review | The dev finished and the task waits for acceptance testing |
| Approved | status: approved | Every test case passes and the Tester clicks Approve |
| Rejected | status: rejected | A test case fails and the task goes back to the dev |
| Done | (the issue is closed) | The PR is merged. The PR description has "Closes #n", so the issue closes itself |
A task goes straight from Todo through In progress, Review, and Approved to Done. If it's Rejected, it goes back to In progress to be fixed, then enters Review again.
Swipe sideways to see the whole diagram.
In addition, each issue has a type: feature | bug | debt | risk label and a level: S | M | L label. The level decides which directory holds the task's test docs. If type: is missing, Phillip reminds you but doesn't block you.
Pick up a task
ph bandum start GH-12The command assigns the task to you, sets the status: in progress label, creates the branch feature/GH-12-<title>, and creates a testcases.md skeleton in the right place. The skeleton isn't committed, and each AC of the task has an entry ## TC-n (AC-x.y) <fill in the name> for you to fill in.
To see the sprint's tasks, or only your own, use:
ph bandum board # the sprint's tasks by state
ph bandum board --mine # only tasks assigned to youWork with the agent
You work with Claude Code through ph as usual, on the branch the command just created. While you do, fill in testcases.md so each AC has at least one test case. The file is in docs/acceptance/GH-12/ for level S and M tasks and in docs/features/GH-12-<name>/ for level L. If you're not sure of the location, ask Phillip with ph bandum paths.
Before you commit, run a check:
ph bandum checkThe command reports format errors, duplicate TC ids, ACs with no test case, and skeleton entries you haven't filled in. It exits with code 0 when there are no errors and 2 when there are.
If you open the AI session with the task id, on a branch of the form feature/GH-12-..., the AI cost is attached to the task in the project's metrics.
Open a PR
Push the branch, then open a PR (an MR on GitLab) with "Closes #12":
git push -u origin HEAD
ph bandum pr GH-12Move to testing
If the project has .bandum.json, run the automated tests first, then move the task:
ph bandum verify GH-12 # run the PR branch's automated acceptance tests
ph bandum review GH-12 # check the PR and test cases, set the status: review labelph bandum review refuses while an AC has no test case. After that, the person testing (a Tester or BA) picks up the task in the Waiting for testing column and marks it Pass or Fail. See Testing and acceptance. The person who opened the PR can't approve their own PR.
What to do when a task is returned
A returned task has the status: rejected label. You handle it with two commands:
ph bandum pull GH-12 # read the comments: failed TCs, ACs, notes
ph bandum fix GH-12 # set back to in progress, check out the PR branch, have the agent fix per the commentsWhen you run ph bandum fix, the agent fixes the problems according to the comments, test cases, and ACs, then commits and pushes. After that, you run ph bandum verify and ph bandum review again. Each test run is appended to acceptance.md, and earlier runs aren't overwritten.
When every test case passes, the Tester clicks Approve and the task moves to status: approved. You merge the PR, the issue closes itself, and the task is done.