@christang/keel 5.1.1

package/plugins/keel/skills/keel-handoff/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: keel-handoff
+description: Create, validate, or clear the optional keel-handoff/v1 pointer override when human intent cannot be inferred uniquely.
+---
+
+# keel-handoff
+
+## Purpose
+
+Use this skill only when `keel context` is ambiguous or blocked because human intent cannot be inferred, or when the user explicitly asks to set or clear an override. HANDOFF is not session state or a startup summary, and it is not a durable follow-up owner.
+
+## Context to read
+
+Run `keel context --json`, then read only the returned paths and the intended durable OpenSpec owner under `openspec/changes/<change>/`.
+
+## Override contract
+
+Write `keel/HANDOFF.md` with YAML front matter only:
+
+```yaml
+---
+schema: keel-handoff/v1
+owner: openspec/changes/<change>/tasks.md#<task>
+action: task-start
+reason: Concise reason automatic inference is insufficient
+---
+```
+
+The only fields are `schema`, `owner`, `action`, and `reason`. The owner must be a durable OpenSpec proposal, design, or tasks pointer. Supported actions are `discuss`, `author`, `task-start`, `task-complete`, and `change-close`.
+
+Never copy task progress, expectation state, evidence details, risks, conversation summaries, `active-backlog`, or `head=...`. Those belong to OpenSpec, archive evidence, or an explicit discard reason.
+
+## Legacy and clearing
+
+Do not rewrite a pre-v1 HANDOFF heuristically. Preserve it byte-for-byte and report the explicit choices: migrate it manually to the v1 contract or run `keel context --clear-handoff`.
+
+Clearing removes only the override; it does not modify the durable owner. Run `keel context --clear-handoff --json`, then verify normal inference resumes.
+
+## Lite boundary
+
+Lite mode does not create HANDOFF for routine cross-session continuity. Use the same optional override contract only when explicit human intent must supersede inference.
+
+## Standalone use
+
+Validate the intended owner first, write or clear only the override, run `keel context --json`, and report the resulting source and next action.

package/plugins/keel/skills/keel-review-checklist/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: keel-review-checklist
+description: Run the current agent's thin semantic consistency review after shared Keel Core gates and before task completion, sync, archive, or meaningful handoff.
+---
+
+# keel-review-checklist
+
+## Purpose
+
+Use this thin Keel consistency gate only at completion gates: after a complete `/opsx:apply` task group, before `/opsx:sync` or `/opsx:archive`, before meaningful handoff, or when delivery reports risks, findings, follow-ups, or out-of-scope need.
+
+Shared Core commands (`keel gate task-start`, `task-complete`, and `change-close`) validate deterministic structure. They do not judge product intent, behavioral test sufficiency, design quality, or risk completeness. Those judgments remain with the current agent.
+
+## Context to read
+
+Read the selected OpenSpec proposal, design, specs, tasks, diff, and command evidence. Read `keel/HANDOFF.md` only when validating an optional override; it is never evidence or a durable follow-up owner.
+
+## Deterministic gate check
+
+- Confirm the appropriate shared Core gate was run and its versioned result is `pass`.
+- Confirm the task's Evidence `Contract` line records the task-start capsule fingerprint and that completion recompiled the same fingerprint; a drift result returns the task to authoring for explicit reauthorization instead of review.
+- A behavioral task's checks must prove observable Acceptance through the public interface, not build-only or shape-only evidence.
+- For a red-green strategy (`vertical-tdd`, `regression-first`), confirm concrete per-label `.red` and `.green` Evidence exists for the same check; evidence-first tasks instead name their observable proof.
+- When no trustworthy explicit Git base exists, do not attribute dirty paths automatically. Review scope semantically.
+- For `Coupling: required`, confirm one complete candidate reached its completion gate and generated artifacts are aligned.
+
+## Semantic Review
+
+Record the current agent's judgment inside the selected task Evidence:
+
+- `Status`: `pass` only when the task is ready to complete.
+- `Acceptance check`: why the behavior evidence proves the authored Acceptance.
+- `Scope check`: why the actual changes stay within Touch; identify an explicit base if deterministic comparison was used.
+- `Findings`: `none`, or each unresolved finding with a durable OpenSpec task/new change, archive-evidence owner, or explicit discard rationale.
+
+The Review remains in tasks.md. A user-facing Report summarizes delivery but is not hidden gate state. Do not let Core or this checklist write evidence automatically.
+
+## Domain reference
+
+When the change's artifacts or Touch extensions signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before concluding the review — only the matching reference, never all of them. When no domain signal exists, load nothing.
+
+## Expectation and follow-up ownership
+
+Each related critical expectation needs behavior evidence, a durable follow-up owner, or an explicit discard reason. Relevant `D<n>`, `F<n>`, `A<n>`, and `Q<n>` references in Covers must agree with their OpenSpec basis and resolution owner. Unresolved authority returns to OpenSpec authoring.
+
+`keel/HANDOFF.md` is an optional pointer override and cannot own findings, critical expectation state, evidence details, or follow-ups.
+
+## Skill change review
+
+For a new or materially expanded dedicated skill, confirm the authoring evidence
+identifies authoritative sources, provenance and license implications, realistic
+positive and negative trigger cases, and real-task evidence. Confirm detailed
+conditional knowledge uses progressive references when it is not needed on
+every activation.
+
+The canonical portable `SKILL.md` must agree with every declared target
+projection. Target metadata may be additive, but it must not redefine skill
+behavior or make Keel the authority for target-native discovery or activation.
+
+## Planning artifact funnel
+
+When the work followed an accepted native plan-mode artifact, confirm its decisions affecting scope, Acceptance, completion, or execution boundaries were recorded in proposal, design, specs, or tasks before implementation. A material decision found only in session state is missing authority and returns to OpenSpec authoring; the session plan file is never execution authority.
+
+## Output
+
+Report one of:
+
+- `pass`
+- `return-to-work`
+- `create-owner-first`
+- `escalate`
+
+Do not expand implementation scope during review.

package/plugins/keel/skills/keel-run-single-task-goal/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: keel-run-single-task-goal
+description: Use when the user explicitly authorizes automatic execution or resume of exactly one OpenSpec task on Codex or Claude. Drives the single-task native goal lifecycle through Keel gates, keeps the current agent the sole writer, and stops at the task boundary. Never activate for ordinary apply, proposal work, ambiguous or multiple tasks, or OpenCode.
+license: UNLICENSED
+metadata:
+  keel-role: single-task-goal-activation
+  keel-targets: codex, claude
+---
+
+# keel-run-single-task-goal
+
+## Purpose
+
+Activate a native goal or subagent runtime to execute exactly one authorized OpenSpec task end to end, while OpenSpec, Git, the task-capsule fingerprint, and deterministic Keel gates stay the only durable authority. The current agent remains the sole writer and owns Review, gate invocation, the task checkbox, and completion. A native evaluator declaring success never marks or reports the task complete.
+
+## Authoritative sources and provenance
+
+These official runtime docs are linked as authoritative references, not copied. Their text and trademarks belong to their owners; Keel paraphrases only the activation semantics it needs and bundles none of their prose.
+
+- Codex goal-following: https://learn.chatgpt.com/use-cases/follow-goals
+- Codex subagents: https://developers.openai.com/codex/subagents
+- Claude goal execution: https://code.claude.com/docs/en/goal
+- Claude subagents: https://code.claude.com/docs/en/sub-agents
+
+License note: this skill is distributed under the Keel package license (UNLICENSED, all rights reserved by the author). Linking the official docs does not relicense them; do not paste their content into Keel artifacts.
+
+## When to activate
+
+Activate only on an explicit, unambiguous request to automatically execute or resume **one** task:
+
+- The user names one OpenSpec change and one executable task and asks to run or continue it automatically.
+- A resume request points at the same durable task whose recorded authorization fingerprint still matches the recompiled capsule.
+
+## When NOT to activate
+
+- Ordinary `/opsx:apply` or manual step-by-step work the user is driving.
+- Proposal, design, or spec authoring before tasks are final.
+- Ambiguous selection, multiple tasks, or a whole task group or change backlog.
+- An unrelated native `/goal` use that is not a Keel OpenSpec task.
+- Unrequested helpers or any request to delegate implementation to another agent.
+- OpenCode, which stays manual compatibility only with no v4 native activation.
+
+If any of these hold, stop and use the normal manual Keel loop.
+
+## Single-task goal lifecycle
+
+1. `keel gate task-start --change C --task T` and record the returned fingerprint in the task Evidence `Contract` line as the durable authorization.
+2. `keel project goal --target codex|claude --change C --task T --json` to compile the disposable `keel-native-goal/v1` projection (objective, Acceptance, command labels, verification strategy, Touch, stop boundary, ownership, terminal condition). The projection is a view, never authority, and never checks the box.
+3. Implement within Touch and produce the strategy's evidence (for example red/green slices for vertical-tdd).
+4. Surface every command result and gate outcome in the transcript before any success claim.
+5. Pass the current agent's Review, then `keel gate task-complete`.
+6. The current agent durably checks the task checkbox.
+7. Stop. Continuing to another task requires a new explicit user instruction and a new start fingerprint; there is no hidden scheduler or automatic next-task selection.
+
+Resume reconstructs the goal from OpenSpec and Git only. Fingerprint drift, checkout divergence, a completed authorization, or missing authorization hard-stops before any product write; pass `--expected-fingerprint` and `--expected-owner` to assert the recorded authorization.
+
+## Bounded read-only helpers
+
+Helpers are optional, read-only evidence producers and never a second writer. Compile one with `keel project helper` for a single bounded question or one repository-byte-stable verification command; a helper never writes products, delegates, nests, or holds acceptance or completion authority. Accept a helper return only after `keel project helper --verify` proves before/after repository byte identity; a modified, added, removed, renamed, or permission-changed path rejects the evidence with exact paths and no cleanup. Helper absence never disables current-agent goal execution.
+
+## Manual fallback
+
+When native activation is unavailable — no plugin, disabled hooks, managed policy, missing trust, or an unsupported surface — do not fake activation. Run the same lifecycle by hand: `keel gate task-start`, `keel project goal ... --json` for the view, implement, surface evidence, `keel gate task-complete`, then check the box. The manual loop preserves the identical single-task lifecycle and stop boundary.
+
+## Target activation
+
+- Codex: where a callable goal/subagent surface exists, activate one bounded goal for the selected task and use subagents only as bounded read-only helpers. Without a callable surface, paste the exact `keel project goal` command and treat the capability as advisory.
+- Claude: activate one `/goal` whose condition stays within the 4,000-character budget; the evaluator is transcript-only, so surface command and gate evidence explicitly. If hooks are disabled, policy blocks activation, or trust is missing, report the manual fallback.

package/plugins/keel/skills/keel-tdd-or-test-first/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: keel-tdd-or-test-first
+description: Drive Keel agent test-first or evidence-first execution for a selected OpenSpec task. Use when a task needs software tests, hardware testbench, assertions, lint, new behavior proof, regression coverage, or red/green evidence before implementation.
+---
+
+# keel-tdd-or-test-first
+## Purpose
+
+Use this skill when Keel execution should start with evidence: software tests first, or hardware testbench, assertion, lint, or equivalent static evidence first. This skill owns the Verify strategy taxonomy, the evidence contract, and their binding to the task capsule; generic test-writing mechanics (how to loop red-green, what to mock) belong to the host runtime and are not restated here.
+
+## Context to read
+
+Read the selected task's compiled capsule: resolved Acceptance, Verify strategy and M<n> checks, Mode, Read, and Touch. `keel gate task-start` returns that capsule and its fingerprint; the fingerprint belongs in the task's Evidence `Contract` line before implementation. Inspect the public interface under test and keep new tests inside the authorized Touch scope.
+
+## Strategy selection
+
+`Verify` names one supported strategy chosen at authoring time as the least-cost proof of the resolved Acceptance:
+
+- `vertical-tdd`: new independently testable deterministic behavior; one check red then green at a time.
+- `regression-first`: an observable defect; reproduce it through the public interface first, then prove the fix with the same check.
+- `characterization` / `snapshot-characterization`: deterministic or generated outputs kept stable by byte or snapshot comparison; not downgraded to build success.
+- `rendered-behavior`: interactive surfaces exercised through the real rendered interface; strict red-green optional by cost.
+- `evidence-first`: docs, configuration, or diagnosis work whose checks state the observable artifact or evidence instead of a red-green loop.
+
+Red-green strategies (`vertical-tdd`, `regression-first`) must record concrete per-label `.red` and `.green` Evidence entries for the same check; `keel gate task-complete` rejects absent or pending entries.
+
+## Domain reference
+
+When the change's proposal/design/specs or the task's Touch extensions signal a supported domain (web, hardware, hardware-dsl), consult the matching reference's `Execution and review checks` section under `keel-align-expectations/references/` before finalizing the strategy and the first check — only the matching reference, never all of them. When no domain signal exists, load nothing.
+
+## Coupled-task preflight
+
+When the selected task declares `Coupling: required`, also read design.md's
+Coupled Iteration Contract plus the task's Candidate Boundary, Stop Rules, and
+Evidence. Before modifying files, run the task's preflight evidence command or
+inspect the explicitly named evidence. If the contract is incomplete or task
+and design disagree, stop and report the gap; do not infer the missing decision.
+
+## TASK boundary
+
+Align every test or check with the selected OpenSpec task's acceptance criteria or verification evidence. Prove behavior through the public interface: evidence that only shows build success or internal shape does not satisfy a behavioral Acceptance, and mocking your own modules invalidates the proof — mock only at true system boundaries.
+
+## Standalone use
+
+When used alone, name the public interface under test, the behavior being checked, the command used, and the red/green evidence.