Advanced on aitasks

Build, Test, and Lint Configuration

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

After implementation, the skill can optionally run a build verification command to catch regressions introduced by the task’s changes. This is configured via aitasks/metadata/project_config.yaml and applies to all three implementation skills: /aitask-pick, /aitask-pickrem, and /aitask-pickweb.

Configuration

# Single command
verify_build: "cargo build"

# Multiple commands (run sequentially, stop on first failure)
verify_build:
 - "npm install"
 - "npm run build"
 - "npm test"

If verify_build is not set (or the file doesn’t exist), the step is skipped entirely.

Contribution Flow

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

When a contribution issue arrives on your repository (created by /aitask-contribute or manually), the aitasks framework provides two layers of analysis before import: an automated CI/CD overlap check and an AI-powered review skill. Together they help maintainers detect duplicates, find related contributions, and make informed import decisions.

Fingerprint Metadata

Each contribution issue created by /aitask-contribute includes a hidden metadata block:

<!-- aitask-contribute-metadata
contributor: username
contributor_email: user@example.com
based_on_version: v1.2.3
fingerprint_version: 1
areas: scripts,claude-skills
file_paths: .aitask-scripts/foo.sh,.aitask-scripts/bar.sh
file_dirs: .aitask-scripts
change_type: enhancement
auto_labels: area:scripts,scope:enhancement
-->

Fields:

Task File Format

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

File Structure

Tasks are markdown files with YAML frontmatter in the aitasks/ directory. Task files use the naming convention t<number>_<name>.md. Executed task files are stored in aitasks/archived/ and their associated plan files in aiplans/archived/.

---
priority: high
effort: medium
depends: []
issue_type: feature  # See aitasks/metadata/task_types.txt for valid types
status: Ready
labels: [ui, backend]
created_at: 2026-01-15 10:00
updated_at: 2026-01-15 10:00
---

## Task description here

Detailed description of what needs to be done.

Frontmatter Fields

Field	Values	Description
`priority`	`high`, `medium`, `low`	Task priority for sorting
`effort`	`low`, `medium`, `high`	Estimated implementation effort
`depends`	`[1, 4]`	List of task numbers this depends on
`issue_type`	`bug`, `chore`, `documentation`, `feature`, `performance`, `refactor`, `style`, `test`	Type of work (from `task_types.txt`)
`status`	`Ready`, `Editing`, `Implementing`, `Postponed`, `Done`, `Folded`	Current status
`labels`	`[ui, backend]`	Categorization labels
`created_at`	`YYYY-MM-DD HH:MM`	Creation timestamp
`updated_at`	`YYYY-MM-DD HH:MM`	Last modification timestamp
`completed_at`	`YYYY-MM-DD HH:MM`	Completion timestamp (set on archival)
`assigned_to`	email address	Developer working on the task
`issue`	URL	Linked GitHub/GitLab/Bitbucket issue
`children_to_implement`	`[t10_1, t10_2]`	Remaining child tasks (parent tasks only)
`boardcol`	column ID	Board UI column placement
`boardidx`	integer	Board UI sort index within column
`folded_tasks`	`[138, 129_5]`	Task IDs folded into this task by `/aitask-explore` or `/aitask-fold` (deleted on archival)
`folded_into`	task number	Task this was folded into (set by `/aitask-fold` or `/aitask-explore`)
`file_references`	`[path, path:N, path:N-M, path:N-M^N-M]`	Structured pointers to source files / line ranges. 1-indexed, inclusive. Exact-string dedup. See Creating Tasks from Code
`verifies`	`[t10_1, t10_2]`	Task IDs this task verifies (used by `manual_verification` sibling tasks that gate release on human-checked behavior)
`implemented_with`	`<agent>/<model>`	Agent and model that implemented the task (e.g., `claudecode/opus4_7_1m`). See Agent attribution
`pull_request`	URL	Linked pull request URL (mirrors `issue`)
`contributor`	name	External contributor credited on the commit (used by PR-import flow)
`contributor_email`	email	Email for the contributor’s `Co-Authored-By` trailer

Status Workflow

Ready → Editing → Implementing → Done → Archived
 ↘ Folded (merged into another task)

Ready — Task is defined and available for implementation
Editing — Task is being refined (description, requirements)
Implementing — Active development in progress (assigned to someone)
Postponed — Deferred for later
Folded — Task was merged into another task via /aitask-fold or /aitask-explore; deleted on archival of the primary task
Done — Implementation complete, pending archival
Archived — Task and plan files moved to archived/ directories

Parent-Child Hierarchies

Tasks support parent-child hierarchies for breaking complex work into subtasks:

/aitask-web-merge

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

Runs locally after /aitask-pickweb completes on Claude Code Web. It detects remote branches with completed task executions, merges code to main (excluding .aitask-data-updated/), copies the plan to aitask-data, archives the task, and cleans up.

Usage:

/aitask-web-merge

No arguments needed — the skill scans all remote branches automatically.

Note: Must be run from the project root directory on your local machine (not on Claude Code Web). See Skills overview for details.

Step-by-Step

The skill follows a scan → select → merge → archive → push → cleanup flow:

Execution Profiles

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

Execution profiles let /aitask-pick and related skills pre-answer workflow questions so you can move from task selection to implementation with fewer prompts.

Profiles are YAML files stored in aitasks/metadata/profiles/. They are loaded at the start of /aitask-pick and can also be reused by related skills that share the task workflow.

Shipped Profiles

default – All questions asked normally (empty profile, serves as a template)
fast – Skip confirmations, use userconfig email, stay on the current branch, pause for confirmation after plan approval, and keep feedback questions enabled

Standard Profile Fields

Key	Type	Description
`name`	string (required)	Display name shown during profile selection
`description`	string (required)	Description shown below the profile name
`skip_task_confirmation`	bool	`true` auto-confirms direct task selection
`default_email`	string	`"userconfig"`, `"first"`, or a literal email address
`create_worktree`	bool	`true` creates a separate worktree; `false` uses the current branch
`base_branch`	string	Branch name used when creating a worktree
`plan_preference`	string	`"use_current"`, `"verify"`, or `"create_new"`
`plan_preference_child`	string	Same values as `plan_preference`, but only for child tasks
`plan_verification_required`	int	Minimum fresh `plan_verified` entries required to skip verification when `plan_preference` is `"verify"` (default `1`)
`plan_verification_stale_after_hours`	int	Hours after which a `plan_verified` entry is considered stale (default `24`)
`post_plan_action`	string	`"start_implementation"` skips the post-plan checkpoint
`post_plan_action_for_child`	string	Same values as `post_plan_action`, but only for child tasks
`enableFeedbackQuestions`	bool	`false` disables satisfaction feedback prompts; `true` or omitted keeps them enabled. See Verified Scores
`explore_auto_continue`	bool	Used by `/aitask-explore` to continue automatically after exploration
`qa_mode`	string	`"ask"`, `"create_task"`, `"implement"`, or `"plan_only"` — used by `/aitask-qa` to control what happens with test proposals
`qa_run_tests`	bool	`true` runs discovered tests, `false` skips test execution — used by `/aitask-qa`
`qa_tier`	string	`"quick"`, `"standard"`, or `"exhaustive"` — pre-selects the QA analysis depth tier
`manual_verification_followup_mode`	string	`"ask"` (default) or `"never"` — used by task-workflow Step 8c to control whether the post-implementation manual-verification follow-up prompt fires

Omitting a key means that question is asked interactively. enableFeedbackQuestions is enabled by default when the key is absent.

Commit Attribution

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

When a task implementation is committed, the workflow can attach two kinds of attribution:

an imported contributor trailer when the task carries contributor and contributor_email metadata
a code-agent trailer for the agent recorded in implemented_with

This applies to the shared Step 8 commit flow used by /aitask-pick and other skills that route through the shared task workflow. The same composition rules are also used by direct-commit variants such as /aitask-pickrem, /aitask-pickweb, and /aitask-wrap.

Feature Reference

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

Keyboard Shortcuts

Key	Action	Context
`q`	Quit the application	Global
`Tab`	Toggle focus between search box and board	Global
`Escape`	Return to board from search / dismiss modal	Global
`Up`	Navigate to previous task in column	Board
`Down`	Navigate to next task in column	Board
`Left`	Navigate to previous column	Board
`Right`	Navigate to next column	Board
`Enter`	Open task detail dialog	Board (focused card)
`r`	Refresh board from disk	Board
`s`	Sync task data with remote	Board
`O`	Open board options/settings dialog	Board
`a`	Switch to All view (show all tasks)	Board
`g`	Switch to Git view (show git-linked tasks)	Board
`i`	Switch to Implementing view (show implementing tasks + context)	Board

Task Operations

Key	Action	Context
`Shift+Right`	Move task to next column (skips collapsed)	Board (parent cards only)
`Shift+Left`	Move task to previous column (skips collapsed)	Board (parent cards only)
`Shift+Up`	Swap task with one above	Board (parent cards only)
`Shift+Down`	Swap task with one below	Board (parent cards only)
`Ctrl+Up`	Move task to top of column	Board (parent cards only)
`Ctrl+Down`	Move task to bottom of column	Board (parent cards only)
`n`	Create a new task	Board
`x`	Toggle expand/collapse child tasks	Board (parent or child card)
`c`	Commit focused modified task	Board (shown when task is modified)
`C`	Commit all modified tasks	Board (shown when any task is modified)
`p`	Pick the focused task (start implementation)	Board (context-dependent — shown when task is pickable)
`b`	Launch brainstorm for the focused task	Board (context-dependent — shown when task is brainstormable)

Column Operations

Key	Action	Context
`Ctrl+Right`	Move column one position right	Board
`Ctrl+Left`	Move column one position left	Board
`X` (Shift+X)	Toggle collapse/expand for focused card’s column	Board (focused card)
`Ctrl+Backslash`	Open command palette	Global
Click `▼` / `▶`	Toggle column collapse/expand	Column header
Click `✎`	Open column edit dialog	Column header

Key	Action	Context
`Up`	Focus previous field	Inside modal dialogs
`Down`	Focus next field	Inside modal dialogs
`Left`	Cycle to previous option	On CycleField
`Right`	Cycle to next option	On CycleField
`Enter`	Activate focused button / navigate to linked task	Inside modal dialogs
`Escape`	Close the dialog	Inside modal dialogs

Task Card Anatomy

┌─────────────────────────────────┐ ← Border color = priority
│ t47 * playlists support │ ← 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
│ 🔗 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.

Feature Reference

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

Keyboard Shortcuts

Application

Key	Action	Context
`q`	Quit the application	Global
`Tab`	Cycle focus between file tree, code viewer, and detail pane	Global
`r`	Refresh explain annotations for current file’s directory	Global
`t`	Toggle annotation gutter visibility	Global
`g`	Open go-to-line dialog	Global
`e`	Launch the configured code agent for explain on the current file	Global
`d`	Toggle detail pane visibility	Global
`D`	Toggle detail pane between default and expanded width	Global
`h`	Toggle completed tasks history view	Global
`H`	Open history screen navigated to the task at cursor	Global (requires annotated line)

History Screen

Key	Action	Context
`h` / `Escape`	Return to code browser	History screen
`v`	Toggle task/plan content view	History screen
`l`	Open label filter dialog	History screen
`Tab`	Cycle focus between list and detail panes	History screen
`Left`	Move focus to list pane (cycles task list / recently opened)	History screen
`Right`	Move focus to detail pane	History screen
`Up` / `Down`	Navigate between focusable fields	History detail
`Enter`	Open link, select task, or navigate to file (context-dependent)	History detail
`s`	Open sibling task picker (on child tasks)	History detail
`a`	Launch QA agent for the selected task	History detail

Label Filter Dialog

Key	Action	Context
`Escape`	Cancel and close dialog	Dialog
`o`	Confirm selection (OK)	Dialog
`r`	Reset filter (show all)	Dialog

Sibling Picker Dialog

Key	Action	Context
`Escape`	Cancel and close dialog	Dialog
`Enter`	Select sibling task	Dialog

Code Viewer

Key	Action	Context
`Up`	Move cursor up one line	Code viewer
`Down`	Move cursor down one line	Code viewer
`Shift+Up`	Extend selection upward	Code viewer
`Shift+Down`	Extend selection downward	Code viewer
`Escape`	Clear selection	Code viewer
`n`	Create a task with `file_references` seeded from the selection or cursor line	Code viewer
`PageUp`	Move cursor up by one screen	Code viewer
`PageDown`	Move cursor down by one screen	Code viewer

Go-to-Line Dialog

Key	Action	Context
`Enter`	Jump to entered line number	Dialog
`Escape`	Cancel and close dialog	Dialog

Mouse Interactions

Action	Effect
Click on file tree entry	Select and open file
Click in code viewer	Position cursor at clicked line
Drag in code viewer	Select line range
Scroll wheel in code viewer	Scroll content

Annotation Data Pipeline

The codebrowser uses the same explain data pipeline as /aitask-explain:

Feature Reference

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

Keyboard Shortcuts

Key	Action	Context
`Tab`	Cycle focus to the next zone (pane list ↔ preview)	Global
`Shift+Tab`	Cycle focus to the previous zone	Global
`Up`	Focus the previous card in the pane list	Pane list zone
`Down`	Focus the next card in the pane list	Pane list zone
`q`	Quit monitor	Global

Pane Interaction

Key	Action	Context
`Enter`	Send an `Enter` keystroke to the focused tmux pane	Pane list zone
`Enter`	Send an `Enter` keystroke to the focused tmux pane	Preview zone
Any other key	Forwarded to the focused tmux pane (characters, Ctrl-combos, arrows, Escape)	Preview zone
`s`	Switch tmux focus to the focused pane (`tmux switch-client`)	Pane list zone
`i`	Show the task detail dialog for the focused agent pane (requires a task ID in the window name)	Pane list zone
`k`	Kill the focused pane after confirmation (`tmux kill-pane`)	Pane list zone
`n`	Pick the next ready sibling task for the focused agent pane	Pane list zone
`R`	Restart the task running in the focused agent pane	Pane list zone
`L`	Open the log for the focused pane in a separate viewer	Pane list zone

Monitor Controls

Key	Action	Context
`j`	Open the TUI switcher overlay	Global
`r`	Refresh the pane list and preview immediately	Global
`F5`	Refresh the pane list and preview immediately (alias for `r`, hidden in footer)	Global
`z`	Cycle the preview size through S / M / L presets	Global
`b`	Toggle the preview scrollbar visibility	Global
`t`	Scroll the preview to its tail (newest output)	Global
`a`	Toggle auto-switch mode (automatically focus idle agents needing attention)	Global
`M`	Toggle the multi-session view ON/OFF (see Multi-session view)	Global

Note: In the preview zone, every keystroke that is not handled by a global binding is forwarded to the tmux pane via tmux send-keys. Special keys (Enter, Escape, Backspace, arrows, Space, Delete, Home, End, PageUp/Down) and Ctrl-combinations are translated; regular characters are sent literally.

Review Guide Format

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

File Structure

Review guides are markdown files with YAML frontmatter in aireviewguides/, organized by environment subdirectory. Each guide contains metadata that powers auto-detection and similarity matching, plus actionable review instructions that /aitask-review applies during code review.

---
name: Python Best Practices
description: Check type hints, modern idioms, context managers, and pythonic patterns
reviewtype: conventions
reviewlabels: [type-hints, idioms, context-managers, pythonic]
environment: [python]
source_url: https://example.com/python-guide
similar_to: general/code_conventions.md
---

## Review Instructions

### Type Hints
- Flag public functions missing type annotations on parameters and return types
- Look for use of `Any` where a more specific type is known

Frontmatter Fields

Field	Required	Values	Description
`name`	Yes	string	Guide display name shown during selection
`description`	Yes	string	Brief description of what the guide reviews
`reviewtype`	Yes	string	Classification type from `reviewtypes.txt`
`reviewlabels`	Yes	`[label1, label2]`	Topic labels from `reviewlabels.txt` (3-6 recommended)
`environment`	No	`[env1, env2]`	Target environments from `reviewenvironments.txt`. Absent = universal guide
`source_url`	No	URL	Reference to the original source material
`similar_to`	No	relative path	Most similar guide, set by `/aitask-reviewguide-classify` when similarity score >= 5

The body must start with ## Review Instructions, followed by ### section headings each containing bullet-point checks. This structure is what /aitask-review reads and applies during code review.

/aitask-pr-import

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

Analyze pull requests from GitHub, GitLab, or Bitbucket using AI-powered code review, then create a well-structured aitask with contributor attribution. This skill bridges external contributions and the aitasks workflow — instead of merging PRs directly, it extracts the intent and approach, validates them against the codebase, and produces a task ready for implementation.

Usage:

/aitask-pr-import

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.

/aitask-contribute

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

Use /aitask-contribute to turn local changes into a structured contribution issue without going through the usual fork, branch, and pull request flow. You can use it to contribute improvements back to the aitasks framework, or to contribute changes to the current project repository when that project uses the aitasks framework.

Usage:

/aitask-contribute

Note: Must be run from the project root directory. Requires the platform CLI installed and authenticated: gh for GitHub (default), glab for GitLab, or bkt for Bitbucket. See Skills overview for details.

/aitask-contribution-review

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

Use /aitask-contribution-review to review incoming contribution issues with AI-powered duplicate detection, overlap analysis, and merge recommendations. The skill fetches the target issue, finds related contributions, analyzes code diffs, and helps you decide whether to merge, import individually, fold into existing tasks, or update an existing task directly.

Usage:

/aitask-contribution-review 42 # Review a specific issue
/aitask-contribution-review # List open contribution issues and choose

Note: Must be run from the project root directory. Requires the platform CLI installed and authenticated: gh for GitHub (default), glab for GitLab. The skill uses a helper script that encapsulates all platform-specific API calls. See Skills overview for details.

Issue Tracker Development Workflow

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

The framework fully supports issue-based development across GitHub, GitLab, and Bitbucket through the ait issue-import and ait issue-update commands, creating a seamless round-trip between your issue tracker and local task management. The source platform is auto-detected from your git remote URL.

The Full Cycle

Import — Run ait issue-import to fetch open issues and create task files. In interactive mode, you can browse issues with fzf, preview their content, and select which ones to import. Issue labels are mapped to aitask labels, and the issue type is auto-detected from labels (bug, chore, documentation, feature, performance, refactor, style, test). A link to the original issue is stored in the task’s issue metadata field

Reference

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

Keyboard Shortcuts

Global

Key	Action
a	Switch to Agent Defaults tab
b	Switch to Board tab
c	Switch to Project Config tab
t	Switch to Tmux tab
m	Switch to Models tab
p	Switch to Profiles tab
e	Export all configs
i	Import configs
r	Reload all configs from disk
q	Quit

Within Tabs

Key	Action	Context
Enter / Space	Edit field or cycle value	Agent Defaults, Board, Profiles
d / Delete	Remove user override	Agent Defaults
?	Toggle field description (summary/expanded)	Profiles
Escape	Close dialog or cancel	Modals

Tabs

Tab	Shortcut	Editable	Description
Agent Defaults	a	Yes	Default agent/model per operation, project and user layers
Board	b	Partially	Columns (read-only), user settings (editable)
Project Config	c	Yes	Shared values from `project_config.yaml` such as coauthor domain and build verification
Tmux	t	Yes	Tmux integration settings (session name, split direction, monitor options, git TUI)
Models	m	No	Available models per agent with verified scores
Profiles	p	Yes	Execution profiles that pre-answer workflow questions

Agent Defaults Operations

Operation	Description
`task-pick`	Model used for picking and implementing tasks
`explain`	Model used for explaining/documenting code
`batch-review`	Model used for batch code review operations
`raw`	Model used for direct/ad-hoc code agent invocations (passthrough mode)

Configuration Files

File	Scope	Editable via TUI	Description
`aitasks/metadata/codeagent_config.json`	Project	Yes (Agent Defaults)	Default agent/model per operation
`aitasks/metadata/codeagent_config.local.json`	User	Yes (Agent Defaults)	Per-user overrides (gitignored)
`aitasks/metadata/board_config.json`	Project	No	Board column definitions
`aitasks/metadata/board_config.local.json`	User	Yes (Board)	User board settings (gitignored)
`aitasks/metadata/project_config.yaml`	Project	Yes (Project Config)	Shared workflow settings such as coauthor domain and build verification
`aitasks/metadata/models_claudecode.json`	Project	No	Claude Code model definitions
`aitasks/metadata/models_geminicli.json`	Project	No	Gemini CLI model definitions
`aitasks/metadata/models_codex.json`	Project	No	Codex CLI model definitions
`aitasks/metadata/models_opencode.json`	Project	No	OpenCode model definitions
`aitasks/metadata/profiles/*.yaml`	Project	Yes (Profiles)	Execution profiles (git-tracked)
`aitasks/metadata/profiles/local/*.yaml`	User	Yes (Profiles)	User execution profiles (gitignored)

Profile Schema

Execution profiles are YAML files with the following keys. All keys are optional – omitted keys cause the corresponding question to be asked interactively.

/aitask-revert

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

Revert changes associated with completed tasks — fully or partially. This skill analyzes a task’s commits, identifies affected areas, and creates a self-contained revert task with all the information needed to undo the changes. Use it when a feature adds unnecessary complexity, an experiment didn’t pan out, or you want to selectively undo parts of a completed task.

Usage:

/aitask-revert # Interactive: discover task to revert
/aitask-revert 42 # Direct: revert task t42
/aitask-revert t42 # Also accepted with t prefix

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

PR Import Workflow

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

The framework supports creating tasks from external pull requests, providing a structured path for incorporating contributions that cannot be merged directly. Instead of accepting or rejecting a PR as-is, the workflow extracts the contributor’s intent and approach, validates it against project conventions, and produces a task that goes through the standard implementation cycle — with proper attribution back to the original contributor.

Motivation

Not every pull request can be merged directly. Common scenarios:

Git Remotes

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

Authentication with Your Git Remote

Authenticating with your git remote enables full aitasks functionality including task locking (prevents two agents from picking the same task), push/pull sync across machines, and issue integration (ait issue-import, ait issue-update).

GitHub

Authenticate the GitHub CLI:

gh auth login

Follow the prompts to authenticate via browser or token.

GitLab

Authenticate the GitLab CLI:

glab auth login

Follow the prompts to authenticate via browser or token. This also configures git credentials for pushing to GitLab remotes.

Issue Integration & Utilities

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

ait issue-import

Import GitHub/GitLab/Bitbucket issues as AI task files. Supports interactive selection with fzf or batch automation. The source platform is auto-detected from the git remote URL (github.com → GitHub, gitlab.com → GitLab, bitbucket.org → Bitbucket). Use --source to override.

Interactive mode (default — requires fzf and gh/glab CLI):

Import mode selection — Choose via fzf: “Specific issue number”, “Fetch open issues and choose”, “Issue number range”, “All open issues”
Issue selection — Depends on mode:
- Specific issue: enter issue number manually
- Fetch & choose: fetches all open issues via gh issue list (or glab issue list for GitLab), presents in fzf with multi-select (Tab to select multiple) and preview pane showing issue body/labels
- Range: enter start and end issue numbers
- All open: fetches all open issues with confirmation prompt showing count
Duplicate check — Searches active and archived tasks for matching issue URL. If found, warns and offers Skip/Import anyway
Issue preview — Shows title and first 30 lines of body (truncated warning if longer). Confirm Import/Skip via fzf
Task name — Auto-generated from issue title (lowercase, sanitized). Editable with free text entry
Labels — Two-phase: first review each issue label individually (keep/skip via fzf), then iterative add loop (select from existing labels in labels.txt, add new label, or done)
Priority — fzf selection: high, medium, low
Effort — fzf selection: low, medium, high
Issue type — Auto-detected from issue labels: bug → bug, refactor/tech-debt/cleanup → refactor, otherwise → feature
Create & commit — Creates task file via aitask_create.sh, then prompts Y/n to commit to git

Batch mode (for automation and scripting):

Parallel Development

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

The aitasks framework supports multiple developers (or multiple AI agent instances) working on different tasks simultaneously.

How Concurrency Is Managed

Status tracking via git: When /aitask-pick starts work on a task, it sets the status to “Implementing”, records the developer’s email in assigned_to, and commits + pushes the change. This makes the assignment visible to anyone who pulls the latest state
Atomic task locking: The atomic lock system prevents two PCs from picking the same task simultaneously. Locks are stored on a separate aitask-locks git branch using compare-and-swap semantics
Atomic ID counter: The atomic ID counter on the aitask-ids branch ensures globally unique task numbers even when multiple PCs create tasks against the same repo
Task data branch (optional): When enabled, task/plan files live on a separate aitask-data branch accessed via a worktree at .aitask-data/. This keeps task management commits off the main branch and allows independent sync via ./ait git push/./ait git pull

Git Worktrees for Isolation

When working on multiple tasks in parallel, use the git worktree option in /aitask-pick. This creates an isolated working directory at aiwork/<task_name>/ on a separate branch, so each task’s changes don’t interfere with each other. After implementation, the branch is merged back to main and the worktree is cleaned up.

PR Import

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

ait pr-import

Import GitHub/GitLab/Bitbucket pull requests as AI task files, or extract structured PR data for use with the /aitask-pr-import skill. Supports interactive selection with fzf or batch automation. The source platform is auto-detected from the git remote URL (github.com → GitHub, gitlab.com → GitLab, bitbucket.org → Bitbucket). Use --source to override.

Interactive mode (default — requires fzf and gh/glab/bkt CLI):

Import mode selection — Choose via fzf: “Specific PR number”, “Fetch open PRs and choose”, “PR number range”, “All open PRs”
PR selection — Depends on mode:
- Specific PR: enter PR number manually
- Fetch & choose: fetches all open PRs via gh pr list (or glab mr list for GitLab, bkt pr list for Bitbucket), presents in fzf with multi-select (Tab to select multiple) and preview pane showing PR details
- Range: enter start and end PR numbers
- All open: fetches all open PRs
PR preview — Shows title, author, branch info, and first 30 lines of description (truncated warning if longer). Choose: “Import as task (basic)”, “Extract PR data only (for /aitask-pr-import skill)”, or “Skip”
Task metadata — Edit task name (auto-generated from PR title), review/keep/add labels, select priority/effort. Issue type is auto-detected from PR labels
Create & commit — Creates task file via ait create, then prompts to commit to git

Batch mode (for automation and scripting):

Parallel Task Planning

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

When you know a feature is complex enough to need child task decomposition, you can run just the planning and decomposition phase — without writing any code. This produces a full set of child tasks with ready-to-use implementation plans, and it can safely happen in parallel with any other ongoing work.

Why This Is Safe

This workflow is pure design work. No source code is modified — only task definitions and implementation plans are created. That means there’s no risk of conflicts with whatever implementation is happening in other terminals or on other machines.

Claude Code Web

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

Claude Code Web is a browser-based Claude Code environment that operates with restricted git permissions — it can only push to its own implementation branch. It cannot access aitask-locks, aitask-data, or main branches directly. This guide covers the end-to-end workflow for running aitasks on Claude Code Web.

Standard vs Claude Web Workflow

Step	Standard (local)	Claude Code Web
1. Lock task	Automatic (during `/aitask-pick`)	Manual pre-lock from local machine
2. Implement	`/aitask-pick` — full branch access	`/aitask-pickweb` — current branch only
3. Archive	Automatic (during `/aitask-pick`)	`/aitask-web-merge` — run locally after

Standard workflow handles everything in one session: lock → implement → commit → archive → push.

/aitask-refresh-code-models

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

Research the latest AI code agent models via web search and update the models_*.json configuration files used by ait codeagent.

Usage:

/aitask-refresh-code-models

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

Step-by-Step

The skill follows an 8-step workflow:

Read current configs — Loads all aitasks/metadata/models_*.json files and codeagent_config.json to identify current models and which are in use
Select agents — Choose which agents to refresh (Claude, Gemini, Codex, OpenCode, or all)
Research latest models — Uses WebSearch and WebFetch against canonical documentation URLs to discover current model offerings
Compare — Categorizes each model as NEW, UPDATED, DEPRECATED?, or UNCHANGED by comparing web research against current config
Present changes — Displays a structured change report marking models that are in use
Update JSON files — Applies approved changes to models_*.json files. Syncs to seed/ if present
Verify research URLs — Checks that the documentation URLs used for research are still reachable (informational only)
Commit — Commits updated model files via ./ait git

Key Behaviors

Never auto-removes models — Deprecated models are flagged but only removed with explicit user approval
Preserves verification scores — Existing verified scores are never overwritten; new models start at zero
Seed sync — If the seed/ directory exists, updated model files are copied there automatically
Graceful degradation — If web research fails for a specific agent, the skill continues with remaining agents

Model Naming Convention

Model name fields follow strict rules: lowercase only, underscores replace dots/hyphens, version numbers concatenated (e.g., Opus 4.6 → opus4_6, Gemini 2.5 Pro → gemini2_5pro).

/aitask-add-model

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

Register a single, already-known code-agent model in the framework’s model registry and optionally promote it to default across codeagent_config.json, the seed/ template, and the hardcoded DEFAULT_AGENT_STRING. Companion to /aitask-refresh-code-models.

Usage:

/aitask-add-model
/aitask-add-model --agent claudecode --name opus4_7_1m --cli-id 'claude-opus-4-7[1m]' --notes "1M context" --promote --promote-ops pick,explore,brainstorm-explorer
/aitask-add-model --dry-run ...

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

When to Use This Skill

Use /aitask-add-model when you already know the model you want to register — a vendor just announced it, or you’ve decided to promote a specific variant to default. Unlike /aitask-refresh-code-models, this skill skips web research and writes deterministic, per-invocation changes.

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.

/aitask-reviewguide-classify

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

Classify a review guide file by assigning metadata and finding similar existing guides. This skill builds the metadata foundation that makes /aitask-review auto-detection work effectively.

Usage:

/aitask-reviewguide-classify security # Classify a specific guide (fuzzy match)
/aitask-reviewguide-classify # Batch: find and classify all incomplete guides

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

Step-by-Step

Single-file mode (with argument):

Resolve file — Fuzzy-matches the argument against markdown files in aireviewguides/. If multiple matches, prompts for selection
Analyze content — Reads the guide’s headings, bullets, and topics to determine what it reviews
Assign metadata — Proposes values for reviewtype (single classification from vocabulary), reviewlabels (3-6 topic tags), environment (language/framework, or universal for general/ guides), and similar_to (guides with overlapping coverage)
Confirm and apply — Shows proposed metadata for review. Options: apply as proposed, modify, or cancel. On apply, updates the frontmatter and commits

Batch mode (no argument):

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.

Releases Workflow

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

Documenting what changed in a new release is one of the most tedious tasks in software development. The aitasks framework solves this by turning your regular development work into the raw material for release notes. Every commit message carries a task ID (tNN), and every completed task has an archived plan file with “Final Implementation Notes.” The /aitask-changelog skill harvests this data and uses AI to generate user-facing release notes automatically.

/aitask-reviewguide-merge

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

Compare two similar review guide files and decide whether to merge them, deduplicate shared content, or keep them separate. This skill keeps the review guide library clean and free of redundant checks.

Usage:

/aitask-reviewguide-merge security perf # Compare two specific guides (fuzzy match)
/aitask-reviewguide-merge security # Compare a guide with its similar_to target
/aitask-reviewguide-merge # Batch: find and process all similar pairs

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

Revert Changes with AI

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

AI-assisted development makes it easy to add features quickly — but not every feature survives contact with real usage. Some experiments don’t pan out, some features add more complexity than value, and sometimes you want to undo part of a large change while keeping the rest. The /aitask-revert skill handles all of this at a higher level than raw git revert, creating structured revert tasks with full traceability.

When to Use

Feature bloat — A completed feature adds unnecessary complexity and you want to remove it cleanly
Failed experiments — A prototype or experimental feature didn’t work out and should be rolled back
Partial cleanup — A large task introduced changes across multiple areas, but only some need to be undone
Post-prototyping — After rapid prototyping, you want to remove scaffolding or temporary code while keeping the core implementation
Dependency simplification — A feature introduced dependencies or patterns that turned out to be overkill

How It Works

The revert workflow follows five stages:

/aitask-reviewguide-import

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

Import external content — a local file, a URL, or a GitHub repository directory — and transform it into a structured review guide with proper metadata. This skill converts coding standards, best practices documents, and style guides into actionable review checklists.

Usage:

/aitask-reviewguide-import ./standards.md # Import a local file
/aitask-reviewguide-import https://example.com/guidelines # Import from a URL
/aitask-reviewguide-import https://github.com/org/repo/blob/main/docs/style.md # GitHub file
/aitask-reviewguide-import https://github.com/org/repo/tree/main/docs/guides/ # GitHub directory (batch)

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

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.

Verified Scores

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

Verified scores track how well each LLM model performs for each skill operation. After a skill completes, users rate the result on a 1–5 scale; these ratings accumulate into per-model, per-operation scores that help choose the best model for a given task.

How Scores Are Collected

At the end of each skill run, the workflow prompts:

How well did this skill work? (Rate 1–5, helps improve model selection)

The raw rating maps to a 20–100 internal scale (1 → 20, 2 → 40, 3 → 60, 4 → 80, 5 → 100). Each rating updates the running average for the current model and operation.

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.

Advanced on aitasks

Build, Test, and Lint Configuration

Configuration

Contribution Flow

Fingerprint Metadata

Task File Format

File Structure

Frontmatter Fields

Status Workflow

Parent-Child Hierarchies

/aitask-web-merge

Step-by-Step

Execution Profiles

Shipped Profiles

Standard Profile Fields

Commit Attribution

Feature Reference

Keyboard Shortcuts

Board Navigation

Task Operations

Column Operations

Modal Navigation

Task Card Anatomy

Feature Reference

Keyboard Shortcuts

Application

History Screen

Label Filter Dialog

Sibling Picker Dialog

Code Viewer

Go-to-Line Dialog

Mouse Interactions

Annotation Data Pipeline

Feature Reference

Keyboard Shortcuts

Zone Navigation

Pane Interaction

Monitor Controls

Review Guide Format

File Structure

Frontmatter Fields

/aitask-pr-import

/aitask-contribute

/aitask-contribution-review

Issue Tracker Development Workflow

The Full Cycle

Reference

Keyboard Shortcuts

Global

Within Tabs

Tabs

Agent Defaults Operations

Configuration Files

Profile Schema

/aitask-revert

PR Import Workflow

Motivation

Git Remotes

Authentication with Your Git Remote

GitHub

GitLab

Issue Integration & Utilities

ait issue-import

Parallel Development

How Concurrency Is Managed

Git Worktrees for Isolation

PR Import

ait pr-import

Parallel Task Planning

Why This Is Safe

Claude Code Web

Standard vs Claude Web Workflow

/aitask-refresh-code-models

Step-by-Step

Key Behaviors

Model Naming Convention

/aitask-add-model

When to Use This Skill

Verified scores

What it is