ai-workflow

ai-workflow is a file-based workflow orchestrator for repositories where AI coding agents such as Codex work through milestones, tasks, ADRs, generated prompts, Git branches, commits, PRs, and sequential handoffs.

It is designed to be installed once and initialized inside any Git repository:

python -m pip install aiw
aiw init

If aiw is installed globally on your machine, bare aiw ... commands remain compatible. Repository-generated examples use uv run aiw ... as the canonical form so the package and project environment are resolved consistently.

Core idea

• Tool logic lives in the installed Python package.
• Package entrypoints use clean module paths only: CLI commands use ai_workflow.cli.main, and rendering entrypoints live under focused ai_workflow.rendering.* modules.
• Project state lives in .ai-workflow.yaml and docs/ai/workspace.
• JSON state is canonical.
• Durable handoff Markdown files are repository-owned; runtime Markdown reports and mirrors are generated.
• One milestone maps to one branch.
• One task maps to one logical commit.
• One finished milestone maps to one pull request.
• AI work is sequential: one active milestone and one active task run through the core execution context.

Quick start

cd my-project
uv run aiw init
uv run aiw doctor
uv run aiw backlog promote BLG-001 --output docs/ai/plan/milestones.md
uv run aiw agent run --lane core --mode queue

Plan With ChatGPT Or Gemini

For a new workpackage, let a general planning model produce the local execution plan before Codex starts coding:

1. Print the milestone-builder prompt:

uv run aiw agent plan-prompt --target milestones --print

2. Paste that prompt into ChatGPT or Gemini with the product goal, repository context, screenshots, constraints, or backlog notes.
3. Paste the returned Markdown into docs/ai/plan/milestones.md. The output must start with # Milestones.
4. Validate and optionally optimize the local plan:

uv run aiw plan validate docs/ai/plan/milestones.md
uv run aiw plan optimize docs/ai/plan/milestones.md --dry-run

5. Import or bootstrap it:

uv run aiw plan import docs/ai/plan/milestones.md
uv run aiw agent bootstrap --plan docs/ai/plan/milestones.md --lane core

docs/ai/plan/milestones.md should contain commit-shaped tasks. A commit-shaped task is one logical commit with observable acceptance criteria and clear conflict scopes. Avoid tiny checklist steps such as "add import", "rename variable", "run formatter", or "write one assertion"; merge those details into the nearest reviewable task.

Bad micro-task plan:

# Milestones

## M01 - Parser cleanup

Tasks:
- Add import
  Acceptance: Import exists.
  Conflict: src/parser.py
- Rename helper
  Acceptance: Helper is renamed.
  Conflict: src/parser.py
- Write assertion
  Acceptance: Assertion exists.
  Conflict: tests/test_parser.py

Optimized workpackage-shaped plan:

# Milestones

## M01 - Parser cleanup

Goal: Make parser cleanup reviewable as one implementation slice.

Tasks:
- Consolidate parser cleanup behavior
  Acceptance: Parser uses the renamed helper through the intended import path.
  Acceptance: Parser behavior is covered by focused tests.
  Conflict: src/parser.py, tests/test_parser.py
- Update parser documentation
  Acceptance: Parser docs describe the cleanup behavior.
  Conflict: docs/parser.md

Open the generated prompt:

docs/ai/workspace/prompts/next-core.md

After the AI finishes the task:

uv run aiw agent finish --lane core --task TASK-001 --commit
uv run aiw agent run --lane core --mode queue

When the final task in a milestone passes checks, uv run aiw agent finish --commit attempts automatic milestone closeout:

uv run aiw agent finish --lane core --commit

The closeout flow finishes the milestone, pushes the milestone branch, creates or reuses the PR, checks mergeability when available, merges when safe, regenerates reports, and records exact blockers when push, PR, merge, credentials, branch protection, or cleanup fail.

Important commands

uv run aiw init
uv run aiw doctor
uv run aiw status
uv run aiw report all

uv run aiw backlog promote BLG-001 --output docs/ai/plan/milestones.md
uv run aiw plan import docs/ai/plan/milestones.md
uv run aiw milestone list
uv run aiw agent run --lane core --mode queue
uv run aiw agent finish --lane core --task TASK-001 --commit
uv run aiw git cleanup --dry-run

Repository-owned files

These files are intended to be durable project files:

.ai-workflow.yaml
docs/ai/START_HERE.md
docs/ai/README.md
docs/ai/plan/backlog.md
docs/ai/workspace/adr/*.md
docs/operator/operator.md
docs/operator/codex-agent.md
docs/ai/workspace/active-roadmap.md
docs/ai/workspace/current-status.md
docs/ai/workspace/next-handoff.md

Runtime/generated files

These files are local execution state or generated artifacts and can be regenerated by aiw:

docs/ai/plan/milestones.md
docs/ai/workspace/state/**/*.json
docs/ai/workspace/locks/
docs/ai/workspace/runs/
docs/ai/workspace/tasks/*.md
docs/ai/workspace/milestones/*.md
docs/ai/workspace/prompts/
docs/ai/workspace/reports/*.md
docs/ai/workspace/archive/
docs/ai/workspace/generated-packs/
docs/operator/queue-run.md

docs/ai/plan/milestones.md is a local execution plan. Keep it ignored by default and commit it only by explicit user opt-in; new workpackages can generate a fresh plan starting again at M01.

Development

uv run python -m pytest