@captain_z/zsk 1.8.3 → 1.8.5

package/templates/project-init/.zsk/config.yaml

@@ -12,6 +12,43 @@ template:
 mode: standard
 scale: auto
 
+# Provider connection profiles. Keep credentials out of this file; reference
+# environment variables or global profiles instead.
+providers: {}
+
+# Resource intents to prepare. Directories under .zsk/raws/** are created only
+# for configured resources that actually produce snapshots.
+resources: []
+
+# Routes map prepared resources into controlled consumption surfaces such as
+# .zsk/modules/<module>/_issues or module source references.
+routes: []
+
+modules:
+  root: .zsk/modules
+  index: .zsk/modules/index.md
+  registry: []
+
+# Demo login bootstrap. Keep real credentials in local env files; put only env
+# key names here, then run `zsk demo auth -m <module>` once to save storageState.
+# automation:
+#   demo:
+#     auth:
+#       required: true
+#       loginUrl: http://localhost:3000/login
+#       storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+#       envFiles:
+#         - ~/.zshrc
+#       env:
+#         username: DEMO_USERNAME
+#         password: DEMO_PASSWORD
+#       selectors:
+#         username: input[name="username"]
+#         password: input[type="password"]
+#         submit: button[type="submit"]
+
+# Current prepare implementation compatibility tree. New resource preparation
+# should prefer providers/resources/routes above as the stable config surface.
 sources: {}
 
 customize:

package/templates/project-init/.zsk/docs/CONFIG-SCHEMA.md

@@ -0,0 +1,127 @@
+# Config Schema
+
+`.zsk/config.yaml` is the project control surface. It should describe intent,
+not runtime results.
+
+## Top-Level Blocks
+
+| Block | Purpose |
+| --- | --- |
+| `project` | Stable project identity. |
+| `template` | ZSK template id and version. |
+| `providers` | Connection profiles such as Jira, Confluence, GitHub, GitLab, Figma, or MCP-backed tools. |
+| `resources` | Resource intents to prepare, such as repositories, issues, documents, designs, or command/MCP outputs. |
+| `routes` | Delivery rules from prepared resources to module or shared consumption surfaces. |
+| `modules` | Module discovery settings and optional module registry entries. |
+| `customize` / `staffing` | Pointers to role, workflow, provider, or gate policy files. |
+| `sources` | Compatibility source tree used by the current prepare implementation until the Resource Preparation Module fully owns `resources`. |
+
+## Materialization
+
+The workspace does not pre-create resource directories.
+
+- `resources` entries produce `.zsk/raws/**` snapshots after sync.
+- `routes` entries may update `.zsk/modules/<module>/_issues/**`,
+  `.zsk/modules/<module>/sources.yaml`, or other controlled artifacts.
+- `zsk prepare sync` writes `.zsk/evidence/prepare/sync-report.md`.
+- Missing provider credentials or route conflicts must be visible in the report
+  with a clear state, reason, output path, and next action.
+
+## Resource Output
+
+Default raw output is derived from `type + id`, but a resource may override it
+with `output.rawPath`.
+
+```yaml
+resources:
+  - id: my-bugs
+    type: issues
+    provider: jira
+```
+
+Default output:
+
+```text
+.zsk/raws/issues/my-bugs/
+```
+
+Only configured resources with produced snapshots create directories.
+
+## Credential References
+
+`.zsk/config.yaml` stores env var names only. Put the values in the runtime
+environment, for example by exporting them from `~/.zshrc` before launching the
+shell that runs `zsk`.
+
+```yaml
+providers:
+  jira:
+    type: issues
+    adapter: jira
+    baseUrl: https://jira.example.com
+    auth:
+      env: ACCESS_TOKEN
+  confluence:
+    type: document
+    adapter: confluence
+    baseUrl: https://confluence.example.com
+    auth:
+      usernameEnv: CONFLUENCE_USER
+      passwordEnv: CONFLUENCE_PASSWORD
+```
+
+## Adapter Fallbacks
+
+`source.adapter` is reserved for built-in source adapters: `jira`,
+`confluence`, `gitlab`, and `figma`. Runtime tools such as `playwright_cli`,
+`playwright_mcp`, `browser_use`, and `computer_use` are fallback or observation
+surfaces, not provider adapters.
+
+Use `fallback` when a source may need a runtime-assisted acquisition path:
+
+```yaml
+sources:
+  product:
+    prd:
+      type: prd
+      origin:
+        kind: url
+        url: https://example.com/prd
+      fallback:
+        acquisition: [playwright_cli]
+        observation: [computer_use]
+```
+
+Compatibility note: if an older config puts `playwright_cli` or `computer_use`
+under `adapter`, config check accepts it with a warning and treats it as a
+fallback alias. `computer_use` remains observation-only; prepare sync will not
+silently launch a Computer Use session.
+
+## Demo Auth
+
+Authenticated demos should configure login resources by reference. Keep real
+credentials in local env files such as `~/.zshrc`; put only env key names in
+`.zsk/config.yaml`.
+
+```yaml
+automation:
+  demo:
+    auth:
+      required: true
+      loginUrl: http://localhost:3000/login
+      storageState: .zsk/modules/{module}/_playwright/.auth/user.json
+      envFiles:
+        - ~/.zshrc
+      env:
+        username: DEMO_USERNAME
+        password: DEMO_PASSWORD
+      selectors:
+        username: input[name="username"]
+        password: input[type="password"]
+        submit: button[type="submit"]
+```
+
+`zsk demo auth -m <module>` writes a module-local Playwright login helper that
+loads those env files, fills configured fields when selectors are available,
+then saves reusable `storageState`. Generated demo specs reuse the same
+`storageState` and fail fast if they are redirected back to a login page.

package/templates/project-init/.zsk/docs/PROJECT-CONFIG.md

@@ -19,9 +19,10 @@ Use this layer to answer three questions before execution:
 | Path | Purpose |
 | --- | --- |
 | `.zsk/config.yaml` | Machine-readable project config and path authority |
-| `.zsk/docs/` | Project-level docs such as this file and `SYSTEM-SPEC.md` |
+| `.zsk/roles.yaml` | Project staffing policy and role pool overrides |
+| `.zsk/docs/` | Project-level docs such as this file, `SYSTEM-SPEC.md`, `CONFIG-SCHEMA.md`, and `SECURITY.md` |
 | `.zsk/modules/{module}/` | Module `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
-| `.zsk/raws/` | Immutable raw fact sources and manifest/index files |
+| `.zsk/raws/` | Config-driven Resource Snapshot Library |
 | `.zsk/modules/{module}/_issues/` | Module-private issue records, created on demand |
 | `.zsk/modules/{module}/_evidence/` | Module-private evidence, screenshots, traces, logs, and verification artifacts, created on demand |
 | `.zsk/modules/{module}/_playwright/` | Module-specific Playwright specs, plans, auth state, results, reports, and execution records, created on demand |
@@ -33,8 +34,8 @@ Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write tar
 
 1. `.zsk/config.yaml`
 2. `.zsk/docs/SYSTEM-SPEC.md`
-3. Project resource origins listed under `.zsk/config.yaml#sources`
-4. `.zsk/raws/manifest.json` and `.zsk/raws/index.md`
+3. Project provider/resource/route intent in `.zsk/config.yaml`
+4. Materialized resource snapshots under `.zsk/raws/**`
 5. `.zsk/modules/{module}/module.yaml`
 6. `.zsk/modules/{module}/spec.md`
 7. `.zsk/modules/{module}/design.md`
@@ -53,9 +54,56 @@ Every module stage document is a handoff contract:
 
 If a document cannot answer its stage questions, stop and record the missing source, decision, blocker, or issue instead of filling the template.
 
+## Resource Snapshot Contract
+
+`prepare sync` materializes configured resources under `.zsk/raws/**`; init does
+not create resource subdirectories or empty indexes.
+
+Default resource output is derived from `type + id`, for example:
+
+| Resource | Default Snapshot Path |
+| --- | --- |
+| `type: repository`, `id: core-api` | `.zsk/raws/repositories/core-api/` |
+| `type: issues`, `id: my-bugs` | `.zsk/raws/issues/my-bugs/` |
+| `type: document`, `id: role-prd` | `.zsk/raws/document/role-prd/` |
+
+Each snapshot directory should contain a human-readable `snapshot.md`, redacted
+`metadata.yaml`, ignored `source.json`, and ignored `assets/` when raw payloads
+or exports exist. Directory-style resources such as git submodules may also
+contain a `repository/` checkout.
+
+## Prepare Capture Strategy
+
+`prepare` records where facts come from and whether they can be acquired. It is
+not a requirement author, interaction designer, code designer, or task planner.
+
+Use this order for source capture:
+
+1. Register provider profiles, resource intents, and routes in `.zsk/config.yaml`.
+2. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
+   sources before writing snapshots.
+3. Run `zsk prepare auth-check` for private URLs so credentials are verified
+   without writing source content. The command reads exported env vars such as
+   `ACCESS_TOKEN`, `CONFLUENCE_USER`, and `CONFLUENCE_PASSWORD`; it never reads
+   `~/.zshrc` directly or prints secret values.
+4. Run `zsk prepare sync` for local/provider/export sources, adding
+   `--allow-network`, `--browser`, and `--auth-state` only when that acquisition
+   is intentional.
+5. Review `.zsk/evidence/prepare/sync-report.md` before downstream stages
+   consume the snapshot.
+
+For Figma or similar design tools, prefer provider API/export payloads, raw node
+exports, screenshots/assets, and local design-source maps over a bare page URL.
+Browser-rendered capture is useful evidence, but it is not complete interaction
+truth. Pair design snapshots with a reviewed
+`.zsk/raws/prepare/ux/{topic}/interaction-handoff.md` when page/module behavior,
+states, empty/error/loading flows, or accessibility rules are needed. For
+module-targeted preproposal work, `{topic}` defaults to the module id unless a
+narrower page/frame split is justified in the raw artifact.
+
 ## Maintenance Checklist
 
-- Update `.zsk/config.yaml` when paths, tools, or source origins change.
+- Update `.zsk/config.yaml` when providers, resources, routes, modules, paths, or tools change.
 - Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.
 - Keep module-specific decisions in `.zsk/modules/{module}/`.
 - Keep shared raw source facts under `.zsk/raws/`.

package/templates/project-init/.zsk/docs/README.md

@@ -0,0 +1,10 @@
+# ZSK Docs
+
+Project-wide governance documents live here.
+
+- `PROJECT-CONFIG.md` explains workspace layout and source authority.
+- `SYSTEM-SPEC.md` records project-wide operating rules.
+- `CONFIG-SCHEMA.md` explains the local config shape used by this project.
+- `SECURITY.md` records raw payload, credential, and commit policy.
+
+Keep module-specific proposal/spec/design/tasks under `.zsk/modules/<module>/`.

package/templates/project-init/.zsk/docs/SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+`prepare sync` can touch private provider data. Keep security rules visible in
+the project, not only in implementation.
+
+## Credentials
+
+- Do not write tokens, cookies, passwords, or authorization headers in
+  `.zsk/config.yaml`.
+- Reference credentials by environment variable or global profile.
+- Shell startup files such as `~/.zshrc` may export those variables, but ZSK
+  only reads the already exported `process.env` values. It does not parse shell
+  startup files or persist their values.
+- For Jira, use a token env such as `ACCESS_TOKEN`.
+- For Confluence instances that do not support access tokens, use Basic auth
+  env names such as `CONFLUENCE_USER` and `CONFLUENCE_PASSWORD`.
+- Readiness reports may say that an env var or profile is present, but must not
+  print secret values.
+
+## Raw Payloads
+
+- `source.json` is ignored by default.
+- `assets/` is ignored by default.
+- `snapshot.md`, `metadata.yaml`, and `sync-report.md` must be redacted before
+  write.
+- `output.commitRaw: true` is required before raw payloads become commit
+  candidates.
+
+## Redaction
+
+Provider payloads must pass through a sanitizer before writing `source.json`,
+`snapshot.md`, `metadata.yaml`, or reports. At minimum, redact credential-shaped
+fields such as `token`, `cookie`, `authorization`, `password`, and provider
+session headers.

package/templates/project-init/.zsk/docs/SYSTEM-SPEC.md

@@ -6,7 +6,7 @@ This document captures project-wide rules that should guide module work.
 
 The `.zsk/` workspace is this project's Halcyon layer. It keeps AI execution grounded by separating:
 
-- raw facts under `paths.raws`;
+- config-declared resource snapshots under `paths.raws`;
 - project-wide rules under `paths.docs`;
 - module-owned stage contracts under `paths.modules`;
 - runtime evidence under module `_evidence` or shared `paths.evidence`;
@@ -19,17 +19,17 @@ Agents must use the smallest sufficient lane: read local sources first, run dete
 
 - `paths.docs` stores project-level docs only.
 - `paths.modules` stores module source-of-truth docs.
-- `paths.raws` stores immutable shared source snapshots and manually provided fact sources.
-- `preproposal` may add candidate/generated product, roadmap, UX, and design-source readiness resources under `paths.raws` only when provenance, assumptions, review checkpoint status, and blockers are explicit.
+- `paths.raws` stores shared Resource Snapshots produced from configured resources.
+- Raw resource directories are not pre-created. A child directory under `paths.raws` must correspond to a configured resource output and a real sync result.
 - Module `_issues` stores module-specific actionable issue records; `paths.issues` is created on demand only for shared/global indexes or cross-module issues.
 - Module `_evidence` stores module-specific runtime evidence and verification artifacts; `paths.evidence` is created on demand only for shared/global evidence.
 - Module `_playwright` stores module-specific Playwright specs, plans, auth state, results, reports, and execution records; `paths.playwright` is created on demand only for shared Playwright assets.
 
-Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are legacy or export surfaces, not default zsk write targets.
+Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are export surfaces, not default zsk write targets.
 
 ## Testing Assets
 
-Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.raws`, normally `.zsk/raws/qa/testing`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
+Original QA, acceptance, release, and manually supplied test cases belong in configured resources and may be snapshotted under `paths.raws`. Module-derived test plans and Playwright specs belong under module `_playwright` unless they are intentionally shared under `paths.playwright`.
 
 ## Completion Feedback
 
@@ -44,9 +44,16 @@ Runtime evidence should be linked from docs, not embedded in docs.
 
 ZSK stage documents are decision artifacts. They are complete only when the next stage can act without hidden chat context.
 
+Every stage document must include `Output Quality Check` near the top, after the
+title/summary and before the body. The block is a compact quality status, not a
+log. It uses stable fields in order: `status`, `owner`, `source_basis`,
+`blocking_items`, and `next_action`; optional fields are `waiver` and
+`updated_at`. Valid statuses are `PASS`, `NEEDS_CLARIFICATION`,
+`NEEDS_REPAIR`, `BLOCKED`, and `WAIVED`.
+
 | Stage | Document Mode | Must Prove |
 | --- | --- | --- |
-| `prepare` | Evidence report | Source origins, freshness, conflicts, and raw snapshot paths are known before planning. |
+| `prepare` | Evidence report | Provider readiness, resource freshness, route results, conflicts, and raw snapshot paths are known before planning. |
 | `preproposal` | Decision brief | Product direction, MVP/phase split, UX/design readiness, assumptions, risks, and readiness review are complete before proposal when no reviewed source pack exists. |
 | `proposal` | Decision brief | Problem, user/business outcome, scope, non-goals, risks, and success criteria are explicit. |
 | `spec` | Behavior contract | FR/NFR, scenarios, edge cases, and acceptance criteria are observable and source-linked. |
@@ -58,4 +65,29 @@ ZSK stage documents are decision artifacts. They are complete only when the next
 | `ready` | Verification handoff | Fixed issues, AC, evidence, replay steps, version, and residual risks are mapped. |
 | `verify` | Independent evidence | The ready claim is replayed with fresh evidence and pass/fail issue status updates. |
 
-Each stage document must separate facts, decisions, assumptions, open questions, evidence, and next action. Do not leave template filler, untraceable "best practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
+Each stage document must separate facts, decisions, assumptions, open questions,
+evidence, and next action. Do not leave template filler, untraceable "best
+practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
+Each `Output Quality Check` must also align terminology against project context,
+configured raw sources, existing artifact IDs, and implementation names when
+implementation-facing work is touched. Conflicting, overloaded, stale, or
+translated terms must be recorded as a blocker or repaired by the owning stage.
+
+When `Output Quality Check` is `NEEDS_CLARIFICATION`, the owning stage uses
+Clarification Prelude: ask one question, show a separate recommendation, refine
+one `待写入确认表达：`, write the accepted expression to `CLAR`, update the stage
+artifact and any reusable `CONTEXT.md` term, then stop after minimal validation.
+
+## Lifecycle Ownership
+
+| Artifact / Decision | Owning Stage | Notes |
+| --- | --- | --- |
+| Provider profiles, resource intents, acquisition plan, auth readiness, raw snapshots, route results, sync report, and downstream impact evidence | `prepare` | Capture-only stage. It may classify resources as ready/stale/blocked/conflict/gap, but it does not invent requirements, interactions, architecture, or tasks. |
+| Product direction, roadmap, UX readiness, interaction handoff, design-source map | `preproposal` | Living raw artifacts. They may change after initial review, but each revision records source, status, impact, and affected downstream stages. |
+| Scope, non-goals, success criteria, high-level risks | `proposal` | Freezes the smallest useful problem/scope boundary before behavior is specified. |
+| FR, NFR, acceptance criteria, scenarios, edge cases | `spec` | Creates observable behavior contracts from proposal/source evidence. Missing quality targets remain `未指定` instead of invented. |
+| ADR / decision records for architecture, interfaces, state/data flow, storage, migration, dependency, rollback, integration, security, permission, privacy, or public API decisions | `design` | Required only for design-significant decisions. N/A must cite why no such decision exists. |
+| Proposal/spec/design/ADR alignment and executable work | `task` | Preserves FR/AC/NFR/ADR traceability into task groups, subtasks, evidence, and stop conditions. |
+
+Downstream stages consume reviewed upstream revisions. They may report gaps, but
+must not silently rewrite another stage's source of truth.

package/templates/project-init/.zsk/evidence/README.md

@@ -0,0 +1,15 @@
+# Shared Evidence
+
+Use this directory for shared evidence and reports that are not owned by a single
+module.
+
+`zsk prepare sync` writes human-readable preparation reports here, such as:
+
+```text
+.zsk/evidence/prepare/sync-report.md
+.zsk/evidence/prepare/blocked-resources.md
+```
+
+Runtime state, temporary files, traces, videos, and raw provider payloads must
+stay out of committed evidence unless a workflow explicitly promotes a redacted
+artifact.

package/templates/project-init/.zsk/issues/README.md

@@ -0,0 +1,10 @@
+# Global Issues
+
+Use this directory for global or cross-module issues:
+
+- missing provider credentials;
+- blocked resource preparation;
+- route conflicts across multiple modules;
+- architecture or governance blockers that are not owned by one module.
+
+Module-specific work belongs in `.zsk/modules/<module>/_issues/**`.

package/templates/project-init/.zsk/modules/README.md

@@ -0,0 +1,19 @@
+# Modules
+
+Modules are explicit business or delivery surfaces. `zsk init` does not create a
+fake default module.
+
+Create a module with:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+Module-local generated/manual artifacts use controlled underscore directories:
+
+- `_issues/` for module task cards and routed external issues.
+- `_evidence/` for module verification evidence.
+- `_playwright/` for module UI automation plans, specs, auth state, results, and
+  reports.
+
+These directories are created only when a real module and artifact exist.

package/templates/project-init/.zsk/modules/index.md

@@ -1,7 +1,11 @@
-# Module Index
+# Modules
 
-Generated and refreshed as modules are added.
+No modules are declared yet.
 
-| Module | Status | Notes |
-| --- | --- | --- |
-|  |  |  |
+Add modules in `.zsk/config.yaml` or run:
+
+```bash
+zsk module init -m <module-id> --name "<Module Name>"
+```
+
+This file is the module registry view. It is not a placeholder module.

package/templates/project-init/.zsk/raws/README.md

@@ -0,0 +1,34 @@
+# Raw Resource Snapshots
+
+`.zsk/raws` is the Resource Snapshot Library.
+
+This directory is config-driven. Do not create empty resource type directories
+because an adapter exists. A child directory is created only when:
+
+1. `.zsk/config.yaml` declares a resource, and
+2. `zsk prepare sync` produces a snapshot for that resource.
+
+## Snapshot Contract
+
+```text
+.zsk/raws/<resource-kind>/<resource-key>/
+  snapshot.md
+  metadata.yaml
+  source.json
+  assets/
+```
+
+`snapshot.md` is the human-readable summary. `metadata.yaml` stores provenance,
+freshness, hashes, provider readiness, and sync state. `source.json` and
+`assets/` hold raw or semi-raw provider payloads and are ignored by default.
+
+Directory-style resources, such as git submodules, may use:
+
+```text
+.zsk/raws/repositories/<resource-key>/
+  repository/
+  snapshot.md
+  metadata.yaml
+```
+
+Generated raw indexes are created by sync only after real snapshots exist.

package/templates/project-init/.zsk/roles.yaml

@@ -1,129 +1,60 @@
-# ZSK role resource pool.
-# Skills dispatch work to these roles as needed; stages and lanes are routing
-# hints, not hard limits. Projects may add roles or lane aliases freely.
+# ZSK role pool.
+#
+# This file declares reusable staffing policy. It does not describe a specific
+# run's chosen subagents; dispatch writes run-specific staffing evidence under
+# .zsk/evidence/**.
 
 version: 1
 
 roles:
-  lead-integrator:
+  leader:
     subagentType: planner
     required: true
     activation: required
-    reason: Own stage scope, dispatch boundaries, integration, and final evidence.
-
-  product-owner:
-    subagentType: analyst
-    stages: [prepare, preproposal, proposal, spec, review, verify, acceptance]
-    lanes: [product, pm, requirement, requirements, srs, prd]
-    activation: when product or requirement evidence is configured or in scope
-    reason: Interpret product scope, requirement semantics, priorities, and acceptance gaps.
-
-  business-analyst:
-    subagentType: analyst
-    stages: [preproposal, proposal, spec]
-    lanes: [business, domain, process, rules]
-    activation: when domain process or business-rule evidence is configured or in scope
-    reason: Map domain process, terminology, business rules, and edge cases.
-
-  architect:
-    subagentType: architect
-    stages: [preproposal, proposal, spec, design, review]
-    activation: when architecture, API, system-boundary, or dependency decisions are in scope
-    reason: Review system boundaries, module relationships, contracts, and technical risks.
-
-  backend-engineer:
-    subagentType: executor
-    stages: [prepare, design]
-    lanes: [backend, api, service, server, repository, repo, repos]
-    activation: when backend, API, service, repository, or data sources are configured
-    reason: Inspect backend sources, API contracts, data models, and service-boundary gaps.
-
-  frontend-engineer:
-    subagentType: executor
-    stages: [design]
-    lanes: [frontend, web, client, mobile]
-    activation: when frontend implementation, routing, state, or UI integration is in scope
-    reason: Map UI implementation, routing, state, and component integration risk.
-
-  design-specialist:
-    subagentType: designer
-    stages: [prepare, preproposal, design]
-    lanes: [design, ui, visual]
-    activation: when design, UI, visual, prototype, or asset sources are configured
-    reason: Inspect design assets, screens, visual states, and design-source gaps.
-
-  ux-specialist:
-    subagentType: designer
-    stages: [prepare, preproposal]
-    lanes: [ux, ue, user-experience, research]
-    activation: when UX, UE, user-flow, or research sources are configured
-    reason: Inspect user flows, interaction constraints, and usability ambiguity.
-
-  qa-engineer:
-    subagentType: test-engineer
-    stages: [prepare, preproposal, spec, task, coding, fix, review, verify]
-    lanes: [qa, test, testing, quality]
-    activation: when QA, test, acceptance, or quality evidence is configured or in scope
-    reason: Connect requirements to acceptance scenarios, test coverage, and verification evidence.
-
-  security-reviewer:
-    subagentType: security-reviewer
-    stages: [spec, design, review]
-    lanes: [security, sec, auth]
-    activation: when auth, permission, privacy, or data-safety boundaries are in scope
-    reason: Review trust boundaries, credentials, privacy, and abuse cases.
-
-  operations-engineer:
-    subagentType: executor
-    lanes: [ops, devops, release, deploy, platform]
-    activation: when environment, CI/CD, deployment, or platform risks are configured or in scope
-    reason: Review release, deployment, rollback, and operational risks.
-
-  auth-fetch-agent:
-    subagentType: researcher
-    stages: [prepare]
-    remoteSources: true
-    activation: when remote or provider-managed sources are configured
-    reason: Materialize remote/provider sources through explicit auth, session, and fetch contracts.
+    reason: Owns scope, sequencing, integration, and final evidence.
 
   researcher:
     subagentType: researcher
     stages: [prepare, preproposal]
-    activation: optional when current official or external evidence is required
-    reason: Collect official/current external references only when configured local sources are insufficient.
+    activation: when current external or provider evidence is required
+    reason: Fetches and validates source evidence without owning stage docs.
 
-  planner:
-    subagentType: planner
-    stages: [preproposal, task]
-    activation: when task sequencing, dependencies, and risk flags are in scope
-    reason: Sequence implementation tasks, dependencies, ownership, and evidence hooks.
+  architect:
+    subagentType: architect
+    stages: [proposal, spec, design, review]
+    activation: when Module, Interface, Implementation, dependency, or system-boundary decisions are in scope
+    reason: Challenges Module/Interface/Implementation fit and long-horizon tradeoffs.
 
   executor:
     subagentType: executor
     stages: [task, coding, fix]
-    activation: when implementation ownership, write scope, or scoped code changes are in scope
-    reason: Implement or estimate scoped code ownership and write boundaries.
+    activation: when scoped implementation changes are approved
+    reason: Applies bounded implementation changes inside assigned write scopes.
 
-  technical-writer:
-    subagentType: writer
-    stages: [proposal, archive]
-    activation: when documentation structure, decision records, or handoff clarity are in scope
-    reason: Preserve traceable docs, decisions, and reusable learning.
-
-  senior-engineering-reviewer:
+  reviewer:
     subagentType: code-reviewer
     stages: [review]
-    activation: when execution-path correctness, maintainability, regressions, or API compatibility need review
-    reason: Review execution-path correctness, maintainability, regressions, and API boundaries.
-
-  ue-a11y-reviewer:
-    subagentType: designer
-    stages: [review]
-    activation: when UI, UX, accessibility, i18n, or visual behavior is touched
-    reason: Review UX, accessibility, i18n, and visual impacts when UI is touched.
+    activation: when risks, regressions, maintainability, or missing evidence need independent review
+    reason: Reviews behavioral risk, regressions, and missing tests or evidence.
 
   verifier:
     subagentType: verifier
     required: true
     activation: required
-    reason: Verify stage outputs against source authority and command evidence.
+    reason: Proves completion against acceptance criteria and fresh evidence.
+
+# Project-specific examples:
+#
+#   issue-curator:
+#     extends: reviewer
+#     stages: [prepare, triage]
+#     resources: [issues]
+#     artifacts: [issues]
+#     writeScopes:
+#       - .zsk/modules/*/_issues/**
+#       - .zsk/issues/**
+#
+#   confluence-researcher:
+#     extends: researcher
+#     stages: [prepare]
+#     resources: [document]