Concepts on aitasks

Tasks

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A task is a markdown file with YAML frontmatter in the aitasks/ directory, named t<N>_<short_name>.md (for example aitasks/t130_add_login.md). The frontmatter block carries fields like priority, effort, depends, status, labels, assigned_to, issue_type, boardcol; the free-form markdown body describes the work. Tasks persist exactly the same way source code does: as files committed to git. Every CLI command, TUI, and code agent skill operates on those files directly.

Why it exists

Treating task tracking as a problem that belongs in version control means the full history of every task is visible in git log, branches and worktrees can carry their own task state, and a code agent can read, write, and reason about tasks with the same tools it uses for source code. The frontmatter schema is intentionally small enough for an LLM to keep in context, but expressive enough to drive prioritization, dependency resolution, and Kanban-style triage.

Plans

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A plan is a markdown file in aiplans/ named p<N>_<short_name>.md (mirroring its task: aiplans/p130_add_login.md corresponds to aitasks/t130_add_login.md). Child task plans live under aiplans/p<parent>/p<parent>_<child>_<name>.md. Each plan starts with a metadata header (the task it implements, the worktree, the branch, the base branch) and contains a context summary, a step-by-step implementation outline, the critical files to be touched, and verification steps. Plans are written during the planning phase of a skill like /aitask-pick and approved by the user before any code is written.

Parent and child tasks

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A parent task is a regular task whose work has been split into smaller child tasks. The parent file lives at the usual location (aitasks/t<N>_<name>.md); its children live in a sibling subdirectory aitasks/t<N>/ named t<N>_<M>_<name>.md — for example aitasks/t130/t130_1_add_login_form.md. The parent’s children_to_implement frontmatter field lists the child IDs that still need work. Children automatically depend on each other in order, and when the last child is archived the parent is archived too.

Folded tasks

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A folded task is a task whose content has been merged into another (the primary task). Folding sets the folded task’s status to Folded and writes a folded_into field pointing at the primary; the primary in turn lists every folded child in its folded_tasks frontmatter field. At fold time the folded task’s body is incorporated into the primary’s description under a ## Merged from t<N> header — the folded file remains on disk only as a reference for archival cleanup, and it is deleted (not archived) when the primary is archived.

Review guides

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A review guide is a markdown file in aireviewguides/ that captures a single concern a reviewer cares about — a security check, a portability rule, a stylistic convention, a project-specific invariant. Each guide carries a YAML frontmatter block (name, review type, language environment, files matched, similarity links to related guides) and a body of structured instructions the agent applies during review. Guides are organized into language-keyed subdirectories (aireviewguides/python/, aireviewguides/bash/, …) so reviews can target only the guides relevant to the changed files.

Execution profiles

Mon, 01 Jan 0001 00:00:00 +0000

What it is

An execution profile is a YAML file in aitasks/metadata/profiles/ that pre-answers the questions a skill would otherwise ask interactively. Each profile sets a handful of named keys — for example skip_task_confirmation, default_email, create_worktree, plan_preference, post_plan_action, qa_mode, manual_verification_followup_mode — that the skill then consults at each decision point. Profiles are picked at the start of a skill run (with --profile <name> or interactively from a list) and remain in effect for that session.

Verified scores

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A verified score is a numeric rating attached to a (code agent, model, operation) triple — for example “claudecode/opus4_7 / implementation” or “geminicli/gemini-2.5-pro / code-review”. Every time a user completes a skill they are prompted for a 1-5 satisfaction rating; those ratings are stored, time-windowed (all-time / month / week), and aggregated into score buckets:

Bucket	Range
Untested	0
Partial	1-49
Verified	50-79
Highly verified	80-100

Scores are surfaced in the Settings TUI and on the model entry pages so you can see which agent/model combinations are reliable for which kinds of work in your project.

Agent attribution

Mon, 01 Jan 0001 00:00:00 +0000

What it is

Agent attribution is the per-task record of which code agent and model did the implementation. It surfaces in three places:

The task’s implemented_with frontmatter field, written at the start of implementation in the form <agent>/<model> — for example claudecode/opus4_7_1m, geminicli/gemini3pro, codex/gpt5_4. The <model> segment is the name field from aitasks/metadata/models_<agent>.json, not the raw runtime CLI ID.
A Co-Authored-By: trailer appended to the implementation commit, naming the model with a project-configurable email domain.
The verified-scores subsystem, which keys per-operation satisfaction ratings off the same <agent>/<model> string.

The <model> segment is a normalized short ID resolved from the agent’s runtime model — Claude Code reads it from its system message, Codex CLI from ~/.codex/config.toml, Gemini CLI from ~/.gemini/settings.json, and OpenCode from its system context. A wrapper-set AITASK_AGENT_STRING environment variable overrides self-detection when present.

Locks

Mon, 01 Jan 0001 00:00:00 +0000

What it is

A task lock is an atomic claim on a single task ID, recorded on a dedicated aitask-locks git branch. When a skill picks a task it acquires the lock — recording the owner email, hostname, and timestamp — and only releases it on archival, abort, or explicit unlock. While a lock is held, other PCs and agents see the task as unavailable: a competing /aitask-pick that targets the same ID will fail with a structured LOCK_FAILED outcome that includes the current owner. Stale locks (held by a hostname/agent no longer working the task) can be force-unlocked, optionally with a confirmation prompt.

Task lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

What it is

Every task carries a status field that captures where it is in its life:

Status	Meaning
`Ready`	Created and triaged. Available to be picked.
`Editing`	Being authored or revised in a TUI; not yet ready for implementation.
`Implementing`	A skill has claimed the task; an agent is actively working on it.
`Postponed`	Deferred — left visible but skipped during normal selection.
`Done`	Implementation finished and committed. Awaiting archival.
`Folded`	The task has been merged into another (the `folded_into` task).

Transitions are driven by the workflow scripts: picking a task moves Ready → Implementing and acquires a lock; a successful run moves Implementing → Done (then Done → Archived as the file moves into aitasks/archived/); aborting reverts to Ready and releases the lock. Folded is a terminal status — folded files are deleted (not archived) when the primary they were merged into is archived.

Git branching model

Mon, 01 Jan 0001 00:00:00 +0000

What it is

aitasks splits the repository across several long-lived branches:

Branch	Purpose
`main` (or your code branch)	Source code only — no `aitasks/` or `aiplans/` content.
`aitask-data`	All task and plan files. Checked out as a worktree at `.aitask-data/`.
`aitask-locks`	Atomic task locks (one commit per lock acquire / release).
`aitask-ids`	Reservation log used to allocate fresh task IDs without collisions.

aitasks/ and aiplans/ at the project root are symlinks into the .aitask-data/ worktree, so they appear in the usual places but actually live on aitask-data. The ./ait git wrapper routes git commands to the correct worktree based on the paths you pass — ./ait git add aitasks/t42_foo.md operates on aitask-data, git add src/foo.py operates on main, and the two are committed independently.

The IDE model

Mon, 01 Jan 0001 00:00:00 +0000

What it is

The aitasks IDE is a tmux session organized by window-naming convention, not a fixed layout. The framework reserves a small set of window names — monitor, board, codebrowser, settings, brainstorm, plus an agent-<n> prefix for code agent windows — and the integrated TUIs all look up tmux windows by these names. Open, close, rearrange, or split them however you like; what matters is the name.

The Monitor TUI acts as the conventional home screen, listing every code agent and TUI window in the session with a live preview and keystroke forwarding. Pressing j in any main TUI opens the TUI switcher dialog, which lists every integrated TUI plus every running code agent window — selecting an entry either focuses the existing window (looked up by name) or spawns it on the fly. A narrow Minimonitor sidebar variant of monitor can sit next to a code agent pane to keep sibling activity visible without giving up screen real estate.

Agent memory

Mon, 01 Jan 0001 00:00:00 +0000

What it is

Once a task is archived, its task file moves to aitasks/archived/ and its plan file — including the post-implementation notes — moves to aiplans/archived/. Together they form a structured, version-controlled record of every change ever made through the framework, linked back to the commits that implemented them. The framework treats this archive as agent memory: a queryable corpus that subsequent agent sessions read instead of re-deriving context from scratch.