ai-dev-workflow 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ado_mcp.py ADDED
@@ -0,0 +1,49 @@
1
+ """Microsoft Azure DevOps MCP configuration helpers."""
2
+ from __future__ import annotations
3
+
4
+ AUTH_MODES = {"interactive", "azcli", "env", "envvar", "pat"}
5
+
6
+
7
+ def build_ado_mcp(organization: str, mode="remote", auth="interactive", project=None, team=None) -> dict:
8
+ if mode not in ("remote", "local"):
9
+ raise ValueError("ADO MCP mode must be remote or local")
10
+ if auth not in AUTH_MODES:
11
+ raise ValueError(f"unsupported ADO MCP auth: {auth}")
12
+ if mode == "remote":
13
+ return {
14
+ "mode": "remote",
15
+ "url": f"https://mcp.dev.azure.com/{organization}",
16
+ "auth": {"type": auth},
17
+ "defaults": {"project": project, "team": team},
18
+ }
19
+ args = ["-y", "@azure-devops/mcp", organization]
20
+ if auth != "interactive":
21
+ args += ["--authentication", auth]
22
+ env = {}
23
+ if project:
24
+ env["ado_mcp_project"] = project
25
+ if team:
26
+ env["ado_mcp_team"] = team
27
+ return {
28
+ "mode": "local",
29
+ "transport": "stdio",
30
+ "command": "npx",
31
+ "args": args,
32
+ "env": env,
33
+ "auth": {"type": auth},
34
+ }
35
+
36
+
37
+ def ado_mcp_credentials(config: dict) -> list[dict]:
38
+ auth = (config.get("auth") or {}).get("type")
39
+ if auth == "envvar":
40
+ return [{"name":"ADO_MCP_AUTH_TOKEN","purpose":"Bearer token for Azure DevOps MCP","store":"environment/secret store"}]
41
+ if auth == "pat":
42
+ return [{"name":"PERSONAL_ACCESS_TOKEN","purpose":"Base64 email:PAT for Azure DevOps MCP","store":"environment/secret store"}]
43
+ if auth == "azcli":
44
+ return [{"name":"az login","purpose":"Active Azure CLI login session","store":"local credential cache"}]
45
+ if auth == "env":
46
+ return [{"name":"Azure Identity environment","purpose":"DefaultAzureCredential inputs","store":"environment/managed identity"}]
47
+ if auth == "interactive":
48
+ return [{"name":"Microsoft sign-in","purpose":"Interactive Azure DevOps MCP authentication","store":"client auth session"}]
49
+ return []
ado_provider.py ADDED
@@ -0,0 +1,245 @@
1
+ """Azure DevOps WorkItemProvider discovery and state mapping."""
2
+ from __future__ import annotations
3
+
4
+ import base64
5
+ import json
6
+ import re
7
+ from urllib.parse import quote
8
+ from urllib.request import Request, urlopen
9
+ from urllib.error import HTTPError
10
+
11
+ from work_item_provider import CANONICAL_STATES
12
+
13
+ API_VERSION = "7.1"
14
+
15
+
16
+ class AzureDevOps:
17
+ def __init__(self, organization: str, token: str, base_url="https://dev.azure.com"):
18
+ self.organization = organization
19
+ self.base = f"{base_url.rstrip('/')}/{quote(organization, safe='')}"
20
+ self.token = token
21
+
22
+ def request(self, path: str):
23
+ auth = base64.b64encode((":" + self.token).encode()).decode()
24
+ req = Request(
25
+ self.base + path,
26
+ headers={
27
+ "Authorization": "Basic " + auth,
28
+ "Accept": "application/json",
29
+ },
30
+ )
31
+ try:
32
+ with urlopen(req, timeout=30) as response:
33
+ return json.load(response)
34
+ except HTTPError as exc:
35
+ body = exc.read().decode("utf-8", "replace")
36
+ raise RuntimeError(f"Azure DevOps API {exc.code}: {body}") from exc
37
+
38
+ def project(self, project: str):
39
+ return self.request(
40
+ f"/_apis/projects/{quote(project, safe='')}?includeCapabilities=true&api-version={API_VERSION}"
41
+ )
42
+
43
+ def project_properties(self, project_id: str):
44
+ return self.request(
45
+ f"/_apis/projects/{quote(project_id, safe='')}/properties"
46
+ f"?keys=System.CurrentProcessTemplateId&api-version=7.1-preview.1"
47
+ )
48
+
49
+ def work_item_types(self, project: str):
50
+ return self.request(
51
+ f"/{quote(project, safe='')}/_apis/wit/workitemtypes?api-version={API_VERSION}"
52
+ ).get("value", [])
53
+
54
+ def states(self, process_id: str, wit_ref_name: str):
55
+ return self.request(
56
+ f"/_apis/work/processes/{quote(process_id, safe='')}/workItemTypes/"
57
+ f"{quote(wit_ref_name, safe='')}/states?api-version={API_VERSION}"
58
+ ).get("value", [])
59
+
60
+ def fields(self, project: str, wit_name: str):
61
+ return self.request(
62
+ f"/{quote(project, safe='')}/_apis/wit/workitemtypes/"
63
+ f"{quote(wit_name, safe='')}/fields?api-version={API_VERSION}"
64
+ ).get("value", [])
65
+
66
+ def discover(self, project_name: str) -> dict:
67
+ project = self.project(project_name)
68
+ props = self.project_properties(project["id"]).get("value", [])
69
+ process_id = next(
70
+ (str(item.get("value")) for item in props
71
+ if item.get("name") == "System.CurrentProcessTemplateId"),
72
+ None,
73
+ )
74
+ if not process_id:
75
+ raise RuntimeError("Azure DevOps project process ID was not found")
76
+
77
+ work_item_types = []
78
+ for wit in self.work_item_types(project_name):
79
+ ref = wit.get("referenceName")
80
+ name = wit.get("name")
81
+ if not ref or not name:
82
+ continue
83
+ states = [
84
+ {
85
+ "name": state.get("name"),
86
+ "category": state.get("stateCategory"),
87
+ "hidden": bool(state.get("hidden", False)),
88
+ "customization_type": state.get("customizationType"),
89
+ }
90
+ for state in self.states(process_id, ref)
91
+ if state.get("name")
92
+ ]
93
+ fields = [
94
+ {
95
+ "name": field.get("name"),
96
+ "reference_name": field.get("referenceName"),
97
+ "type": field.get("type"),
98
+ "required": bool(field.get("alwaysRequired", False)),
99
+ "read_only": bool(field.get("readOnly", False)),
100
+ }
101
+ for field in self.fields(project_name, name)
102
+ if field.get("referenceName")
103
+ ]
104
+ work_item_types.append({
105
+ "name": name,
106
+ "reference_name": ref,
107
+ "states": states,
108
+ "fields": sorted(fields, key=lambda x: x["reference_name"]),
109
+ })
110
+
111
+ return {
112
+ "organization": self.organization,
113
+ "project": project_name,
114
+ "project_id": project["id"],
115
+ "process_id": process_id,
116
+ "work_item_types": sorted(work_item_types, key=lambda x: x["reference_name"]),
117
+ }
118
+
119
+
120
+ def suggest_state(state_name: str, category: str | None) -> str:
121
+ name = re.sub(r"\s+", " ", state_name.strip().lower())
122
+ if any(token in name for token in ("block", "reject", "hold", "waiting external")):
123
+ return "blocked"
124
+ if "runtime" in name or "uat" in name:
125
+ return "runtime-pending"
126
+ if any(token in name for token in ("review", "qa", "verify", "validation", "test")):
127
+ return "in-review"
128
+ if any(token in name for token in ("release", "deploy", "staging")):
129
+ return "release-pending"
130
+ if any(token in name for token in ("ready", "approved", "to do", "todo", "committed")):
131
+ return "ready"
132
+ if any(token in name for token in ("doing", "active", "progress", "development", "implement")):
133
+ return "in-progress"
134
+ if any(token in name for token in ("done", "closed", "complete", "completed")):
135
+ return "completed"
136
+
137
+ normalized_category = (category or "").replace(" ", "").lower()
138
+ if normalized_category == "completed":
139
+ return "completed"
140
+ if normalized_category == "resolved":
141
+ return "release-pending"
142
+ if normalized_category == "inprogress":
143
+ return "in-progress"
144
+ if normalized_category == "proposed":
145
+ return "draft"
146
+ return "draft"
147
+
148
+
149
+ def build_state_mapping(discovery: dict) -> dict:
150
+ mapping = {}
151
+ for wit in discovery.get("work_item_types", []):
152
+ states = {}
153
+ for state in wit.get("states", []):
154
+ if state.get("hidden"):
155
+ continue
156
+ states[state["name"]] = suggest_state(state["name"], state.get("category"))
157
+ mapping[wit["reference_name"]] = states
158
+ return mapping
159
+
160
+
161
+ def validate_mapping(discovery: dict, mapping: dict) -> list[str]:
162
+ errors = []
163
+ for wit in discovery.get("work_item_types", []):
164
+ ref = wit["reference_name"]
165
+ configured = mapping.get(ref, {})
166
+ for state in wit.get("states", []):
167
+ if state.get("hidden"):
168
+ continue
169
+ name = state["name"]
170
+ if name not in configured:
171
+ errors.append(f"unmapped ADO state: {ref} / {name}")
172
+ continue
173
+ if configured[name] not in CANONICAL_STATES:
174
+ errors.append(
175
+ f"invalid canonical state for {ref} / {name}: {configured[name]}"
176
+ )
177
+ return errors
178
+
179
+
180
+ FIELD_KEYS = (
181
+ "workflow_phase",
182
+ "github_issue",
183
+ "worker",
184
+ "agent_role",
185
+ "pull_request",
186
+ "test_status",
187
+ "runtime_status",
188
+ "workflow_profile",
189
+ )
190
+
191
+
192
+ def available_fields(discovery: dict, wit_ref: str) -> list[dict]:
193
+ wit = next((w for w in discovery.get("work_item_types", [])
194
+ if w.get("reference_name") == wit_ref), None)
195
+ return list((wit or {}).get("fields", []))
196
+
197
+
198
+ def validate_field_mapping(discovery: dict, field_mapping: dict) -> list[str]:
199
+ """Validate mappings against existing ADO fields. Never creates schema."""
200
+ errors = []
201
+ by_wit = {w["reference_name"]: w for w in discovery.get("work_item_types", [])}
202
+ for wit_ref, mappings in (field_mapping or {}).items():
203
+ wit = by_wit.get(wit_ref)
204
+ if not wit:
205
+ errors.append(f"unknown ADO WIT in field mapping: {wit_ref}")
206
+ continue
207
+ fields = {f["reference_name"]: f for f in wit.get("fields", [])}
208
+ for key, config in (mappings or {}).items():
209
+ if key not in FIELD_KEYS:
210
+ errors.append(f"unsupported ADO execution field key: {key}")
211
+ continue
212
+ if not isinstance(config, dict):
213
+ errors.append(f"invalid ADO field mapping for {wit_ref} / {key}")
214
+ continue
215
+ ref = config.get("field")
216
+ if not ref:
217
+ errors.append(f"missing ADO field reference for {wit_ref} / {key}")
218
+ continue
219
+ field = fields.get(ref)
220
+ if not field:
221
+ errors.append(f"ADO field does not exist: {wit_ref} / {ref}")
222
+ continue
223
+ if field.get("read_only"):
224
+ errors.append(f"ADO field is read-only: {wit_ref} / {ref}")
225
+ return errors
226
+
227
+
228
+ def defaults_for_wit(field_mapping: dict, wit_ref: str) -> dict:
229
+ result = {}
230
+ for config in (field_mapping or {}).get(wit_ref, {}).values():
231
+ if not isinstance(config, dict) or not config.get("field"):
232
+ continue
233
+ if "default" in config:
234
+ result[config["field"]] = config.get("default")
235
+ return result
236
+
237
+
238
+ def execution_field_updates(field_mapping: dict, wit_ref: str, values: dict) -> dict:
239
+ result = {}
240
+ for key, value in values.items():
241
+ config = (field_mapping or {}).get(wit_ref, {}).get(key)
242
+ if not config or not config.get("field"):
243
+ continue
244
+ result[config["field"]] = value
245
+ return result
@@ -0,0 +1,348 @@
1
+ Metadata-Version: 2.4
2
+ Name: ai-dev-workflow
3
+ Version: 0.1.0
4
+ Summary: Provider-neutral AI-assisted development workflow and CLI
5
+ Author: vuthethienlong
6
+ Project-URL: Homepage, https://github.com/vuthethienlong/ai-dev-workflow
7
+ Project-URL: Repository, https://github.com/vuthethienlong/ai-dev-workflow
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Python :: 3 :: Only
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: PyYAML>=6.0
14
+
15
+ # AI Dev Workflow
16
+
17
+ Reusable, provider-neutral workflow for AI-assisted software development.
18
+
19
+ 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.
20
+
21
+ ## Default lifecycle
22
+
23
+ ```text
24
+ Brainstorm
25
+ -> Spec
26
+ -> ADR (when needed)
27
+ -> Issue Ready Freeze
28
+ -> Implementation Plan
29
+ -> TesterAgent writes executable tests
30
+ -> RED
31
+ -> ImplementerAgent implements
32
+ -> GREEN + regression
33
+ -> ReviewerAgent (optional/manual by default)
34
+ -> Integration
35
+ -> Runtime verification batch when required
36
+ -> Promotion / Done
37
+ ```
38
+
39
+ ## Roles
40
+
41
+ - `ArchitectAgent`: brainstorm, spec, ADR and acceptance criteria.
42
+ - `TesterAgent`: derives tests from the frozen contract and proves RED before implementation.
43
+ - `ImplementerAgent`: implements without changing the frozen test contract; must reach GREEN and run applicable regression checks.
44
+ - `ReviewerAgent`: optional semantic/architecture reviewer. Disabled/manual by default in v1.
45
+ - `RuntimeVerifierAgent`: optional, project-specific runtime verification role.
46
+
47
+ A role is not a model. GPT, Codex, Claude, local models or future providers are replaceable adapters under these contracts.
48
+
49
+ ## Core rules
50
+
51
+ - Work item is the task source of truth through a configurable WorkItemProvider (GitHub Issues or Azure DevOps).
52
+ - `Ready` is the commitment/freeze boundary.
53
+ - Test design happens before implementation.
54
+ - Implementer may report a bad test/spec as blocked, but must not rewrite expectations merely to make tests pass.
55
+ - Deterministic CI gates run before optional semantic AI review.
56
+ - Runtime verification is separate from offline/CI verification.
57
+ - Projects consume versioned reusable workflows such as `@v1`; they do not copy the engine.
58
+
59
+ ## Consumer project
60
+
61
+ A project keeps only project-specific context/config:
62
+
63
+ ```text
64
+ AGENTS.md
65
+ CURRENT.md (optional bootstrap/router)
66
+ .ai-workflow.yml
67
+ .github/workflows/ai.yml
68
+ project tests/runtime rules
69
+ ```
70
+
71
+ Its caller workflow will reference this repository's reusable workflow.
72
+
73
+ See:
74
+ - `AGENTS.md`
75
+ - `docs/lifecycle.md`
76
+ - `docs/agent-contracts.md`
77
+ - `docs/tdd-handoff.md`
78
+ - `.ai-workflow.example.yml`
79
+
80
+ Refs #1
81
+
82
+
83
+ ## Execution environments
84
+
85
+ Execution environments are provider-neutral. The first supported project contract is GitHub Codespaces with three modes:
86
+
87
+ - `off`: never use Codespaces.
88
+ - `on-demand`: provision/start a Codespace only when a routed task requires it.
89
+ - `always-on`: keep a Codespace available according to project policy.
90
+
91
+ The recommended default is `on-demand`.
92
+
93
+ Agent role, provider and environment are independent dimensions. For example, `ImplementerAgent` may run through different provider adapters while using the same Codespaces workspace.
94
+
95
+
96
+ ## Project bootstrap
97
+
98
+ The central framework owns the shared repository metadata contract.
99
+
100
+ 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.
101
+
102
+ Managed labels currently include:
103
+ - workflow states: `status:ready`, `status:in-progress`, `status:blocked`, `status:in-review`, `status:runtime-pending`, `status:release-pending`;
104
+ - priorities: `priority:P0`, `priority:P1`, `priority:P2`.
105
+
106
+ This keeps label semantics portable when the framework or a project is copied to another repository/account.
107
+
108
+
109
+ ## Workspace planning context
110
+
111
+ Multi-repository brainstorming uses a workspace registry in `.ai-workspace.yml`.
112
+
113
+ Before a work item is published, the Planning Context Resolver normalizes:
114
+ - repositories and their purpose/ref/access;
115
+ - context paths relevant to architecture/brainstorming;
116
+ - the default target repository;
117
+ - GitHub Project identity;
118
+ - logical initiatives and repository-local milestone mappings.
119
+
120
+ ArchitectAgent then emits a planning decision identifying the correct target repository, affected repositories, initiative/release, dependencies, issue type, and runtime requirement.
121
+
122
+ This keeps brainstorming portable across ChatGPT, Claude, Codex, local models, or future providers and prevents repository selection from depending on model memory.
123
+
124
+
125
+ ## Azure DevOps initialization
126
+
127
+ Azure DevOps is supported through the provider-neutral WorkItemProvider boundary.
128
+
129
+ Run:
130
+
131
+ ```bash
132
+ AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow init-ado \
133
+ --organization <org> \
134
+ --project <project>
135
+ ```
136
+
137
+ 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.
138
+
139
+ Role/provider assignments can be supplied during init:
140
+
141
+ ```bash
142
+ ./bin/ai-workflow init-ado \
143
+ --organization <org> \
144
+ --project <project> \
145
+ --role-provider ArchitectAgent=claude \
146
+ --role-provider TesterAgent=codex \
147
+ --role-provider ImplementerAgent=codex
148
+ ```
149
+
150
+ Validate later with:
151
+
152
+ ```bash
153
+ ./bin/ai-workflow doctor \
154
+ --config .ai-workflow.yml \
155
+ --discovery .ai-workflow.yml.ado-discovery.json
156
+ ```
157
+
158
+ 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.
159
+
160
+
161
+ ## Plugin-style repository initialization
162
+
163
+ Existing repositories can install the workflow with one command:
164
+
165
+ ```bash
166
+ ./bin/ai-workflow init \
167
+ --work-items github-issues \
168
+ --environment codespaces \
169
+ --codespaces-mode on-demand
170
+ ```
171
+
172
+ For Azure DevOps:
173
+
174
+ ```bash
175
+ AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow init \
176
+ --work-items azure-devops \
177
+ --ado-organization <org> \
178
+ --ado-project <project> \
179
+ --environment codespaces \
180
+ --role-provider ArchitectAgent=claude \
181
+ --role-provider TesterAgent=codex \
182
+ --role-provider ImplementerAgent=codex
183
+ ```
184
+
185
+ 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.
186
+
187
+
188
+ ## Guided setup wizard
189
+
190
+ For first-time installation, prefer the step-by-step setup flow over raw `init` flags:
191
+
192
+ ```bash
193
+ GH_TOKEN=... ./bin/ai-workflow setup \
194
+ --work-items github-issues \
195
+ --github-repository owner/repo \
196
+ --environment codespaces
197
+ ```
198
+
199
+ For Azure DevOps:
200
+
201
+ ```bash
202
+ AZURE_DEVOPS_TOKEN=... ./bin/ai-workflow setup \
203
+ --work-items azure-devops \
204
+ --ado-organization <org> \
205
+ --ado-project <project> \
206
+ --environment codespaces
207
+ ```
208
+
209
+ Setup runs eight phases: repository context analysis, provider selection, current-status discovery, mapping confirmation, workflow policy, agent assignment, environment/credential guidance, then doctor/apply.
210
+
211
+ 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.
212
+
213
+ Use `--plan-only` to generate `.ai-setup-plan.yml` without applying repository changes, or `--non-interactive` for automation.
214
+
215
+
216
+ ## AI provider registry
217
+
218
+ Agent roles reference provider IDs. Provider type, endpoint, model and authentication are configured separately.
219
+
220
+ Examples:
221
+
222
+ ```bash
223
+ ./bin/ai-workflow setup ... \
224
+ --ai-provider codex=chatgpt-codex,model=gpt-5.6-codex \
225
+ --ai-provider openai=openai,model=gpt-5.6,auth=api-key-env,env=OPENAI_API_KEY \
226
+ --ai-provider claude=anthropic,model=claude-sonnet,auth=api-key-env,env=ANTHROPIC_API_KEY \
227
+ --ai-provider litellm=litellm,base_url=http://litellm:4000/v1,auth=bearer-env,env=LITELLM_API_KEY \
228
+ --ai-provider local=local-openai-compatible,base_url=http://host.docker.internal:11434/v1,model=qwen-local,auth=none \
229
+ --role-provider ImplementerAgent=local
230
+ ```
231
+
232
+ Supported provider types are `openai`, `chatgpt-codex`, `anthropic`, `litellm`, `openai-compatible`, `local-openai-compatible`, and `interactive`.
233
+
234
+ 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.
235
+
236
+
237
+ ## Connection-first setup
238
+
239
+ Guided setup now connects the source host before repository/provider discovery.
240
+
241
+ GitHub authentication supports:
242
+
243
+ - `gh-cli` (default): reuse the authenticated GitHub CLI OAuth session from `gh auth login`;
244
+ - `token-env`: read a PAT/token from an environment variable such as `GH_TOKEN`.
245
+
246
+ SSH keys remain valid for Git fetch/push but are not used as GitHub API/WorkItem authentication.
247
+
248
+ Example:
249
+
250
+ ```bash
251
+ gh auth login
252
+ ./bin/ai-workflow setup \
253
+ --github-auth gh-cli \
254
+ --github-repository owner/repo \
255
+ --work-items github-issues
256
+ ```
257
+
258
+ 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.
259
+
260
+ ### Azure DevOps MCP
261
+
262
+ When Azure DevOps is the WorkItemProvider, setup can also configure Microsoft's Azure DevOps MCP connection for agents.
263
+
264
+ Remote MCP is the default:
265
+
266
+ ```bash
267
+ ./bin/ai-workflow setup \
268
+ --github-repository owner/repo \
269
+ --work-items azure-devops \
270
+ --ado-organization contoso \
271
+ --ado-project App \
272
+ --ado-mcp-mode remote \
273
+ --ado-mcp-auth interactive
274
+ ```
275
+
276
+ 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.
277
+
278
+
279
+ ## Worker registration
280
+
281
+ Setup can register local, Codespaces, or cloud workers separately from AI provider configuration.
282
+
283
+ Example local hybrid worker:
284
+
285
+ ```bash
286
+ ./bin/ai-workflow setup ... \
287
+ --worker desktop=hybrid,provider=local,environment=local,roles=ArchitectAgent|ImplementerAgent,assignee=my-github-login,planning_updates=approval-required
288
+ ```
289
+
290
+ Example Codespaces executor:
291
+
292
+ ```bash
293
+ ./bin/ai-workflow setup ... \
294
+ --worker cs=executor,provider=codex,environment=codespaces,roles=TesterAgent|ImplementerAgent,capacity=2
295
+ ```
296
+
297
+ 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.
298
+
299
+
300
+ ## Complete setup documentation
301
+
302
+ For the full first-run and customization guide, see:
303
+
304
+ - `docs/setup-guide.md` — human-readable step-by-step setup, examples, credentials, providers, workers, ADO/GitHub, Codespaces/local and multi-repo.
305
+ - `docs/setup-agent-playbook.md` — canonical AI-readable SetupAgent playbook, invariants, approval boundaries and customization contract.
306
+
307
+ Recommended workflow:
308
+
309
+ ```text
310
+ AI or user reads setup guide/playbook
311
+ → run setup --plan-only
312
+ → review discovered status/WIT mappings and recommendations
313
+ → approve/customize
314
+ → run setup/apply
315
+ → configure required secrets/sign-ins
316
+ → doctor
317
+ ```
318
+
319
+ The setup flow is customizable, but provider-specific states, credential values and frozen-contract changes must never be silently guessed.
320
+
321
+
322
+ ## Updating the framework
323
+
324
+ 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.
325
+
326
+
327
+ ## Install from PyPI
328
+
329
+ Once a release is published to PyPI, consumers do not need to clone this repository:
330
+
331
+ ```bash
332
+ python -m pip install --upgrade ai-dev-workflow
333
+ ai-workflow --help
334
+ ai-workflow setup
335
+ ```
336
+
337
+ The GitHub repository may remain private because normal consumers install the built distribution from PyPI rather than cloning the source repository.
338
+
339
+ 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.
340
+
341
+ Framework CLI/package upgrades and project installation upgrades are separate:
342
+
343
+ ```bash
344
+ python -m pip install --upgrade ai-dev-workflow
345
+ ai-workflow update
346
+ ```
347
+
348
+ The first command upgrades the installed CLI package. The second migrates/updates the workflow installation in the current project.
@@ -0,0 +1,20 @@
1
+ ado_mcp.py,sha256=Jv1zUVyAMvRKVcNPphdHq8CgnNnq34M46AFnAHE7HFQ,2006
2
+ ado_provider.py,sha256=nE12VIG2nvHAM4rBhaSFmQmMu1yk1aj5jfvl4g-p9v0,9213
3
+ ai_provider.py,sha256=lKHb95_zwqs4isohAGT9a8ZJDHr5l5SuTCS4qjw5snY,5072
4
+ ai_workflow_cli.py,sha256=gVbCwFfvqNC0cB4l0PK65YNVujhDjGK5UcVr7_8q9vw,28544
5
+ composite_work_item.py,sha256=_t4opeewAR8QXguFl-wuNfWSZjkcxFr2fTHcRbktDa0,1703
6
+ framework_update.py,sha256=0G6L_hwl1gTLlqIw2pzsYJuKHWAEXnbKkuxouHqBImE,5053
7
+ github_work_item_provider.py,sha256=fXoKBUjNksFVcj3wFdzdpmxZjg-xn7Rt8wPnmB7-SZs,5179
8
+ issue_publisher.py,sha256=azt08D1WmPZThMMvz5eROyUx2DxsDqoOX4giIXQmmbc,8814
9
+ planning_context.py,sha256=LNe9qO7CLWVJwih3JEfRlrtamDxOvEHdxsnFQe7tdNA,6176
10
+ setup_context.py,sha256=6WOvZJztCo-17NFpRnD2jvdUbjb-9hXOiPxA3de0R9I,3268
11
+ setup_wizard.py,sha256=BUB0fGWh7svUfYEtlKQSjTZy2TAyw1MVjKOm-9moRZM,9320
12
+ source_connection.py,sha256=lFoYE1uJ2eT1EH8WXgY2qFyg7_UhmKjSuV5q9yNIDEM,790
13
+ work_item_provider.py,sha256=EPXIfYi5SNY38q-D5zL-DPFmP0LCr12W_HarvJXrxuU,386
14
+ work_item_registry.py,sha256=Rh5-Bsp02sS4C9EXakg-kSlB8C-kMcXg3PfSjyFKHZ8,764
15
+ worker_registry.py,sha256=Fp-9RKXgoqfoodpRt3omY7mrd3YkCiDDe2HXZyIiwcs,6432
16
+ ai_dev_workflow-0.1.0.dist-info/METADATA,sha256=BVycJM0AlmVUPrWOoQjnwJ88HvbPT4khas7KQi-X7aA,13420
17
+ ai_dev_workflow-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
18
+ ai_dev_workflow-0.1.0.dist-info/entry_points.txt,sha256=-Zva2sernbyUqrpaeQ0ZLFTGlSmr0d8r8h2y_jxV1aI,53
19
+ ai_dev_workflow-0.1.0.dist-info/top_level.txt,sha256=PQfFXz0WHllSxP_Jv50BbKdYV5AB8fxk2xjcLWcBjnE,244
20
+ ai_dev_workflow-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ ai-workflow = ai_workflow_cli:main
@@ -0,0 +1,15 @@
1
+ ado_mcp
2
+ ado_provider
3
+ ai_provider
4
+ ai_workflow_cli
5
+ composite_work_item
6
+ framework_update
7
+ github_work_item_provider
8
+ issue_publisher
9
+ planning_context
10
+ setup_context
11
+ setup_wizard
12
+ source_connection
13
+ work_item_provider
14
+ work_item_registry
15
+ worker_registry