How it works

patok works through a Markdown task list one task at a time. For each task it runs separate research, plan, build and review sessions using the coding-agent CLIs you already have, then commits the result.

Start with a spec

A SPEC.md at the project root holds what every task needs to know: the core business rules and the architecture of the app. It's free-form Markdown that you write by hand and keep up to date as the project evolves.

# Recipe box

## Business rules
- One shared collection, no accounts
- A recipe needs a title and at least one ingredient
- Tags are lowercase, unique per recipe, max 10
- Deleting a recipe is soft: it stays recoverable for 30 days

## Architecture
- Rust, axum, SQLite via sqlx
- JSON API under /api/v1, handlers in src/api/, domain logic in src/core/
- Full-text search uses SQLite FTS5, kept in sync by triggers

Tasks stay small and say only what to change. The spec carries the rest. The research and planner agents read it before a task is planned, and the reviewer checks the result against it, so every task is held to the same rules and structure without repeating them in each task. The discovery agent reads it too, and when there's no task list yet, the research agent uses it to draft the first batch of tasks.

The task list

Tasks live in a TASKS.md at the project root. They can be written by you, drafted by patok from the spec, or appended by the discovery agent. Any line starting with - [ ] is a task; everything else in the file is left alone.

- [ ] T1.1: Add a login form with email and password
- [ ] T1.2: Validate the form and show inline errors
- [ ] T2.1: Persist sessions across restarts

The number before the dot groups tasks into a phase. patok ticks a task (- [x]) only once it has passed its checks.

Each task goes through the loop

  1. Research

    A read-only session looks through the code and writes a report. Simple tasks can skip it.

  2. Plan

    A read-only session produces a plan. It must list the file operations and how to verify them, or it is sent back once and then rejected.

  3. Build

    The builder implements the task and finishes by stating what it claims to have done.

  4. Review

    A fresh-context reviewer reads the diff, runs the project's build and tests, and fixes what it finds in the same pass.

  5. Commit

    The result is committed with git, so your hooks and signing apply.

Every stage can use a different agent and model. When the queue is empty, an optional Discover pass scans the project and appends follow-up tasks, so the loop can keep going.

Reviews follow phases

By default patok reviews once per group: tasks sharing a number, like T1.1 and T1.2, are reviewed together against the whole group's diff when the last one finishes. Fewer review sessions, and the reviewer sees the full change.

When something fails

If the build or the review fails, patok commits the work as WIP, leaves the task unchecked and stops, rather than piling more work on a broken state. Progress is stored in TASKS.md, so the next run picks up at the first unfinished task.

Bring your own agents

patok drives Claude Code, Codex and Vibe CLIs found on your PATH. You choose the provider and model per role.

Interactive or unattended

Good to know

Install patok