| name | ba |
| description | Task tracker for LLM sessions. Use "$ba ready" to see available work, "$ba claim <id>" to take ownership, "$ba finish <id>" when done. |
ba - Task Tracking for LLM Sessions
Simple ownership-based task tracking for multi-agent coordination.
$ba ready
Show issues ready to work on (open + not blocked by dependencies).
Run:
ba ready
Output shows:
- Issue ID, priority (0-4), type, title
- Only open issues with no unfinished blockers
- Sorted by priority
Use this to: Pick your next task from the ready queue.
$ba claim
Take ownership of an issue (moves it to in_progress).
Run:
ba claim <id> --session $SESSION_ID
Example:
ba claim ab-x7k2 --session $SESSION_ID
Important:
- Always use
--session $SESSION_ID to identify yourself
- Claiming changes status:
open → in_progress
- Claiming a
closed issue reopens it automatically
- Only one agent can own an issue at a time
Use this before: Starting work on any issue.
$ba mine
Show issues you currently own.
Run:
ba mine --session $SESSION_ID
Output shows:
- All issues you've claimed in
in_progress status
- Sorted by priority
Use this to: See what you're currently working on.
$ba finish
Complete an issue (moves it to closed).
Run:
ba finish <id>
Example:
ba finish ab-x7k2
Requirements:
- You must be the current owner (claimed it with your session)
- Changes status:
in_progress → closed
Use this when: Work is done and tested.
$ba release
Release an issue back to the ready queue (abandon work).
Run:
ba release <id>
Requirements:
- You must be the current owner
- Changes status:
in_progress → open
Use this when: You can't complete the work or need to switch focus.
$ba show
Show detailed information about an issue.
Run:
ba show <id>
Output shows:
- Full details: status, owner, created_at, updated_at
- Description if present
- Labels and priority
- Comments
- Dependencies (blocks, blocked_by)
Use this to: Understand issue requirements before claiming.
$ba list
List all open issues (excludes closed by default).
Run:
ba list # Open issues only
ba list --all # Include closed
ba list --status open
ba list --status in_progress
ba list --status closed
Use this to: Browse available work.
$ba create </h2>
<p>Create a new issue.</p>
<p><strong>Run:</strong></p>
<pre><code class="language-bash">ba create "Fix auth bug" -t task -p 1
ba create "Add feature" -t epic -d "Detailed description"
</code></pre>
<p><strong>Options:</strong></p>
<ul>
<li><code>-t, --type</code> - task, epic, refactor, spike (default: task)</li>
<li><code>-p, --priority</code> - 0 (critical) to 4 (backlog), default: 2</li>
<li><code>-d, --description</code> - Longer description</li>
<li><code>-l, --labels</code> - Comma-separated labels</li>
</ul>
<p><strong>Use this when:</strong> You discover new work that needs tracking.</p>
<h2>$ba comment <id> <message></h2>
<p>Add a comment to an issue.</p>
<p><strong>Run:</strong></p>
<pre><code class="language-bash">ba comment ab-x7k2 "Found root cause in auth.rs:42" --author $SESSION_ID
</code></pre>
<p><strong>Use this to:</strong> Document progress, findings, or blockers.</p>
<h2>$ba block <id> <blocker-id></h2>
<p>Mark an issue as blocked by another.</p>
<p><strong>Run:</strong></p>
<pre><code class="language-bash">ba block ab-x7k2 ab-y8m3 # ab-x7k2 is blocked by ab-y8m3
</code></pre>
<p><strong>Effect:</strong></p>
<ul>
<li><code>ab-x7k2</code> won't appear in <code>ba ready</code> until <code>ab-y8m3</code> is closed</li>
<li>Use <code>ba tree <id></code> to visualize dependencies</li>
</ul>
<p><strong>Use this when:</strong> Work has prerequisites.</p>
<h2>$ba unblock <id> <blocker-id></h2>
<p>Remove a blocking dependency.</p>
<p><strong>Run:</strong></p>
<pre><code class="language-bash">ba unblock ab-x7k2 ab-y8m3
</code></pre>
<h2>$ba tree <id></h2>
<p>Visualize issue dependencies.</p>
<p><strong>Run:</strong></p>
<pre><code class="language-bash">ba tree ab-x7k2
</code></pre>
<p><strong>Output shows:</strong></p>
<ul>
<li>Tree structure of issue and its blockers</li>
<li>Status of each issue</li>
</ul>
<h2>Workflow Example</h2>
<pre><code class="language-bash"># 1. See what's available
ba ready
# 2. Pick an issue and claim it
ba show ab-x7k2 # Check details
ba claim ab-x7k2 --session $SESSION_ID
# 3. Work on it
# ... make changes, run tests ...
# 4. Document progress
ba comment ab-x7k2 "Implemented feature, tests passing" --author $SESSION_ID
# 5. Complete or release
ba finish ab-x7k2 # If done
# OR
ba release ab-x7k2 # If can't complete
</code></pre>
<h2>Ownership State Machine</h2>
<p>ba uses ownership-based state transitions:</p>
<pre><code class="language-text">open ──claim──> in_progress ──finish──> closed
(take) (done)
│
release
│
▼
open
(abandon)
</code></pre>
<p>Key rule: <strong>Every <code>in_progress</code> issue has an owner.</strong></p>
<p>Claiming a closed issue automatically reopens it as <code>in_progress</code> with you as owner.</p>
<h2>Issue Types</h2>
<ul>
<li><code>task</code> - Default, general work item</li>
<li><code>epic</code> - Container for grouping related issues</li>
<li><code>refactor</code> - Improving existing code (no new behavior)</li>
<li><code>spike</code> - Research/investigation (may not produce code)</li>
</ul>
<h2>Priorities</h2>
<ul>
<li><code>0</code> - Critical (security, data loss, broken builds)</li>
<li><code>1</code> - High (major features, important bugs)</li>
<li><code>2</code> - Medium (default - nice-to-have features, minor bugs)</li>
<li><code>3</code> - Low (polish, optimization)</li>
<li><code>4</code> - Backlog (future ideas)</li>
</ul>
<h2>JSON Output</h2>
<p>All commands support <code>--json</code> for programmatic use:</p>
<pre><code class="language-bash">ba --json ready
ba --json show ab-x7k2
ba --json mine --session $SESSION_ID
</code></pre>
<h2>Storage</h2>
<p>Issues stored in <code>.ba/issues.jsonl</code>:</p>
<ul>
<li>One issue per line (JSONL format)</li>
<li>Git-friendly (conflicts are per-issue, not per-field)</li>
<li>Human-readable</li>
<li>Grep-able: <code>grep ab-x7k2 .ba/issues.jsonl</code></li>
</ul>
<h3>Merge Conflicts</h3>
<p>When multiple agents modify issues concurrently, git conflicts occur at the line level (one line = one issue).</p>
<p><strong>Resolution strategy:</strong></p>
<ol>
<li>Pull latest changes: <code>git pull</code></li>
<li>If conflicts occur, each conflicting issue will show both versions</li>
<li>Choose the correct version (usually the one with latest <code>updated_at</code>)</li>
<li>Validate JSON: <code>jq empty .ba/issues.jsonl</code></li>
<li>Commit the resolution</li>
</ol>
<p><strong>Prevention:</strong> Always pull before starting work. Use <code>ba ready</code> to see current state.</p>
<p><strong>Note:</strong> ba does not detect conflicting edits automatically. The line-based format makes conflicts <strong>obvious</strong> (entire issue on one line) but not <strong>automatic</strong> to resolve. Consider this when coordinating multiple agents.</p>
<h2>Environment and SESSION_ID</h2>
<h3>Required: SESSION_ID</h3>
<p>The <code>$SESSION_ID</code> environment variable <strong>must be set</strong> for ownership operations (claim, mine, comment with --author).</p>
<p><strong>Verification:</strong></p>
<pre><code class="language-bash"># Check if SESSION_ID is set
echo ${SESSION_ID:-(not set - operations will fail)}
</code></pre>
<p><strong>Claude Code provides this automatically in active sessions.</strong> If commands fail with "SESSION_ID not set":</p>
<pre><code class="language-bash"># Generate and export a session ID
export SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
</code></pre>
<p><strong>Why required?</strong> ba's ownership model prevents multi-agent conflicts by requiring explicit session identification. Without it:</p>
<ul>
<li><code>ba claim</code> will fail (cannot establish ownership)</li>
<li><code>ba mine</code> will fail (cannot identify your issues)</li>
<li>Multi-agent coordination breaks down</li>
</ul>
<h3>Error Handling</h3>
<p>If SESSION_ID is not set, ba commands will fail with:</p>
<pre><code class="language-text">ERROR: --session is required
</code></pre>
<p>This is intentional - ownership without identity doesn't make sense.</p>
<h2>Known Limitations</h2>
<h3>Stale Ownership</h3>
<p>If a Claude Code session crashes mid-task, the issue remains <code>in_progress</code> with a stale owner. ba currently has no automatic timeout/reclaim mechanism.</p>
<p><strong>Workaround for the original owner:</strong></p>
<pre><code class="language-bash">ba release <id> # If you were the owner (SESSION_ID matches)
</code></pre>
<p><strong>Workaround for a different agent (manual intervention required):</strong></p>
<pre><code class="language-bash"># 1. View the issue to see who owns it
ba show <id>
# 2. Manually edit .ba/issues.jsonl to remove owner/claimed_at fields
# Find the line with the issue ID and set:
# "status": "open"
# "owner": null
# "claimed_at": null
# 3. Now you can claim it
ba claim <id> --session $SESSION_ID
</code></pre>
<p><strong>Important:</strong> Manual JSON editing is fragile. Validate syntax after editing:</p>
<pre><code class="language-bash">jq empty .ba/issues.jsonl # Exit 0 = valid, non-zero = syntax error
</code></pre>
<p><strong>Future consideration:</strong> Add <code>ba reclaim --force <id> --session $SESSION_ID</code> command to handle this safely.</p>
<h2>Quick Reference Card</h2>
<pre><code class="language-text">ba ready # See available work
ba claim <id> --session $SESSION_ID # Take ownership
ba show <id> # Check details
ba mine --session $SESSION_ID # See your work
ba finish <id> # Complete
ba release <id> # Abandon
ba comment <id> "msg" --author $SESSION_ID
ba create "title" -t task -p 1 # New issue
ba list [--all] [--status <status>] # Browse
</code></pre>
</div> </article> </section> </div> </main> <vercel-analytics data-props="{}" data-params="{"slug":"@cloud-atlas-ai/ba/codex-skill"}" data-pathname="/skills/@cloud-atlas-ai/ba/codex-skill"></vercel-analytics> <script type="module">var f="@vercel/analytics",l="1.5.0",w=()=>{window.va||(window.va=function(...r){(window.vaq=window.vaq||[]).push(r)})};function d(){return typeof window<"u"}function u(){try{const e="production"}catch{}return"production"}function v(e="auto"){if(e==="auto"){window.vam=u();return}window.vam=e}function m(){return(d()?window.vam:u())||"production"}function c(){return m()==="development"}function b(e,r){if(!e||!r)return e;let n=e;try{const t=Object.entries(r);for(const[a,i]of t)if(!Array.isArray(i)){const o=s(i);o.test(n)&&(n=n.replace(o,`/[${a}]`))}for(const[a,i]of t)if(Array.isArray(i)){const o=s(i.join("/"));o.test(n)&&(n=n.replace(o,`/[...${a}]`))}return n}catch{return e}}function s(e){return new RegExp(`/${h(e)}(?=[/?#]|$)`)}function h(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function y(e){return e.scriptSrc?e.scriptSrc:c()?"https://va.vercel-scripts.com/v1/script.debug.js":e.basePath?`${e.basePath}/insights/script.js`:"/_vercel/insights/script.js"}function g(e={debug:!0}){var r;if(!d())return;v(e.mode),w(),e.beforeSend&&((r=window.va)==null||r.call(window,"beforeSend",e.beforeSend));const n=y(e);if(document.head.querySelector(`script[src*="${n}"]`))return;const t=document.createElement("script");t.src=n,t.defer=!0,t.dataset.sdkn=f+(e.framework?`/${e.framework}`:""),t.dataset.sdkv=l,e.disableAutoTrack&&(t.dataset.disableAutoTrack="1"),e.endpoint?t.dataset.endpoint=e.endpoint:e.basePath&&(t.dataset.endpoint=`${e.basePath}/insights`),e.dsn&&(t.dataset.dsn=e.dsn),t.onerror=()=>{const a=c()?"Please check if any ad blockers are enabled and try again.":"Be sure to enable Web Analytics for your project and deploy again. See https://vercel.com/docs/analytics/quickstart for more information.";console.log(`[Vercel Web Analytics] Failed to load script from ${n}. ${a}`)},c()&&e.debug===!1&&(t.dataset.debug="false"),document.head.appendChild(t)}function p({route:e,path:r}){var n;(n=window.va)==null||n.call(window,"pageview",{route:e,path:r})}function k(){try{return}catch{}}customElements.define("vercel-analytics",class extends HTMLElement{constructor(){super();try{const r=JSON.parse(this.dataset.props??"{}"),n=JSON.parse(this.dataset.params??"{}");g({...r,disableAutoTrack:!0,framework:"astro",basePath:k(),beforeSend:window.webAnalyticsBeforeSend});const t=this.dataset.pathname;p({route:b(t??"",n),path:t})}catch(r){throw new Error(`Failed to parse WebAnalytics properties: ${r}`)}}});</script> </body></html>