vstack 3.2.0__tar.gz → 3.3.0__tar.gz

{vstack-3.2.0 → vstack-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 3.2.0
+Version: 3.3.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -261,7 +261,41 @@ Execution semantics:
 
 - `workflow.stages` order is the canonical progression order.
 - `agentic` is stage-sequential by default: planner advances one stage at a time in configured order.
-- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+- Set `depends_on` to unlock a DAG topology and let planner run independent branches in parallel.
+
+**Parallel stages with `depends_on`:** By default each stage implicitly depends on the previous one. Add `depends_on` to declare explicit predecessors. The canonical vstack DAG (seeded automatically by `vstack install`):
+
+```yaml
+workflow:
+  mode: agentic
+  version: 1
+  stages:
+    - role: product
+      gate: required
+      hitl: always
+    - role: architect
+      gate: required
+      hitl: always
+      depends_on: [product]
+    - role: designer
+      gate: optional
+      hitl: on-change
+      depends_on: [product]        # runs in parallel with architect
+    - role: engineer
+      gate: required
+      hitl: always
+      depends_on: [architect, designer]   # waits for both
+    - role: tester
+      gate: required
+      hitl: always
+      depends_on: [engineer]
+    - role: release
+      gate: required
+      hitl: always
+      depends_on: [tester]
+```
+
+`depends_on: []` marks a root stage. Absent `depends_on` falls back to sequential. Circular dependencies are caught at install/init time.
 
 Handoff target semantics:
 
@@ -272,12 +306,37 @@ Handoff target semantics:
 
 Mode quickstart in Copilot Agent Mode:
 
+In `agentic` mode, `@planner` is the primary entry point. Start every session with `@planner` and let it drive all stage transitions automatically.
+
 | Mode      | Start here               | First prompt example                                    |
 | --------- | ------------------------ | ------------------------------------------------------- |
 | `agentic` | `@planner`               | `@planner Run the workflow for this repository change.` |
 | `manual`  | `@product`               | `@product Define requirements for this change.`         |
 | `hybrid`  | `@planner` or `@product` | `@planner Run the workflow for this repository change.` |
 
+What planner does: reads `workflow.stages` and `depends_on`, invokes each role agent as a subagent at the right time, runs independent branches in parallel when `depends_on` permits, pauses at each gate for human approval, and reports a structured stage outcome after each step. Valid role names: `product`, `architect`, `designer`, `engineer`, `tester`, `release`.
+
+Agentic runbook (copy/paste):
+
+```text
+@planner Run the workflow for this repository change.
+@planner Show current stage status, ready stages, blocked stages, and next action.
+@planner Continue with all ready stages in parallel where workflow.depends_on allows it.
+@planner Pause at required HITL gates and ask for approval before advancing.
+@planner Finalize with a release-readiness summary and list changed artifacts.
+```
+
+Troubleshooting: why planner is not running stages in parallel
+
+- Check `workflow.mode` in `.vstack/config.yaml`: parallel orchestration requires `agentic` (or planner-led `hybrid`).
+- Validate stage dependencies: run `vstack validate` to catch invalid roles, self-dependencies, and cycles.
+- Inspect `depends_on` shape: a stage runs only when all listed predecessors are `ready` or `skipped`.
+- Check implicit sequential fallback: if `depends_on` is omitted, the stage depends on the previous stage.
+- Check optional stage behavior: `gate: optional` can be skipped when unaffected, reducing apparent parallel fan-out.
+- Check blockers in stage report: any `blocked` predecessor prevents dependent stages from becoming ready.
+- Check mixed execution path: in `hybrid`, mixing manual handoffs and planner in one session can mask parallel readiness.
+- Confirm you started with planner: in `agentic`, begin with `@planner`, not a worker role agent.
+
 Usage guidance:
 
 - Use `agentic` when you want one deterministic orchestration path.

{vstack-3.2.0 → vstack-3.3.0}/README-pypi.md

@@ -230,7 +230,41 @@ Execution semantics:
 
 - `workflow.stages` order is the canonical progression order.
 - `agentic` is stage-sequential by default: planner advances one stage at a time in configured order.
-- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+- Set `depends_on` to unlock a DAG topology and let planner run independent branches in parallel.
+
+**Parallel stages with `depends_on`:** By default each stage implicitly depends on the previous one. Add `depends_on` to declare explicit predecessors. The canonical vstack DAG (seeded automatically by `vstack install`):
+
+```yaml
+workflow:
+  mode: agentic
+  version: 1
+  stages:
+    - role: product
+      gate: required
+      hitl: always
+    - role: architect
+      gate: required
+      hitl: always
+      depends_on: [product]
+    - role: designer
+      gate: optional
+      hitl: on-change
+      depends_on: [product]        # runs in parallel with architect
+    - role: engineer
+      gate: required
+      hitl: always
+      depends_on: [architect, designer]   # waits for both
+    - role: tester
+      gate: required
+      hitl: always
+      depends_on: [engineer]
+    - role: release
+      gate: required
+      hitl: always
+      depends_on: [tester]
+```
+
+`depends_on: []` marks a root stage. Absent `depends_on` falls back to sequential. Circular dependencies are caught at install/init time.
 
 Handoff target semantics:
 
@@ -241,12 +275,37 @@ Handoff target semantics:
 
 Mode quickstart in Copilot Agent Mode:
 
+In `agentic` mode, `@planner` is the primary entry point. Start every session with `@planner` and let it drive all stage transitions automatically.
+
 | Mode      | Start here               | First prompt example                                    |
 | --------- | ------------------------ | ------------------------------------------------------- |
 | `agentic` | `@planner`               | `@planner Run the workflow for this repository change.` |
 | `manual`  | `@product`               | `@product Define requirements for this change.`         |
 | `hybrid`  | `@planner` or `@product` | `@planner Run the workflow for this repository change.` |
 
+What planner does: reads `workflow.stages` and `depends_on`, invokes each role agent as a subagent at the right time, runs independent branches in parallel when `depends_on` permits, pauses at each gate for human approval, and reports a structured stage outcome after each step. Valid role names: `product`, `architect`, `designer`, `engineer`, `tester`, `release`.
+
+Agentic runbook (copy/paste):
+
+```text
+@planner Run the workflow for this repository change.
+@planner Show current stage status, ready stages, blocked stages, and next action.
+@planner Continue with all ready stages in parallel where workflow.depends_on allows it.
+@planner Pause at required HITL gates and ask for approval before advancing.
+@planner Finalize with a release-readiness summary and list changed artifacts.
+```
+
+Troubleshooting: why planner is not running stages in parallel
+
+- Check `workflow.mode` in `.vstack/config.yaml`: parallel orchestration requires `agentic` (or planner-led `hybrid`).
+- Validate stage dependencies: run `vstack validate` to catch invalid roles, self-dependencies, and cycles.
+- Inspect `depends_on` shape: a stage runs only when all listed predecessors are `ready` or `skipped`.
+- Check implicit sequential fallback: if `depends_on` is omitted, the stage depends on the previous stage.
+- Check optional stage behavior: `gate: optional` can be skipped when unaffected, reducing apparent parallel fan-out.
+- Check blockers in stage report: any `blocked` predecessor prevents dependent stages from becoming ready.
+- Check mixed execution path: in `hybrid`, mixing manual handoffs and planner in one session can mask parallel readiness.
+- Confirm you started with planner: in `agentic`, begin with `@planner`, not a worker role agent.
+
 Usage guidance:
 
 - Use `agentic` when you want one deterministic orchestration path.

{vstack-3.2.0 → vstack-3.3.0}/pyproject.toml

@@ -45,7 +45,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
 ]
-version = "3.2.0"
+version = "3.3.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"

vstack-3.3.0/src/vstack/_templates/agents/_partials/agent-skill-boundary.md

@@ -0,0 +1,7 @@
+## agent-skill boundary
+
+- **You (agent) = who/what/when** — decisions, scope, escalation, and handoffs within your role.
+- **Skills = how** — detailed procedures, checklists, and execution playbooks.
+- Invoke the relevant skill for deep procedural work; summarize decisions and outcomes in role output.
+- **Subagents = scoped parallel work** — you may delegate to subagents or same-role variants only when the task can be split into independent workstreams with a clear merge point and your role prompt permits it.
+- Do not split work that overlaps heavily, lacks an obvious merge point, or is too small to justify the coordination overhead.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/architect/template.md

@@ -37,6 +37,14 @@ You are a **senior software architect** acting as the **architect role**. You de
 - Capture significant structural choices in ADRs.
 - Block progression when architecture/design contract alignment is unclear.
 
+## parallel delegation
+
+- If the scope naturally decomposes into independent architecture questions, you may split work across subagents or same-role variants.
+- Good split candidates include separate ADRs, distinct failure-mode analyses, boundary decisions, and architecture overview updates when they do not depend on one another.
+- Only split when each workstream has a clear merge point and the architectural conclusions are not mutually dependent.
+- Do not split tightly coupled blueprint decisions that require one consistent system view.
+- Make each delegated context explicit in the output so the resulting architecture baseline remains auditable.
+
 ## communication style
 
 - Structured, opinionated, and evidence-based.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/designer/template.md

@@ -37,6 +37,14 @@ You are a **senior interaction designer** acting as the **designer role**. You t
 - Escalate structural implications before finalizing design items.
 - Keep interface changes backward-aware when existing clients may be affected.
 
+## parallel delegation
+
+- If the design surface decomposes cleanly, you may split work across subagents or same-role variants.
+- Good split candidates include API contracts, event schemas, state models, UX flows, and module boundaries when they do not share a mandatory merge decision.
+- Only split when each design stream can be validated independently and recombined without ambiguity.
+- Do not split tightly coupled interface decisions that require one coherent contract set.
+- Make the merge point explicit so downstream implementation work sees one actionable design baseline.
+
 ## communication style
 
 - Concrete and specification-oriented.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/planner/template.md

@@ -7,11 +7,20 @@ invoking role agents as subagents and enforcing explicit gate progression.
 
 ## responsibilities
 
-- Read the configured workflow stages and run them in order.
-- Invoke the correct role agent for each stage.
+- Read the configured workflow stages and evaluate `depends_on` to determine execution order.
+- Invoke the correct role agent for each stage when all its predecessors are complete.
+- Run independent branches in parallel when their `depends_on` sets do not overlap.
 - Apply gate and human-in-the-loop policy at each transition.
 - Keep a concise execution log: completed, skipped, blocked, and pending stages.
 
+## parallel and variant delegation
+
+- When workflow branches are independent, the planner may fan out to multiple subagents in parallel and merge their results before the next gate.
+- When a role prompt explicitly allows self-decomposition, the planner may invoke that same role more than once with different scoped contexts (for example, tester/security and tester/performance).
+- Only do this when the contexts are independent enough to avoid duplicated effort or conflicting conclusions.
+- Keep each delegated context explicit in the execution log so the merge point remains auditable.
+- Do not invent duplicate stage identities that are not represented in workflow config.
+
 ## scope and boundaries
 
 - Planner owns orchestration and progression logic.
@@ -27,7 +36,11 @@ invoking role agents as subagents and enforcing explicit gate progression.
 ## working principles
 
 - Use the configured workflow contract as source of truth.
-- Execute one stage at a time unless the user asks otherwise.
+- Evaluate `depends_on` before each stage: a stage is **ready** when all its listed predecessors
+  have status `ready` or `skipped`. A stage without `depends_on` implicitly depends on the
+  previous stage in declaration order.
+- Run all ready stages before advancing past a gate boundary. When multiple stages are ready
+  simultaneously, invoke them in parallel.
 - Prefer explicit user confirmation at gate boundaries.
 - Keep summaries short, factual, and stage-oriented.
 
@@ -49,15 +62,23 @@ invoking role agents as subagents and enforcing explicit gate progression.
 
 Execution model:
 
-1. Load workflow stages from project config.
+1. Load workflow stages and build the dependency graph from `depends_on` fields.
+   - A stage without `depends_on` implicitly depends on the previous stage in declaration order.
+   - `depends_on: []` marks a stage as a root with no predecessors.
 1. Read `workflow.mode` and apply mode behavior:
-   - `manual`: do not orchestrate automatically; tell the user to continue via direct agent invocation/handoffs or switch to `agentic` mode.
-   - `agentic`: orchestrate stages sequentially and treat planner as the progression controller.
+   - `manual`: do not orchestrate automatically; tell the user to continue via direct agent
+     invocation/handoffs or switch to `agentic` mode.
+   - `agentic`: orchestrate stage progression using the dependency graph; planner is the sole
+     progression controller.
    - `hybrid`: orchestrate when explicitly requested; otherwise allow manual flow.
-1. For each stage, invoke the mapped role agent as a subagent.
-1. Capture stage result and evaluate gate policy.
-1. Pause for user approval when required.
-1. Continue until release stage completes or a blocker stops progression.
+1. Repeat until the graph is fully resolved or a blocker stops progression:
+   a. Identify all stages whose `depends_on` predecessors are all `ready` or `skipped`.
+   These are the **ready set**.
+   b. Invoke all stages in the ready set. Stages with no unresolved predecessors may run
+   in parallel.
+   c. Collect stage reports and mark each stage `ready`, `skipped`, or `blocked`.
+   d. Evaluate gate and hitl policy. Pause for user approval where required before continuing.
+1. Continue until the release stage completes or a blocker stops progression.
 
 When invoking a worker stage, require this structured stage report at the end:
 
@@ -69,7 +90,9 @@ When invoking a worker stage, require this structured stage report at the end:
 
 ## success criteria
 
-- Stage order follows configured workflow.
+- Dependency graph was evaluated before each stage transition.
+- All ready stages ran before each gate boundary advanced.
+- Independent branches ran in parallel where `depends_on` permitted.
 - Gate progression decisions are explicit and auditable.
 - User always understands current stage and next action.
 
@@ -92,7 +115,9 @@ that requires changes to upstream items, flag it and trigger a reverse handoff.
 
 ## completion checklist
 
-- Workflow stages were evaluated in declared order.
+- Dependency graph was evaluated; stages ran only after all predecessors were complete.
+- All ready stages were identified before advancing past each gate.
+- Independent branches ran in parallel where `depends_on` permitted.
 - Each stage has a clear outcome (`ready`, `blocked`, or `skipped`).
 - User approval points were respected.
 - Final summary includes completed work and pending actions.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/product/template.md

@@ -37,6 +37,14 @@ You are a **senior product manager** acting as the **product role**. You define
 - Prefer small, reviewable scope slices over broad ambiguous deliveries.
 - Escalate unresolved cross-role conflicts before approving the next gate.
 
+## parallel delegation
+
+- If discovery naturally separates into independent tracks, you may split work across subagents or same-role variants.
+- Good split candidates include vision, requirements, roadmap shaping, and release-scope analysis when they can be merged back into one acceptance story.
+- Only split when the tracks are independent enough to avoid contradictory scope decisions.
+- Do not split the final acceptance decision or any scope slice that requires a single integrated product judgment.
+- Keep the merge point explicit so downstream roles receive one coherent baseline.
+
 ## communication style
 
 - Be concise, explicit, and decision-oriented.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/release/template.md

@@ -37,6 +37,14 @@ You are a **senior platform and release engineer** acting as the **release role*
 - Treat contradictory evidence as a blocker until reconciled.
 - Prioritize auditability and deterministic release records.
 
+## parallel delegation
+
+- If evidence gathering or sign-off collection can be separated safely, you may split it across subagents or same-role variants.
+- Good split candidates include independent baseline checks, artifact validation, and role-perspective review collection when the findings can be merged before the final release decision.
+- Only split when the outputs are independent and the final release gate still remains a single coherent decision.
+- Do not split the release verdict itself or any activity that would create conflicting acceptance signals.
+- Record the merge point explicitly so the release record stays deterministic and auditable.
+
 ## communication style
 
 - Gate-oriented and explicit about pass/fail state.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/agents/tester/template.md

@@ -38,6 +38,14 @@ You are a **senior QA, security, and reliability engineer** acting as the **test
 - Escalate immediately when required evidence cannot be produced.
 - Use explicit go/no-go language for release readiness.
 
+## parallel delegation
+
+- If the verification scope spans independent dimensions, you may split the work into specialized subagents and run them in parallel.
+- Good split candidates include security, performance, functional correctness, compatibility, and regression checks when those areas do not share critical setup or state.
+- Only split when each subagent has a clearly bounded context and the results can be merged into one verdict.
+- Do not split narrow or tightly coupled test scopes; the coordination overhead will outweigh the benefit.
+- Make the subagent context explicit in the report so the merge step is reproducible.
+
 ## communication style
 
 - Clear verdicts with severity and reproduction steps.

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/_templates/project/.vstack/config.yaml

@@ -135,9 +135,12 @@
 #
 # Execution order:
 # - Stage order in workflow.stages is the canonical progression order.
-# - agentic is stage-sequential by default (planner advances per stage in order).
-# - Parallel work can still happen inside a stage (for independent subtasks),
-#   but cross-stage progression remains ordered by workflow.stages.
+# - Without depends_on, each stage implicitly depends on the previous stage
+#   (fully sequential, backward-compatible behavior).
+# - Set depends_on explicitly to enable DAG orchestration and parallel branches.
+#   Example: architect and designer can both depend on product.
+# - Use depends_on: [] to make a stage an independent root.
+# - In agentic mode planner can evaluate ready stages from dependency completion.
 #
 # Handoffs:
 # - handoffs.prompt is the message used when transitioning to the next stage.
@@ -156,6 +159,7 @@
 # gate: required   — stage always runs
 # gate: optional   — stage may be skipped when its domain is unaffected
 # gate: skip        — stage is never executed (explicit opt-out)
+# depends_on: []    — optional list of prerequisite stage roles
 #
 # hitl: always     — pipeline pauses for human approval before handoff (default for required)
 # hitl: on-change  — pipeline pauses only when the stage made changes (default for optional)
@@ -188,15 +192,20 @@ workflow:
     - role: architect
       gate: required
       hitl: always
+      depends_on: [product]
     - role: designer
       gate: optional
       hitl: on-change
+      depends_on: [product]
     - role: engineer
       gate: required
       hitl: always
+      depends_on: [architect, designer]
     - role: tester
       gate: required
       hitl: always
+      depends_on: [engineer]
     - role: release
       gate: required
       hitl: always
+      depends_on: [tester]

{vstack-3.2.0 → vstack-3.3.0}/src/vstack/agents/generator.py

@@ -260,16 +260,37 @@ class AgentGenerator(GenericArtifactGenerator):
                 }
             ]
 
-        roles = [s["role"] for s in self.workflow_stages]
-        try:
-            idx = roles.index(agent_role)
-        except ValueError:
-            return []
-        if idx >= len(roles) - 1:
+        stage_by_role = {
+            str(stage.get("role", "")).strip(): stage for stage in self.workflow_stages
+        }
+        if agent_role not in stage_by_role:
             return []
-        next_role = roles[idx + 1]
 
-        stage_handoffs: list[dict[str, str]] = self.workflow_stages[idx].get("handoffs", [])
+        dependencies_by_role: dict[str, list[str]] = {}
+        ordered_roles = [str(stage.get("role", "")).strip() for stage in self.workflow_stages]
+        role_set = set(ordered_roles)
+        for index, role in enumerate(ordered_roles):
+            stage = stage_by_role.get(role, {})
+            if "depends_on" in stage:
+                raw_depends_on = stage.get("depends_on", [])
+                depends_on = raw_depends_on if isinstance(raw_depends_on, list) else []
+                normalized = []
+                for dep in depends_on:
+                    dep_role = str(dep).strip()
+                    if dep_role and dep_role in role_set and dep_role not in normalized:
+                        normalized.append(dep_role)
+                dependencies_by_role[role] = normalized
+            elif index > 0:
+                dependencies_by_role[role] = [ordered_roles[index - 1]]
+            else:
+                dependencies_by_role[role] = []
+
+        next_roles = [
+            role for role in ordered_roles if agent_role in dependencies_by_role.get(role, [])
+        ]
+        primary_next_role = next_roles[0] if next_roles else ""
+
+        stage_handoffs: list[dict[str, str]] = stage_by_role[agent_role].get("handoffs", [])
         if not isinstance(stage_handoffs, list):
             stage_handoffs = []
 
@@ -278,12 +299,15 @@ class AgentGenerator(GenericArtifactGenerator):
         if not stage_handoffs:
             if not handoff_prompt.strip():
                 return []
+            if not next_roles:
+                return []
             return [
                 {
                     "label": f"Go to next stage: {next_role.capitalize()}",
                     "agent": next_role,
                     "prompt": handoff_prompt.strip(),
                 }
+                for next_role in next_roles
             ]
 
         result: list[dict[str, str]] = []
@@ -293,7 +317,9 @@ class AgentGenerator(GenericArtifactGenerator):
             if not isinstance(h, dict):
                 continue
             h_agent = str(h.get("agent", "") or "").strip()
-            target_agent = h_agent or next_role
+            target_agent = h_agent or primary_next_role
+            if not target_agent:
+                continue
 
             # Apply per-agent handoff_prompt override to the first handoff that
             # targets the natural next stage (no explicit agent override).