Metadata-Version: 2.4
Name: aiw
Version: 0.1.0
Summary: Autonomous file-based AI workflow orchestrator for repository-based coding agents.
Project-URL: Homepage, https://github.com/SunneV/AIWorkflow
Project-URL: Repository, https://github.com/SunneV/AIWorkflow
Project-URL: Issues, https://github.com/SunneV/AIWorkflow/issues
Author: SunneV
License: MIT
License-File: LICENSE
Keywords: ai,automation,cli,codex,git,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# 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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```markdown
# 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:

```markdown
# 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:

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

After the AI finishes the task:

```bash
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:

```bash
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

```bash
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:

```text
.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`:

```text
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

```bash
uv run python -m pytest
```
