ai-dev-workflow 0.3.0__tar.gz → 0.3.1__tar.gz

{ai_dev_workflow-0.3.0 → ai_dev_workflow-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-workflow
-Version: 0.3.0
+Version: 0.3.1
 Summary: Provider-neutral AI-assisted development workflow and CLI
 Author: vuthethienlong
 Project-URL: Homepage, https://github.com/vuthethienlong/ai-dev-workflow
@@ -364,6 +364,26 @@ 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:
@@ -380,8 +400,168 @@ ready/queued
 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 `
+  --mode hybrid `
+  --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 planner/executor/hybrid mode;
+4. choose an existing AI provider;
+5. choose roles;
+6. choose the local workspace folder;
+7. choose `git-worktree` or `folder` workspace strategy;
+8. choose whether to inherit an existing local worker's credential references or configure separate GitHub/ADO references;
+9. choose skills and capacity;
+10. review the final worker configuration 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 `
+  --mode hybrid `
+  --roles "ArchitectAgent|TesterAgent|ImplementerAgent|ReviewerAgent" `
+  --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.

{ai_dev_workflow-0.3.0 → ai_dev_workflow-0.3.1}/README.md

@@ -350,6 +350,26 @@ 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:
@@ -366,8 +386,168 @@ ready/queued
 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 `
+  --mode hybrid `
+  --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 planner/executor/hybrid mode;
+4. choose an existing AI provider;
+5. choose roles;
+6. choose the local workspace folder;
+7. choose `git-worktree` or `folder` workspace strategy;
+8. choose whether to inherit an existing local worker's credential references or configure separate GitHub/ADO references;
+9. choose skills and capacity;
+10. review the final worker configuration 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 `
+  --mode hybrid `
+  --roles "ArchitectAgent|TesterAgent|ImplementerAgent|ReviewerAgent" `
+  --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.

{ai_dev_workflow-0.3.0 → ai_dev_workflow-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-dev-workflow"
-version = "0.3.0"
+version = "0.3.1"
 description = "Provider-neutral AI-assisted development workflow and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -43,6 +43,7 @@ py-modules = [
   "github_work_item_provider",
   "instruction_adapter",
   "issue_publisher",
+  "planning_approval",
   "planning_context",
   "setup_context",
   "setup_wizard",
@@ -52,5 +53,8 @@ py-modules = [
   "work_item_provider",
   "work_item_registry",
   "worker_identity",
+  "worker_presence",
   "worker_registry",
+  "worker_runtime_manager",
+  "worker_session",
 ]

{ai_dev_workflow-0.3.0 → ai_dev_workflow-0.3.1}/tests/test_ado_provider.py

@@ -1,10 +1,12 @@
 import sys, unittest
 from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tools"))
-from ado_provider import build_state_mapping, suggest_state, validate_mapping, available_fields
+from ado_provider import build_state_mapping, suggest_state, validate_mapping, available_fields, flatten_classification_paths, validate_project_defaults
 
 DISCOVERY={
   "organization":"org","project":"proj","project_id":"p","process_id":"proc",
+  "area_paths":["proj","proj\\Backend"],
+  "iteration_paths":["proj","proj\\2026","proj\\2026\\Sprint 1"],
   "work_item_types":[
     {"name":"Bug","reference_name":"Custom.Bug","fields":[{"name":"AI Phase","reference_name":"Custom.AIPhase","type":"string","required":False,"read_only":False}],"states":[
       {"name":"New","category":"Proposed","hidden":False},
@@ -19,6 +21,34 @@ DISCOVERY={
 }
 
 class Tests(unittest.TestCase):
+    def test_classification_tree_flattens_to_work_item_paths(self):
+        node={
+            "name":"Area",
+            "children":[
+                {"name":"Backend","children":[{"name":"API"}]},
+                {"name":"Frontend"},
+            ],
+        }
+        self.assertEqual(
+            flatten_classification_paths(node,"proj"),
+            ["proj","proj\\Backend","proj\\Backend\\API","proj\\Frontend"],
+        )
+
+    def test_project_defaults_validate_wit_area_and_iteration(self):
+        cfg={
+            "work_item_types":{"epic":"Custom.Bug","issue":"Custom.Bug"},
+            "defaults":{"area_path":"proj\\Backend","iteration_path":"proj\\2026\\Sprint 1"},
+        }
+        self.assertEqual(validate_project_defaults(DISCOVERY,cfg),[])
+        bad={
+            "work_item_types":{"epic":"Custom.Missing","issue":"Custom.Bug"},
+            "defaults":{"area_path":"proj\\Other","iteration_path":"proj\\Missing"},
+        }
+        errors=validate_project_defaults(DISCOVERY,bad)
+        self.assertTrue(any("Custom.Missing" in x for x in errors))
+        self.assertTrue(any("Area Path" in x for x in errors))
+        self.assertTrue(any("Iteration Path" in x for x in errors))
+
     def test_name_and_category_suggestions(self):
         self.assertEqual(suggest_state("Ready for Dev","Proposed"),"ready")
         self.assertEqual(suggest_state("Code Review","InProgress"),"in-review")

{ai_dev_workflow-0.3.0 → ai_dev_workflow-0.3.1}/tests/test_ai_provider.py

@@ -16,6 +16,20 @@ class Tests(unittest.TestCase):
         self.assertEqual(provider_template("local-openai-compatible",base_url="http://127.0.0.1:11434/v1")["auth"]["type"],"none")
         self.assertEqual(provider_template("openai",model="gpt-5")["auth"]["type"],"api-key-env")
 
+    def test_claude_code_router_defaults_to_local_gateway(self):
+        cfg=provider_template("claude-code-router")
+        self.assertEqual(cfg["base_url"],"http://127.0.0.1:3456")
+        self.assertEqual(cfg["auth"]["type"],"none")
+        self.assertEqual(validate_provider("ccr",cfg),[])
+
+    def test_claude_code_router_can_use_client_key_env(self):
+        cfg=provider_template(
+            "claude-code-router",
+            auth_type="api-key-env",
+            env="CCR_CLIENT_KEY",
+        )
+        self.assertEqual(validate_provider("ccr",cfg),[])
+
     def test_custom_and_litellm_require_base_url(self):
         self.assertTrue(any("base_url" in e for e in validate_provider("x",provider_template("litellm"))))
         cfg=provider_template("litellm",base_url="http://litellm:4000/v1",auth_type="bearer-env",env="LITELLM_API_KEY")
@@ -38,12 +52,15 @@ class Tests(unittest.TestCase):
             "local=local-openai-compatible,base_url=http://host.docker.internal:11434/v1,model=qwen",
             "litellm=litellm,base_url=http://litellm:4000/v1,auth=bearer-env,env=LITELLM_API_KEY",
             "claude=anthropic,model=claude-sonnet,auth=api-key-env,env=ANTHROPIC_API_KEY",
+            "ccr=claude-code-router,model=sonnet",
         ])
         self.assertIn("manual",providers)
         self.assertIn("codex",providers)
         self.assertEqual(providers["local"]["auth"]["type"],"none")
         self.assertEqual(providers["litellm"]["auth"]["env"],"LITELLM_API_KEY")
         self.assertEqual(providers["claude"]["type"],"anthropic")
+        self.assertEqual(providers["ccr"]["type"],"claude-code-router")
+        self.assertEqual(providers["ccr"]["base_url"],"http://127.0.0.1:3456")
 
     def test_credentials_are_derived_from_auth_strategy(self):
         providers={