Main-Concept on aitasks

Overview

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

The Challenge

AI coding agents have reached a proficiency level where, given correct specs and intent, they can handle most code-development tasks on their own. The real bottleneck is transferring intent from developer to agent — structured enough to build useful context, fast enough that the human does not become the drag. aitasks is a full agentic IDE in your terminal built around this transfer: tasks are living markdown files, refined iteratively alongside the code that implements them.

/aitask-pick

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

The central skill of the aitasks framework. This is a full development lifecycle skill that manages the complete task lifecycle from selection through implementation, review, and archival.

Usage:

/aitask-pick # Interactive task selection from prioritized list
/aitask-pick 10 # Directly select parent task t10
/aitask-pick 10_2 # Directly select child task t10_2

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

Codex CLI note: 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.

Kanban Board

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

The ait board command launches an interactive terminal-based kanban board for managing your tasks visually. Built with Textual, it provides a full-featured TUI with columns, task cards, inline metadata editing, git integration, and keyboard-driven navigation.

The ait board kanban view with task cards organized into columns

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.

Getting Started

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

This guide walks you through aitasks from installation to completing your first task with Claude Code, Gemini CLI, OpenCode, or Codex CLI.

1. Install aitasks

macOS: Homebrew must be installed before running ait setup.

In your project directory (the root of the git repository, where .git/ lives):

curl -fsSL https://raw.githubusercontent.com/beyondeye/aitasks/main/install.sh | bash

Run from the project root. aitasks expects to be invoked from the directory containing .git/ — the root of your project’s git repository. aitasks is tightly integrated with git — it uses git branches for task IDs, locking, and syncing, and task and plan files are committed to your repository. Always run the installer and ait setup from there.

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.

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.