@captain_z/zsk 1.8.4 → 1.8.6

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: [preproposal, design]
-    lanes: [frontend, web, client, mobile]
-    activation: when frontend implementation, routing, state, or UI integration is in scope
-    reason: Map existing UI implementation surfaces, routing, state, candidate page/module-to-code mapping, and component integration risk.
-
-  design-specialist:
-    subagentType: designer
-    stages: [prepare, preproposal]
-    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]

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

@@ -0,0 +1,104 @@
+# Example provider/entry-source/route shapes. Configure each platform once,
+# then add only durable entry sources to .zsk/config.yaml. Let prepare produce
+# .zsk/evidence/prepare/<run>/config-draft.yaml and
+# source-promotion-suggestions.md for discovered child pages, nodes, issues, or
+# files; promote selected candidates only after human review.
+#
+# Store secret values in the shell environment, not in config. If credentials
+# live in ~/.zshrc, export them there, for example:
+#   export ACCESS_TOKEN=...
+#   export CONFLUENCE_USER=...
+#   export CONFLUENCE_PASSWORD=...
+# ZSK reads process.env after the shell starts; it does not parse ~/.zshrc.
+
+providers:
+  jira:
+    type: issues
+    adapter: jira
+    baseUrl: https://jira.example.com
+    auth:
+      env: ACCESS_TOKEN
+    defaults:
+      project: ZSK
+      assignee: me
+  confluence:
+    type: document
+    adapter: confluence
+    baseUrl: https://confluence.example.com
+    auth:
+      usernameEnv: CONFLUENCE_USER
+      passwordEnv: CONFLUENCE_PASSWORD
+
+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"]
+
+resources:
+  - id: core-api-entry
+    type: repository
+    area: Backend Services
+    source:
+      kind: git-submodule
+      path: .zsk/raws/repositories/core-api-entry/repository
+
+  - id: assigned-bugs-entry
+    type: issues
+    provider: jira
+    query:
+      jql: assignee = currentUser() AND issuetype = Bug ORDER BY updated DESC
+    classify:
+      by: [priority, component, status]
+
+  - id: product-requirements-entry
+    type: document
+    area: Confluence
+    provider: confluence
+    source:
+      kind: confluence
+      pageId: "12345"
+    metadata:
+      note: Child Confluence pages should be reviewed in config-draft.yaml before promotion.
+
+  - id: public-product-entry
+    type: document
+    area: Product
+    source:
+      kind: url
+      url: https://example.com/prd
+      fallback:
+        acquisition: [playwright_cli]
+        observation: [computer_use]
+
+# Compatibility prepare tree for projects that still use sources.* directly.
+# Keep this entry-level too: one platform/domain entry here may fan out into
+# many draft candidates under evidence before selected children are promoted.
+sources:
+  prepare:
+    product:
+      product-requirements-entry:
+        type: prd
+        adapter: confluence
+        origin:
+          kind: confluence
+          url: https://confluence.example.com/pages/viewpage.action?pageId=12345
+        metadata:
+          provider: product_requirements_entry
+          promotionPolicy: review config-draft.yaml before adding child pages
+
+routes:
+  - from: assigned-bugs-entry
+    to:
+      module: permission
+      artifact: issues

package/templates/project-init/.zsk/templates/issue-card.md

@@ -0,0 +1,23 @@
+---
+id: "<issue-id>"
+title: "<issue-title>"
+status: open
+priority: medium
+module: "<module-id>"
+source:
+  resource: "<resource-id>"
+  provider: "<provider-id>"
+  key: "<provider-issue-key>"
+---
+
+# <issue-title>
+
+<!-- zsk:source:start -->
+Provider source summary will be updated by `zsk prepare sync`.
+<!-- zsk:source:end -->
+
+## Local Notes
+
+## Decision
+
+## Next Action

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

@@ -0,0 +1,13 @@
+# Module Template
+
+Copy this template through `zsk module init`; do not create real module
+directories by hand unless the same file contract is preserved.
+
+Required files:
+
+- `module.yaml`
+- `README.md`
+- `proposal.md`
+- `spec.md`
+- `design.md`
+- `tasks.md`

package/templates/project-init/.zsk/templates/module/design.md

@@ -0,0 +1,22 @@
+# Design
+
+## Output Quality Check
+
+status: NEEDS_CLARIFICATION
+owner: design
+source_basis: []
+blocking_items:
+  - Map approved behavior to implementation surfaces.
+next_action: Resolve Interface, data flow, rollout, and verification gaps.
+
+## Module
+
+## Interfaces
+
+## Implementation
+
+## Data Flow
+
+## Risks
+
+## Verification

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

@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=__ZSK_MODULE_SCHEMA_URL__
+
+module:
+  id: "<module-id>"
+  name: "<Module Name>"
+
+outputs:
+  docs: .zsk/modules/<module-id>
+  issues: .zsk/modules/<module-id>/_issues
+
+tests:
+  raw_cases: []
+  derived_cases: []
+  automated:
+    e2e: []

package/templates/project-init/.zsk/templates/module/proposal.md

@@ -0,0 +1,20 @@
+# Proposal
+
+## Output Quality Check
+
+status: NEEDS_CLARIFICATION
+owner: proposal
+source_basis: []
+blocking_items:
+  - Fill the proposal from reviewed sources.
+next_action: Record scope, non-goals, success criteria, and open questions.
+
+## Problem
+
+## Scope
+
+## Non-Goals
+
+## Success Criteria
+
+## Open Questions

package/templates/project-init/.zsk/templates/module/spec.md

@@ -0,0 +1,22 @@
+# Spec
+
+## Output Quality Check
+
+status: NEEDS_CLARIFICATION
+owner: spec
+source_basis: []
+blocking_items:
+  - Fill observable behavior and acceptance criteria from reviewed sources.
+next_action: Resolve missing behavior questions before design.
+
+## Functional Requirements
+
+## Non-Functional Requirements
+
+## Acceptance Criteria
+
+## Scenarios
+
+## Edge Cases
+
+## Open Questions

package/templates/project-init/.zsk/templates/module/tasks.md

@@ -0,0 +1,16 @@
+# Tasks
+
+## Output Quality Check
+
+status: NEEDS_CLARIFICATION
+owner: task
+source_basis: []
+blocking_items:
+  - Convert design into executable tasks.
+next_action: Add ordered tasks with dependencies, owners, and evidence hooks.
+
+## Task Queue
+
+- [ ] Define the first implementation task.
+
+## Evidence Hooks

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

@@ -1,34 +0,0 @@
-# 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/product/{topic}/product-brief.md` and `roadmap.md` for preproposal-generated product direction and MVP/phase decomposition after checkpoint review.
-- `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/design/{topic}/design-source-needs.md` for preproposal design-source readiness gaps after checkpoint review.
-- `prepare/design/{topic}/design-source-map.md` for provider-backed design source coverage and missing Figma/prototype metadata.
-- `prepare/ux/` for user flows, interaction notes, IA, and usability evidence.
-- `prepare/ux/{topic}/ux-readiness.md` for preproposal journey/flow/IA/readiness seeds after checkpoint review.
-- `prepare/ux/{topic}/interaction-handoff.md` for sourced interaction matrices, state coverage, accessibility contract, and unresolved interaction gaps. For module-targeted preproposal work, `{topic}` defaults to the module id.
-- `prepare/qa/` for test cases, acceptance scenarios, regression matrices, and QA evidence.
-
-Interaction handoff files are living raw artifacts owned by `preproposal`, not
-inline sections of module `proposal.md` or `design.md`. Downstream module stages
-should reference a reviewed revision, for example:
-
-```md
-Interaction source:
-- `.zsk/raws/prepare/ux/{topic}/interaction-handoff.md`
-- Accepted revision: <review evidence or commit/date>
-```
-
-If later UX changes alter scope or behavior, revise the raw artifact first,
-record source/status/impact, then route affected module stages back through
-`proposal`, `spec`, `design`, or `task` as needed.
-
-| Provider | Type | Status | Snapshot / Origin |
-| --- | --- | --- | --- |
-|  |  |  |  |

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

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

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

@@ -1,4 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# Design Sources
-
-Design handoff files, wireframes, prototype exports, visual assets, design tokens, and platform snapshots.
-
-Use `prepare/design/{topic}/design-source-map.md` for provider-backed design
-sources such as Figma, MasterGo, exports, screenshots, and assets.
-
-Rules:
-
-- Preserve provider URL, file/page/frame/node ids, capture method, raw payload,
-  screenshots/assets, capture time, and tool/auth limits.
-- Record prototype links, annotations, variables/tokens, components, variants,
-  and missing source data when available.
-- Treat design files as source evidence, not complete interaction truth.
-- Pair source maps with `prepare/ux/{topic}/interaction-handoff.md` when visual
-  sources need page/module interaction detail.
-- For module-targeted preproposal work, `{topic}` defaults to the module id so
-  the design-source map and interaction handoff can be consumed by the same
-  module proposal/spec/design chain.
-- Code design remains owned by module `design.md`; this lane provides source
-  evidence and gaps only.

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

@@ -1,37 +0,0 @@
-# Prepare Source Lanes
-
-Reusable source snapshots for prepare. Iterations and releases should reference these snapshots instead of copying source content.
-
-## Responsibility
-
-`prepare` is the source acquisition and evidence stage. It owns:
-
-- source origin registration from `.zsk/config.yaml#sources`;
-- repository inventory and draft source discovery;
-- acquisition planning, blocked-source questions, and correspondence prompts;
-- auth preflight and reusable Playwright storageState helpers;
-- raw snapshot materialization through local, provider, URL, browser, or
-  metadata-only strategies;
-- `.zsk/raws/manifest.json`, raw indexes, adapter results, and downstream impact
-  evidence.
-
-`prepare` does not own product decisions, formal FR/NFR, interaction decisions,
-code design, or task planning. If a source is missing or private, preserve the
-previous snapshot when present, write a blocked/gap artifact, and route the
-missing decision to the owning stage.
-
-## Capture Strategy
-
-Use the least lossy acquisition method that is explicit and repeatable:
-
-| Source Kind | Preferred Strategy | Notes |
-| --- | --- | --- |
-| Local docs/contracts/exports | `origin.kind: local` + `zsk prepare sync` | Best default for PRD, API, QA, Figma JSON exports, screenshots, and manually reviewed handoffs. |
-| Provider APIs | `origin.provider` + API/export URL + `--allow-network` | Use Confluence/Jira/GitLab/design-source adapters when provider payloads are available. |
-| Private web pages | `zsk prepare auth-check`, then `zsk prepare sync --browser --auth-state ... --allow-network` | Browser capture is fallback evidence, not a replacement for provider exports. |
-| Repository roots | metadata-only snapshot | Do not crawl broad repositories; configure concrete contracts/files instead. |
-| Figma/design URLs | provider export or local raw payload first; browser URL only as fallback | Pair with `prepare/ux/{topic}/interaction-handoff.md` for interaction details. |
-
-Record incomplete provider coverage as a source gap. A successful prepare run is
-allowed to say "blocked" or "needs confirmation"; that is expected behavior, not
-a silent failure.

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

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

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

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

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

@@ -1,22 +0,0 @@
-# UX Sources
-
-User flows, interaction maps, screen behavior notes, usability findings, and experience research artifacts.
-
-Use `prepare/ux/{topic}/interaction-handoff.md` when UI, UX, or design-source
-interaction needs clarification before formal proposal/spec/design work. When
-the brief targets a module, `{topic}` defaults to the module id.
-
-Rules:
-
-- `preproposal` owns this file as a living source artifact.
-- Generate an AI brief from available Figma/design/source/code evidence before
-  asking humans to fill gaps.
-- Separate sourced facts, accepted decisions, inferred assumptions, missing
-  details, recommended answers, and human confirmation status.
-- Record revisions and impact. Downstream module docs consume only reviewed or
-  accepted revisions.
-- For module-targeted work, name the target module, module path, reviewed module
-  artifacts, scope boundary, terminology alignment, and any page/frame split
-  rationale in the interaction handoff.
-- Do not use this lane for final code design, formal FR/NFR, or task execution
-  planning.