Metadata-Version: 2.4
Name: ai-dev-workflow
Version: 0.3.0
Summary: Provider-neutral AI-assisted development workflow and CLI
Author: vuthethienlong
Project-URL: Homepage, https://github.com/vuthethienlong/ai-dev-workflow
Project-URL: Repository, https://github.com/vuthethienlong/ai-dev-workflow
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0

# AI Dev Workflow

Reusable, provider-neutral workflow for AI-assisted software development.

This repository provides a reusable, provider-neutral AI development workflow with first-class brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification artifacts.

## Default lifecycle

```text
Brainstorm
  -> Spec
  -> ADR (when needed)
  -> Issue Ready Freeze
  -> Implementation Plan
  -> TesterAgent writes executable tests
  -> RED
  -> ImplementerAgent implements
  -> GREEN + regression
  -> ReviewerAgent (automatic independent review by default)
  -> Integration
  -> Runtime verification batch when required
  -> Promotion / Done
```

## Roles

- `ArchitectAgent`: brainstorm, spec, ADR and acceptance criteria.
- `TesterAgent`: derives tests from the frozen contract and proves RED before implementation.
- `ImplementerAgent`: implements without changing the frozen test contract; must reach GREEN and run applicable regression checks.
- `ReviewerAgent`: automatic semantic/architecture reviewer by default; must use a different worker_id from the Implementer. Separate credential/identity is optional.
- `RuntimeVerifierAgent`: optional, project-specific runtime verification role.

A role is not a model. GPT, Codex, Claude, local models or future providers are replaceable adapters under these contracts.

## Core rules

- Work item is the task source of truth through a configurable WorkItemProvider (GitHub Issues or Azure DevOps).
- `Ready` is the commitment/freeze boundary.
- Test design happens before implementation.
- Implementer may report a bad test/spec as blocked, but must not rewrite expectations merely to make tests pass.
- Deterministic CI gates run before automatic independent semantic review.
- Runtime verification is separate from offline/CI verification.
- Projects consume versioned reusable workflows such as `@v1`; they do not copy the engine.

## Consumer project

A project keeps only project-specific context/config:

```text
AGENTS.md
CURRENT.md (optional bootstrap/router)
.ai-workflow.yml
.github/workflows/ai.yml
project tests/runtime rules
```

Its caller workflow will reference this repository's reusable workflow.

The framework does **not** install its own CI/check workflow into consumer repositories, does not configure required status checks, and does not modify branch protection. Existing consumer-repository build, test, lint, security, approval, and merge policies remain authoritative. The generated `.github/workflows/ai-workflow.yml` is orchestration only.

See:
- `AGENTS.md`
- `docs/lifecycle.md`
- `docs/agent-contracts.md`
- `docs/tdd-handoff.md`
- `.ai-workflow.example.yml`

Refs #1


## Execution environments

Execution environments are provider-neutral. The first supported project contract is GitHub Codespaces with three modes:

- `off`: never use Codespaces.
- `on-demand`: provision/start a Codespace only when a routed task requires it.
- `always-on`: keep a Codespace available according to project policy.

The recommended default is `on-demand`.

Agent role, provider and environment are independent dimensions. For example, `ImplementerAgent` may run through different provider adapters while using the same Codespaces workspace.


## Project bootstrap

The central framework owns the shared repository metadata contract.

Consumer repositories can run the reusable `bootstrap-project.yml` workflow to create or update the managed workflow labels. Bootstrap is idempotent and does not delete project-specific labels.

Managed labels currently include:
- workflow states: `status:ready`, `status:in-progress`, `status:blocked`, `status:in-review`, `status:runtime-pending`, `status:release-pending`;
- priorities: `priority:P0`, `priority:P1`, `priority:P2`.

This keeps label semantics portable when the framework or a project is copied to another repository/account.


## Workspace planning context

Multi-repository brainstorming uses a workspace registry in `.ai-workspace.yml`.

Before a work item is published, the Planning Context Resolver normalizes:
- repositories and their purpose/ref/access;
- context paths relevant to architecture/brainstorming;
- the default target repository;
- GitHub Project identity;
- logical initiatives and repository-local milestone mappings.

ArchitectAgent then emits a planning decision identifying the correct target repository, affected repositories, initiative/release, dependencies, issue type, and runtime requirement.

This keeps brainstorming portable across ChatGPT, Claude, Codex, local models, or future providers and prevents repository selection from depending on model memory.


## Azure DevOps initialization

Azure DevOps is supported through the provider-neutral WorkItemProvider boundary.

Run:

```bash
AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow init-ado \
  --organization <org> \
  --project <project>
```

The initializer discovers the project's current process, Work Item Types, and all visible states through Azure DevOps REST API 7.1. It writes explicit per-WIT state mappings into `.ai-workflow.yml`; runtime execution does not guess custom state meanings.

Role/provider assignments can be supplied during init:

```bash
./bin/ai-workflow init-ado \
  --organization <org> \
  --project <project> \
  --role-provider ArchitectAgent=claude \
  --role-provider TesterAgent=codex \
  --role-provider ImplementerAgent=codex
```

Validate later with:

```bash
./bin/ai-workflow doctor \
  --config .ai-workflow.yml \
  --discovery .ai-workflow.yml.ado-discovery.json
```

Doctor fails when ADO introduces a visible state that has no explicit mapping, when no ADO state maps to the canonical `ready` or `completed` state, or when required agent roles have no provider.


## Plugin-style repository initialization

Existing repositories can install the workflow with one command:

```bash
./bin/ai-workflow init \
  --work-items github-issues \
  --environment codespaces \
  --codespaces-mode on-demand
```

For Azure DevOps:

```bash
AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow init \
  --work-items azure-devops \
  --ado-organization <org> \
  --ado-project <project> \
  --environment codespaces \
  --role-provider ArchitectAgent=claude \
  --role-provider TesterAgent=codex \
  --role-provider ImplementerAgent=codex
```

The initializer updates only workflow-owned configuration sections and preserves unrelated custom YAML. It creates missing `AGENTS.md`, `CURRENT.md`, Codespaces devcontainer, and GitHub workflow caller stubs without overwriting existing project files unless `--force` is supplied. Doctor validation runs after init.


## Guided setup wizard

For first-time installation, prefer the step-by-step setup flow over raw `init` flags:

```bash
GH_TOKEN=... ./bin/ai-workflow setup \
  --work-items github-issues \
  --github-repository owner/repo \
  --environment codespaces
```

For Azure DevOps:

```bash
AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow setup \
  --work-items azure-devops \
  --ado-organization <org> \
  --ado-project <project> \
  --environment codespaces
```

Setup runs eight phases: repository context analysis, provider selection, current-status discovery, mapping confirmation, workflow policy, agent assignment, environment/credential guidance, then doctor/apply.

The setup context is exposed through a provider-neutral `SetupAgent` contract so an AI provider can recommend project-specific defaults after reading existing docs/tests/workflows. GitHub setup discovers existing labels and maps status-like labels; Azure DevOps setup discovers states per Work Item Type. Mapping is persisted explicitly and is never guessed during runtime.

Use `--plan-only` to generate `.ai-setup-plan.yml` without applying repository changes, or `--non-interactive` for automation.


## AI provider registry

Agent roles reference provider IDs. Provider type, endpoint, model and authentication are configured separately.

Examples:

```bash
./bin/ai-workflow setup ... \
  --ai-provider codex=chatgpt-codex,model=gpt-5.6-codex \
  --ai-provider openai=openai,model=gpt-5.6,auth=api-key-env,env=OPENAI_API_KEY \
  --ai-provider claude=anthropic,model=claude-sonnet,auth=api-key-env,env=ANTHROPIC_API_KEY \
  --ai-provider litellm=litellm,base_url=http://litellm:4000/v1,auth=bearer-env,env=LITELLM_API_KEY \
  --ai-provider local=local-openai-compatible,base_url=http://host.docker.internal:11434/v1,model=qwen-local,auth=none \
  --role-provider ImplementerAgent=local
```

Supported provider types are `openai`, `chatgpt-codex`, `anthropic`, `litellm`, `openai-compatible`, `local-openai-compatible`, and `interactive`.

Authentication is an independent strategy: `chatgpt-oauth`, `api-key-env`, `bearer-env`, or `none`. Secrets are never written into project configuration; configuration stores only the environment variable name or interactive auth strategy.


## Connection-first setup

Guided setup now connects the source host before repository/provider discovery.

GitHub authentication supports:

- `gh-cli` (default): reuse the authenticated GitHub CLI OAuth session from `gh auth login`;
- `token-env`: read a PAT/token from an environment variable such as `GH_TOKEN`.

SSH keys remain valid for Git fetch/push but are not used as GitHub API/WorkItem authentication.

Example:

```bash
gh auth login
./bin/ai-workflow setup \
  --github-auth gh-cli \
  --github-repository owner/repo \
  --work-items github-issues
```

The WorkItemProvider is selected from a registry. Built-ins are currently `github-issues` and `azure-devops`; core validation is registry-based so future providers can be added without changing canonical workflow states.

### Azure DevOps MCP

When Azure DevOps is the WorkItemProvider, setup can also configure Microsoft's Azure DevOps MCP connection for agents.

Remote MCP is the default:

```bash
./bin/ai-workflow setup \
  --github-repository owner/repo \
  --work-items azure-devops \
  --ado-organization contoso \
  --ado-project App \
  --ado-mcp-mode remote \
  --ado-mcp-auth interactive
```

Local stdio MCP remains available with `--ado-mcp-mode local`. Supported MCP auth modes are `interactive`, `azcli`, `env`, `envvar`, and `pat`. Secrets are represented only by auth strategy/environment requirements and are never written to project configuration.


## Worker registration

Setup can register local, Codespaces, or cloud workers separately from AI provider configuration. Worker IDs are independent from credential identities, so multiple workers may share one credential reference.

Example local hybrid worker:

```bash
./bin/ai-workflow setup ... \
  --worker desktop=hybrid,provider=local,environment=local,roles=ArchitectAgent|ImplementerAgent,assignee=my-github-login,planning_updates=approval-required
```

Example Codespaces executor:

```bash
./bin/ai-workflow setup ... \
  --worker cs=executor,provider=codex,environment=codespaces,roles=TesterAgent|ImplementerAgent,capacity=2
```

Planner/hybrid workers can connect directly to the configured WorkItemProvider (for example Azure DevOps MCP) to read current work items, analyze repository/work-item context, brainstorm, and propose updates. Planning mutations default to approval-required; frozen ready contracts cannot be silently changed. Executor/hybrid workers project into the existing queue-dispatcher worker registry and follow the reservation → provider accepted → in-progress lifecycle.


## Complete setup documentation

For the full first-run and customization guide, see:

- `docs/setup-guide.md` — human-readable step-by-step setup, examples, credentials, providers, workers, ADO/GitHub, Codespaces/local and multi-repo.
- `docs/setup-agent-playbook.md` — canonical AI-readable SetupAgent playbook, invariants, approval boundaries and customization contract.

Recommended workflow:

```text
AI or user reads setup guide/playbook
→ run setup --plan-only
→ review discovered status/WIT mappings and recommendations
→ approve/customize
→ run setup/apply
→ configure required secrets/sign-ins
→ doctor
```

The setup flow is customizable, but provider-specific states, credential values and frozen-contract changes must never be silently guessed.


## Updating the framework

Use `./bin/ai-workflow update --check` to inspect the configured framework ref, and `./bin/ai-workflow update --to <ref>` to update framework-managed files and schema metadata. Project-owned configuration and files are preserved; locally modified managed files are skipped unless `--force` is explicitly used. See `docs/setup-guide.md` for the full update and migration rules.


## Install from PyPI

Consumers do not need to clone this repository:

```bash
python -m pip install --upgrade ai-dev-workflow
```

After installation, start with the built-in guide:

```bash
ai-workflow guide
```

Typical first-run flow:

```bash
cd /path/to/project
ai-workflow setup
ai-workflow doctor
```

The setup wizard detects the containing Git repository by default, shows the generated plan/configuration, and prints the next required steps after apply. Use `ai-workflow setup --help` for setup options and `ai-workflow guide` at any time for the end-to-end usage flow.

The GitHub repository may remain private because normal consumers install the built distribution from PyPI rather than cloning the source repository.

On another machine, install Python 3.10+ and run the same `pip install ai-dev-workflow` command. Project-specific configuration remains in each consumer repository.

Framework CLI/package upgrades and project installation upgrades are separate:

```bash
python -m pip install --upgrade ai-dev-workflow
ai-workflow update
```

The first command upgrades the installed CLI package. The second migrates/updates the workflow installation in the current project.


## Active work and claims

A selected task is not considered started until its worker/provider acknowledges it:

```text
ready/queued
-> reserved
-> offered
-> accepted by worker/provider
-> claim committed
-> active status
```

Local agents acknowledge with the registered worker identity (for example through `ai-workflow claim`). Phase completion can be recorded with `ai-workflow complete-phase`, which releases the current claim and reserves an eligible worker for the next role. Automatic review always excludes the implementation worker_id; identity separation is enforced only when the optional strict-review policy is enabled.


## Worker credentials and identity

Worker IDs and credentials are separate concepts. Several workers may intentionally use the same credential reference and therefore operate as the same GitHub/ADO actor. This is valid for normal planning, testing, implementation, and runtime work.

The workflow verifies effective actor identity where possible. A distinct credential is not required merely because workers are different. By default, ReviewerAgent only needs a different worker_id from the Implementer. Projects that require stronger separation may enable `reviewer.require_distinct_identity: true`.
