Skip to content

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.

The journey of a task across five lanes. The BA writes an issue with acceptance criteria. The dev picks up the task with ph bandum start, the agent works under Guardrails, then the dev runs verify, opens a PR and moves the task to testing with review. The BA tests for acceptance, then approves (Duyệt) or sends the task back (Trả lại). If sent back, the dev runs fix and returns to the agent. After approval the task is Done, Ryoma records metrics and sends the PM the weekly digest.BA / PODev and agentGuardrailsBandumRyoma / PMWrite issueAC, labelsPick up taskph bandum startCreate branchtest scaffoldAgent worksuses Claude CodeGuardrailsblock, mask,and logAuto checkph bandum verifyOpen PRph bandum prMove to testingph bandum reviewChange labelstatus: reviewTestingacceptanceSend backa TCfailedApproveall TCs passDoneissue closedLog metricsFlow andAI costWeekly digestsent to PMMonday morningFailPassph bandum fix

Swipe sideways to see the whole diagram.

When a task is sent back, the ph bandum fix loop repeats until the tester approves. Bandum changes the status label at each step.

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.

StateLabelWhen
Todo(no status: label yet)The issue is created and nobody has picked it up
In progressstatus: in progressA dev has picked up the task and is working on it
Reviewstatus: reviewThe dev finished and the task waits for acceptance testing
Approvedstatus: approvedEvery test case passes and the Tester clicks Approve
Rejectedstatus: rejectedA 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.

The task state machine. Todo moves to In progress with ph bandum start. In progress moves to Review with ph bandum review. From Review, the tester clicks Duyệt (Approve) to make it Approved, then merging the PR moves it to Done, or clicks Trả lại (Send back) to make it Rejected. Rejected returns to In progress with ph bandum fix.Todono status labelIn progressstatus: in progressReviewstatus: reviewRejectedstatus: rejectedApprovedstatus: approvedDoneissue closedph bandum startph bandum reviewSend back on web or testph bandum fixApprovemerge PR

Swipe sideways to see the whole diagram.

Bandum sets the status label itself at each transition, so you never add it by hand. A task with no status label is Todo, and a closed issue is Done.

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.

Each column on the Board matches a state in the table above, and the status label on the issue decides which column a task sits in.

Pick up a task ​

bash
ph bandum start GH-12

The 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:

bash
ph bandum board              # the sprint's tasks by state
ph bandum board --mine       # only tasks assigned to you

Work 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:

bash
ph bandum check

The 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":

bash
git push -u origin HEAD
ph bandum pr GH-12

Move to testing ​

If the project has .bandum.json, run the automated tests first, then move the task:

bash
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 label

ph 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:

bash
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 comments

When 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.

Read more ​