Intermediate on aitasks

Capturing Ideas Fast

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

The most important thing when a new task idea comes to mind is capturing it immediately, before the thought fades. The ait create script is designed for this: you can write a task description as a raw stream of consciousness without worrying about structure, grammar, or completeness.

The philosophy: capture intent now, refine later.

In interactive mode, ait create walks you through metadata selection (priority, effort, labels) via fast fzf menus, then lets you enter the description as consecutive text blocks. There is no need to open an external editor or craft a polished specification — the follow-up planning workflow is designed to turn rough, unstructured descriptions into actionable implementation plans.

How-To Guides

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

How to Organize Tasks into Columns

Moving a task to a different column:

Focus the task card using arrow keys
Press Shift+Right to move it to the next column, or Shift+Left to move it to the previous column

The task is appended to the end of the target column. Column order follows the configured order, with “Unsorted / Inbox” on the far left. Collapsed columns are skipped when moving tasks.

How-To Guides

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

How to Navigate Files in the Tree

Press Tab to focus the file tree (if not already focused)
Use Up / Down arrows to move between files and directories
Press Enter or click a file to open it in the code viewer
Directories expand and collapse as you navigate into them

The tree shows only git-tracked files, automatically excluding __pycache__, node_modules, and .git directories. Dotfiles (like .gitignore) are included.

How to Navigate Code

Once a file is open in the code viewer:

How-To Guides

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

How Minimonitor Is Auto-Spawned

Minimonitor is meant to be auto-spawned — you almost never start it yourself. Every ait TUI that launches a new code agent window also creates a minimonitor split next to it:

ait board — when you pick a task and launch its agent (action menu or agent command screen).
ait codebrowser — when you launch an agent from a code file or the history screen.
ait monitor — when you press n on an agent card to pick its next ready sibling task, which creates a new agent window.
The TUI switcher’s explore launch — when it creates an agent window for an explore target.

In every case the flow is the same: the launching TUI creates a new tmux window named agent-..., then the auto-spawn helper creates a horizontal right-split inside that window and runs ait minimonitor in it. The helper skips the split if the window name does not start with the configured agent prefix (default agent-) or if a monitor/minimonitor is already running in the window.

How-To Guides

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

How to Start the Monitor

Recommended — via ait ide:

ait ide

This is the one-command path to the ait tmux IDE. ait ide resolves the tmux session name from tmux.default_session in project_config.yaml (defaulting to aitasks), creates or attaches to that session, and opens a monitor window inside it. Because it always passes an explicit session name, the session-rename dialog never fires.

Standalone — from inside an existing tmux session:

ait monitor

Run this from within a tmux session you already have open. Monitor attaches to the current session.

Setup & Install

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

ait setup

Cross-platform dependency installer and configuration tool. This is typically the first command to run after installing aitasks.

Run from the project root. Both ait setup and the curl installer must be executed from the root of your git repository (the directory containing .git/). aitasks stores task files, plans, skills, and configuration inside the repo and relies on git for task IDs, locking, and multi-machine synchronization.

ait setup

Auto-bootstrap: When run via the global shim (~/.local/bin/ait) in a directory without an existing aitasks installation, ait setup automatically downloads and installs the latest release before running the setup flow. This lets you bootstrap new projects with a single command — no need to run the curl | bash installer separately.

/aitask-pickrem

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

A mostly autonomous version of /aitask-pick designed for non-interactive environments. It combines task selection and implementation into a single flow with zero AskUserQuestion calls — all decisions are driven by an execution profile. The only interactive step is plan approval, which still requires the user to review and confirm the implementation plan via ExitPlanMode.

Note: This skill requires write access to the task data branch, so it is suited for local Claude Code or CI-like environments. For Claude Code Web (which cannot write to branches other than the code branch), use /aitask-pickweb instead.

/aitask-pickweb

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

A sandboxed version of /aitask-pickrem designed specifically for Claude Code Web, where the environment has no push access to aitask-locks, aitask-data, or main branches. It combines task selection and implementation into a single flow with zero AskUserQuestion calls — all decisions are driven by an execution profile. The only interactive step is plan approval, which still requires the user to review and confirm the implementation plan via ExitPlanMode.

All task metadata (plans, completion markers) is stored in .aitask-data-updated/ on the current working branch. After the Claude Web session completes, run /aitask-web-merge locally to merge code to main and archive the task.

Monitor

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

The ait monitor command launches an interactive TUI that shows every pane in the current tmux session, categorized as code agents, TUIs, or other panes, with a live preview of the focused pane and keystroke forwarding. It is the dashboard of the ait tmux-based development environment: from a single window you can watch agents work, jump to any other TUI, and interact with running processes without leaving the monitor.

Tutorial

Launching the Monitor

The recommended way to start monitor is via ait ide:

Retroactive Change Tracking

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

Not every change starts with a task. Quick fixes get applied directly, debugging sessions turn into real improvements, config changes happen on the fly, and pair programming sessions accumulate changes without formal tracking. The /aitask-wrap skill retroactively integrates these changes into the aitasks framework so nothing falls through the cracks.

The philosophy: never lose traceability, even for unplanned work.

When You Need This

Quick fixes applied directly — You spotted a bug during code review and fixed it in 30 seconds. It’s uncommitted, untracked, and will be lost in the noise if not documented
Debugging that became an improvement — You started investigating an issue, found the root cause, and fixed it — but never created a task because you weren’t sure it would lead anywhere
Config or dependency changes — Updated a package version, tweaked a build setting, or adjusted environment config outside the normal task flow
Pair programming or live-coding — Changes accumulated during a collaborative session without task tracking

Walkthrough: Wrapping a Quick Fix

You fixed a shell quoting bug in aitask_ls.sh while working on something else. The fix is uncommitted and you want to document it properly.

Minimonitor

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

ait minimonitor is a narrow (~40 column) sidebar TUI that lists every running code agent across every aitasks tmux session on the current tmux server, with idle indicators and a companion-pane focus model. It is the agents-only cousin of ait monitor: no preview panel, no TUI/other pane categories — just the running agents in a compact column designed to sit next to a code pane while you work.

Minimonitor is meant to be auto-spawned alongside every code agent you launch from the ait TUIs. You rarely need to start it yourself — whenever a new agent window is created, the launching TUI also splits a minimonitor pane next to it, and minimonitor closes itself automatically when the agent pane exits. Manual launch via ait minimonitor is supported but is an escape hatch rather than the primary workflow.

/aitask-explore

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

Explore the codebase interactively with guided investigation, then create a task from findings. This skill bridges the gap between “I think something needs work” and a well-defined task with context.

Usage:

/aitask-explore [--profile <name>]

The optional --profile <name> argument overrides execution-profile selection for this invocation, mirroring /aitask-pick --profile.

Note: Must be run from the project root directory. See Skills overview for details.

Codex CLI note: When continuing from this skill into implementation, in Codex wrappers, after implementation, most of the times you will need to explicitly tell the agent to continue the workflow because request_user_input is only available in plan mode. Example prompts: Good, now finish the workflow or Good, now continue.

Code Browser

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

The ait codebrowser command launches an interactive terminal-based code browser for exploring project files with task-aware annotations. Built with Textual, it provides syntax-highlighted file viewing, a git-aware file tree, and an annotation gutter that maps lines of code to the aitasks that introduced them — powered by the explain data pipeline.

The ait codebrowser with file tree (left) and syntax-highlighted code viewer (right)

How-To Guides

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

Change the Default Model for an Operation

Open the Settings TUI: ait settings
Press a to go to the Agent Defaults tab
Navigate to the operation you want to change (e.g., task-pick)
Press Enter to open the agent/model picker
Step 1: Select the code agent (claudecode, geminicli, codex, opencode)
Step 2: Select the model from the list, then choose the target layer:
- Project – Saves to codeagent_config.json (shared, git-tracked)
- User – Saves to codeagent_config.local.json (personal, gitignored)
The change takes effect immediately

Note: Choosing User layer means this override only applies to your machine. Other team members will continue using the project default.

Complex Task Decomposition

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

For tasks that are too large or risky for a single implementation run, the aitasks framework supports decomposition into child subtasks. This gives you controlled, disciplined execution of complex features while maintaining full context across all subtasks.

Two complementary skills cover adjacent patterns: /aitask-explore creates tasks (often multiple) from codebase exploration — useful when you need to discover the shape of the work before decomposing it — and /aitask-fold is the inverse, merging overlapping tasks into one (see Task Consolidation).

Task Management

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

ait create

Create new task files with YAML frontmatter metadata. Supports standalone and parent/child task hierarchies.

Interactive mode (default — requires fzf):

Draft management — If drafts exist in aitasks/new/, a menu appears: select a draft to continue editing, finalize (assign real ID and commit), or delete — or create a new task
Parent selection — Choose “None - create standalone task” or select an existing task as parent from a fzf list of all tasks (shown with status/priority/effort metadata)
Priority — Select via fzf: high, medium, low
Effort — Select via fzf: low, medium, high
Issue type — Select via fzf from aitasks/metadata/task_types.txt (bug, chore, documentation, feature, performance, refactor, style, test)
Status — Select via fzf: Ready, Editing, Implementing, Postponed
Labels — Iterative loop: pick from existing labels in aitasks/metadata/labels.txt, add a new label (auto-sanitized to lowercase alphanumeric + hyphens/underscores), or finish. New labels are persisted to the labels file for future use
Dependencies — fzf multi-select from all open tasks. For child tasks, sibling tasks appear at the top of the list. Select “None” or press Enter with nothing selected to skip
Sibling dependency (child tasks only, when child number > 1) — Prompted whether to depend on the previous sibling (e.g., t10_1). Defaults to suggesting “Yes”
Task name — Free text entry, auto-sanitized: lowercase, spaces to underscores, special chars removed, max 60 characters. Preview shows draft_*_<name>.md (real ID is assigned during finalization)
Description — Iterative loop: enter text blocks, optionally add file references (fzf file walker with preview of first 50 lines, can also remove previously added references), then choose “Add more description” or “Done - create task”
Post-creation — Choose: “Finalize now” (claim real ID and commit), “Show draft”, “Open in editor” ($EDITOR), or “Save as draft” (finalize later via ait create or --batch --finalize)

Batch mode (for automation and scripting):

Windows & WSL Installation

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

Step-by-step guide for installing and configuring aitasks on Windows via the Windows Subsystem for Linux (WSL).

Prerequisites

Windows 10 version 2004+ or Windows 11
Administrator access (for WSL installation)

Install WSL

aitasks runs inside WSL (Windows Subsystem for Linux). If you don’t have WSL installed:

Open PowerShell as Administrator
Run:
```
wsl --install
```
Restart your computer when prompted
On first launch, create a Unix username and password

For detailed instructions, see the official WSL installation guide.

Task Consolidation (Folding)

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

When multiple people capture ideas independently, or separate exploration sessions uncover the same issue, you end up with overlapping tasks. Rather than implementing them separately (duplicating effort) or manually deleting the extras (losing context), the aitasks framework lets you fold related tasks into a single primary task that incorporates all their content.

This is conceptually the opposite of task decomposition but serves a different purpose: decomposition splits a complex task for controlled execution, while consolidation merges redundant tasks for efficient execution.

/aitask-fold

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

Identify and merge related tasks into a single task, then optionally execute it. This skill provides the same folding capability as /aitask-explore but as a standalone skill — no codebase exploration required.

Usage:

/aitask-fold # Interactive: discover and fold related tasks
/aitask-fold 106,108,112 # Explicit: fold specific tasks by ID

Note: Must be run from the project root directory. See Skills overview for details.

Codex CLI note: When continuing from this skill into implementation, in Codex wrappers, after implementation, most of the times you will need to explicitly tell the agent to continue the workflow because request_user_input is only available in plan mode. Example prompts: Good, now finish the workflow or Good, now continue.

Board, Code Browser & Stats

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

ait board

Open the kanban-style TUI board for visual task management.

ait board

Launches a Python-based terminal UI (built with Textual) that displays tasks in a kanban-style column layout. All arguments are forwarded to the Python board application.

For full usage documentation — including tutorials, keyboard shortcuts, how-to guides, and configuration — see the Kanban Board documentation.

Requirements:

Python venv at ~/.aitask/venv/ with packages: textual, pyyaml, linkify-it-py
Falls back to system python3 if venv not found (warns about missing packages)
Checks terminal capabilities and warns on legacy terminals (e.g., WSL default console)

ait codebrowser

Open the code browser TUI for file exploration with task annotations.

Known Agent Issues

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

This page tracks current workflow issues by code agent. Issues are grouped by agent below.

Claude Code

Medium-effort models can miss workflow steps

In strict multi-step aitask-* workflows, medium-effort models may skip required checkpoints or finalization steps.

Use stronger reasoning/model settings when you need reliable workflow compliance.

Gemini CLI

Per-project shell command policies are not applied

Gemini CLI supports policy files (.gemini/policies/*.toml) for pre-approving shell commands via commandPrefix and commandRegex rules. However, per-project policy files are not applied — the CLI ignores them even when they are correctly referenced in .gemini/settings.json via policyPaths.

Settings

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

Launching

ait settings

The Settings TUI requires the shared Python virtual environment (installed by ait setup) with the textual and pyyaml packages.

Understanding the Layout

The Settings TUI organizes configuration into five tabs, each accessible via a keyboard shortcut displayed in the footer.

Agent Defaults (a)

The Agent Defaults tab shows which code agent and model is configured for each operation

Terminal Setup

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

Terminal emulator vs. terminal multiplexer

Two distinct pieces of software cooperate when you use aitasks from the terminal:

A terminal emulator is the GUI application you run — Ghostty, WezTerm, Alacritty, kitty, iTerm2, Konsole, gnome-terminal, and so on.
A terminal multiplexer runs inside a terminal emulator and splits your single terminal window into multiple independent sessions, windows, and panes. tmux is the multiplexer aitasks integrates with.

tmux is not a terminal emulator — it always runs inside one.

Explain Utilities

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

ait explain-runs

Manage aitask-explain run directories. The /aitask-explain skill generates reference data (git history analysis, task/plan mappings) in directories under .aitask-explain/. Over time these accumulate. Use ait explain-runs to list, inspect, and clean up old run data.

Interactive mode (default — requires fzf):

ait explain-runs

Presents a list of all existing runs (both top-level and codebrowser) with file counts and previews. Select a run to delete it, or choose “Delete ALL runs” to remove everything. Confirmation is required before deletion.

Stats

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

Launching

ait stats-tui

The Stats TUI requires the shared Python virtual environment (installed by ait setup) with the textual and pyyaml packages. Interactive chart panes additionally need the optional plotext package — ait setup prompts Install plotext for 'ait stats-tui' chart panes? [y/N] in the Python venv step. Without plotext, the TUI still launches but chart panes render placeholders instead of charts.

Inside tmux you can also reach the TUI via the TUI switcher — press j in any other aitasks TUI and pick Stats.

Sync

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

ait sync

Sync task data with a remote repository: auto-commit local changes, fetch, pull with rebase, and push. Designed for multi-machine workflows where task files may be edited on different PCs.

ait sync # Interactive mode with colored progress
ait sync --batch # Structured output for scripting/automation

Option	Description
`--batch`	Structured single-line output for scripting (no colors, no interactive prompts)
`--help, -h`	Show usage help

Interactive Mode

In interactive mode, ait sync displays colored progress messages as it works through each step:

Lock

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

ait lock

Lock and unlock tasks to prevent two users or agents from working on the same task simultaneously. Uses atomic git operations on a separate aitask-locks branch.

ait lock 42 # Lock task t42 (auto-detects email)
ait lock 42 --email user@co.com # Lock with explicit email
ait lock --unlock 42 # Release lock on t42
ait lock --check 42 # Check if t42 is locked
ait lock --list # Show all active locks

Command	Description
`<task_id>`	Lock a task. Auto-detects email from `userconfig.yaml`, falling back to `emails.txt`
`--lock <task_id> [--email EMAIL]`	Explicit lock syntax (same as bare task ID)
`--unlock <task_id>`	Release a task lock. Idempotent (succeeds even if not locked)
`--check <task_id>`	Check lock status. Exit 0 = locked (prints lock info), exit 1 = free
`--list`	List all currently locked tasks
`--init`	Initialize the `aitask-locks` branch on the remote (usually done by `ait setup`)
`--cleanup`	Remove stale locks for tasks that have been archived

Option	Description
`--email EMAIL`	Override email for locking (default: auto-detect)
`--debug`	Enable verbose debug output

Email Auto-Detection

When locking a task without --email, the command resolves the email in this order:

/aitask-create

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

Create a new task file with automatic numbering and proper metadata via interactive code agent prompts.

Usage:

/aitask-create

Note: Must be run from the project root directory. See Skills overview for details.

Step-by-Step

The skill guides you through task creation using interactive prompts:

Parent selection — Choose standalone or child of existing task
Task number — Auto-determined from active, archived, and compressed tasks
Metadata — Priority, effort, dependencies (with sibling dependency prompt for child tasks)
Task name — Free text with auto-sanitization
Definition — Iterative content collection with file reference insertion via Glob search
Create & commit — Writes task file with YAML frontmatter and commits to git

Batch Mode

For non-interactive task creation (e.g., scripting or automation), use the underlying script directly with --batch:

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.

/aitask-wrap

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

Retroactively wraps uncommitted changes into the aitasks framework. When you’ve made changes outside the normal task flow — quick fixes, debugging improvements, config tweaks — this skill analyzes the diff, creates a task and plan file documenting the changes, commits everything with proper format, and archives it in one flow.

Usage:

/aitask-wrap

Note: Must be run from the project root directory. See Skills overview for details.

Step-by-Step

Detect changes — Scans for uncommitted changes (staged, unstaged, and untracked). Aborts if nothing to wrap
Select files — Choose to include all changes or select specific files
Analyze diff — Reads the full diff and determines: factual summary, probable intent, suggested issue type, task name, labels, priority, and effort. In Claude Code, also checks ~/.claude/plans/ for a recent internal plan that matches the changes and incorporates it into the plan file if found
Confirm analysis — Presents the analysis for review. Adjust task name, metadata, or descriptions before proceeding
Execute — After a final confirmation gate, runs everything without further prompts: creates task file → creates plan file → commits code changes → archives task and plan → pushes to remote
Summary — Displays the created task, plan, commit hashes, and archive status
Satisfaction feedback — Optional prompt to record how well the wrap served your needs. Controlled by enableFeedbackQuestions; see Verified Scores

Key Capabilities

Auto-analysis — Reads the diff to infer intent, suggest an issue type (feature, bug, refactor, etc.), and generate task/plan descriptions
Metadata suggestions — Suggests priority, effort, and labels based on diff size and file paths. All suggestions are adjustable before execution
Single confirmation gate — All user interaction happens before Step 5. Once confirmed, everything executes sequentially without interruption
All-in-one execution — Task creation, plan creation, code commit, archival, and push happen in a single automated sequence
Edge case handling — Handles large diffs (>2000 lines) with truncation warnings, mixed staged/unstaged changes, and untracked files

When to Use

Scenario	Skill
Changes already made, need to document retroactively	`/aitask-wrap`
Planning work before starting implementation	`/aitask-create`
Want to explore the codebase first, then create a task	`/aitask-explore`

Use /aitask-wrap when you’ve accumulated uncommitted changes that weren’t tracked through the normal task flow — quick fixes applied directly, debugging sessions that turned into real improvements, config or dependency changes made outside the framework, or pair programming sessions where changes accumulated without task tracking.

Code Agent

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

ait codeagent

Unified wrapper for invoking AI code agents (Claude Code, Gemini CLI, Codex CLI, OpenCode) with configurable per-operation model selection.

ait codeagent list-agents # Show available agents
ait codeagent list-models claudecode # List Claude models
ait codeagent resolve task-pick # Show configured agent/model
ait codeagent check "claudecode/opus4_6" # Validate an agent string
ait codeagent coauthor "codex/gpt5_4" # Resolve commit coauthor metadata
ait codeagent invoke task-pick 42 # Pick task 42 with configured agent
ait codeagent --agent-string geminicli/gemini2_5pro invoke explain src/ # Override agent
ait codeagent --dry-run invoke task-pick 42 # Preview command without running

Agent String Format

An agent string identifies both the code agent and the model to use, in the format <agent>/<model>:

/aitask-stats

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

View task completion statistics via a code agent.

Usage:

/aitask-stats

Note: Must be run from the project root directory. See Skills overview for details.

Runs ./.aitask-scripts/aitask_stats.sh and displays the results. Provides the same statistics as ait stats, including:

Summary counts (7-day, 30-day, all-time)
Daily breakdown with optional task IDs
Day-of-week averages
Per-label weekly trends (4 weeks)
Label day-of-week breakdown (30 days)
Task type weekly trends
Label + issue type trends
Code agent weekly trends (last 4 weeks)
LLM model weekly trends (last 4 weeks)
Verified model score rankings per skill (pick, explain, batch-review) – see Verified Scores for how scores are accumulated
- All-providers aggregated view with per-provider breakdowns
- Time-windowed display (all-time, this month)

Supports all command-line options (-d, -v, --csv, -w). For interactive terminal charts (including code agent / LLM model histograms and verified score ranking bar charts per skill), run ait stats-tui or switch into it from any other aitasks TUI via the TUI switcher. For CSV export, provides guidance on opening the file in LibreOffice Calc with pivot tables and charts.

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.

/aitask-explain

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

Explain files in the project by providing detailed analysis of their functionality, real usage examples from the codebase, and code evolution history traced through aitask and aiplan records. The unique value of this skill is answering not just “what does this code do” but “why does it exist and how did it get here” — by connecting code sections back to the tasks that motivated each change and the plan notes that document the reasoning.

/aitask-changelog

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

Generate a changelog entry by analyzing commits and archived plans since the last release. Orchestrates the ait changelog command with AI-powered summarization.

Usage:

/aitask-changelog

Note: Must be run from the project root directory. See Skills overview for details.

Step-by-Step

Gather release data — Runs ait changelog --gather to collect all tasks since the last release tag, with their issue types, plan files, commits, and implementation notes
Summarize plans — Reads each task’s archived plan file and generates concise user-facing summaries (what changed from the user’s perspective, not internal details)
Draft changelog entry — Groups summaries by issue type under ### Features, ### Bug Fixes, ### Improvements headings. Format: - **Task name** (tNN): summary
Version number — Reads VERSION file, calculates next patch/minor, asks user to select or enter custom version
Version validation — Ensures the selected version is strictly greater than the latest version in CHANGELOG.md (semver comparison)
Overlap detection — Checks if any gathered tasks already appear in the latest changelog section. If overlap found, offers: “New tasks only”, “Replace latest section”, or “Abort”
Review and finalize — Shows the complete formatted entry for approval. Options: “Write to CHANGELOG.md”, “Edit entry”, or “Abort”
Write and commit — Inserts the entry into CHANGELOG.md (after the # Changelog header) and commits

Key Features

User-facing summaries: focuses on what changed, not implementation details
Version validation prevents duplicate or regressive version numbers
Overlap detection handles incremental changelog updates when some tasks were already documented
Supports both new CHANGELOG.md creation and insertion into existing files

Workflows

For a full workflow guide covering the release pipeline, see Releases.

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.

Follow-Up Tasks and Task Discovery

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

While working on a task via /aitask-pick, your code agent session has full context about the current implementation: the codebase, the task definition, the plan, and all changes made so far. This makes it an ideal moment to create follow-up tasks, but also to discover and update existing tasks — far more effective than doing either separately.

During Implementation

When you notice something that needs a follow-up task while the agent is working, simply ask:

Creating Tasks from Code

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

When you spot a TODO, a smell, or a bug while reading a file, you want a task that points at the exact lines so the implementing agent already has the context. The file_references frontmatter field is the structured home for those pointers, and ait codebrowser + aitask_create.sh together turn “I saw something weird on line 42” into a committed task without ever leaving your viewer.

This workflow ties together:

/aitask-review

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

Review code using configurable review guides, then create tasks from findings. This skill separates code quality review from implementation — first build something that works, then systematically review it for quality improvements.

Usage:

/aitask-review # Interactive: choose scope and review guides

Note: Must be run from the project root directory. See Skills overview for details.

Codex CLI note: When continuing from this skill into implementation, in Codex wrappers, after implementation, most of the times you will need to explicitly tell the agent to continue the workflow because request_user_input is only available in plan mode. Example prompts: Good, now finish the workflow or Good, now continue.

Code Review Workflow

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

The aitasks review system separates code quality review from implementation. The philosophy: first build something that works, then review it for quality improvements. This separation of concerns makes more efficient use of the LLM context — implementation and review are distinct cognitive tasks that benefit from dedicated focus.

The Review Cycle

After completing an implementation task with /aitask-pick, run a targeted review:

Run /aitask-review — Select the files or commits to review, and choose which review guides to apply. The skill auto-detects the most relevant guides based on the languages and frameworks in your code
Review findings — Examine the results grouped by guide and severity. Select which findings to act on
Create tasks — Turn selected findings into tasks (single task, grouped by guide, or one per finding)
Implement fixes — Run /aitask-pick on the review task to fix the issues

This cycle can be repeated with different review guides to cover multiple quality dimensions (security, performance, style, etc.).

/aitask-qa

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

Run QA analysis on any task — discover tests, run them, identify gaps, and create follow-up test tasks. This skill works with both active and archived tasks, making it useful for reviewing test coverage at any point in the task lifecycle.

Usage:

/aitask-qa # Interactive: select from recently archived tasks
/aitask-qa 42 # Analyze a specific parent task
/aitask-qa 16_2 # Analyze a specific child task

Note: Must be run from the project root directory. See Skills overview for details.

Exploration-Driven Development

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

Sometimes you don’t know what the task should be. You have a vague symptom, an unfamiliar module to understand, or a hunch that something could be improved — but you can’t write a task description yet because you haven’t explored enough to know what needs doing. The /aitask-explore skill is designed for exactly this situation.

The philosophy: explore first, define the task from what you find.

This inverts the normal aitasks flow. Instead of define task → pick task → implement, you follow explore → discover → define task → implement. The exploration phase is interactive and iterative — you direct the agent’s investigation, review findings after each round, and decide when you’ve learned enough to crystallize a task.

QA and Testing Workflow

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

Automated tests should be part of every implementation — when you run /aitask-pick, the implementation step naturally includes writing tests alongside the feature code. But real-world constraints mean test coverage gaps are common:

LLM context limits may prevent full test coverage during implementation, especially for complex tasks that consume most of the available context with source code and plan content
Test requirements discovered later — edge cases, integration scenarios, and failure modes often become apparent only after the feature is used or reviewed
Incremental test strategy — some teams prefer a quick implementation pass followed by a dedicated test-hardening round

/aitask-qa exists to systematically identify and fill these gaps. It analyzes what was built, discovers existing tests, runs them, identifies coverage holes, and proposes a test plan — optionally creating a follow-up task to implement the missing tests.

Manual Verification Workflow

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

Some behavior cannot be covered by automated tests: TUI flows, tmux-driven agents, multi-screen navigation, on-disk artifact inspection, live LLM calls. /aitask-qa handles everything that is script-testable; manual verification covers the rest as first-class tasks with their own checklist, lock, and archival gate.

A task with issue_type: manual_verification is a human-checklist runner. When /aitask-pick picks one, Step 3 Check 3 routes it into a dedicated Pass/Fail/Skip/Defer loop instead of the normal plan-and-implement flow. Failing items auto-generate pre-populated bug tasks; deferred items block archival or spawn carry-over tasks for later.

Understanding Code with Explain

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

When AI agents accelerate development, teams can ship features faster than they can understand them. Code that works perfectly may still be opaque — nobody knows why it exists, which task motivated it, or how its design evolved. This gap between code velocity and code comprehension is what Margaret Storey calls cognitive debt: “the debt compounded from going fast lives in the brains of the developers.” The /aitask-explain skill addresses this by tracing code back through the aitask and aiplan records that document every change’s purpose.