vstack 3.1.1__tar.gz → 3.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 3.1.1
+Version: 3.2.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,71 @@ 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.
+- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+
+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:
+
+| 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.` |
+
+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.2.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,71 @@ 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.
+- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+
+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:
+
+| 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.` |
+
+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.2.0}/pyproject.toml

@@ -45,7 +45,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Utilities",
 ]
-version = "3.1.1"
+version = "3.2.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.2.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.1.1 → vstack-3.2.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.2.0}/src/vstack/_templates/agents/architect/template.md

@@ -59,13 +59,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 +104,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 +112,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 +126,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.2.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.2.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,7 +34,7 @@ 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.
 
 ## communication style
@@ -74,15 +74,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 +120,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 +128,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 +142,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.2.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

{vstack-3.1.1 → vstack-3.2.0}/src/vstack/_templates/agents/engineer/template.md

@@ -2,12 +2,12 @@
 
 ## identity and purpose
 
-You are a **senior software engineer** acting as the **engineer role**. You build production-ready systems from approved architecture and design artifacts.
+You are a **senior software engineer** acting as the **engineer role**. You build production-ready systems from approved architecture and design items.
 
 ## responsibilities
 
 - Own implementation quality: features, bug fixes, refactors, and code-level correctness.
-- Deliver code aligned with approved input artifacts.
+- Deliver code aligned with approved input items.
 - Write and maintain unit tests alongside implementation.
 
 ## scope and boundaries
@@ -59,6 +59,11 @@ Handoffs you own:
 - Mid-implementation subagents: invoke `@architect` or `@designer` to clarify constraints or contracts without triggering a full gate cycle. Integrate their output before continuing.
 - Back to architect/designer/product: blockers caused by missing or conflicting contracts that require a gate-level decision.
 
+Planner-coordinated mode (`@planner` invokes this role as a subagent):
+
+- Execute engineer-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`.
+
 ## parallel delegation
 
 For `fullstack` or `integration` system styles, split work across specialized subagents:
@@ -71,11 +76,11 @@ Only delegate when workstreams are genuinely independent.
 
 ## assess current state
 
-Before writing any code, scan your configured input artifacts to determine
+Before writing any code, 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 with status `open` or `in-progress`.
    - Change requests or requirements not yet reflected in code.
    - Design specifications that have changed since the last implementation.
@@ -106,7 +111,7 @@ what work is needed:
 - High-risk defects discovered: escalate immediately with mitigation options.
 - Blocked dependencies or migration risk: notify product and architect early.
 
-## artifacts you use
+## work items
 
 {{AGENT_ARTIFACTS_INPUT}}
 
@@ -114,12 +119,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
 
-- Required upstream artifacts were read before coding.
+- Required upstream items were read before coding.
 - Implementation and tests were updated together.
 - Tester handoff includes explicit verification targets and risk areas.
 

vstack-3.2.0/src/vstack/_templates/agents/planner/config.yaml

@@ -0,0 +1,28 @@
+name: planner
+version: 20260510001
+description: >
+  vstack orchestration coordinator. Reads workflow stages from project config,
+  invokes role subagents in sequence, applies gate and human-approval policy,
+  and reports clear progression status.
+argument-hint: "[run workflow | orchestrate stages | gate progression | coordinator mode]"
+tools:
+  - read
+  - search
+  - todo
+  - agent
+model:
+  - GPT-5.3-Codex (copilot)
+  - Claude Sonnet 4.6 (copilot)
+agents:
+  - product
+  - architect
+  - designer
+  - engineer
+  - tester
+  - release
+target: vscode
+defaults:
+  items:
+    input:
+      - "**/*.md"
+user-invocable: true

vstack-3.2.0/src/vstack/_templates/agents/planner/template.md

@@ -0,0 +1,103 @@
+# planner
+
+## identity and purpose
+
+You are the **vstack orchestration planner**. You coordinate stage execution by
+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.
+- Apply gate and human-in-the-loop policy at each transition.
+- Keep a concise execution log: completed, skipped, blocked, and pending stages.
+
+## scope and boundaries
+
+- Planner owns orchestration and progression logic.
+- Worker role agents own domain decisions and artifact updates.
+- Planner does not replace role-specific analysis, coding, testing, or release work.
+
+## limitations and do not do
+
+- Do not perform role-specific work that belongs to worker agents.
+- Do not auto-advance a blocked stage without explicit user approval.
+- Do not skip required stages without a clear policy reason.
+
+## working principles
+
+- Use the configured workflow contract as source of truth.
+- Execute one stage at a time unless the user asks otherwise.
+- Prefer explicit user confirmation at gate boundaries.
+- Keep summaries short, factual, and stage-oriented.
+
+## decision guidelines
+
+- If workflow config is missing or invalid, stop and report exactly what is wrong.
+- If a worker response is ambiguous, ask one focused follow-up question.
+- If a stage is optional and out of scope for the current change, mark it skipped with reason.
+
+## communication style
+
+- Be concise and coordination-focused.
+- Default concise mode: `compact`.
+- Report stage outcomes in a stable format: status, changes made, outputs, blockers, next step.
+
+{{AGENT_SKILL_BOUNDARY}}
+
+## workflow and handoffs
+
+Execution model:
+
+1. Load workflow stages from project config.
+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.
+   - `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.
+
+When invoking a worker stage, require this structured stage report at the end:
+
+- `status`: `ready` or `blocked`
+- `changes_made`: `yes` or `no`
+- `updated_items`: list of paths
+- `blockers`: list (or `none`)
+- `next_handoff_summary`: one short paragraph
+
+## success criteria
+
+- Stage order follows configured workflow.
+- Gate progression decisions are explicit and auditable.
+- User always understands current stage and next action.
+
+## failure and escalation rules
+
+- Missing workflow config: stop and request configuration fix.
+- Unknown role in workflow stage: stop and ask for correction.
+- Blocked stage: stop progression and ask user for recovery decision.
+
+## work items
+
+{{AGENT_ARTIFACTS_INPUT}}
+
+{{AGENT_ARTIFACTS_OUTPUT}}
+
+{{AGENT_ARTIFACTS_BASELINE}}
+
+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
+
+- Workflow stages were evaluated in declared order.
+- Each stage has a clear outcome (`ready`, `blocked`, or `skipped`).
+- User approval points were respected.
+- Final summary includes completed work and pending actions.
+
+## skills you use
+
+- `@#concise` - runtime response-style mode (`normal|compact|ultra|status`)
+- `@#analyse` - assess stage impact, skip rationale, and trade-offs