Getting started for BA, PO, PM
BAs, POs, and PMs do all their work in the browser, with nothing to install. You sign in to Tara once. After that, you write tasks, run acceptance testing, and track projects right on the web.
Tara, Ryoma, and the Bandum website all run online. You need an organization on Tara first: either an Owner or Admin invites you as a Viewer, or you create your own. See Create or join an organization. Viewers are free and take no seat. This documentation writes the Tara address as https://tara.phillipcli.cloud. If you want to test on your own machine with commands, see Dev and Test.
Sign in for the first time
- Open
https://tara.phillipcli.cloud. - Click Continue with GitHub. If your organization enables single sign-on, click the SSO button instead.
- GitHub asks whether to let Tara read your account information. Click Authorize.
- If an Owner or Admin invited you, you land in their organization. Otherwise Tara shows Get started, where you can open an invitation link or create an organization.
When you see your organization and your name in the top corner, you're signed in. The Bandum website has a sign-in button that goes through Tara. You use this same account, with no separate password.
If you see no organization, ask an Owner or Admin for an invitation. If several organizations list you, use the switcher at the top. Other errors are in Troubleshooting.
Label your issues
Bandum reads your issues on GitHub or GitLab, so an issue needs two labels: one that says what kind of work it is, and one that says whether it's big or small.
| Label | Values |
|---|---|
type: | feature, bug, debt, risk |
level: | S, M, L (the size of the work) |
Ryoma uses type: to split metrics by work type, so reports skew when this label is missing. Bandum changes the status: ... label itself, so you don't set it. The full lifecycle is in Task lifecycle.
Write acceptance criteria
Each acceptance criterion (AC) goes on its own line in the issue description and starts with the code AC-<number>.<number>. The code can be preceded by - , - [ ] , or **.
## Acceptance criteria
- [ ] AC-1.1 Signing in with the correct password goes to the home page
- [ ] AC-1.2 Five wrong passwords lock the account for 15 minutes
- [ ] AC-2.1 Forgot password sends a reset email within 1 minuteDevs use these codes to write test cases, and ph bandum review doesn't allow the move to testing while any AC has no test case. So make each AC verifiable with one clear action, and avoid statements like "the system runs fast".
For L-level tasks, the spec lives in the repo at docs/features/GH-<number>-<name>/spec.md, and each AC is a #### AC-1.1 ... heading. The full rules are in Bandum format.
Where to find information
| You want to know | Open | In section |
|---|---|---|
| Project overview: progress, first-pass approval, rework, AI cost, risky tasks | Tara | Projects, then click a project |
| Sprint progress | Bandum website | Board, choose the repo and sprint |
| Tasks awaiting testing, tasks sent back | Bandum website | Board, the matching column |
| First-pass approval rate, number of returns, time awaiting testing | Bandum website | Metrics |
| The project's workflow (Flow) and AI usage | Tara | Projects, the Workflow (Flow) and AI sections |
| Your organization's AI resources | Tara | Explore, filter by type |
Bandum gets its data from GitHub or GitLab. If the numbers look stale, click Sync now on the Board. If you don't see your project under Projects, ask an Admin to check that the project exists in your organization (Settings, then Projects).
Acceptance testing on the web
When the dev finishes, the task moves to the Waiting for testing column. Each task has a list of test cases (TC). Each TC maps to one or more ACs, and you mark each TC Pass or Fail.
- Open the Bandum website, sign in through Tara, go to Board, and click the task in the Waiting for testing column.
- Scroll down to the Manual testing section. The first time, a Connect box appears. Paste your GitHub or GitLab token and click Connect. The table below lists the token permissions.
- If the project has a staging environment, click Open staging to try it. If not, the task page explains how to run the app on your machine.
- Follow each TC and choose Pass or Fail. If you choose Fail, you must describe the bug.
- If needed, add a General note.
- When every TC passes, click Approve. If any TC fails, click Send back.
When you finish, the page shows "Recorded run N" with the result, and the task moves columns on the Board. Each test run is appended to the task's acceptance.md file on the PR branch, and earlier runs aren't edited.
| Platform | Token permissions needed |
|---|---|
| GitHub | Fine-grained: Issues, Pull requests, and Contents all set to Read and write on the project repo. Or classic: repo |
| GitLab | The api scope, with the Developer role or higher |
Step-by-step instructions, with screenshots, for creating a token are in Connect GitHub or GitLab.
The token lives only in an encrypted browser cookie, and the server doesn't store it. When you click Disconnect or sign out, the token is deleted. Results are recorded under your name, and the person who opened a PR can't approve their own PR.
If you prefer the command line, use ph bandum test GH-12. The full marking process is in Testing and acceptance.
Report bugs during testing
If the bug is inside the task under test, mark that TC Fail and describe the bug, and the dev receives it back through the comments. For a bug outside the task's scope, use the Report a bug section on the task page to create a new issue with the type: bug label. Details are in Report bugs.
Track project health (PM)
Everyone in the organization, Viewers included, can see every project of the organization. In Tara, the Projects section shows tasks by status, first-pass approval rate, rework, AI cost, and a table of risky tasks with reasons.
Project contacts also receive a weekly digest, by default on Monday morning. The digest summarizes last week's velocity, flow time, WIP, rework cost, and label coverage, with the direction of change compared to the previous week, and it doesn't judge good or bad. New risky-task alerts also arrive through the notification channel that your organization has turned on.
The equivalent in a terminal, if you use Phillip:
ph ryoma projects # projects you can view
ph ryoma report --project <code> # project health and risky tasks
ph ryoma alerts # the project's quotaIf the list is empty, check which organization is current with ph org current.
Dashboards
Your metrics are in the Portal, under Projects. The list shows Flow and AI metrics for your whole organization, and each project page shows the detail, over the time range you pick, with a short explanation of every metric. See Metrics on the Projects pages.
Read Flow and AI metrics
These two sections are on the project's detail page in Tara. Hover over a metric's name to see its explanation.
| Metric | What it means | How to read it |
|---|---|---|
| Velocity | Tasks completed in the week | Look at the trend across weeks |
| Flow time (median, p85) | From the first "in progress" to done | A p85 far above the median means a few tasks sit for a very long time |
| Flow efficiency | The share of time a task is worked on, out of total working and waiting time | Low means tasks wait more than they're worked on |
| WIP | Tasks in progress or waiting | High usually goes with long flow time |
| Label coverage, cost coverage | The share of tasks with a type: label, and the share of AI cost attributable to a task | Below 80%, the by-type or by-task breakdown isn't reliable yet |
| Rework cost | AI cost incurred after a task is first sent back | If high, review the quality of the ACs and test cases |
Don't use metrics to grade individuals
These are project and workflow metrics. Don't compare one project with another, don't use them to evaluate people, and don't treat the difference between with-AI and without-AI as cause and effect. When a task sits for a long time, ask the whole team what's blocking it. Per-person figures are visible only to that person, and administrators can also see them to manage quotas. See also Measurement.