Metadata-Version: 2.4
Name: ai-dev-workflow
Version: 0.1.1
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 starts from the workflow proven in the Dragon's Dogma 2 project and keeps Superpowers-style artifacts as first-class inputs: brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification.

## Default lifecycle

```text
Brainstorm
  -> Spec
  -> ADR (when needed)
  -> Issue Ready Freeze
  -> Implementation Plan
  -> TesterAgent writes executable tests
  -> RED
  -> ImplementerAgent implements
  -> GREEN + regression
  -> ReviewerAgent (optional/manual 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`: optional semantic/architecture reviewer. Disabled/manual by default in v1.
- `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 optional semantic AI 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.

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.

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

Once a release is published to PyPI, consumers do not need to clone this repository:

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

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.
