vstack 3.1.1__tar.gz → 3.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 3.1.1
+Version: 3.3.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -45,7 +45,7 @@ The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
 
-It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`.
+It provides six delivery roles for end-to-end software work: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`, coordinated by `planner`.
 
 ## Best for
 
@@ -55,7 +55,7 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 
 ## What you get
 
-- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release`
+- Fixed role model: six delivery roles plus a planner coordinator
 - Template-driven install model from `src/vstack/_templates/`
 - Backend-first verification, security, and release discipline
 - One runtime dependency: PyYAML
@@ -229,6 +229,130 @@ vstack install --dry-run
 
 The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
+## Reading `.vstack/config.yaml`
+
+- Lines starting with `#` are comments, explanation, or example configuration and are not active.
+- Only uncommented YAML keys are active configuration.
+- To enable an example block, remove `#` from that block and keep valid YAML indentation.
+- After any config change, run `vstack init` to apply it to generated `.github/` artifacts.
+
+## Workflow modes
+
+vstack supports three workflow modes via `.vstack/config.yaml`:
+
+```yaml
+workflow:
+  mode: agentic  # default
+```
+
+After changing `workflow.mode`, regenerate artifacts:
+
+```bash
+vstack init
+```
+
+| Mode      | Behavior                                                     | Planner file  | Worker handoff buttons |
+| --------- | ------------------------------------------------------------ | ------------- | ---------------------- |
+| `agentic` | Planner orchestrates stage progression using subagents       | generated     | omitted                |
+| `manual`  | User progresses stage-by-stage manually                      | not generated | shown                  |
+| `hybrid`  | Both planner orchestration and manual handoffs are available | generated     | shown                  |
+
+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.
+- 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:
+
+- `handoffs.prompt` is the transition prompt text.
+- If `handoffs.agent` is omitted, the target defaults to the next role in `workflow.stages`.
+- You can set `handoffs.agent` explicitly to override that default target in `manual`/`hybrid`.
+- In `agentic`, worker handoff buttons are hidden; planner controls progression.
+
+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.
+- Use `manual` when your team prefers explicit user-controlled stage transitions.
+- Use `hybrid` only when your team intentionally wants both options.
+
+Hybrid operating rule:
+
+- Choose one path per session (planner-led or manual handoffs) and stay on it.
+- Mixing both paths in one session increases the chance of duplicate stage transitions.
+
+Hybrid warning:
+
+- In `hybrid`, users can click handoff buttons while a planner-led flow is also available.
+- This can cause unintended progression jumps or duplicated transitions if your process assumes one strict path.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`

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

@@ -14,7 +14,7 @@ The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
 
-It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`.
+It provides six delivery roles for end-to-end software work: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`, coordinated by `planner`.
 
 ## Best for
 
@@ -24,7 +24,7 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 
 ## What you get
 
-- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release`
+- Fixed role model: six delivery roles plus a planner coordinator
 - Template-driven install model from `src/vstack/_templates/`
 - Backend-first verification, security, and release discipline
 - One runtime dependency: PyYAML
@@ -198,6 +198,130 @@ vstack install --dry-run
 
 The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
+## Reading `.vstack/config.yaml`
+
+- Lines starting with `#` are comments, explanation, or example configuration and are not active.
+- Only uncommented YAML keys are active configuration.
+- To enable an example block, remove `#` from that block and keep valid YAML indentation.
+- After any config change, run `vstack init` to apply it to generated `.github/` artifacts.
+
+## Workflow modes
+
+vstack supports three workflow modes via `.vstack/config.yaml`:
+
+```yaml
+workflow:
+  mode: agentic  # default
+```
+
+After changing `workflow.mode`, regenerate artifacts:
+
+```bash
+vstack init
+```
+
+| Mode      | Behavior                                                     | Planner file  | Worker handoff buttons |
+| --------- | ------------------------------------------------------------ | ------------- | ---------------------- |
+| `agentic` | Planner orchestrates stage progression using subagents       | generated     | omitted                |
+| `manual`  | User progresses stage-by-stage manually                      | not generated | shown                  |
+| `hybrid`  | Both planner orchestration and manual handoffs are available | generated     | shown                  |
+
+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.
+- 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:
+
+- `handoffs.prompt` is the transition prompt text.
+- If `handoffs.agent` is omitted, the target defaults to the next role in `workflow.stages`.
+- You can set `handoffs.agent` explicitly to override that default target in `manual`/`hybrid`.
+- In `agentic`, worker handoff buttons are hidden; planner controls progression.
+
+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.
+- Use `manual` when your team prefers explicit user-controlled stage transitions.
+- Use `hybrid` only when your team intentionally wants both options.
+
+Hybrid operating rule:
+
+- Choose one path per session (planner-led or manual handoffs) and stay on it.
+- Mixing both paths in one session increases the chance of duplicate stage transitions.
+
+Hybrid warning:
+
+- In `hybrid`, users can click handoff buttons while a planner-led flow is also available.
+- This can cause unintended progression jumps or duplicated transitions if your process assumes one strict path.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`

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

@@ -45,7 +45,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
 ]
-version = "3.1.1"
+version = "3.3.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"
@@ -74,16 +74,16 @@ include = [
 # PEP 621 mode, which otherwise causes noisy key reordering.
 
 [tool.poetry.requires-plugins]
-poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+poetry-dynamic-versioning = { version = ">=1.10.0,<2.0.0", extras = ["plugin"] }
 
 [tool.poetry.group.dev.dependencies]
-pytest = ">=9.0"
-pytest-cov = ">=6.0"
+pytest = ">=9.0.3"
+pytest-cov = ">=7.1.0"
 ruff = ">=0.15.12"
-mypy = ">=1.20.2"
+mypy = ">=2.1.0"
 pre-commit = ">=4.6.0"
-tox = ">=4.15"
-types-PyYAML = ">=6.0"
+tox = ">=4.54.0"
+types-PyYAML = ">=6.0.12.20260510"
 
 
 # ---------------------------------------------------------------------------
@@ -132,12 +132,21 @@ warn_unused_ignores = true
 warn_return_any = false
 ignore_missing_imports = true
 
+# ---------------------------------------------------------------------------
+# pylint
+# ---------------------------------------------------------------------------
+
+[tool.pylint.main]
+# Ensure src-layout imports (e.g. vstack.hooks) resolve in editor-integrated pylint runs.
+init-hook = "import sys; sys.path.insert(0, 'src')"
+py-version = "3.11"
+
 # ---------------------------------------------------------------------------
 # build system
 # ---------------------------------------------------------------------------
 
 [build-system]
-requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+requires = ["poetry-core>=2.4.0", "poetry-dynamic-versioning>=1.10.0,<2.0.0"]
 build-backend = "poetry_dynamic_versioning.backend"
 
 # ---------------------------------------------------------------------------
@@ -168,7 +177,7 @@ extraPaths = ["scripts"]
 [tool.tox]
 legacy_tox_ini = """
 [tox]
-min_version = 4.15
+min_version = 4.54.0
 env_list = py311, py312, py313, py314, lint, type
 skip_missing_interpreters = true
 
@@ -176,9 +185,9 @@ skip_missing_interpreters = true
 description = Run pytest for {env_name}
 package = skip
 deps =
-    pytest>=9.0
-    pytest-cov>=6.0
-    pyyaml>=6.0
+    pytest>=9.0.3
+    pytest-cov>=7.1.0
+    pyyaml>=6.0.3
 setenv =
     PYTHONPATH = {tox_root}/src
 commands =
@@ -188,7 +197,7 @@ commands =
 description = Run ruff lint checks
 package = skip
 deps =
-    ruff>=0.15
+    ruff>=0.15.12
 commands =
     ruff check src tests
 
@@ -196,8 +205,8 @@ commands =
 description = Run mypy type checks
 package = skip
 deps =
-    mypy>=1.20
-    types-PyYAML>=6.0
+    mypy>=2.1.0
+    types-PyYAML>=6.0.12.20260510
 commands =
     mypy src tests
 """

{vstack-3.1.1 → vstack-3.3.0}/src/vstack/_migrations/README.md

@@ -27,8 +27,9 @@ and the current package major.
 | `--dry-run`      | Print moves without touching the filesystem                     |
 
 `vstack migrate` only moves files that exist at the old path; absent files are silently
-skipped. It reads `artifacts.root` from `.vstack/config.yaml` and adjusts destination
-paths when the project uses a custom docs root.
+skipped. It reads `items.root` from `.vstack/config.yaml` (with `artifacts.root`
+as a legacy fallback) and adjusts destination paths when the project uses a custom
+docs root.
 
 ## Schema
 

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.1.1 → vstack-3.3.0}/src/vstack/_templates/agents/architect/config.yaml

@@ -4,7 +4,7 @@ description: >
   Senior software architect. Sets the system blueprint: service decomposition,
   technology direction, standards, NFRs, and organizational constraints.
   Structural decisions stay at blueprint level — interaction design is
-  designer's territory. Reads product artifacts; produces architecture overview
+  designer's territory. Reads product items; produces architecture overview
   and ADRs. Baseline-first on branch.
 argument-hint: "[design architecture | write ADR | review architecture | check implementation alignment]"
 tools:
@@ -29,7 +29,7 @@ defaults:
       design specifications as needed. If your domain is not affected by
       this change, assess and confirm that explicitly, then pass through to
       the next stage.
-  artifacts:
+  items:
     dir: architecture
     input:
       - product/**/*.md

{vstack-3.1.1 → 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.
@@ -59,13 +67,18 @@ Handoffs you own:
 - Pass-through: if the architecture is not affected by this change, confirm that explicitly before passing through.
 - Back to product: material risks, unresolved tradeoffs, and decisions requiring scope change.
 
+Planner-coordinated mode (`@planner` invokes this role as a subagent):
+
+- Execute architect-stage scope only; do not invoke downstream roles unless explicitly asked.
+- End with a stage report containing: `status`, `changes_made`, `updated_items`, `blockers`, and `next_handoff_summary`.
+
 ## assess current state
 
-Before producing any output, scan your configured input artifacts to determine
+Before producing any output, scan your configured input items to determine
 what work is needed:
 
-1. Read your input artifacts.
-1. Identify artifacts that require action:
+1. Read your input items.
+1. Identify items that require action:
    - Issues or change requests with status `open` or `draft` that touch architecture.
    - Vision or requirements that have changed since the last architecture update.
    - ADRs with status `proposed` that require a decision.
@@ -99,7 +112,7 @@ what work is needed:
 - Conflicting constraints or unresolvable tradeoffs: escalate to user with options.
 - Breaking architecture changes without migration plan: block progression.
 
-## artifacts you use
+## work items
 
 {{AGENT_ARTIFACTS_INPUT}}
 
@@ -107,8 +120,8 @@ what work is needed:
 
 {{AGENT_ARTIFACTS_BASELINE}}
 
-Agents do not write to artifacts owned by other roles. If you discover something
-that requires changes to upstream artifacts, flag it and trigger a reverse handoff.
+Agents do not write to items owned by other roles. If you discover something
+that requires changes to upstream items, flag it and trigger a reverse handoff.
 
 ## completion checklist
 
@@ -121,7 +134,7 @@ that requires changes to upstream artifacts, flag it and trigger a reverse hando
 - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`)
 - `@#architecture` — architecture document writing and review
 - `@#adr` — architecture decision record writing (when available)
-- `@#docs` — keep architecture artifacts and supporting documentation synchronized
+- `@#docs` — keep architecture items and supporting documentation synchronized
 - `@#threat-model` — design-time threat modeling (STRIDE-first, with DREAD/PASTA as needed)
 - `@#code-review` — review existing code for architectural alignment
 - `@#explore` — codebase discovery and mapping

{vstack-3.1.1 → vstack-3.3.0}/src/vstack/_templates/agents/designer/config.yaml

@@ -4,7 +4,7 @@ description: >
   Senior interaction designer. Translates architecture blueprint into
   developer-ready specifications: API contracts, event schemas, data flows,
   state models, component interfaces, and module boundaries. Reads architecture
-  artifacts; produces design overview. Baseline-first on branch.
+  items; produces design overview. Baseline-first on branch.
 argument-hint: "[write design | API contracts | event and data flows | state models | interaction review]"
 tools:
   - read
@@ -27,8 +27,8 @@ defaults:
       code and tests as needed. If your domain is not affected by this
       change, assess and confirm that explicitly, then pass through to
       engineering. If working on an issue, document findings in RCA or
-      post-mortem artifacts as relevant.
-  artifacts:
+      post-mortem items as relevant.
+  items:
     dir: design
     input:
       - architecture/**/*.md

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

@@ -26,7 +26,7 @@ You are a **senior interaction designer** acting as the **designer role**. You t
 
 - Baseline-first design docs on branch.
 - Prefer explicit schemas, error models, and flow definitions.
-- Keep design artifacts aligned with architecture constraints.
+- Keep design items aligned with architecture constraints.
 - Optimize for clarity, consistency, and implementability.
 - If a design choice affects architecture, escalate to architect.
 - Favor conventions over novelty unless justified.
@@ -34,9 +34,17 @@ You are a **senior interaction designer** acting as the **designer role**. You t
 ## decision guidelines
 
 - Prefer explicit schemas and error contracts over prose-only guidance.
-- Escalate structural implications before finalizing design artifacts.
+- 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.
@@ -74,15 +82,20 @@ Handoffs you own:
 - Pass-through: if the design is not affected by this change, confirm that explicitly before passing through.
 - Back to architect: design findings that require structural changes.
 
+Planner-coordinated mode (`@planner` invokes this role as a subagent):
+
+- Execute designer-stage scope only; do not invoke downstream roles unless explicitly asked.
+- End with a stage report containing: `status`, `changes_made`, `updated_items`, `blockers`, and `next_handoff_summary`.
+
 ## assess current state
 
-Before producing any output, scan your configured input artifacts to determine
+Before producing any output, scan your configured input items to determine
 what work is needed:
 
-1. Read your input artifacts.
-1. Identify artifacts that require action:
+1. Read your input items.
+1. Identify items that require action:
    - Architecture overview or ADRs updated since the last design revision.
-   - Issues or change requests in the architecture artifacts that affect design.
+   - Issues or change requests in the architecture items that affect design.
    - Design overview missing or inconsistent with current architecture.
 1. If nothing has changed and no open items require design work, say so
    explicitly and offer to hand off to the next stage.
@@ -115,7 +128,7 @@ what work is needed:
 - Contract conflicts with architecture: escalate before implementation.
 - Unclear requirements affecting interaction decisions: request product clarification.
 
-## artifacts you use
+## work items
 
 {{AGENT_ARTIFACTS_INPUT}}
 
@@ -123,12 +136,12 @@ what work is needed:
 
 {{AGENT_ARTIFACTS_BASELINE}}
 
-Agents do not write to artifacts owned by other roles. If you discover something
-that requires changes to upstream artifacts, flag it and trigger a reverse handoff.
+Agents do not write to items owned by other roles. If you discover something
+that requires changes to upstream items, flag it and trigger a reverse handoff.
 
 ## completion checklist
 
-- Design artifacts cover contracts, errors, and edge cases for scoped flows.
+- Design items cover contracts, errors, and edge cases for scoped flows.
 - Architectural implications have been escalated where required.
 - Engineer handoff contains concrete implementation-ready contracts.
 
@@ -137,7 +150,7 @@ that requires changes to upstream artifacts, flag it and trigger a reverse hando
 - `@#concise` — runtime response-style mode (`normal|compact|ultra|status`)
 - `@#design` — API and service design
 - `@#consult` — API ergonomics and developer experience review
-- `@#docs` — keep design artifacts and related docs aligned with delivered changes
+- `@#docs` — keep design items and related docs aligned with delivered changes
 - `@#explore` — codebase discovery and mapping
 - `@#analyse` — impact analysis, tradeoffs, feasibility
 - `@#openapi` — OpenAPI 3.1 spec writing and review

{vstack-3.1.1 → vstack-3.3.0}/src/vstack/_templates/agents/engineer/config.yaml

@@ -28,7 +28,7 @@ defaults:
       analysis. If this is an issue (bug, problem, or incident), also produce
       or update an RCA and, if stakeholder impact is significant, a
       post-mortem.
-  artifacts:
+  items:
     input:
       - product/**/*.md
       - architecture/**/*.md