Taskrail

Turn goals into tracked work, kept aligned to one authoritative state file.

Taskrail is a deterministic execution harness for humans and AI agents. It turns goals into structured tasks, keeps every transition aligned to a single authoritative state file, and advances work through validation, verification, and explicit follow-up.

It is built on durable primitives — Git for history and review, plain Markdown with YAML frontmatter for specs, tasks, and state. No database. No hidden automation. No opaque dashboards. Your repo stays inspectable, and the same taskrail commands work whether a person or an agent is at the keyboard.

taskrail init          # adopt Taskrail in an existing repo, non-destructively
taskrail validate      # confirm the layout and state are consistent
taskrail status        # see the active spec, task counts, and what's next

From there, the daily loop is next → start → complete → verify (see Commands).

Contents

• Why Taskrail
• What It Is Not
• Install
• Commands
• Quickstart
• What a Verification Leaves Behind
• State Contract
• Repository Layout
• Development
• Status
• License
• Read Next

Why Taskrail

• Deterministic: the workflow is validate → next → start → complete → verify, and next-task selection follows status, dependencies, priority, and stable tie-breaking — same repo, same answer, every time.
• State-first: one authoritative planning/STATE.md is the continuity and control surface for all work.
• Repo-native: work is tracked as Markdown task files with an explicit, machine-checkable schema — specs under specs/, tracked work under planning/. No database, no hidden automation.
• Verification is first-class: completing implementation and verifying it are distinct steps; verification records pass/fail outcomes, writes inspectable artifacts, and opens follow-up tasks as needed.
• Retrofit-friendly: taskrail init (or retrofit) drops the contract into an existing repository with no rewrite.
• Agent-ready: every command has a --json path where it matters, so coding agents drive the same workflow humans do.

What It Is Not

• Not a built-in LLM provider integration — Taskrail is provider-agnostic and manual-first. (import structures notes; it never calls a model.)
• Not a sandbox, container, or worktree orchestrator.
• Not a background daemon, distributed worker pool, or multi-lane scheduler.
• Not a semantic spec-to-task generator or drift detector — import produces structural drafts only; LLM-assisted generation is deferred.

Install

Homebrew (macOS and Linux):

brew install tessariq/tap/taskrail
taskrail --version

This pulls the release binary from the tessariq/homebrew-tap tap.

Windows (WinGet):

winget install Tessariq.Taskrail
taskrail --version

Build from source (needs Go 1.26):

git clone https://github.com/tessariq/taskrail.git
cd taskrail
go install ./cmd/taskrail
taskrail version

Plain go build/go install produce a development build that reports version 0.0.0-dev. To produce a release build that reports a real version, inject it at build time:

go build -ldflags "-X main.version=v0.3.0" -o taskrail ./cmd/taskrail
# or, via Taskfile:
VERSION=v0.3.0 task release
./taskrail version   # -> v0.3.0

Tagged v* releases are built and published automatically with GoReleaser — Linux/macOS/Windows binaries for amd64/arm64, with archives, checksums, and notes from CHANGELOG.md. See docs/workflow/releasing.md for the release checklist.

Commands

The core loop is five commands — the ones you run every day:

taskrail validate                                    # check the repo is consistent
taskrail next --json                                 # pick the next eligible task, deterministically
taskrail start T-001                                 # mark it active
taskrail complete T-001 --note "implemented"         # mark implementation done
taskrail verify T-001 --result pass --summary "acceptance met"

Every command takes --json where it matters, so agents drive the same loop.

Beyond the core loop

• Adopt an existing repo — init and retrofit scaffold specs/ + planning/ non-destructively; import turns rough notes into spec/task drafts without an LLM; repair reconciles mechanical STATE.md drift.
• See where work stands — status, stats, and coverage report a live snapshot, aggregate metrics, and advisory spec-linkage, all read-only.
• Author and steer specs — the spec family (list, show, add, activate) inspects and evolves versioned specs.
• Handle the messy parts — block/unblock park and resume work, and task new scaffolds a task with the next free id.

Run taskrail --help, or taskrail <command> --help, for the full command list and every flag.

Shell completion

Taskrail ships shell completion via Cobra. Load it for your shell (or add the line to your shell profile):

source <(taskrail completion bash)   # bash
taskrail completion zsh > "${fpath[1]}/_taskrail"   # zsh
taskrail completion fish | source   # fish

Run taskrail completion --help for per-shell install steps. Completion is read-only: it never writes STATE.md or task files. Beyond every command and flag, it completes spec versions for spec show/spec activate and real <path>#<anchor> values for task new --spec-ref (the anchors it offers are exactly the ones validate accepts, so a completed reference authors a task that passes validate).

Quickstart

Initialize Taskrail inside an existing repository, then confirm it is sane:

taskrail init
taskrail validate

Tasks live under planning/tasks/ as Markdown with YAML frontmatter:

---
id: T-001
title: Bootstrap repository structure
status: pending
priority: high
spec_ref: specs/v0.1.0.md#summary
dependencies: []
---

# T-001 Bootstrap repository structure

## Description

Create the initial Taskrail structure, specs, and planning area.

## Acceptance

- `planning/STATE.md` exists.
- `taskrail validate` passes.

Let Taskrail pick the next eligible task, start it, and advance it:

taskrail next --json
taskrail start T-001
taskrail complete T-001 --note "implementation landed"
taskrail verify T-001 --result pass --summary "validate passes; acceptance met"

When verification reveals more work, spawn a follow-up task in the same step:

taskrail verify T-001 \
  --result fail \
  --summary "missing dependency check" \
  --create-followup \
  --followup-title "Add dependency validation" \
  --followup-priority high

Bootstrap drafts from rough notes without any LLM — preview first, then apply:

taskrail import notes.md --to tasks                # preview the structural task drafts
taskrail import notes.md --to tasks --emit-prompt  # print an agent prompt for a richer draft
taskrail import --apply draft.json                 # validate an agent draft and write real files

Typical flow:

1. Write a goal as a Markdown task inside planning/tasks/.
2. validate the repository.
3. next to select deterministically, then start.
4. complete the implementation.
5. verify to record the outcome and leave artifacts — opening follow-up tasks as needed.

What a Verification Leaves Behind

Every verification writes repo-local evidence under planning/artifacts/verify/<task-id>/<timestamp>/:

planning/
  STATE.md                         # single authoritative state surface
  tasks/
    T-001.md                       # task with frontmatter schema
  artifacts/
    verify/
      T-001/
        20260619T113646Z/
          plan.md                  # verification plan
          report.json              # machine-readable outcome
          report.md                # human-readable outcome

These are plain files — no proprietary formats, no database required. The planning/artifacts/ tree is gitignored, reproducible local output: verify creates it on demand, taskrail init never pre-creates it, and neither committed state nor validate depends on it surviving a Git round-trip.

State Contract

planning/STATE.md is the authoritative execution state. It carries the active spec, current task, status summary, blockers, the next action, and the last verification result, plus pointers to relevant artifacts. Do not hand-edit machine-managed state fields — let the taskrail transitions update them.

Repository Layout

.
├── AGENTS.md          # guidance for coding agents
├── CHANGELOG.md
├── README.md
├── cmd/taskrail/      # CLI entry point
├── internal/          # core packages
├── lefthook.yml       # opt-in local git hooks (mirror CI)
├── mise.toml          # optional pinned developer toolchain (mise)
├── planning/          # authoritative tracked work and STATE.md
├── scripts/
└── specs/             # versioned, normative product specs

The packaged skill set lives in internal/taskrail/skills/ (embedded; installed by taskrail init --with-skills). This repository adopts it: committed copies in .agents/skills/ and .claude/skills/ are kept byte-identical to the package by task check:skills.

Development

mise can pin and provision the developer toolchain (Go, task, lefthook) from the committed mise.toml. It is optional convenience — direct go commands and the Taskfile.yml targets work without it:

mise install     # provision the pinned toolchain on a fresh clone
mise run setup   # provision, build taskrail onto PATH, wire the opt-in git hooks

mise run setup (and task taskrail:install) build the working-tree ./cmd/taskrail into ./bin and mise puts ./bin on PATH, so a bare taskrail resolves to the current build with no TASKRAIL override. task taskrail:check fails loudly if the on-PATH binary is stale versus the working tree.

The mise.toml pins are the single source of truth: the go pin matches go.mod and the lefthook pin matches the hooks guidance below. CI provisions the same toolchain via jdx/mise-action, so local and CI builds share one set of pinned versions. The build/test job runs as an OS matrix over Linux, Windows, and macOS, catching cross-platform regressions (path separators, line endings, file modes) before merge.

Optional git hooks mirror the CI checks locally via lefthook. mise run setup wires them; to install by hand:

go install github.com/evilmartians/lefthook@v1.13.6   # or: brew install lefthook
task hooks:install

• pre-commit: gofmt, go vet ./..., taskrail validate, skill package-parity check.
• commit-msg: Conventional Commit subject; rejects automated-attribution trailers.
• pre-push: go test ./....

Hooks are a convenience; CI (.github/workflows/ci.yml) remains the authoritative gate. Do not bypass them with --no-verify.

See CONTRIBUTING.md for the PR checklist, the AI-assisted contribution policy, and tracked-work rules.

Status

Taskrail is an in-progress open-source project. The current release is v0.3.0.

• v0.1.0 established the repository contract: deterministic task progression, the authoritative STATE.md, and verification as a first-class concept.
• v0.2.0 makes adoption in existing repositories easy — guided retrofit, LLM-free import of rough notes into spec/task drafts, opt-in shippable agent skills, a version-aware non-destructive init, and conservative STATE.md repair — while keeping the core CLI provider- and tooling-independent.
• v0.3.0 adds read-only insight into tracked work — status, stats, and coverage — plus the spec command family for inspecting and authoring specs, unblock to release blocked tasks, and Windows install via WinGet.
• Later work is tracked under specs/README.md.

This repository also dogfoods the Taskrail workflow style — using planning/, docs/workflow/, and the packaged skill set it adopts like any adopter — until the product itself fully replaces that scaffolding.

License

Apache-2.0. See LICENSE.

Read Next

• specs/v0.3.0.md — current release scope
• specs/README.md — spec reading order and versioning
• planning/STATE.md — live execution state
• AGENTS.md — guidance for coding agents
• CHANGELOG.md

The versioned specs in specs/ remain the normative source of truth for release scope and behavior.