@captain_z/zsk 1.8.1 → 1.8.2

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

@@ -1,11 +1,73 @@
 # __MODULE_NAME__ Design
 
+## Project Rules Gate
+
+| Rule Source | Rule / Constraint | Design Impact | Status |
+| --- | --- | --- | --- |
+| `.zsk/docs/PROJECT-CONFIG.md` |  |  | TODO |
+| `.zsk/docs/SYSTEM-SPEC.md` |  |  | TODO |
+
+Do not approve this design until project-level path boundaries, evidence routing, issue routing, source priority, and stage-document rules are mapped to implementation surfaces or recorded as blockers.
+
 ## Implementation Map
 
 | Requirement / AC | Surface | Files / Modules | Interface / State / Data Flow | Risk |
 | --- | --- | --- | --- | --- |
 | FR-001 / AC-001 |  |  |  |  |
 
+## Design Views
+
+Use Mermaid or linked configured design-source evidence to make boundaries, flows, states, and dependencies reviewable. Keep a view N/A only with rationale.
+
+### Context / Container View
+
+```mermaid
+flowchart LR
+    User[User / Actor] --> App[Module / Application]
+    App --> API[API / Service]
+    API --> Data[(Data Store)]
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### Sequence / Flow View
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant UI as UI
+    participant API as API
+    User->>UI: Trigger scenario
+    UI->>API: Request
+    API-->>UI: Response
+    UI-->>User: Observable result
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### State View
+
+```mermaid
+stateDiagram-v2
+    [*] --> Loading
+    Loading --> Success
+    Loading --> Error
+    Error --> Retry
+    Retry --> Loading
+```
+
+Clarifies:
+- Spec / AC:
+- Decision / risk / verification path:
+
+### Data Flow / UX Flow View
+
+N/A rationale or diagram:
+
 ## Decisions
 
 | Decision | Alternatives Rejected | Rationale / Evidence | Rollback / Migration Note |
@@ -32,8 +94,17 @@ Guidelines:
 - Prefer user-facing locators: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByTestId`.
 - Add implementation tasks for missing accessible names, labels, or stable test ids.
 - Define auth/storage reuse before demo so Playwright can run repeatably.
+- Keep generated docs, issues, evidence, and Playwright assets inside the `.zsk` paths required by `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md`.
 - Route unclear behavior back to spec instead of redesigning requirements here.
 
+## Best-Practice Checklist
+
+- [ ] Behavior maps to files/modules/interfaces/state/data flow without changing approved requirements.
+- [ ] Design includes useful diagrams/charts for context, flow, state, data, dependency, or UX where complexity requires them; otherwise N/A rationale is explicit.
+- [ ] Security/auth/privacy, migration/rollback, performance, and rollout risks are recorded when touched.
+- [ ] UI work includes accessible locator/state strategy and Playwright evidence needs.
+- [ ] Project military rules from `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md` are enforced or blocked.
+
 ## Documentation Feedback
 
 - No-update rationale:

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

@@ -1,11 +1,21 @@
 # __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
 
@@ -26,6 +36,13 @@
 | --- | --- | --- |
 |  |  |  |
 
+## 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:

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

@@ -1,5 +1,14 @@
 # __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 |
@@ -22,11 +31,19 @@ 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
 
 - No-update rationale:

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

@@ -1,16 +1,43 @@
 # __MODULE_NAME__ Tasks
 
-## Execution Plan
+## Project Rules Gate
 
-| ID | Task | Depends On | Scope / Files | Linked FR/AC | Evidence Hook | Status |
-| --- | --- | --- | --- | --- | --- | --- |
-| T-001 |  |  |  | FR-001 / AC-001 |  | TODO |
+| 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 | Test / Scenario Task | Docs / Issue / Evidence Task |
+| FR/AC | Implementation Task/Subtask | Test / Scenario Task/Subtask | Docs / Issue / Evidence Task/Subtask |
 | --- | --- | --- | --- |
-| FR-001 / AC-001 | T-001 |  |  |
+| FR-001 / AC-001 | T-001.1 | T-001.2 |  |
 
 ## Playwright Case Tasks
 
@@ -20,11 +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,102 +5,14 @@ layoutVersion: 2
 project:
   name: "<project-name>"
 
-paths:
-  docs: .zsk/docs
-  modules: .zsk/modules
-  raws: .zsk/raws
-  issues: .zsk/issues
-  evidence: .zsk/evidence
-  playwright: .zsk/playwright
+template:
+  id: founder-os
+  version: 1
 
-# Raw source origins. AI or zsk config setup should fill these with online URLs,
-# git repositories, design-platform links/assets, OpenAPI locations, or local files.
-# Optional snapshots should land under paths.raws with stable role/provider paths.
-# Dates belong in manifest metadata such as syncedAt, not in path authority.
-#
-# sources:
-#   srs:
-#     type: srs
-#     origin:
-#       kind: url
-#       url: https://example.com/srs
-#     snapshot: .zsk/raws/product/srs.md
-#   design_main:
-#     type: design
-#     origin:
-#       kind: design
-#       provider: figma
-#       url: https://www.figma.com/file/...
-#     snapshot: .zsk/raws/ue/design-main.json
-#   backend_api:
-#     type: api_contract
-#     origin:
-#       kind: git
-#       repository: https://github.com/example/backend-api.git
-#       path: openapi.yaml
-#     snapshot: .zsk/raws/backend/api-contract.yaml
-#   acceptance_cases:
-#     type: test_case
-#     origin:
-#       kind: url
-#       url: https://example.com/qa-cases
-#     snapshot: .zsk/raws/qa/testing/acceptance-cases.md
-sources: {}
-
-tools:
-  runtime_ui:
-    - playwright_cli
-    - playwright_mcp
-    - playwright
-    - computer_use
-    - browser_use
-  design:
-    - manual
-    - figma_mcp
+mode: standard
+scale: auto
 
-modules:
-  index: .zsk/modules/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/raws/qa/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/modules/{module}/_evidence/demo
-    scenarioDir: .zsk/modules/{module}/_playwright/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/modules/{module}/_playwright/execution/operation-plan.json
-      executionFile: .zsk/modules/{module}/_playwright/execution/playwright-execution.json
-  verify:
-    commands:
-      - pnpm test:e2e
+customize:
+  roles: .zsk/roles.yaml

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

@@ -2,6 +2,14 @@
 
 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/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/raws/backend/index.md

@@ -1,3 +0,0 @@
-# Backend Sources
-
-Backend repositories, API contracts, OpenAPI files, and integration notes.

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

@@ -1,3 +0,0 @@
-# Jira Sources
-
-Jira exports, linked issue references, and ticket snapshots.

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

@@ -1,3 +0,0 @@
-# Manual Sources
-
-Manually supplied notes, local files, and ad hoc source material.

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

@@ -1,3 +0,0 @@
-# Product Sources
-
-SRS, PRD, requirements, release notes, and customer/product feedback.

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

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

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

@@ -1,3 +0,0 @@
-# UE Sources
-
-Design handoff, Figma/Modao references, UX notes, and interaction assets.