Metadata-Version: 2.4
Name: ai-dev-workflow
Version: 0.3.1.19
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
Requires-Dist: azure-identity>=1.25.0

# AI Dev Workflow

**Provider-neutral, automation-first software-development orchestration framework.**

AI Dev Workflow orchestrates **the entire software-development lifecycle** across arbitrary
software projects (web, API, desktop, mobile, infrastructure, libraries and more).
It is **not** a particular coding agent, single-product tool, IDE or GitHub Action.
Agents and workers should perform routine planning, execution, validation, review,
integration and reporting autonomously; humans remain accountable for **explicit
decision gates** such as product direction, material scope/architecture changes,
security-sensitive actions and production/release policy.

The target is **human-on-the-loop, policy-driven automation**: an agent proposes
decisions; the system automatically executes allowed work; the human approves
only decisions whose risk or policy requires approval. Human approval must not be
silently bypassed. Current behavior and unimplemented automation are distinguished
in the [roadmap](docs/roadmap.md).

## Target end-to-end lifecycle

```text
Idea / request
  -> PMAgent: product contract, classify Epic / Issue, Keep / Split / Merge
  -> Policy / human decision gate (when required)
  -> ArchitectAgent: technical spec, ADR when needed, dependencies
  -> Policy / human decision gate (when required)
  -> Publish provider-neutral work-item graph (Epic -> execution-leaf Issues)
  -> Ready / frozen acceptance contract
  -> Dispatcher: select eligible worker -> reserve -> offer -> accept -> claim
  -> TesterAgent: executable tests + RED evidence
  -> ImplementerAgent: code + GREEN / regression + PR
  -> Independent ReviewerAgent: approve or request changes
  -> Integration gate (CI + project policy)
  -> Optional release-scoped runtime verification batch
  -> Promote / close / release with traceable evidence
```

Workflow state is **not** agent session state: all transitions must be durable,
auditable and recoverable. An Epic is a planning container; only a ready,
dependency-unblocked **leaf Issue** may be claimed for execution.

### Control plane and data plane

```text
                         Human decision maker
                           (policy gates only)
                                   |
    Request -> PM/Architect -> Workflow Engine <-> WorkItemProvider
                                   |            (GitHub / Azure DevOps)
                            Planning & context
                                   |
                               Dispatcher <-> Worker Registry & Presence
                                   |
                        eligible worker / claim
                                   |
          +------------------------+-------------------------+
          |                        |                         |
     Local worker             Cloud worker              Human worker
     Codex/Claude/etc.        Codespaces/etc.           (exception)
          +------------------------+-------------------------+
                                   |
                          Tests / PR / review evidence
                                   |
                      Integration / runtime batch / release
                                   |
                       Workflow Engine updates work items
```

| Component | Owns | Must not own |
| --- | --- | --- |
| **Workflow Engine** | State machine, approval policies, durable transitions, recovery | Provider-specific API or agent model |
| **WorkItemProvider** | Epic/Issue CRUD, hierarchy, dependencies, status mapping | Worker execution |
| **Workspace & Artifact Store** | Repository context, Spec/ADR/plan, test and review evidence | Work-item canonical state |
| **Worker Registry & Presence** | Provider, worker identity, roles, capabilities, capacity, location, liveness | Agent role semantics |
| **Dispatcher / Claim Journal** | Eligibility, queue order, reservation, acceptance, ownership and handoff | Work before worker accepts |
| **Execution Runtime** | Launch worker, isolate workspace, execute task, capture evidence | Approval-policy decisions |

Roles specify **what** must happen. Workers specify **who** performs it.
A worker's provider/client specifies **how** it executes; the execution
environment specifies **where**. Never bind an AI provider to an agent role.

### Data flow, by phase

| Phase | Input | Owner / operation | Output and durable source |
| --- | --- | --- | --- |
| **0. Setup** | Repository, GitHub/ADO connection, policy | Setup wizard, metadata discovery, worker registration | `.ai-workflow.yml`, optional `.ai-workspace.yml`, worker registry |
| **1. Product planning** | Idea / request / existing work | PMAgent, policy-aware approval | Product contract, Epic/Issue proposal, approved decisions |
| **2. Technical planning** | Approved product contract + repo context | ArchitectAgent, Spec/ADR, dependencies, Ready Freeze | Versioned spec/plan; canonical work item in GitHub/ADO |
| **3. Dispatch/claim** | Ready leaf Issue + required role/capabilities | Dispatcher + worker accept | Durable dispatch/claim, ActiveWorkContext, active status |
| **4. TDD/review** | Frozen contract + project test rules | Tester -> Implementer -> independent Reviewer | RED/GREEN evidence, PR, review findings, CI |
| **5. Integration/release** | Approved PRs + release policy | Integration + runtime verifier when needed | Integration evidence, optional runtime batch, Done/release |

`AGENTS.md` contains agent instructions; `CURRENT.md` is an **optional
minimal context router**, never the system of record. Secrets stay in worker
credential stores or environment references, not committed configuration.

**Implementation boundaries:** The core currently contains GitHub-specific
claim and phase-completion paths; Azure DevOps-only execution is **not yet**
fully end-to-end provider-neutral. Runtime handoff currently can enter
`runtime-verify` directly after review; the target is a **separate, user- or
policy-triggered multi-Issue runtime batch**. Routing does not yet fully enforce
every capability/capacity/policy constraint. These are tracked as roadmap gaps,
not advertised as completed capabilities.

## Roles

- `SetupAgent`: discover configuration, propose safe defaults and validate setup.
- `PMAgent`: product intent, value, priority, scope, Epic/Issue classification and proposals.
- `ArchitectAgent`: technical boundaries, spec, ADR, dependencies 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

- The WorkItemProvider is the source of truth for work items (GitHub Issues, Azure DevOps); code/docs/PR evidence remain in project repositories.
- `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.
- Favor automatic execution within explicit policy boundaries; request human decisions only at configured risk/approval gates. Never silently approve high-impact actions.
- Changes to frozen requirements require a reviewed revision, not an agent rewriting the contract.

## Consumer project

A project keeps only project-specific context/config:

```text
AGENTS.md
CURRENT.md (optional bootstrap/router)
.ai-workflow.yml
.github/workflows/ai-workflow.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.

Agent roles are provider-neutral. Register worker providers separately with `setup`
or `add-worker`; the deprecated `--role-provider` flag is ignored.

Validate later with:

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

Doctor reports unmapped visible ADO states, missing canonical `ready`/`completed` coverage, missing required agent roles and invalid worker/provider references.


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

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.


## Agent roles and workers

Agent roles (SetupAgent, PMAgent, ArchitectAgent, TesterAgent, ImplementerAgent,
ReviewerAgent and RuntimeVerifierAgent) define responsibilities only; they do
**not** select an AI provider. Set each worker's `provider` and `capacity` when registering the worker. All roles are available automatically. Worker routing
resolves which eligible worker handles each phase.

The setup wizard no longer asks for a provider for each agent role.
Agent entries do not contain a provider. To change which model carries out a task,
configure the worker's provider. The framework assigns roles dynamically by phase.

## 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 discovers repository/provider metadata, confirms mappings, configures policies and workspaces, registers workers with their providers and credentials, then validates and applies. There is **no agent-role provider assignment step**.

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.


## Headless / cloud authentication

Interactive setup supports both GUI and headless environments.

- **GitHub:** existing `gh` CLI session, browser login, token environment variable, or secure pasted token prompt.
- **Azure DevOps:** browser login, device-code login, existing Azure CLI session, PAT/token environment variable, or secure pasted PAT/token prompt.
- Tokens pasted into prompts are used only for the current setup validation and are **not written to project configuration**.
- On cloud/headless Linux, prefer environment-variable credentials for unattended automation; device-code or secure token prompt is suitable for interactive terminal setup.
- Every selected credential is live-validated immediately before setup continues.

## AI provider registry

Setup validates each connection **when it is configured**, before Worker setup:
GitHub must resolve the authenticated account through the GitHub API; Azure
DevOps must resolve the authenticated identity and requested project; every AI
provider must pass a live client/endpoint/authentication check. A failed
validation stops setup at that step and the provider is not available to
Workers. Local Workers share the already-validated project/machine GitHub and
Azure DevOps credentials; setup does not create separate credentials per local
Worker.


No providers are automatically created, including Codex or a manual provider.
Register providers explicitly before creating workers. During initial setup
the wizard offers provider types, then the Worker step lists **only** provider
IDs configured in the preceding step. The operator must choose an item; there
is no preselected Codex option. The `add-worker` wizard similarly lists only
providers saved in the current project's configuration. If none are registered,
configure at least one provider before adding a worker.


**Workers**, not 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 \
  --worker desktop=hybrid,provider=local,environment=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

**Worker registration defaults:** During initial setup, choose one shared local workspace root once (for example `G:\\ai-workers`). Then select a configured provider, choose how many workers to create, and capacity per worker. Worker IDs are generated automatically as `worker-<provider>-<n>`, and each workspace is created under the shared root, e.g. `G:\\ai-workers\\worker-codex-1`. No worker-name or per-worker workspace prompt is required.

**Worker registration defaults:** New workers operate in `hybrid` mode and
automatically receive **all seven Agent Roles** (Setup, PM, Architect, Tester,
Implementer, Reviewer and RuntimeVerifier). No role or mode selection is required
in the wizard. Choose the AI provider and capacity; the wizard still gathers
essential credentials, environment and workspace settings. Roles express workflow
responsibilities, **not unrestricted permissions**: authentication, project
policies, execution readiness and reviewer separation still apply. No Worker role selection or role migration is part of the new setup contract.


Setup can register local, Codespaces, or cloud workers separately from AI provider configuration. The registration wizard does not ask for a role or mode. 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,assignee=my-github-login,planning_updates=approval-required
```

Example Codespaces executor:

```bash
./bin/ai-workflow setup ... \
  --worker cs=hybrid,provider=codex,environment=codespaces,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.


## PM and architecture planning

Product planning and technical architecture are separate roles:

```text
Idea / chat
→ PMAgent
→ product Keep/Split/Merge proposal
→ human approval
→ ArchitectAgent
→ technical Spec / ADR / decomposition
→ approval for structural architecture changes
→ Ready Freeze
→ TesterAgent
```

PMAgent owns what/why: intent, value, scope, priority, product acceptance boundaries, Epic/Issue classification and product-level decomposition. ArchitectAgent owns how: technical boundaries, interfaces, data model, Spec/ADR, technical dependencies and execution decomposition.

By default `workflow.planning.approval_policy` is `always`. Create, Split, Merge, Re-parent and Ready Freeze require explicit approval before provider mutation, and frozen contracts cannot be silently changed.

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


## Azure DevOps configuration boundary

Azure DevOps project metadata and credentials are separate:

- project configuration owns organization/project, logical Epic/Issue Work Item Type mappings, and Area/Iteration defaults;
- worker configuration owns the Azure DevOps authentication strategy/credential reference;
- setup may borrow a worker credential temporarily to discover project metadata, but never persists the raw token;
- workers may share a credential reference when they intentionally act as the same ADO identity.

Area Path and Iteration Path options are discovered from the project's existing Azure DevOps classification nodes. Setup selects from existing values; it does not create or modify the project's classification hierarchy.

## 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`.


## Local parallel workers

One local machine may register multiple workers that intentionally share the same GitHub/Azure DevOps credential sessions while using isolated working folders.

Example:

```yaml
workers:
  - worker_id: codex-01
    environment: local
    provider: codex
    workspace:
      strategy: git-worktree
      root: G:\ai-workers\codex-01

  - worker_id: ccr-01
    environment: local
    provider: ccr
    workspace:
      strategy: git-worktree
      root: G:\ai-workers\ccr-01
```

Add another local worker after initial setup:

```powershell
ai-workflow add-worker
```

or non-interactively:

```powershell
ai-workflow add-worker `
  --worker-id codex-02 `
  --provider codex `
  --workspace G:\ai-workers\codex-02 `
  --workspace-strategy git-worktree
```

By default the new local worker inherits credential references from an existing local worker. It still receives its own `worker_id` and isolated workspace. Use `--no-inherit-credentials` when the worker must use a different identity.

At runtime, a local worker is resolved in this order:

1. explicit `--worker <id>`;
2. `AI_WORKFLOW_WORKER_ID`;
3. current working directory contained by one configured `workspace.root`.

This makes it possible to open separate terminals in separate worker folders and run tasks concurrently without repeating the worker ID.

## Claude Code Router local provider

Claude Code Router can be registered as a local provider:

```yaml
providers:
  ccr:
    type: claude-code-router
    base_url: http://127.0.0.1:3456
    auth:
      type: none
```

The gateway defaults to `http://127.0.0.1:3456`. A client-key environment reference can be configured when the local router is protected. Claude Code Router uses the same `CLAUDE.md` instruction adapter as Claude Code, while `AGENTS.md` remains the shared workflow instruction source.

A local CCR worker can then be registered with its own workspace:

```powershell
ai-workflow add-worker `
  --worker-id ccr-01 `
  --provider ccr `
  --workspace G:\ai-workers\ccr-01
```


### Step-by-step add-worker wizard

Running `ai-workflow add-worker` with no `--non-interactive` flag now opens a structured wizard:

1. review existing project/provider configuration;
2. choose a worker id;
3. choose an AI provider;
4. choose a local machine/agent client;
5. choose the local workspace and its isolation strategy;
6. configure GitHub/ADO credential references;
7. choose skills and capacity;
8. review and confirm before saving.

The wizard never stores raw tokens. It only stores credential strategies/references already supported by the worker identity model.

For scripting/automation, keep the deterministic flag-based flow:

```powershell
ai-workflow add-worker `
  --non-interactive `
  --worker-id codex-02 `
  --provider codex `
  --workspace G:\ai-workers\codex-02 `
  --workspace-strategy git-worktree
```

Use `--no-inherit-credentials` when the new worker must not reuse an existing local worker's credential references.


## Consumer worker registry and live presence

When a GitHub Issues or composite project has execution workers, setup writes:

```text
.github/ai-workflow-worker-registry.json
```

This committed registry contains routing metadata only:

- worker id;
- execution location;
- provider id;
- roles/capabilities;
- capacity;
- managed/unmanaged flag;
- GitHub assignee when required.

It intentionally excludes machine-local paths, machine ids, client launch commands, credential references, tokens, identities, heartbeat data, and active sessions.

For local execution workers, setup also creates or reuses one closed coordination Issue marked with:

```text
<!-- ai-dev-workflow:worker-presence -->
```

The Issue number is stored as project-level dispatcher metadata. Local workers publish the existing queue-dispatcher presence-v2 contract to that Issue using their own verified GitHub identity.

`ai-workflow worker open <worker-id>` keeps the local and central heartbeat alive while the configured Codex/Claude Code client process is running. When the client exits, the worker is reported offline.

For headless or daemon-style workers:

```powershell
ai-workflow worker serve <worker-id>
```

A worker keeps one presence comment and updates it on each heartbeat; it does not append a new comment every interval. The central dispatcher reads the consumer registry plus live presence before reserving work.

The consumer orchestration workflow remains `.github/workflows/ai-workflow.yml`. This integration does not install framework CI/check workflows, does not configure required status checks, and does not modify branch protection.


## Roadmap and automation maturity

See **[Architecture & Improvement Roadmap](docs/roadmap.md)** for phased milestones,
acceptance criteria, priority fixes, compatibility/migration work, security gates
and the distinction between existing components and the autonomous end state.
The roadmap is software-domain agnostic: runtime checks mean validation in a
real target environment (service, desktop, mobile, infrastructure, etc.),
not any particular product domain.
