@captain_z/zsk-skills 1.4.2 → 1.5.1

package/core/archive/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: zsk:archive
+description: Use when accepted work must be closed and preserved; archives
+  artifacts, decisions, issues, and learning proposals without deleting current
+  docs or mutating standards silently.
+kind: workflow-node
+pack: core
+stage: archive
+requires:
+  - constraints.evidence-rules
+domain: core
+category: stage
+tier: core
+triggers:
+  - archive
+  - zsk:archive
+---
+
+# Archive
+
+Use this stage to close an accepted iteration. Archive preserves the evidence trail and proposes learning updates; it does not silently rewrite project standards.
+
+## Inputs
+
+- Accepted proposal/spec/design/tasks and final diff summary.
+- Acceptance decision, verify report, demo report, and issue summaries.
+- Release notes, ADRs, postmortems, or learning proposals created during the work.
+
+## Procedure
+
+1. Collect the final artifact set and link it from the module archive or closeout note.
+2. Summarize decisions, rejected alternatives, issue outcomes, and evidence.
+3. Promote only durable lessons as learning proposals; leave policy changes for explicit review.
+4. Mark the iteration closed in workflow state.
+
+## Constraints
+
+- Do not delete current module docs.
+- Do not auto-edit core standards from a single iteration.
+- Do not promote project-specific experience into core skills or constraints.
+- Do not claim closure while blocking issues remain open.
+- Keep runtime screenshots/logs in `.issues`, not `docs`.
+
+## Outputs
+
+- `archive` closeout.
+- Optional learning proposals.
+- Final issue and evidence index.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/archive/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/coding/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: zsk:coding
+description: Use when approved tasks are ready for implementation; requires
+  small auditable diffs, existing-pattern reuse, tests/evidence, and blocker
+  reporting instead of scope rewriting.
+kind: workflow-node
+pack: core
+stage: coding
+requires:
+  - constraints.stage-gates
+  - constraints.evidence-rules
+domain: core
+category: stage
+tier: core
+triggers:
+  - coding
+  - zsk:coding
+---
+
+# Coding
+
+Use this stage when tasks are approved and the next step is implementation. Coding owns small behavior changes, tests, and evidence capture; it does not redefine scope.
+
+## Inputs
+
+- Approved tasks with FR/AC links and expected evidence.
+- Spec/design constraints, resource manifest, and current code.
+- Existing tests and known blockers.
+
+## Procedure
+
+1. Read the task and the smallest required source set before editing.
+2. Preserve existing behavior unless the task explicitly changes it.
+3. Prefer deletion, reuse, and local patterns before new abstraction.
+4. Add or update tests at the same risk level as the change.
+5. Record commands, evidence, blockers, and changed files for `self-test`/`review`.
+
+## Constraints
+
+- No drive-by refactors, dependency additions, or unrelated formatting.
+- No speculative abstraction reserved for imagined reuse.
+- No skipping tests because the change “looks small”.
+- Stop and report when a required resource is missing or contradicted.
+
+## Outputs
+
+- Implementation diff.
+- Test/evidence notes.
+- Blocker or ready-for-self-test status.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/coding/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/commit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: zsk:commit
+description: Use only after self-test and review pass; prepares a scoped commit
+  with intent and evidence, and forbids staging unrelated dirty files or
+  continuing implementation.
+kind: workflow-node
+pack: core
+stage: commit
+requires:
+  - constraints.evidence-rules
+domain: core
+category: stage
+tier: core
+triggers:
+  - commit
+  - zsk:commit
+---
+
+# Commit
+
+Use this stage only after self-test and review gates pass. Commit prepares a reviewable change record and preserves intent; it is not a place to continue implementation.
+
+## Inputs
+
+- Passing self-test evidence.
+- Review verdict and resolved/waived findings.
+- Final diff and issue links.
+
+## Procedure
+
+1. Inspect the final diff for unrelated files or generated churn.
+2. Confirm evidence links are present for changed behavior.
+3. Stage only files belonging to the approved scope.
+4. Write a commit message that explains why the change was made and records test evidence.
+
+## Constraints
+
+- Do not commit failing gates.
+- Do not stage unrelated dirty work.
+- Do not rewrite user changes outside the task scope.
+- Do not hide known gaps; use `Not-tested:` or issue links.
+
+## Outputs
+
+- `commit-evidence` with staged files, message intent, and tests.
+- Commit-ready or blocked status.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/commit/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/demo/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: zsk:demo
+description: Use before formal testing to prove the changed user flow can be
+  demonstrated; requires planned scenarios, demo-only issue separation,
+  evidence, and no acceptance claims.
+kind: workflow-node
+pack: core
+stage: demo
+requires:
+  - constraints.stage-gates
+  - constraints.issue-taxonomy
+  - constraints.evidence-rules
+actions:
+  - start
+  - pause
+  - resume
+  - terminate
+  - complete
+  - run playwright
+  - run computer-use
+  - run hybrid
+  - capture
+  - scenario generate
+produces:
+  - demo-outline
+  - demo-report
+  - demo-issues
+  - demo-scenarios
+  - synthesized-playwright-cases
+domain: core
+category: stage
+tier: core
+triggers:
+  - demo
+  - zsk:demo
+---
+
+# zsk:demo
+
+Development demo before formal testing. Build a module-grouped smoke demo outline, run manual or automated demonstration steps, record demo-only issues, preserve evidence, and leave reusable Playwright scenarios when possible.
+
+Demo should execute and refine Playwright scenarios that were planned earlier by spec/design/task. It should not be the first stage that invents UI scenarios unless upstream artifacts are missing, in which case the gap must be recorded as a resource blocker or learning proposal.
+
+If a formal test case and structured page information are both available, demo may generate or refresh a Playwright case before running it. Prefer `aria_snapshot + test case + getByRole` over screenshot-driven generation.
+
+## Operating Constraints
+
+- Do not treat demo as final acceptance or formal QA.
+- Do not invent flows when spec/design/task resources are missing; record the resource gap.
+- Do not use Computer Use when deterministic Playwright or app APIs are sufficient.
+- Do not mark ready-for-testing with P0 blockers or untriaged core P1 issues.
+- Every claim needs reusable scenario evidence, screenshot/trace evidence, or a documented manual run.
+
+## Routing
+
+The skill is the conversational entrypoint. The harness/CLI is the execution authority.
+
+```text
+$zsk:demo start              -> zsk demo start
+$zsk:demo pause              -> zsk demo pause
+$zsk:demo resume             -> zsk demo resume
+$zsk:demo run playwright     -> zsk demo run --playwright
+$zsk:demo run computer-use   -> zsk demo run --computer-use
+$zsk:demo run hybrid         -> zsk demo run --hybrid
+$zsk:demo capture            -> zsk demo capture
+$zsk:demo scenario generate  -> zsk demo scenario generate --test-case <path> --snapshot <path>
+$zsk:demo complete           -> zsk demo complete
+```
+
+## Automation Priority
+
+1. Prefer deterministic scripts or app/test APIs when they are sufficient.
+2. Prefer Playwright CLI for low-token, repeatable UI runs, screenshots, traces, and scenario execution.
+3. Use Playwright MCP when structured accessibility snapshots or locator planning are needed before execution.
+4. Use the hybrid lane only when page understanding is uncertain: Playwright MCP or Computer Use decides, then Playwright executes precise actions and records evidence.
+5. Use Browser Use or Computer Use-only only when Playwright CLI/MCP cannot see or operate the required surface.
+
+Browser Use or Computer Use must record why scripts, Playwright CLI, or Playwright MCP were insufficient.
+
+## Tool Bridge
+
+The hybrid lane exchanges structured artifacts:
+
+- `operation-plan.json`: page understanding from Playwright MCP or Computer Use, next operation, target intent, confidence, and fallback note.
+- `playwright-execution.json`: selector/action attempted, result, screenshot/trace paths, scenario update, and issue link.
+
+## Three-step Demo Loop
+
+1. Observe: Playwright CLI/MCP returns an `aria_snapshot`, accessibility tree, screenshot, or trace; Computer Use provides visual understanding only when structured output is insufficient.
+2. Decide: Claude/agent converts the observation into `operation-plan.json`, preferring role-based locators.
+3. Execute: Playwright consumes the plan using `getByRole`, `getByLabel`, `getByPlaceholder`, or `getByTestId`, then writes `playwright-execution.json` with screenshots/traces/scenario links.
+
+Repeat the loop until the demo function point is passed, paused, or converted into a Demo Issue.
+
+## Scenario Generation
+
+The agent can synthesize Playwright cases from structured page info:
+
+1. Load the test case and linked spec/design rows.
+2. Read Playwright MCP `aria_snapshot` or accessibility tree.
+3. Generate a Playwright spec using role-first locators.
+4. Save it under `docs/{module}/scenarios/`.
+5. Run it with Playwright and preserve trace/screenshots.
+
+Browser Use or Computer Use is reserved for cases where the structured page tree and Playwright CLI/MCP evidence are insufficient.
+
+CLI example:
+
+```bash
+zsk demo scenario generate \
+  -m checkout \
+  --test-case .raws/testing/checkout-happy-path.md \
+  --snapshot .raws/testing/checkout.aria.md \
+  --name "Checkout happy path"
+```
+
+## Session Lifecycle
+
+- `start`: create session id, outline, checklist, evidence directory, and cursor.
+- `pause`: persist cursor, completed points, open questions, evidence, and issues.
+- `resume`: continue from the next unfinished function point.
+- `terminate`: intentionally stop the session with reason and owner.
+- `complete`: summarize coverage, issues, risks, and reusable scenarios.
+
+Pause is recoverable. Terminate is terminal for the session but does not mean ready for test.
+
+## Evidence
+
+Normalize manual, script, Playwright, and computer-use evidence into the same demo report and issue taxonomy.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/demo/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/deploy/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: zsk:deploy
+description: Use when reviewed work must be deployed to a non-production/demo
+  environment; requires URL/version, smoke evidence, rollback owner, and
+  explicit production-authority guard.
+kind: workflow-node
+pack: core
+stage: deploy
+requires:
+  - constraints.stage-gates
+  - constraints.evidence-rules
+domain: core
+category: stage
+tier: core
+triggers:
+  - deploy
+  - zsk:deploy
+---
+
+# Deploy
+
+Use this stage to publish a reviewed change to a configured non-production or demo environment. Deploy records where the change can be exercised and how to recover.
+
+## Inputs
+
+- Commit evidence or equivalent version identifier.
+- Configured deploy command/environment.
+- Smoke check plan and rollback owner.
+
+## Procedure
+
+1. Confirm the target is non-production unless explicit production authority exists.
+2. Run the configured deploy command or document why deployment is manual.
+3. Record URL, version, timestamp, environment, and owner.
+4. Run the smallest smoke check that proves the environment serves the changed path.
+
+## Constraints
+
+- Do not deploy to production without explicit authority.
+- Do not mark deploy passed without a reachable URL or documented manual handoff.
+- Do not proceed to demo when smoke evidence is missing.
+
+## Outputs
+
+- `deployment` record.
+- Runtime evidence and rollback note.
+- Demo-ready or blocked status.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/deploy/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/design/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: zsk:design
+description: Use after spec freeze to map behavior to implementation structure;
+  requires interfaces/data flow/rollout/risks and rejects speculative
+  architecture or invented design facts.
+kind: workflow-node
+pack: core
+stage: design
+requires:
+  - constraints.source-of-truth
+  - constraints.stage-gates
+domain: core
+category: stage
+tier: core
+triggers:
+  - design
+  - zsk:design
+---
+
+# Design
+
+Design the solution after spec freeze: architecture, interfaces, data flow, rollout, risks, and implementation mapping.
+
+## Inputs
+
+- Approved spec and scenario contracts.
+- Current code structure, API contracts, domain docs, and design assets when relevant.
+- Project constraints from harness and module config.
+
+## Procedure
+
+1. Map each required behavior to implementation surfaces: files, modules, interfaces, state, data flow, and rollout.
+2. Record tradeoffs, rejected alternatives, migration/rollback notes, and risks.
+3. For UI work, define routes, accessible names, component states, API observations, and locator strategy.
+4. Identify test/demo scenario needs before task breakdown.
+
+## Constraints
+
+- Do not rewrite requirements; route unclear behavior back to `spec`.
+- Do not add architecture that is not needed for the approved scope.
+- Do not invent design facts when Figma/SRS/API sources are missing.
+- Do not rely on CSS/layout selectors for UI verification strategy.
+
+## Playwright Design Inputs
+
+For UI modules, design should provide enough implementation detail for stable Playwright cases:
+
+- route and navigation entry points
+- accessible names, labels, roles, and test-id policy
+- loading/empty/error/permission states
+- network/API contracts that the scenario observes or mocks
+- storage/auth state strategy
+- trace/screenshot evidence requirements
+
+Prefer user-facing locators (`getByRole`, `getByLabel`, `getByPlaceholder`, `getByTestId`) and avoid selectors coupled to layout or styling.
+
+## Outputs
+
+- `design` artifact.
+- Locator/scenario strategy when UI-visible.
+- Task-ready implementation map and risks.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/design/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/issue/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: zsk:issue
+description: Use when any stage finds a defect, blocker, question, or risk that
+  needs tracking; requires taxonomy, severity, owner, reproduction/evidence, and
+  no gate bypass.
+kind: utility
+pack: core
+requires:
+  - constraints.issue-taxonomy
+  - constraints.evidence-rules
+actions:
+  - create
+  - list
+  - update
+  - summarize
+produces:
+  - issue-record
+  - issue-summary
+domain: core
+category: utility
+tier: core
+triggers:
+  - issue
+  - zsk:issue
+---
+
+# Issue
+
+Cross-stage issue utility. Use this from demo, self-test, review, formal testing, verify, and acceptance so every issue follows the same taxonomy, path, severity, owner, status, steps, and evidence rules.
+
+This utility records issues. It does not replace the `test-issue` workflow stage.
+
+## Inputs
+
+- Finding, failure, question, or risk from any stage.
+- Evidence: command output, screenshot, trace, log, reproduction steps, source reference, or user report.
+- Stage and issue type.
+- Known module, environment, affected FR/AC/task, and current/expected behavior when available.
+
+## Procedure
+
+1. Classify issue type: demo, self-test, review, test, verify, acceptance, or generic bug.
+2. Ask only for missing intake fields: reproduction steps, actual/current behavior, expected behavior, environment, severity rationale, and evidence.
+3. Assign severity, owner, status, affected artifacts, expected/actual behavior, and reproduction steps.
+4. Analyze likely root cause with confidence and identify whether the fix route is coding, test data, design/spec correction, environment, or invalid report.
+5. Link FR/AC/task/evidence where available.
+6. Decide feedback target: module spec/design/tasks, project `SYSTEM-SPEC.md`, issue memory, or `.zsk/learning/proposals`.
+7. Update summaries without erasing historical evidence.
+
+## Constraints
+
+- Do not create issue records without enough evidence to act.
+- Do not ask the user for fields already present in logs, screenshots, traces, command output, or failing tests.
+- Do not mix issue types in the wrong directory.
+- Do not close issues without fix/verify evidence or rejection rationale.
+- Do not use issue creation to bypass a blocking stage gate.
+- Do not let a repeated defect disappear after a local fix; add a regression guard or learning proposal.
+
+## Outputs
+
+- `issue-record`.
+- Updated issue summary when requested.
+- Root-cause note, fix route, feedback target, and regression guard.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/issue/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/prepare-resources/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: zsk:prepare-resources
+description: Use after project init and before proposal/spec work to collect
+  SRS, PRD, API, backend repository, design, and test resources; asks only for
+  missing origins, chooses low-token acquisition tools, snapshots evidence, and
+  updates config/manifests without inventing facts.
+kind: workflow-node
+pack: core
+stage: prepare-resources
+requires:
+  - resources.resource-catalog
+  - constraints.source-of-truth
+  - constraints.filesystem-boundaries
+  - constraints.evidence-rules
+produces:
+  - configured-sources
+  - resource-manifest
+  - resource-gaps
+domain: core
+category: stage
+tier: core
+triggers:
+  - prepare-resources
+  - zsk:prepare-resources
+---
+
+# Prepare Resources
+
+Use this stage immediately after `zsk init` or when a module lacks trustworthy upstream resources. It turns user-provided files, URLs, Figma/Modao links, API specs, backend repository addresses, and test assets into configured sources and local snapshots.
+
+## Inputs
+
+- Project root with `.zsk/config.yaml`, `.raws/`, `docs/`, and `.issues/`.
+- User-provided resource origins: local files, URLs, Figma/Modao links, OpenAPI URLs/files, backend repositories, QA sheets, or manual notes.
+- Target module or feature area when known.
+- Tool availability: local filesystem, git, HTTP/browser, Figma MCP, Playwright CLI, Browser Use, Computer Use.
+
+## Procedure
+
+1. Read `.zsk/config.yaml`, `.raws/index.md`, `.zsk/resource-manifest.json`, and existing module docs.
+2. Ask only for missing high-value origins: requirements, API/backend contract, design source/assets, test cases, and runtime URL if UI validation is needed.
+3. Classify each origin into `sources.*` with `type`, `origin.kind`, and an optional `snapshot` under `.raws/`.
+4. Acquire resources with the lowest-token reliable method:
+   - local files: read/copy metadata first, snapshot only relevant files;
+   - backend repositories: inspect API contract paths, route docs, generated OpenAPI, or controller entrypoints before broad code reading;
+   - URLs/docs: fetch direct content before browser automation;
+   - Figma/Modao/design: prefer platform MCP/API metadata, then exported snapshots/assets;
+   - runtime UI: prefer Playwright CLI/MCP snapshots and traces; use Browser Use or Computer Use only when structured automation is insufficient.
+5. Update `.zsk/config.yaml` `sources`, `.raws/*/index.md`, `.raws/manifest.json`, and `.zsk/resource-manifest.json` with origin, snapshot, freshness, and evidence.
+6. Run `zsk config check` and `zsk prep`; stop on schema/path errors.
+7. Record unresolved gaps as issue records or Documentation Feedback instead of guessing.
+
+## Constraints
+
+- Do not invent SRS/API/design/test facts from file names or screenshots.
+- Do not place runtime screenshots, debug logs, or failed verification evidence under `.raws/` or `docs/`; use `.issues/`.
+- Do not clone or crawl large repositories blindly; identify contract-bearing paths first.
+- Do not use Computer Use when Playwright CLI/MCP, direct HTTP, local parsing, or git inspection is sufficient.
+- Do not overwrite existing snapshots without preserving provenance or creating a new dated snapshot.
+- Do not proceed to `proposal`/`spec` with missing required resources unless the gap is explicitly recorded and accepted.
+
+## Outputs
+
+- Updated `.zsk/config.yaml` `sources`.
+- Updated `.raws/manifest.json` and `.zsk/resource-manifest.json`.
+- Resource gap list with owner, impact, and next action.
+- Evidence of commands/tools used to acquire or validate resources.
+- Next legal stage recommendation: usually `proposal` or `spec`, otherwise blocked.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/prepare-resources/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+

package/core/proposal/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: zsk:proposal
+description: Use before spec work to frame why/what/not-what; requires scope,
+  non-goals, success criteria, stakeholders, risks, and explicit resource gaps
+  instead of assumptions.
+kind: workflow-node
+pack: core
+stage: proposal
+requires:
+  - constraints.source-of-truth
+  - constraints.stage-gates
+domain: core
+category: stage
+tier: core
+triggers:
+  - proposal
+  - zsk:proposal
+---
+
+# Proposal
+
+Use this stage to frame the change before writing a behavioral spec. Proposal decides why the work matters, what is in/out, and which resources are required.
+
+## Inputs
+
+- Resource manifest and available requirements/SRS/PRD/customer notes.
+- User request, issue, or business problem statement.
+- Known constraints, stakeholders, timelines, and non-goals.
+
+## Procedure
+
+1. State the problem and desired outcome in product language.
+2. Define scope, non-goals, stakeholders, and success criteria.
+3. Identify required resources for spec/design/testing.
+4. Surface assumptions and conflicts instead of resolving them silently.
+5. Pass only when the spec writer has enough context to define behavior.
+
+## Constraints
+
+- Do not design implementation here.
+- Do not invent requirements when SRS/PRD is missing; mark the resource gap.
+- Do not expand scope to unrelated cleanup.
+- Keep proposal short enough to be reviewed before spec work.
+
+## Outputs
+
+- `proposal` artifact.
+- Resource gaps and open questions.
+- Pass/block status for `spec`.
+
+## Installed Harness Contract
+
+This core skill is generated from root `skills/proposal/SKILL.md` and is governed by the zsk harness. Enforce these rules even when the full harness files are not present in the target:
+
+- Stage gates: do not skip required inputs, illegal transitions, blockers, or evidence checks.
+- Evidence rules: no PASS / DONE / READY claim without linked command, artifact, issue, scenario, or human decision evidence.
+- Source of truth: read configured resources before inventing intent; record conflicts instead of choosing silently.
+- Issue taxonomy: route demo, self-test, review, test, verify, and acceptance findings to the correct issue type.
+- Learning loop: reusable gaps become learning proposals; never mutate core constraints, templates, packs, or skills automatically.
+