Feature Reference

Keyboard Shortcuts

Board Navigation

Task Operations

Column Operations

Modal Navigation

Task Card Anatomy

┌─────────────────────────────────┐  ← Border color = priority
│ ▲ □ t47 *  playlists support    │  ← Follow-up glyph (only on follow-up tasks), mark (✓ marked / □ unmarked), task number (cyan), * if modified (orange), title (bold)
│ 💪 medium | 🏷️ ui,api | GH | PR:GH | @alice │  ← Effort, labels, issue/PR indicator, contributor
│ 🔒 alice@example.com            │  ← Lock indicator (if locked)
│ 🚫 blocked | 👤 alice           │  ← Status/blocked, assigned to
│ 📋 Ready · Planned              │  ← Status, with `· Planned` when an approved plan awaits implementation
│ 🔗 t12, t15                     │  ← Blocking dependency links
│ 📎 folded into t42              │  ← Folded indicator (if applicable)
│ 👶 3 children                   │  ← Child task count (if parent)
└─────────────────────────────────┘

Not all lines are shown on every card — lines only appear when the corresponding data exists.

The · Planned qualifier marks a task whose plan was approved and whose implementation was deliberately deferred (the “Approve and stop here” checkpoint), so it reads differently from a task nobody has looked at yet. The card carries no timestamp — a card is a narrow surface — and the approval time appears in the task detail dialog as Plan approved: <YYYY-MM-DD HH:MM> under Tracking & provenance. Such a task also gets its own In-Flight lane.

Group Header Anatomy

Tasks that share a boardgroup slug are drawn under a group header row inside their column:

▾ perf work (3) · 2 match · ▲2 ◈1
│ │          │        │       └─ Follow-up roll-up: a per-kind tally of the members' glyphs
│ │          │        └────────- Match count — only during a filter pass
│ │          └─────────────────- Member count
│ └────────────────────────────- Group title, humanized from the slug (perf_work → perf work)
└──────────────────────────────- ▾ expanded / ▸ collapsed

A group of a single member draws no header — it renders as a plain card, while keeping its slug. See How to Group Tasks in a Column.

Priority Color Coding

The focused card always shows a double cyan border, regardless of priority.

Follow-up Provenance Glyphs

A task carrying a followup_kind — one that was auto-spawned by a workflow seam rather than created as new work — shows a coloured glyph at the start of its card:

Reading the glyphs:

• An ordinary task draws nothing — no glyph and no blank placeholder, so cards for genuine new work are unchanged.
• A task whose followup_kind is not one of the known kinds still renders, as the uncoloured ·, rather than being dropped.
• A group header rolls up its members’ kinds as a per-kind tally (▲2 ◈1), in the order of the table above with unrecognized kinds last. A collapsed group mounts no member cards, so the header is the only place that provenance can surface.
• A trail ghost card carries no glyph by design — a ghost is a referenced task with no local file, so there is nothing to classify.

Reading and changing the kind in Task Detail

The Task Detail dialog carries a Follow-up row directly below Type, showing the same glyph and colour as the card plus the kind’s name — so the glyph on a card is decodable without leaving the board. A task that is not a follow-up shows (none).

Press Enter on the row to open a picker listing every kind, plus a (none) — not a follow-up row at the top that removes the field.

• Choosing a kind writes it immediately and reloads the dialog — unlike Priority, Effort, Status and Type, it is not held until you press Save. Because of that, the row is inert while those fields have unsaved edits: it shows (save or revert pending edits first) and tells you so if you press Enter. Save or revert first, then set the kind.
• Clearing removes followup_kind from the task file rather than blanking it. There is no “empty” state to leave behind.
• manual_verification may only be set on a task whose issue_type is also manual_verification. Choosing it otherwise is refused, and the reason appears as an error notification.
• A task carrying an unrecognized value shows it verbatim beside the · glyph, and the picker names it and starts on Cancel — so a stray Enter cannot delete the value you opened the dialog to inspect.
• Archived and folded tasks show the row as a plain line, and only when a kind is set.

ait ls and the pick flow surface the same provenance in text form — see Task Management.

Issue Platform Indicators

The board detects the issue tracking platform from the URL hostname:

PR Platform Indicators

Tasks created from pull requests (via ait pr-import) display a pull request indicator on the task card info line:

GitLab uses “MR” (Merge Request) terminology, which the indicator reflects.

View Filters

The View Selector widget at the top-left of the filter area renders as:

[a All | l Locked | f Free | i In-Flight | y By-Topic | z By-Trail]   g Git   t Type

It splits filtering into a base radio (mutually exclusive — exactly one is always active) and two independent add-on toggles. The active base and any active toggle are highlighted in bold cyan; inactive segments are dimmed. All filters compose with text search using AND logic.

Base filters (radio)

Pressing the key for the currently active base is a no-op. Locked and Free are leaf-level inverses (Locked ∪ Free = All, Locked ∩ Free = ∅) — the Locked view additionally includes parent/sibling cards as context.

By-Topic lanes: The By-Topic view uses the task’s anchor field when set; otherwise a child falls back to its parent topic and a standalone task falls back to its own id. If the root task is archived or not currently loaded, the anchor id still remains the stable lane key. Topics with only one visible task are collected in the trailing Ungrouped lane. See Topic anchoring for creation flags, inheritance rules, and when to use anchors instead of parent-child tasks or dependencies.

By-Topic lane sort order: Lanes are ordered most-recently-touched first by default. In the By-Topic view, press o to open a picker and choose the lane sort mode:

The Ungrouped lane stays pinned last in every mode. The choice persists per-user (in your local board settings), so it survives restarts without affecting teammates.

By-Trail

An implementation trail is a durable, wave-structured record of how a group of tasks should be sequenced, with the evidence behind that ordering. Trails are created and re-authored by the /aitask-trail skill — on the board, focus a task in a kanban or By-Topic view and press T to start one (T is hidden in In-Flight and in By-Trail itself). The By-Trail view is a read-only projection of a stored trail: it never writes the trail itself.

Press z to enter the view and s to choose which trail it shows. Each wave becomes a column headed W1 · <title>, and each card shows the member’s classification glyph, its confidence, its task status, and any drift marker. Enter opens the full narrative for that member. Members that are not live tasks in this repository — cross-repo members, archived tasks, and tasks that have gone missing — appear as read-only ghost cards.

The summary pane. A short pane below the wave columns carries the trail’s free-form summary — the prose answer to “what should land next, and why”. It appears only in By-Trail, and only when the trail has a summary to show; the columns take the full height otherwise. Press v to open the same text in a scrollable dialog when it is longer than the pane, and Escape to close.

The depth label. The view’s subtitle states the trail’s authoring depth when the artifact records one — · lite or · deep. A trail written before depth was recorded shows no label at all rather than being presented as either, so an unlabelled trail means “depth not recorded”, never “deep”.

Reading one card’s context. In the detail screen the focused member’s own material comes first: its entry, its wave, its drift reasons, and the observations and evidence that concern it. The trail-wide sections that are not about this card are withheld and summarized as a count; press a to reveal the whole document, and a again to return. A card in a trail with no observations or exclusions reads as complete rather than empty — there is nothing withheld to reveal.

Keeping the view current. Five keys refresh different things, at very different costs:

Reach for r when a task’s status changed on this machine — it is free. Reach for s when a new trail was created since the board started: the scan reads task files from disk, so the new trail is listed without restarting the board (leaving and re-entering the view with z re-scans too). Reach for S when the change was made elsewhere: task data lives on the aitask-data branch, so a status set by another machine or a remote agent only arrives in this checkout through a sync. Use d to re-check drift without re-authoring anything; it never modifies the stored trail. R is the heavyweight option — it hands the trail to an agent, which rewrites it. After a refresh is launched, the view watches for the new version and reloads on its own when it lands, giving up after about half an hour.

R re-authors at the lite depth, which is the default for the trail skill. A lite trail keeps the waves, entries, per-member rationale and the summary, and omits the trail-wide observations, relations and exclusions along with the per-member evidence citations — so it is much cheaper to produce and still renders here with full lanes, badges, landed marks and drift markers. Because the depths differ in what they store, pressing R on a trail authored at deep replaces it with a lite version; the agent lists exactly what that discards and asks before writing, and the previous version stays retrievable from the artifact’s history. To re-author at full depth, run the trail skill directly with its --deep flag rather than using R.

If the scan cannot read one of your task files — a task being rewritten at that exact moment, or a malformed one — the view says so and leaves the trail list alone rather than reporting that there are no trails. Press s again.

Drift markers. A trail records what it knew when it was written. When a member’s live state no longer matches that snapshot, the card shows an amber marker:

⚠ status_changed: status 'Ready' -> 'Implementing'

Up to two reasons are shown per card, with (+N more) when there are others; the complete list is in the detail screen. Common reasons are status_changed, task_completed, task_archived, task_folded, task_deleted, dependency_changed, gate_state_changed, and plan_changed. Drift is a signal that the trail’s sequencing advice may be out of date — R re-authors it.

Moving a wave into a column

The By-Trail view is read-only about the trail, but it can move the underlying tasks onto the board. m moves the focused entry’s task; M moves every task in the focused wave.

M always shows the review dialog first, listing the tasks in wave order — not board order — and that order is preserved through the move, so a wave dropped into an empty column lands in the sequence the trail recommends. m on a single focused card skips the review and goes straight to the destination picker.

Both report what they leave behind rather than a bare count:

• Ghost members — archived, cross-repo, or missing tasks — cannot move; there is no local task file behind them. m refuses outright on a ghost card, and M names the ghosts it skipped while moving the rest of the wave.
• Child tasks move with their parent, so M skips them and names them. m is withheld entirely on a focused child, while M stays available — a focused child still identifies a wave whose parents can move.
• A task appearing twice in one wave moves once, and the duplicate is reported.

If nothing in the wave can move, the board says so instead of opening a picker. The move never writes to the trail: board column and position are not part of a trail’s freshness, so moving cards cannot make one stale.

Keys that behave differently here. The footer relabels itself per view, so it always shows what the keys actually do. In By-Trail it reads:

r Refresh   R Agent Refresh   d Freshness   s Select Trail   S Sync   v Summary   m Move to Col   M Move Wave

v Summary is listed only while the shown trail actually has a summary — the footer advertises the key when there is something behind it, not before. m Move to Col and M Move Wave are gated differently, and the difference shows on a focused child card: M needs any focused live card, while m additionally requires that card not be a child — a child moves with its parent, but it still identifies a wave whose parents can move. Both are withheld on a ghost card, which has no local task file behind it.

C (commit all modified tasks) is hidden in this view. A trail is a reading projection rather than a set of tasks you own, while “commit all” acts on every modified task in the repository — so the key is withheld rather than silently doing something wider than the view suggests. T, w, the reordering keys and marking (Space) are hidden for the same reason: a wave lane is not a column, so there is no position within it to reorder into.

Moving tasks out of a trail is the exception, because it is the one action whose target is an ordinary board column. m moves the focused entry’s task and M moves the whole focused wave — see Moving a wave into a column below.

Add-on filters (toggle)

Add-ons compose with the active base. Example: l + g shows busy tasks linked to an issue/PR; f + t (with bug selected) shows free bug tasks ready to pick.

Locked view auto-expansion: When the base filter switches to Locked, parent tasks that have at least one busy child are automatically expanded (their child cards are displayed). When switching away, these auto-expanded parents are collapsed back unless they were manually expanded before entering the view.

In-Flight Lanes and Workflow Phases

The In-Flight view describes work already under way along two independent axes:

• the lane (the column a card sits in) answers what happens next;
• the phase chip (a line on the card) answers where the task sits in the workflow.

Every card sits in exactly one lane and carries exactly one chip. Both are single values on the card; there is no multi-membership.

“Independent” means neither axis determines the other. It does not mean a task appears twice. The two pairs below are the worked examples — read both, because with only one of them the chip looks like a restatement of the lane.

Same phase, different lanes — the lane is not derivable from the phase:

Same lane, different phases — the phase is not derivable from the lane:

resume_point is the checkpoint a task’s gate ledger says it would resume from, and it takes three values: PLAN (nothing durable recorded yet), IMPLEMENT (the plan was approved, so the next thing owed is code) and POSTIMPL (the review passed, so what remains is merge and archival). marker is the deferred-plan marker — the frontmatter field recording an approved plan whose implementation was deliberately put off.

A and B are two different tasks. They share a phase because an approve-and-stop task reverts to Ready but keeps its gate ledger — the last thing recorded is still that the plan was approved — while the lane splits them on the question the operator actually asks: one can be handed to an agent, the other has not started.

The four lanes

In render order, with the card operations each offers:

Two rules that are not guessable from the lane names:

• Blocked outranks every other lane. A task with an approved plan and an unresolved dependency renders in Blocked, not Planned — the lane reports what can happen next, and the answer there is “nothing”.
• A Planned task offers p and nothing else, and the other keys are refused rather than merely hidden. Pressing g, s or f on one — through the key, a rebinding, or the command palette — shows an explanation instead of acting. Resuming would start implementation without passing the planning checkpoint and its remote drift check, and signing off would approve a review of code that was never written.

The five workflow phases

needs_attended_agent exists because a gate can be machine-run and still need a person to launch it: docs_updated is a machine gate whose work is a procedure, so the headless engine defers it and only an attended agent can run it. A task whose review already passed can therefore still be held back from archival, and reporting it as post-implementation would say “ready to archive” about a task the archival guard will refuse.

The label above is the chip’s stem. The rendered form differs between the two surfaces — the card’s chip is deliberately compact, and the task detail dialog carries the expanded one:

The (from marker) qualifier belongs to a Ready-plus-marker task and is detail-only. The marker outranks the ledger, so the chip does not claim there is no ledger — such a task usually has one. The card omits every qualifier on purpose: its own action line already says what to do, in plainer words than the ledger vocabulary.

Gate progress

Where a chip carries a fraction, it counts satisfied gates against enforced ones. Two rules read as bugs unless you know them:

• The denominator is the enforced active set, not the declared gates: list. A gate your execution profile filters out is not counted at all — it is neither in the numerator nor in the denominator. A task declaring three gates under a profile that enforces one shows x/1.
• A stale signature counts as not satisfied, even though the ledger says pass. A human approval is bound to the code it approved; when that code changes the signature no longer binds, and the archival guard treats the gate as outstanding. The board matches the guard rather than the raw ledger, and such a card says awaiting re-sign: <gate> so the action is the re-signing rather than a first signature.

A skipped gate is the mirror case: skip is terminal — “not applicable” — so it is satisfied and does count toward the numerator, even though it is not a pass.

Honest degradation

Under an execution profile that records no gates there is no ledger to read, so the view derives what it can from the task’s status, whether a plan file exists, and the deferred-plan marker — and says which of those it used:

unknown means “we cannot tell how far it got”, not “it has not started”. A task whose status is Implementing has asserted that implementation began; with neither a ledger nor a plan the board simply has no evidence of progress. No fraction is shown in that state — an absent fraction is a different claim from 0/N, and the board will not fabricate one.

Gates in Task Detail

Press Enter on a card to open the task detail dialog. When the task has gates or a ledger, it carries a Gates section — the expanded counterpart of the card’s chip, titled with the same fraction, e.g. Gates (2/3). It leads with the phase chip, then lists one row per enforced gate:

Gates your profile filtered out are listed afterwards under a dimmed filtered by profile (audit only) heading. They are shown so the difference between what a task declares and what is enforced is visible, and they are counted in nothing.

The section is read-only; gates are signed from the In-Flight view with s / f, or from the command line with ait gate.

Column Configuration

Columns are stored in aitasks/metadata/board_config.json:

{
  "columns": [
    {"id": "now", "title": "Now", "color": "#FF5555"},
    {"id": "next", "title": "Next Week", "color": "#50FA7B"},
    {"id": "backlog", "title": "Backlog", "color": "#BD93F9"}
  ],
  "column_order": ["now", "next", "backlog"],
  "settings": {
    "auto_refresh_minutes": 0,
    "sync_on_refresh": false
  }
}

• id — Unique identifier (auto-generated from title on creation)
• title — Display name (can include emojis)
• color — Hex color code for the column header and border
• column_order — Controls left-to-right display order
• settings.auto_refresh_minutes — Interval in minutes for periodic board refresh (0 to disable, default 0)
• settings.sync_on_refresh — Enable automatic sync with remote on each auto-refresh interval (default false). Requires .aitask-data worktree (data branch mode). When enabled, the board subtitle shows “+ sync”
• settings.collapsed_columns — List of column IDs that are currently collapsed (default: empty). Collapsed columns show only their title and task count in a narrow strip. Tasks in collapsed columns are not rendered, which improves performance for boards with many tasks

The “Unsorted / Inbox” column is a special dynamic column (ID: unordered) that appears automatically when any task resolves to it. Two states do: a task with no boardcol assignment at all, and a task explicitly moved into this column — moving a card here writes boardcol: unordered verbatim, as does ait update --boardcol unordered. Both render in this one lane, and ait ls --boardcol unordered lists both.

Color Palette

When adding or editing a column, you can choose from 8 predefined colors:

Task Metadata Fields

The board reads and displays the following frontmatter fields from task files:

Board Data Fields

Three metadata fields are managed internally by the board:

• boardcol — The column ID where the task is placed (e.g., "now", "backlog", "unordered"). Tasks without this field appear in the “Unsorted / Inbox” column, as do tasks carrying an explicit "unordered" — the two states are one lane. A non-string value (e.g. boardcol: 42, which YAML parses as an integer) matches no column at all and renders nowhere.
• boardgroup — The group slug within the column. The slug is the group’s identity — there is no group registry, no group ID and no stored title — so two spellings are two different groups, and ait update --boardgroup rejects a slug outside [a-z0-9_]+ rather than normalizing one into the other. An explicit "" means “deliberately ungrouped”, which is not the same as the field being absent.
• boardidx — The sort index within a column. Lower values appear higher; ties are broken by filename. Values are widely spaced rather than consecutive, and may be negative — a movement writes only the moved task’s file, placing it in the gap between its new neighbours rather than renumbering the column. Only the relative order is meaningful. When repeated moves into the same position exhaust a gap, that single column is re-spaced automatically.

These fields are always written last in the frontmatter and are updated using a reload-and-save mechanism that prevents overwriting other metadata fields changed externally.

Lock Status Display

Lock information is not stored in task files – it is fetched from the remote aitask-locks branch via aitask_lock.sh --list and maintained in memory as a lock map. The board refreshes the lock map on startup, on every manual/auto refresh, and after lock/unlock operations.

Locks older than 24 hours show a (may be stale) warning in the detail view.

Button states in detail dialog:

For details on the underlying lock mechanism, see the ait lock command reference.

Modal Dialogs Reference

Git Integration Details

The board auto-detects whether task data lives on a separate aitask-data branch (via the .aitask-data/ worktree) or on the current branch (legacy mode). All git operations are routed through a worktree-aware helper, so the board works transparently in both modes.

Modified file detection:

The board queries git status --porcelain -- aitasks/ on startup and after each refresh to identify modified .md files. Modified tasks show an orange asterisk (*) next to their task number. In branch mode, this targets the aitask-data worktree automatically.

Commit workflow:

1. Selected files are staged with git add <filepath>
2. A commit is created with the user-provided message
3. The board refreshes git status after commit

In branch mode, commits target the aitask-data branch, not the main code branch.

Revert workflow:

Runs git checkout -- <filepath> to discard local changes and restore the last committed version.

Delete workflow:

1. Files are removed with git rm -f <filepath> (falls back to os.remove for untracked files)
2. Empty child task/plan directories are cleaned up
3. An automatic commit is created: “Delete task t and associated files”

Configuration Files

These files are auto-created with defaults if they don’t exist. The .local.json layer is yours alone — collapsing a column or a group changes only your view, never a teammate’s.

Environment Variables

Terminal auto-detection order: $TERMINAL, then x-terminal-emulator, xdg-terminal-exec, gnome-terminal, konsole, xfce4-terminal, lxterminal, mate-terminal, xterm. If none found, the board suspends to run commands in the current terminal.

Next: Monitor — the dashboard of every pane in your tmux session.