@captain_z/zsk 1.7.0 → 1.8.2

package/templates/module/frontend-module/proposal.md

@@ -1,7 +1,49 @@
 # __MODULE_NAME__ Proposal
 
+## Project Rules Gate
+
+| Rule Source | Rule / Constraint | Proposal Impact | Status |
+| --- | --- | --- | --- |
+| `.zsk/docs/PROJECT-CONFIG.md` |  |  | TODO |
+| `.zsk/docs/SYSTEM-SPEC.md` |  |  | TODO |
+
+Do not draft or pass this proposal until project-level path, source-priority, evidence, issue-routing, and stage-document rules from both files are reflected here or explicitly blocked.
+
+## Problem
+
+- Target user / stakeholder:
+- Problem:
+- Why now:
+- Source evidence:
+- Project-rule evidence:
+
+## Scope
+
+- In scope:
+- Out of scope:
+- Assumptions:
+- Open questions / blockers:
+
+## Success Criteria
+
+| Criterion | Evidence Source | Owner / Next Stage |
+| --- | --- | --- |
+|  |  |  |
+
+## Risks And Rejected Alternatives
+
+| Item | Decision | Rationale / Evidence |
+| --- | --- | --- |
+|  |  |  |
+
+## Best-Practice Checklist
+
+- [ ] Problem, target user, business outcome, scope, non-goals, success criteria, risks, and blockers are explicit.
+- [ ] Local configured sources were used before external/current research.
+- [ ] External/current research, if used, is separated from accepted product requirements.
+- [ ] Conflicts with `PROJECT-CONFIG.md` or `SYSTEM-SPEC.md` are recorded as blockers or issues.
+
 ## Documentation Feedback
 
 - No-update rationale:
   - Created from the ZSK module template; no proposal has been drafted yet.
-

package/templates/module/frontend-module/spec.md

@@ -1,5 +1,26 @@
 # __MODULE_NAME__ Spec
 
+## Project Rules Gate
+
+| Rule Source | Rule / Constraint | Behavior Impact | Status |
+| --- | --- | --- | --- |
+| `.zsk/docs/PROJECT-CONFIG.md` |  |  | TODO |
+| `.zsk/docs/SYSTEM-SPEC.md` |  |  | TODO |
+
+Do not freeze this spec until source-priority, conflict-routing, evidence, and stage-document rules from both project files are reflected in requirements, scenarios, and acceptance criteria.
+
+## Behavior Contract
+
+| ID | Requirement | Type | Source / Decision | Priority | Observable Outcome |
+| --- | --- | --- | --- | --- | --- |
+| FR-001 |  | FR |  | P0 |  |
+
+## Acceptance Criteria
+
+| AC | Linked Requirement | Given / When / Then | Evidence Route |
+| --- | --- | --- | --- |
+| AC-001 | FR-001 | Given  / When  / Then  |  |
+
 ## Scenario Contracts
 
 | Scenario | User Goal | Entry | Preconditions | Observable Result | PRD/SRS / FR/AC | Automate |
@@ -10,9 +31,18 @@ Rules:
 
 - Define behavior and observable outcomes here.
 - Link every P0/P1 scenario back to the original PRD/SRS or accepted FR/AC.
+- Link every project-wide rule that changes behavior back to `PROJECT-CONFIG.md` or `SYSTEM-SPEC.md`.
 - Mark unclear or conflicting facts as blockers instead of choosing behavior silently.
 - Do not write brittle selectors in spec.
 - Mark which P0/P1 scenarios must become Playwright cases.
+- Keep implementation choices out unless they are part of the product contract.
+
+## Best-Practice Checklist
+
+- [ ] FR/NFR, scenarios, edge cases, and acceptance criteria are observable.
+- [ ] Every P0/P1 behavior has a source link or is explicitly marked as an assumption/blocker.
+- [ ] Project military rules from `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md` are enforced or blocked.
+- [ ] Design can proceed without hidden chat context.
 
 ## Documentation Feedback
 

package/templates/module/frontend-module/tasks.md

@@ -1,5 +1,44 @@
 # __MODULE_NAME__ Tasks
 
+## Project Rules Gate
+
+| Rule Source | Rule / Constraint | Task Impact | Status |
+| --- | --- | --- | --- |
+| `.zsk/docs/PROJECT-CONFIG.md` |  |  | TODO |
+| `.zsk/docs/SYSTEM-SPEC.md` |  |  | TODO |
+
+Do not start coding until path boundaries, evidence routing, issue routing, validation commands, and source-priority rules from both project files are reflected in the task list or recorded as blockers.
+
+## Task Todo List
+
+- [ ] T-001:
+  - Owner:
+  - Depends on:
+  - Scope / files:
+  - Linked FR/AC:
+  - Evidence hook:
+  - Stop condition:
+  - [ ] T-001.1:
+    - Owner:
+    - Output:
+    - Evidence:
+  - [ ] T-001.2:
+    - Owner:
+    - Output:
+    - Evidence:
+
+## Dependency Order
+
+| Order | Task / Subtask | Depends On | Can Run In Parallel With | Blocker / Decision Needed |
+| --- | --- | --- | --- | --- |
+| 1 | T-001.1 |  |  |  |
+
+## Coverage Matrix
+
+| FR/AC | Implementation Task/Subtask | Test / Scenario Task/Subtask | Docs / Issue / Evidence Task/Subtask |
+| --- | --- | --- | --- |
+| FR-001 / AC-001 | T-001.1 | T-001.2 |  |
+
 ## Playwright Case Tasks
 
 | Task | Scenario Contract | Case File | Fixture/Auth | Reuse Target | Status |
@@ -8,10 +47,14 @@
 
 Rules:
 
+- Use a Kiro-style checkbox hierarchy: task IDs for deliverables, subtask IDs for executable steps.
+- Every task and subtask must have owner, dependency, output, evidence hook, and stop condition.
 - Create Playwright skeletons under `__PLAYWRIGHT_SPECS__` before demo.
 - Create or update source-aligned tests/scenarios before implementation for testable behavior changes.
 - Tag cases as smoke/demo/verify/regression.
 - Include tasks for labels/test ids required by stable locators.
+- Do not create vague tasks such as "implement feature"; each task needs scope, dependency, and evidence.
+- Do not treat docs feedback, issue updates, evidence capture, or verification as optional cleanup.
 
 ## Documentation Feedback
 

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

@@ -5,100 +5,14 @@ layoutVersion: 2
 project:
   name: "<project-name>"
 
-paths:
-  docs: .zsk/docs
-  modules: .zsk/modules
-  resources: .zsk/resources
-  issues: .zsk/issues
-  evidence: .zsk/evidence
-  playwright: .zsk/playwright
-  plans: .zsk/plans
+template:
+  id: founder-os
+  version: 1
 
-# Resource origins. AI or zsk config setup should fill these with online URLs,
-# git repositories, Figma/Modao links, OpenAPI locations, or local files.
-# Optional snapshots should land under paths.resources, for example:
-#
-# sources:
-#   srs:
-#     type: srs
-#     origin:
-#       kind: url
-#       url: https://example.com/srs
-#     snapshot: .zsk/resources/requirements/srs.md
-#   figma_main:
-#     type: design
-#     origin:
-#       kind: figma
-#       url: https://www.figma.com/file/...
-#     snapshot: .zsk/resources/design-sources/figma-main.json
-#   backend_api:
-#     type: backend_repo
-#     origin:
-#       kind: git
-#       repository: https://github.com/example/backend-api.git
-#       path: openapi.yaml
-#     snapshot: .zsk/resources/backend-repositories/backend-openapi.yaml
-#   acceptance_cases:
-#     type: test_case
-#     origin:
-#       kind: url
-#       url: https://example.com/qa-cases
-#     snapshot: .zsk/resources/testing/acceptance-cases.md
-sources: {}
-
-tools:
-  runtime_ui:
-    - playwright_cli
-    - playwright_mcp
-    - playwright
-    - computer_use
-    - browser_use
-  design:
-    - figma_mcp
+mode: standard
+scale: auto
 
-modules:
-  index: .zsk/modules/_module-index.md
-  root: .zsk/modules
+sources: {}
 
-automation:
-  smoke:
-    commands:
-      - pnpm lint
-      - pnpm typecheck
-      - pnpm test
-  deploy:
-    command: pnpm deploy:staging
-  demo:
-    # Default optimized lane:
-    # - Formal test cases come from module tests.raw_cases or sources.testing, normally snapshots under .zsk/resources/testing.
-    # - Playwright storageState is the preferred way to reuse login/session state without stopping on login pages.
-    # - Computer Use is the preferred visual/current-page observation lane when it is available and authorized.
-    # - Browser Use is optional and runtime-specific; use it only where the agent platform supports it and permissions are available.
-    # - If neither Computer Use nor Browser Use exists, use Playwright MCP/ARIA/CDP snapshots or documented manual evidence as the compatible handoff.
-    # - zsk/agent generation writes test-plan.json, then Playwright CLI/Skills generate executable .spec.ts cases.
-    # - Playwright Test executes/debugs and records evidence. No MCP or bridge fallback is used in optimized mode.
-    # - Use --hybrid explicitly for the legacy bridge lane.
-    defaultMode: optimized
-    baseUrl: http://localhost:3000
-    command: pnpm dev
-    evidenceDir: .zsk/evidence/{module}/demo
-    scenarioDir: .zsk/playwright/{module}/specs
-    playwright:
-      config: playwright.config.ts
-      project: chromium
-      cli: playwright-cli
-    computerUse:
-      enabled: false
-      role: understand-and-decide
-    bridge:
-      enabled: true
-      # Legacy hybrid-only bridge. Not used by defaultMode: optimized.
-      # Prefer computer_use for visual/system-level understanding when available.
-      # Fall back to playwright_mcp for structured accessibility snapshots, or browser_use only on runtimes that support it.
-      decisionTool: playwright_mcp
-      executionTool: playwright
-      planFile: .zsk/playwright/{module}/execution/operation-plan.json
-      executionFile: .zsk/playwright/{module}/execution/playwright-execution.json
-  verify:
-    commands:
-      - pnpm test:e2e
+customize:
+  roles: .zsk/roles.yaml

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

@@ -2,6 +2,16 @@
 
 This file is the human-readable companion to `.zsk/config.yaml`.
 
+## Halcyon Layer
+
+This `.zsk/` workspace is project-specific. It is the Halcyon operating layer for this project: the place where AI agents read raw facts, produce stage documents, route issues/evidence, and prove stage completion. It is not a generic docs folder and it is not a replacement for the application's source tree.
+
+Use this layer to answer three questions before execution:
+
+- What facts and decisions are authoritative for this project?
+- Which module/stage owns the next artifact?
+- What evidence or issue update proves the stage is complete?
+
 ## Workspace Layout
 
 `zsk init` owns only the `.zsk/` workspace by default:
@@ -11,10 +21,11 @@ This file is the human-readable companion to `.zsk/config.yaml`.
 | `.zsk/config.yaml` | Machine-readable project config and path authority |
 | `.zsk/docs/` | Project-level docs such as this file and `SYSTEM-SPEC.md` |
 | `.zsk/modules/{module}/` | Module `module.yaml`, `proposal.md`, `spec.md`, `design.md`, `tasks.md` |
-| `.zsk/resources/` | Shared source snapshots and manually provided resources |
-| `.zsk/issues/` | Issues and issue indexes created on demand |
-| `.zsk/evidence/` | Runtime evidence, screenshots, traces, logs, and verification artifacts |
-| `.zsk/playwright/{module}/` | Playwright specs, plans, auth state, results, reports, and execution records |
+| `.zsk/raws/` | Immutable raw fact sources and manifest/index files |
+| `.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 |
+| `.zsk/playwright/` | Shared Playwright config/auth/helpers only, created on demand |
 
 Root `docs/`, `.raws/`, `.issues/`, and `.playwright/` are not default write targets. Use explicit export or migration tooling when you need project-root copies.
 
@@ -23,17 +34,29 @@ 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/modules/{module}/module.yaml`
-5. `.zsk/modules/{module}/spec.md`
-6. `.zsk/modules/{module}/design.md`
-7. Runtime evidence under `.zsk/evidence/` and `.zsk/playwright/`
+4. `.zsk/raws/manifest.json` and `.zsk/raws/index.md`
+5. `.zsk/modules/{module}/module.yaml`
+6. `.zsk/modules/{module}/spec.md`
+7. `.zsk/modules/{module}/design.md`
+8. Runtime evidence under module `_evidence` / `_playwright` or shared `.zsk/evidence` / `.zsk/playwright`
+
+When sources conflict, record the conflict under the module `_issues` directory, or shared `.zsk/issues` only for cross-module/global issues, and update the affected module docs with a Documentation Feedback note or an explicit no-update rationale.
+
+## Authoring Rule
+
+Every module stage document is a handoff contract:
+
+- `proposal.md` explains why the work exists, who it serves, what is in scope, what is out of scope, and how success will be recognized.
+- `spec.md` defines observable behavior, scenarios, acceptance criteria, edge cases, and source-linked assumptions.
+- `design.md` maps approved behavior to implementation surfaces, interfaces, state, data flow, risks, and verification strategy.
+- `tasks.md` breaks the design into ordered work with owners/scope, dependencies, FR/AC coverage, and evidence hooks.
 
-When sources conflict, record the conflict under `.zsk/issues/{module}/` and update the affected module docs with a Documentation Feedback note or an explicit no-update rationale.
+If a document cannot answer its stage questions, stop and record the missing source, decision, blocker, or issue instead of filling the template.
 
 ## Maintenance Checklist
 
 - Update `.zsk/config.yaml` when paths, tools, or source origins change.
 - Keep project-wide reusable rules in `.zsk/docs/SYSTEM-SPEC.md`.
 - Keep module-specific decisions in `.zsk/modules/{module}/`.
-- Keep shared raw resources under `.zsk/resources/`.
-- Keep runtime outputs out of docs and under `.zsk/evidence/` or `.zsk/playwright/`.
+- Keep shared raw source facts under `.zsk/raws/`.
+- Keep runtime outputs out of docs and under module-private `_evidence` / `_playwright` unless they are deliberately shared under `.zsk/evidence` / `.zsk/playwright`.

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

@@ -2,20 +2,33 @@
 
 This document captures project-wide rules that should guide module work.
 
+## Operating Model
+
+The `.zsk/` workspace is this project's Halcyon layer. It keeps AI execution grounded by separating:
+
+- raw facts 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`;
+- issue records under module `_issues` or shared/global `paths.issues`;
+- Playwright plans/specs/results under module `_playwright` or shared `paths.playwright`.
+
+Agents must use the smallest sufficient lane: read local sources first, run deterministic CLI checks when possible, delegate only when the work has independent expert lanes, and record blockers instead of filling missing facts from chat memory.
+
 ## Path Boundaries
 
 - `paths.docs` stores project-level docs only.
 - `paths.modules` stores module source-of-truth docs.
-- `paths.resources` stores shared source snapshots and manually provided resources.
-- `paths.issues` stores actionable issue records and indexes created on demand.
-- `paths.evidence` stores runtime evidence and verification artifacts.
-- `paths.playwright` stores Playwright specs, plans, auth state, results, reports, and execution records.
+- `paths.raws` stores immutable shared source snapshots and manually provided fact sources.
+- 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.
 
 ## Testing Assets
 
-Original QA, acceptance, release, and manually supplied test cases belong in configured project sources and may be snapshotted under `paths.resources`. Module-derived test plans and Playwright specs belong under `paths.playwright/{module}`.
+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`.
 
 ## Completion Feedback
 
@@ -25,3 +38,22 @@ Every stage document that changes durable behavior should include Documentation
 - an explicit no-update rationale.
 
 Runtime evidence should be linked from docs, not embedded in docs.
+
+## Stage Document Standards
+
+ZSK stage documents are decision artifacts. They are complete only when the next stage can act without hidden chat context.
+
+| Stage | Document Mode | Must Prove |
+| --- | --- | --- |
+| `prepare` | Evidence report | Source origins, freshness, conflicts, and raw snapshot paths are known before planning. |
+| `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. |
+| `design` | Implementation contract | Behavior maps to files/modules/interfaces/state/data flow, with risks and verification strategy. |
+| `task` | Execution plan | Work is ordered, owned, independently reviewable, and tied to FR/AC plus evidence hooks. |
+| `coding` | Implementation evidence | Changed files, behavior, tests, and residual risks are tied back to tasks. |
+| `smoke` | Evidence report | Local proof names the claim, command/scenario, result, artifacts, and failures. |
+| `review` | Evidence report | Findings are severity-ranked, traceable, and cover scope, correctness, tests, risk, and harness compliance. |
+| `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.

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

@@ -0,0 +1,7 @@
+# Module Index
+
+Generated and refreshed as modules are added.
+
+| Module | Status | Notes |
+| --- | --- | --- |
+|  |  |  |

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

@@ -0,0 +1,15 @@
+# Raw Source Index
+
+Immutable fact sources for this project. Generated and refreshed by `zsk prep`.
+
+Active source snapshots should be organized by prepare responsibility lane:
+
+- `prepare/product/` for SRS, PRD, business process, acceptance semantics, and work items.
+- `prepare/backend/` for backend repositories, API contracts, data model, and service-boundary evidence.
+- `prepare/design/` for design/prototype sources, screen maps, and visual assets.
+- `prepare/ux/` for user flows, interaction notes, IA, and usability evidence.
+- `prepare/qa/` for test cases, acceptance scenarios, regression matrices, and QA evidence.
+
+| Provider | Type | Status | Snapshot / Origin |
+| --- | --- | --- | --- |
+|  |  |  |  |

package/templates/project-init/.zsk/raws/manifest.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "resources": []
+}

package/templates/project-init/.zsk/raws/prepare/backend/index.md

@@ -0,0 +1,4 @@
+# Backend Sources
+
+Backend repositories, API contracts, OpenAPI files, data model notes, auth boundaries, and integration evidence.
+

package/templates/project-init/.zsk/raws/prepare/design/index.md

@@ -0,0 +1,3 @@
+# Design Sources
+
+Design handoff files, wireframes, prototype exports, visual assets, design tokens, and platform snapshots.

package/templates/project-init/.zsk/raws/prepare/index.md

@@ -0,0 +1,4 @@
+# Prepare Source Lanes
+
+Reusable source snapshots for prepare. Iterations and releases should reference these snapshots instead of copying source content.
+

package/templates/project-init/.zsk/raws/prepare/product/index.md

@@ -0,0 +1,4 @@
+# Product Sources
+
+SRS, PRD, business process, acceptance semantics, product decisions, and work items.
+

package/templates/project-init/.zsk/raws/prepare/qa/index.md

@@ -0,0 +1,4 @@
+# QA Sources
+
+QA cases, acceptance cases, regression matrices, test data, and verification source material.
+

package/templates/project-init/.zsk/raws/prepare/ux/index.md

@@ -0,0 +1,3 @@
+# UX Sources
+
+User flows, interaction maps, screen behavior notes, usability findings, and experience research artifacts.

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

@@ -0,0 +1,129 @@
+# 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.
+
+version: 1
+
+roles:
+  lead-integrator:
+    subagentType: planner
+    required: true
+    activation: required
+    reason: Own stage scope, dispatch boundaries, integration, and final evidence.
+
+  product-owner:
+    subagentType: analyst
+    stages: [prepare, 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: [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: [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, 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]
+    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, spec, task, coding, 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.
+
+  researcher:
+    subagentType: researcher
+    stages: [prepare]
+    activation: optional when current official or external evidence is required
+    reason: Collect official/current external references only when configured local sources are insufficient.
+
+  planner:
+    subagentType: planner
+    stages: [task]
+    activation: when task sequencing, dependencies, and risk flags are in scope
+    reason: Sequence implementation tasks, dependencies, ownership, and evidence hooks.
+
+  executor:
+    subagentType: executor
+    stages: [task, coding]
+    activation: when implementation ownership, write scope, or scoped code changes are in scope
+    reason: Implement or estimate scoped code ownership and write boundaries.
+
+  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:
+    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.
+
+  verifier:
+    subagentType: verifier
+    required: true
+    activation: required
+    reason: Verify stage outputs against source authority and command evidence.

package/templates/project-init/.zsk/evidence/.gitkeep

@@ -1 +0,0 @@
-

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

@@ -1,58 +0,0 @@
-# .zsk/issues - Local Verification And Bug Evidence
-
-This is the default issue root configured by `.zsk/config.yaml` `paths.issues`. It stores local review findings, bug reports, screenshots, logs, reproduction evidence, and verification records created during project work.
-
-Every actionable finding from demo, smoke, review, formal test, verify, or acceptance should be persisted here or under the configured `paths.issues` root. Chat-only findings are not durable tracking.
-
-## Directory Contract
-
-```text
-.zsk/issues/
-├── README.md
-├── _taxonomy.md
-├── index.md                         # global module issue totals
-└── {area-or-module}/
-    ├── index.md                     # module issue index and status table
-    ├── BUG-0001-short-slug/
-    │   ├── issue.md                 # required issue body
-    │   ├── analysis.md              # optional root-cause notes
-    │   ├── reproduction.md          # optional detailed repro script
-    │   ├── assets/                  # screenshots, videos, HAR, exported state
-    │   │   └── index.md
-    │   └── debug-logs/              # console, test, network, investigation logs
-    │       └── index.md
-    ├── demo/                        # optional stage view / evidence bucket
-    │   └── index.md
-    ├── _evidence/                   # shared evidence referenced by multiple issues/docs
-    └── _debug-logs/                 # untriaged or cross-issue historical logs only
-```
-
-Use `zsk issue create -m <module-id>` to generate issue folders from the packaged template. `zsk init` does not write `_templates/` into the project.
-
-`zsk issue update -m <module-id> --id <issue-dir> --status <status>` updates the concrete issue and refreshes:
-
-- `.zsk/issues/{module}/index.md` - all issues and statuses for one module.
-- `.zsk/issues/index.md` - module totals across the project.
-
-## Bug Directory Rules
-
-- Keep one confirmed bug per `BUG-xxxx-short-slug/` directory.
-- Put the issue body in `issue.md`.
-- Put screenshots, recordings, HAR files, JSON payloads, exported browser state, and reproduction artifacts that belong to one bug under that bug's `assets/`.
-- Put console output, test output, debug logs, and investigation notes that belong to one bug under that bug's `debug-logs/`.
-- Use `analysis.md` only when root-cause reasoning is long enough that it would obscure the issue body.
-- If two symptoms share one root cause, keep one bug directory and list all symptoms as evidence inside it.
-
-## Closure And Documentation Feedback
-
-- Record the affected PRD/SRS, spec, design, task, test case, and evidence links in the issue.
-- After the fix is verified and confirmed by the user/product owner, update the relevant `.zsk/modules/{module}/spec.md`, `.zsk/modules/{module}/design.md`, `.zsk/modules/{module}/tasks.md`, or `.zsk/docs/SYSTEM-SPEC.md` for gaps or vague behavior exposed by the issue.
-- Close the issue only after it links verification evidence, confirmation, documentation feedback update or no-update rationale, and regression guard.
-
-## Relationship To Other Project Directories
-
-| Directory | Purpose | May contain local screenshots/logs? |
-|---|---|---|
-| `.zsk/resources/` | Upstream facts, mirrored snapshots, original external test cases | No |
-| `.zsk/modules/{module}/` | Human-authored module proposal/spec/design/tasks | No |
-| `.zsk/issues/{module}/` | Local defects, verification evidence, debug logs, issue-quality records | Yes |