ai-dev-workflow 0.1.0__tar.gz

ai_dev_workflow-0.1.0/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: ai-dev-workflow
+Version: 0.1.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 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.

ai_dev_workflow-0.1.0/README.md

@@ -0,0 +1,334 @@
+# 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.