@captain_z/zsk 1.8.6 → 1.8.8

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

@@ -0,0 +1,218 @@
+# ZSK talent pool.
+#
+# Roles describe responsibility. Agents describe concrete execution capacity.
+# Squads group agents behind a leader for cross-functional or ambiguous work.
+# Provider-specific ids are adapter references, not ZSK role names.
+
+version: 1
+
+roles:
+  product-owner:
+    responsibilities:
+      - Own product outcome, scope, priority, and acceptance intent.
+      - Keep proposal/spec/task claims tied to sourced product evidence.
+    stages: [prepare, preproposal, proposal, spec, task, acceptance]
+    subagentTypes: [analyst]
+
+  business-analyst:
+    responsibilities:
+      - Convert product, policy, and workflow material into requirements and edge cases.
+      - Preserve open questions and conflicts as issues instead of assumptions.
+    stages: [prepare, preproposal, proposal, spec]
+    subagentTypes: [analyst]
+
+  researcher:
+    responsibilities:
+      - Gather and validate external or provider-backed evidence when local sources are insufficient.
+      - Record source freshness, uncertainty, and gaps.
+    stages: [prepare, preproposal, proposal]
+    subagentTypes: [researcher]
+
+  architect:
+    responsibilities:
+      - Own module boundaries, interfaces, data flow, integration risks, and ADR-worthy decisions.
+      - Keep implementation tasks aligned with design decisions.
+    stages: [design, task, review]
+    subagentTypes: [architect]
+
+  frontend-engineer:
+    responsibilities:
+      - Own browser-facing implementation, UI state, accessibility, and visual/runtime evidence.
+      - Preserve TDD and demo evidence for assigned work items.
+    stages: [task, coding, demo, smoke]
+    subagentTypes: [executor]
+
+  backend-engineer:
+    responsibilities:
+      - Own API, data, integration, permission, and service behavior.
+      - Preserve contract, migration, and rollback evidence for assigned work items.
+    stages: [task, coding, smoke]
+    subagentTypes: [executor]
+
+  test-engineer:
+    responsibilities:
+      - Define RED/GREEN/REFACTOR expectations, regression coverage, and verification strategy.
+      - Reject untestable acceptance criteria or missing evidence hooks.
+    stages: [spec, design, task, coding, smoke, verify]
+    subagentTypes: [test-engineer, verifier]
+
+  reviewer:
+    responsibilities:
+      - Review behavioral risk, maintainability, regressions, and missing evidence.
+      - Report findings without taking implementation ownership.
+    stages: [review]
+    subagentTypes: [code-reviewer, reviewer]
+
+  verifier:
+    responsibilities:
+      - Prove or block completion claims against acceptance criteria and fresh evidence.
+      - Keep provider done status separate from ZSK verified status.
+    stages: [verify, acceptance]
+    subagentTypes: [verifier]
+
+agents:
+  solo-lead:
+    roles: [product-owner, architect, reviewer, verifier]
+    route: leader-sequential
+    capacity: primary
+
+  product-agent:
+    roles: [product-owner, business-analyst, researcher]
+    stages: [prepare, preproposal, proposal, spec]
+    subagentTypes: [analyst, researcher]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: product-agent
+
+  architecture-agent:
+    roles: [architect, reviewer]
+    stages: [design, task, review]
+    subagentTypes: [architect, code-reviewer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: architecture-agent
+
+  frontend-agent:
+    roles: [frontend-engineer, test-engineer]
+    stages: [task, coding, demo, smoke]
+    subagentTypes: [executor, test-engineer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: frontend-agent
+
+  backend-agent:
+    roles: [backend-engineer, test-engineer]
+    stages: [task, coding, smoke]
+    subagentTypes: [executor, test-engineer]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: backend-agent
+
+  verification-agent:
+    roles: [test-engineer, reviewer, verifier]
+    stages: [smoke, review, verify, acceptance]
+    subagentTypes: [test-engineer, code-reviewer, verifier]
+    route: native-or-provider
+    capacity: high
+    priority: 4
+    providerRefs:
+      multica:
+        agent: verification-agent
+
+squads:
+  product:
+    leader: product-agent
+    members: [product-agent, architecture-agent, verification-agent]
+    useWhen:
+      - Product direction, resource readiness, or acceptance intent is unclear.
+      - External research or source conflict resolution is required.
+
+  design:
+    leader: architecture-agent
+    members: [architecture-agent, frontend-agent, backend-agent, verification-agent]
+    useWhen:
+      - Interfaces, data flow, UX, integration, security, or rollback decisions are coupled.
+      - A design decision affects more than one module or implementation lane.
+
+  delivery:
+    leader: solo-lead
+    members: [frontend-agent, backend-agent, verification-agent]
+    useWhen:
+      - Approved task work needs implementation, tests, and verification evidence.
+      - Multiple implementation lanes can proceed without write-scope conflict.
+
+# Optional provider expert catalogs can enrich the local talent pool without
+# making the work ledger provider-specific. A Multica export can be normalized
+# into a generic experts.yaml with id/providerAgent/roles/stages/modules.
+# `zsk work import-experts` writes `.zsk/providers/<provider>/experts.yaml`,
+# and dispatch auto-discovers that default path when the file exists.
+providerCatalogs:
+  # multica:
+  #   path: .zsk/providers/multica/experts.yaml
+
+assignmentPolicy:
+  defaultMode: squad-for-ambiguous-direct-for-clear
+  directWhen:
+    - Work item has a single module, clear role, clear write scope, and test contract.
+  squadWhen:
+    - Work item crosses product, design, implementation, or verification concerns.
+    - Required source, acceptance, or evidence ownership is uncertain.
+  neverAutoStartFromStages:
+    - task
+  requiresDispatchBeforeProviderAssignment: true
+  dispatch:
+    assignmentMode: agent
+    ownerRoleHints:
+      enabledForStaffingRoles: [executor, planner]
+    stageRoutes:
+      prepare:
+        roles: [product-owner, business-analyst, researcher, test-engineer]
+        subagentTypes: [analyst, researcher, test-engineer]
+      proposal:
+        roles: [product-owner, business-analyst, architect, researcher]
+        subagentTypes: [analyst, architect, researcher]
+      spec:
+        roles: [product-owner, business-analyst, architect, test-engineer]
+        subagentTypes: [analyst, architect, test-engineer]
+      design:
+        roles: [architect, frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [architect, executor, test-engineer]
+      task:
+        roles: [architect, frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [planner, architect, executor, test-engineer]
+      coding:
+        roles: [frontend-engineer, backend-engineer, test-engineer]
+        subagentTypes: [executor, test-engineer]
+      demo:
+        roles: [frontend-engineer, test-engineer]
+        subagentTypes: [executor, test-engineer]
+      review:
+        roles: [reviewer, architect, test-engineer]
+        subagentTypes: [code-reviewer, architect, test-engineer]
+      verify:
+        roles: [verifier, test-engineer]
+        subagentTypes: [verifier, test-engineer]
+    roleMappings:
+      auth-fetch-agent: [researcher]
+      design-specialist: [frontend-engineer]
+      executor: [frontend-engineer, backend-engineer]
+      lead-integrator: [verifier, architect, product-owner]
+      market-researcher: [researcher]
+      planner: [architect, product-owner]
+      qa-engineer: [test-engineer]
+      senior-engineering-reviewer: [reviewer]
+      technical-writer: [product-owner]
+      ue-a11y-reviewer: [reviewer, frontend-engineer]
+      ux-specialist: [frontend-engineer]

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

@@ -0,0 +1,75 @@
+# ZSK work management policy.
+#
+# This file maps provider-agnostic ZSK Work Events to external work systems.
+# Multica is the default adapter reference, but .zsk/work.jsonl remains generic
+# and can be translated to Jira, GitHub Issues, GitLab, Linear, or local Markdown.
+
+version: 1
+
+ledger:
+  path: .zsk/work.jsonl
+  format: jsonl
+  createWhen: first-work-event
+  providerAgnostic: true
+
+defaultProvider: multica
+
+providers:
+  multica:
+    adapter: multica
+    mode: dry-run-until-explicit-sync
+    workspace: "<workspace-slug>"
+    # Optional generic expert catalog exported or normalized from the provider.
+    # Dispatch also auto-discovers .zsk/providers/<provider>/experts.yaml when
+    # `zsk work import-experts` creates it.
+    # Prefer `.zsk/team.yaml providerCatalogs` when the catalog is part of the
+    # local talent-pool contract.
+    # expertCatalog:
+    #   path: .zsk/providers/multica/experts.yaml
+    commandPlan:
+      executable: multica
+      mode: dry-run-template
+    projectMapping:
+      strategy: module-to-project
+      projects: {}
+    statusMapping:
+      draft: backlog
+      ready: todo
+      implementing: in_progress
+      review: in_review
+      verified: done
+      blocked: blocked
+      cancelled: cancelled
+    assignment:
+      taskCreatesIssuesOnly: true
+      dispatchAssignsAgentsOrSquads: true
+      verifyControlsDone: true
+
+events:
+  accepted:
+    - work.item.upserted
+    - work.item.linked
+    - work.item.status_changed
+    - work.provider_status.imported
+    - work.assignment.requested
+    - work.assignment.accepted
+    - work.comment.added
+    - work.item.verified
+    - work.item.blocked
+
+syncPolicy:
+  idempotency:
+    localKey: workItem.id
+    remoteRefPath: externalRefs
+  dryRunFirst: true
+  createRemoteWhen:
+    - provider is configured
+    - work item has project, module, stage, local id, title, status, and source artifacts
+  updateRemoteWhen:
+    - local work item has an existing remote reference
+    - status, source links, assignment, comments, or evidence changed
+  neverSync:
+    - secrets
+    - raw credential values
+    - provider cookies
+    - private auth state paths

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

@@ -1,21 +0,0 @@
-# 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/<run>/config-draft.yaml
-.zsk/evidence/prepare/<run>/source-promotion-suggestions.md
-.zsk/evidence/prepare/sync-report.md
-.zsk/evidence/prepare/blocked-resources.md
-```
-
-`config-draft.yaml` and `source-promotion-suggestions.md` are review artifacts.
-They do not mutate `.zsk/config.yaml`; selected entries must be applied only
-after human confirmation.
-
-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/evidence/prepare/README.md

@@ -1,22 +0,0 @@
-# Prepare Evidence
-
-Prepare runs write per-run artifacts here:
-
-```text
-.zsk/evidence/prepare/<run>/
-  repo-inventory.json
-  config-draft.yaml
-  source-promotion-suggestions.md
-  acquisition-plan.json
-  blocked-sources.md
-  correspondence-questions.md
-```
-
-Default collaboration rule:
-
-- `config-draft.yaml` is a candidate tree, not an applied config.
-- `source-promotion-suggestions.md` explains which candidates are ready or need
-  review.
-- `.zsk/config.yaml` changes only after human confirmation.
-- `sync-report.md` summarizes actual materialization results after
-  `zsk prepare sync`.

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

@@ -1,10 +0,0 @@
-# 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/templates/module/README.md

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

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

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

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

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

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