v0.22.2

Runtime spec fix for the Copilot platform. The Copilot runtime now recognises Copilot's native subagent dispatch capability as the default parallel-execution path, so PARALLEL blocks and bold-marked subagent calls actually run in parallel instead of falling back to sequential inline evaluation when neither /fleet nor a named custom agent is configured. No skill content changes; behaviour is corrected at the runtime-spec layer.

Fixed

• skills/canopy-runtime/references/runtime-copilot.md — added a unified Dispatch path resolution section that all subagent dispatch (marker-based calls, PARALLEL children, soft-compat ## Agent) shares. New four-path chain (first match wins):
  1. /fleet orchestration
  2. @CUSTOM-AGENT-NAME reference
  3. Native Copilot subagent dispatch — new default path; uses Copilot's built-in subagent capability (e.g. runSubagent) to spawn each subagent in its own context window in parallel.
  4. Sequential inline fallback — now gated on an explicit user ASK before degrading, so parallelism loss is never silent.
• Failure semantics codified — paths 1–3 follow Promise.allSettled (sibling failure does not abort); path 4 short-circuits on first failure. Previously this was implicit and varied per call site.
• Spec-level deduplication — the per-section duplicated path lists under Marker-based dispatch, Soft-compat ## Agent, and Parallel subagent invocation were replaced with references to the single canonical chain.

Changed

• docs/reference/RUNTIMES.md regenerated via scripts/sync-runtime-docs.py to mirror the runtime-copilot.md update. CI --check mode was failing on this drift before the regenerate.

Notes

• Claude Code runtime (runtime-claude.md) unchanged — Claude's native parallel Task dispatch was already the documented default there.
• No primitive, op-lookup, or skill-content changes; every existing skill executes unchanged on both platforms. Consumers on Copilot should now observe true parallelism for marker-based PARALLEL blocks where they previously got sequential inline reads.
• All 7 version sources of truth bumped to 0.22.2 per the standard release procedure.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.22.2

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.22.2.tar.gz --owner kostiantyn-matsebora

v0.22.1

Doc-only patch. Updates the contributor-facing examples-sync.md rule so future feature rollouts don't repeat the v0.20-era mistake of leaving legacy-form skills in the demo set "for soft-compat coverage". No runtime, primitive, or skill-content changes.

Changed

• .claude/rules/examples-sync.md — corrected the "New dispatch mode / convention" decision-flow row. Previous guidance said "leave some skills on soft-compat to test soft-compat", which led to 4-of-6 example skills carrying the legacy ## Agent form for two releases (v0.20–v0.22) and misled new authors learning by example. New guidance: retrofit every demo to the canonical form; soft-compat coverage moves to a dedicated test fixture in docs/TEST_SCENARIOS.md.
• New "Soft-compat coverage" section in the rule explaining the rationale (why soft-compat doesn't belong in the demo set, where it does belong, the per-feature decision shape).
• New anti-pattern entry flagging soft-compat-via-examples as the v0.20-era mistake the rule prevents going forward.

Notes

• This release pairs with claude-canopy-examples v0.9.0, which decommissioned ## Agent from bump-version, review-file, and generate-readme (the practical correction the rule update now codifies for future feature rollouts).
• No published-skill content changes — the rule lives in .claude/rules/, which is contributor-facing and not part of the gh skill install bundle. Consumers upgrading from v0.22.0 to v0.22.1 see no behavior difference.
• All 7 version sources of truth bumped to 0.22.1 per the standard release procedure.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.22.1

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.22.1.tar.gz --owner kostiantyn-matsebora

v0.22.0

S3 release — universal op contracts plus opt-in runtime enforcement. Any op (inline or subagent) may now declare typed JSON Schema input/output contracts via blockquote markers. The vscode extension (separate package, v0.15.0) walks the binding graph to flag drift between producer and consumer at authoring time. Strict-contract mode (metadata.canopy-contracts: strict) opts skills into per-op runtime validation. Fully backward-compatible — every existing skill executes unchanged.

Added

• Universal op contracts. Inline ops gain contract markers with the same syntax as the v0.20 subagent marker, minus the dispatch flag:

  ## RENDER << input >> output
  
  > **Input contract:** `assets/schemas/render-input.json`
  > **Output contract:** `assets/schemas/render-output.json`

  Subagent ops continue to declare contracts inside the > **Subagent.** blockquote. Both forms populate the same inputContract / outputContract fields. Schema-less ops continue to work unchanged.

• metadata.canopy-contracts: strict opt-in. Skills declare strict mode in frontmatter; the runtime then validates each contract-bearing op's input before firing and output before binding. Halts with [contract-violation] on drift. Default (omitted) keeps contracts descriptive only.

• Schema composition through bindings. A consumer op's input contract may $ref into the producer op's output schema (same skill). The vscode extension surfaces drift across the binding graph as authoring-time diagnostics.

• /canopy improve contract-scaffolding pass. New audit step: for each op without contracts, propose assets/schemas/<op-name>-{input,output}.json generated from the op's << / >> named fields. Permissive defaults (additionalProperties: true, every property type: string) — author refines. Opt-in via --scaffold-contracts flag in the apply prompt.

• /canopy validate contract checks. New error/warning catalog covering missing schema files, schema-vs-signature drift, binding-edge drift between producer and consumer, and the strict-mode-without-contracts no-op case.

• /canopy advise and /canopy convert-to-canopy contract recommendations. Both ops now propose contract markers for ops with stable signatures, and propose strict mode once the skill carries contracts on the majority of non-trivial ops.

Changed

• docs/reference/FRAMEWORK_SPEC.md gains an "Op Contracts" section + a Contract-bearing op row in the Tree Execution Model node-types table.
• skills/canopy-runtime/references/skill-resources.md gains an "Op contracts" section describing the marker syntax, contract composition, strict-contract mode, and the scaffolding pathway.
• skills/canopy-runtime/references/ops/subagent.md gains a brief "Contracts on subagent ops" section cross-referencing the universal form so readers don't conclude that contracts are subagent-only.
• skills/canopy/assets/policies/authoring-rules.md gains a "Universal op contracts" section covering marker forms, schema location, when to declare, when to skip, and the strict-mode opt-in.
• skills/canopy/assets/constants/control-flow-notation.md gains rows mapping (a) signature-stable inline ops to contract-marker adoption and (b) contract-bearing skills to the strict-mode flag.

Notes

• vscode extension v0.15.0 (separate package) ships the static type-flow analyzer + binding-graph builder + new diagnostics, hover, completion, and snippets.
• claude-canopy-examples/parallel-review retrofitted as the canonical S3 demo: input contracts on every subagent op + universal contracts on MERGE_ASPECT_FINDINGS and REPORT_BY_SEVERITY (the inline ops) + metadata.canopy-contracts: strict. Other example skills intentionally remain contract-less to demonstrate the back-compat path.
• Cross-skill $ref is out of scope for this release — single-skill schema composition only.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.22.0

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.22.0.tar.gz --owner kostiantyn-matsebora

v0.21.0

Context-optimization release. Cuts the per-skill canopy tax from ~700 lines of always-loaded runtime spec to ~150–400 depending on feature usage. Fully backward-compatible — skills authored on prior versions continue to work without changes.

Added

• Sliced primitive spec. skills/canopy-runtime/references/framework-ops.md (monolithic, 151 lines) is replaced by per-feature slice files under references/ops/:
  • core.md — IF, ELSE_IF, ELSE, END, BREAK (always loaded)
  • interaction.md — ASK, SHOW_PLAN
  • control-flow.md — SWITCH, CASE, DEFAULT, FOR_EACH
  • parallel.md — PARALLEL
  • subagent.md — subagent dispatch (marker + bold call-site)
  • explore.md — EXPLORE + ## Agent soft-compat
  • verify.md — VERIFY_EXPECTED
  • references/ops.md — index pointing at the slices
• Per-skill metadata.canopy-features manifest. Skills declare which feature slices they use; the runtime loads only those (core is implicit-always-loaded). Auto-generated by /canopy create/scaffold/improve/convert-to-canopy. Authors don't maintain it by hand.
• /canopy measure-context <skill> op (skills/canopy/references/ops/measure-context.md). Reports the line-count breakdown a skill costs to load — marker block + runtime baseline + manifest-driven slices + skill-local files. Highlights drift between the manifest and actual feature usage. Pure inspection; no mutations.
• MEASURE_CONTEXT registered in operations dispatch + detection + dispatch-schema.json enum. Trigger phrases include "measure context", "context size", "context cost", "manifest size".

Changed

• Slim marker block in assets/constants/marker-block.md (and the byte-identical mirrors in install.sh build_marker_block() and install.ps1 Build-MarkerBlock). The block is now a 2-line trigger + pointer (~5 lines including markers) — down from ~30 lines. Pre-v0.21.0 markers inlined the full spec dump in every canopy-active project's ambient instructions; the new block defers all spec to canopy-runtime/SKILL.md, loaded only when the runtime is engaged.
• canopy-runtime/SKILL.md documents the manifest-aware load procedure: read the skill's frontmatter, parse metadata.canopy-features, load core.md plus the listed slices. Manifest absent → load every slice (back-compat).
• runtime-claude.md and runtime-copilot.md reference the slice index instead of the deleted monolithic framework-ops.md. Cross-references updated throughout.
• skill-resources.md trimmed: subagent dispatch content moved to ops/subagent.md. Adds a new section documenting the manifest.
• Authoring agent ops updated for the manifest:
  • create.md — computes the manifest from the planned tree and emits it in produced SKILL.md frontmatter.
  • scaffold.md — template includes the manifest stub.
  • improve.md — audits skills for missing or drifted manifests; proposes additions/corrections in the decision table.
  • validate.md — new check pass: manifest presence (warning), feature-vs-tree drift (warning), core listed (warning), unknown values (warning).
  • convert-to-canopy.md — emits the manifest in produced SKILL.md.
• assets/constants/validate-checks.md — new "Warnings → manifest" section enumerating the four drift cases and the "manifest absent" warning.
• assets/templates/skill.md — template now includes metadata.canopy-features: [interaction] (the typical small-skill default).

Removed

• skills/canopy-runtime/references/framework-ops.md — the monolithic primitive file is split across references/ops/<slice>.md. Skills that referenced it by path will need to update; this is rare in practice (the runtime resolves primitives by lookup, not by path). /canopy improve reports any stale path references.

Notes

• No new feature surface. All v0.20.1 features (subagent dispatch, PARALLEL, etc.) keep working unchanged. v0.21.0 only changes how the runtime spec is structured and loaded.
• Marker-block parity. Canonical, install.sh, install.ps1 all updated. The vscode extension's MARKER_BLOCK constant must follow in a sibling-repo PR.
• Back-compat. Skills without a canopy-features manifest continue to run — the runtime falls back to load-everything. /canopy validate warns; never errors. Adoption is gradual.
• Footprint estimate. A skill using [interaction, verify] loads roughly 400 lines of runtime context (down from ~700). A skill using [parallel, subagent] loads ~470. A skill with [interaction, control-flow, parallel, subagent, explore, verify] (full feature surface) loads ~770 — comparable to pre-v0.21.0.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.21.0

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.21.0.tar.gz --owner kostiantyn-matsebora

v0.20.1

Patch release. Closes a versioning-process gap exposed during the v0.20.0 release.

Fixed

• metadata.version in all three SKILL.md frontmatters bumped to 0.20.1. The canopy, canopy-runtime, and canopy-debug skills had been carrying version: "0.18.1" since that release — gh skill install --pin vX.Y.Z only pins the git ref it pulls from, so these per-skill values stayed stale through the v0.19.0 and v0.20.0 bumps. No runtime behavior change; the fields are informational metadata that consumers see embedded in the installed file.

Changed

• .claude/rules/versioning.md extended from 4 → 7 sources of truth. Adds the three per-skill metadata.version fields to the lockstep group and includes a sanity-check grep snippet for pre-tag verification. Auto-loads on every SKILL.md open in addition to the existing version-tracking files.
• .claude/rules/versioning.md "How to bump" rewritten as a manual procedure — there is no /bump-version skill in this repo (it was removed; only the references lingered). CLAUDE.md and docs/CONTRIBUTING.md updated to match.

Notes

• No spec or runtime changes. gh skill install --pin v0.20.1 is the same install as v0.20.0 modulo the corrected metadata strings. Consumers who pinned v0.20.0 don't need to upgrade unless they read metadata.version from the installed SKILL.md.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.20.1

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.20.1.tar.gz --owner kostiantyn-matsebora

v0.20.0

S2 of the parallel-subagent design. Adds subagent dispatch via per-op markers — an op's definition decides whether it runs inline (today's behavior) or out-of-context as a subagent. No new primitives, no new section types.

Added

• Subagent dispatch by marker. Op definitions in references/ops.md (or references/ops/<name>.md) may carry a > **Subagent.** Output contract: <schema-path> blockquote as the first content under the heading. Calls to such ops use **OP_NAME** << input >> output (bold around the op name) — bold = out-of-context dispatch; plain = inline. Op-call syntax stays uniform; the marker decides dispatch. Documented in skills/canopy-runtime/references/skill-resources.md → ## Subagent dispatch.
• Strict-contract rule for subagent ops. Bodies of marked ops may use only << inputs + static skill assets (assets/constants/..., assets/templates/..., assets/policies/...). Ambient context.* reads not in the signature are contract violations — reserved for inline ops only.
• Bidirectional consistency. Bold call site ↔ op-def marker must match. /canopy validate flags mismatches in either direction.
• Composition with PARALLEL (S1). Bold-marked op calls as PARALLEL children give multi-typed parallel subagent fan-out — the canonical multi-source-explore / multi-aspect-review pattern. No grammar change to PARALLEL needed.

Changed

• skills/canopy-runtime/references/skill-resources.md — replaces ## Explore subagent with ## Subagent dispatch; covers marker shape, call-site convention, strict-contract rule, composition with PARALLEL, and soft-compat for ## Agent + EXPLORE.
• skills/canopy-runtime/references/runtime-claude.md and runtime-copilot.md — ## Agent Execution rewritten as ## Subagent dispatch with marker-based path (preferred) and ## Agent + EXPLORE soft-compat path. ## Parallel Subagent Invocation extended to mention marker-based children inside PARALLEL.
• skills/canopy-runtime/references/framework-ops.md — ## PARALLEL block notes that marker-based op-call children dispatch out-of-context; cross-references skill-resources.md.
• skills/canopy/assets/policies/authoring-rules.md — ## Subagent contract rewritten with marker dispatch as the primary form; legacy ## Agent body shapes (A/B/C) retained as a soft-compat subsection for existing skills only.
• skills/canopy/assets/constants/validate-checks.md — adds bidirectional-mismatch / missing-schema / strict-contract-violation / missing-input-schema / top-level-redundancy checks.
• skills/canopy/assets/constants/control-flow-notation.md — adds rows mapping legacy ## Agent/**explore** body to the marker form, and inline-op promotion.
• Authoring ops — improve.md proposes migration of ## Agent skills to the marker form and promotion of strict-contract-honoring inline ops; convert-to-canopy.md produces marker-form skills (no ## Agent for new skills); advise.md recommends marker form for new subagent work; validate.md cites the new check rules; create.md/scaffold.md no longer emit ## Agent for new skills.
• docs/CONCEPTS.md — adds "Inline op vs subagent op (dispatch model)" subsection under Op Lookup.
• docs/reference/FRAMEWORK_SPEC.md — Tree Execution Model table gains a row for the bold-marked subagent op call.

Soft-compat

• ## Agent (singular) section + EXPLORE >> context first-tree-node continues to work — the runtime treats it as a single-element marked op named EXPLORE. No skills break. Hard removal of the legacy path is deferred to a pre-1.0 cleanup.
• Existing inline ops without markers continue to run inline. No mass migration is required.

Deferred to S3

• Universal input/output contracts on every op (not just subagent-marked) + JSON Schema $ref composition through bindings + static type-flow analysis in vscode + runtime call-time input validation. S2 introduces the dispatch model; S3 layers the type system on top.
• Async/await opt-in (| async modifier) for non-blocking sequential subagents. Out of scope here.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.20.0

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.20.0.tar.gz --owner kostiantyn-matsebora

v0.19.0

Added

• PARALLEL block primitive — heterogeneous parallel-subagent fan-out as a real grammar element. PARALLEL takes no input and accepts ≥2 indented children; each child runs in its own context window. Defined in skills/canopy-runtime/references/framework-ops.md (mirrored to docs/reference/PRIMITIVES.md); platform emission rules in runtime-claude.md (multi-Task in one assistant turn) and runtime-copilot.md (fleet subtask / @CUSTOM-AGENT-NAME / sequential inline fallback). Failure semantics: Promise.allSettled — sibling failures don't abort. Backward-compatible: prose fan-out continues to work as the dynamic-shape escape hatch.

Changed

• Authoring agent now recognizes PARALLEL as a structural target. /canopy improve flags prose-fan-out patterns and proposes PARALLEL-block migration alongside existing primitive-migration suggestions. /canopy convert-to-canopy maps "spawn N in parallel" prose to PARALLEL blocks during conversion. /canopy advise recommends PARALLEL when a skill has ≥2 sequential ## Agent invocations with no data dependency between them.
• Marker-block updated in all framework sources (marker-block.md, install.sh, install.ps1) to list PARALLEL in the control-flow primitives. The vscode-extension mirror (claude-canopy-vscode/src/commands/installCanopy.ts) is updated separately in extension v0.12.0; parity check passes once both PRs land.
• Spec narrative docs (CONCEPTS.md, FRAMEWORK_SPEC.md Tree Execution Model + Op Lookup Order) extended to enumerate PARALLEL alongside existing primitives.

Notes

• This is the Tier 1 / S1 step from the parallel-subagent design ideation. S2 (## Agents + SPAWN per-subagent schema declarations) and S3 (PARALLEL_FOR_EACH data-parallel iterator) are deferred — escalate only if real skills demonstrate Tier 1 isn't enough.
• No behavioral break: every existing skill continues to parse and run unchanged.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.19.0

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.19.0.tar.gz --owner kostiantyn-matsebora

v0.18.1

Fixed

• scripts/validate.sh safety-preamble check: regex now matches the canonical period form (> **Runtime required.**); previously required a colon (> **Runtime required:**), which no actual template, policy, op, or SKILL.md in the repo uses — only the validator and one stray spot in docs/README.md. Result: post-merge CI on master flagged spec-compliant skills (including the bundled canopy and canopy-debug) as missing the preamble.

Notes — release integrity

• Tags are now SSH-signed. Verify with git verify-tag v0.18.1. The local clone has tag.gpgsign true set; the public key is registered as a Signing Key on GitHub.
• SLSA build provenance is attached to every release. release.yml now uses actions/attest-build-provenance@v2 to produce a Sigstore-signed provenance record over the install tarball (canopy-${VERSION}.tar.gz), each SKILL.md, and both plugin manifests. Verify with gh attestation verify canopy-0.18.1.tar.gz --owner kostiantyn-matsebora.
• Install tarball is now uploaded as a release asset. Same install surface as gh skill install / plugin marketplace, just packaged for offline / scripted consumption.
• SECURITY.md added at the repo root (private vulnerability reporting, supported versions, integrity-verification snippet, in-scope / out-of-scope list). Auto-surfaces on the repo's Security tab.
• master branch protection enabled: PR required, status check validate must pass, no force pushes, no deletions, linear history, conversation resolution required, admin enforcement on (no bypass).
• Docs site published at https://kostiantyn-matsebora.github.io/claude-canopy/ — full reference rendered with cayman theme, dark/light toggle, and per-section TOC.

No skill behavior changes from 0.18.0; this is a patch release for repo hygiene + verifiable supply-chain.

---

---

Verifying this release

# Verify the signed tag (uses GitHub's pubkey for SSH/GPG signatures)
git verify-tag v0.18.1

# Verify SLSA build provenance for the install tarball
gh attestation verify canopy-0.18.1.tar.gz --owner kostiantyn-matsebora

v0.18.0

Added

• agentskills.io standard layout: framework skills migrated to the spec-aligned layout — only SKILL.md at the root, with scripts/ (executable code), references/ (docs loaded on demand, including ops.md / ops/), and assets/ (static resources: templates/, constants/, schemas/, checklists/, policies/, verify/). Old flat layout (category dirs at the skill root) remains fully supported by canopy-runtime — Read references resolve literally. /canopy improve can migrate legacy skills on user opt-in.
• compatibility field on every ## Tree skill: spec-compliant free-text declaring the canopy-runtime requirement and its source repo, listing install tools as alternatives (gh skill install, git clone, install.sh/install.ps1, plugin marketplace) so the agent picks the install method its environment supports. Per agentskills.io spec, compatibility is a max-500-char string — structured shapes like compatibility: { requires: [...] } are non-spec and rejected by /canopy validate / migrated by /canopy improve. Authoring ops (CREATE, SCAFFOLD, CONVERT_TO_CANOPY, MODIFY) emit the canonical free-text form automatically.
• Safety preamble on every ## Tree skill: a fail-fast guard block at the top of the body that halts execution on agents without canopy-runtime active. Prevents silent wrong execution on unsupported platforms.
• canopy-runtime self-activation: canopy-runtime/SKILL.md now includes an Activation section that writes the marker block to CLAUDE.md (Claude Code) or .github/copilot-instructions.md (Copilot). Replaces the explicit /canopy:canopy activate step for all install paths.
  • Who writes the marker block, by install path:
    • install.sh / install.ps1 — the script writes it during install. Shell-context, no agent to defer to → project is fully activated when install completes.
    • gh skill install — file placement only. Marker block is written by the next agent invocation that loads canopy-runtime/SKILL.md and runs Activation.
    • Claude Code plugin marketplace — same as gh skill install: file placement only; agent writes the block on first load.
  • Idempotent — running Activation on a fully activated project is a no-op.
• Repo context detection: CREATE and SCAFFOLD choose the target skill location based on context.repo_context — distribution repos (skills/ at root) get skills written to skills/<name>/; consumer projects get them in .claude/skills/<name>/ or .github/skills/<name>/.
• Cross-skill extraction constraint: REFACTOR_SKILLS now requires extracted shared logic to become a complete, named, installable skill (with its own SKILL.md, compatibility field, and safety preamble); dependent skills declare it via compatibility. No more bare shared files referenced from sibling directories — preserves agentskills.io skill autonomy.
• SKILL.md uppercase enforcement: validate.sh and /canopy validate flag lowercase skill.md files. Required for case-sensitive filesystems (Linux, macOS APFS) and for gh skill install discovery.
• Frontmatter compliance enforcement: argument-hint and user-invocable are non-spec at frontmatter root and must live inside metadata. validate.sh rejects root-level placement.
• Cross-client install target (agentskills.io spec): a single install at .agents/skills/ serves both Claude Code and GitHub Copilot. canopy-runtime self-identifies the active host at runtime and applies the matching runtime spec (runtime-claude.md or runtime-copilot.md) — no path-derived platform detection. Cross-client is additive; existing claude / copilot / both install targets are preserved.
  • install.sh --target agents and install.ps1 -Target agents install to .agents/skills/. Marker block goes to whichever instructions file already exists (CLAUDE.md and/or .github/copilot-instructions.md); CLAUDE.md is created as fallback.
  • gh skill install ... --dir .agents/skills is the equivalent path for the gh-CLI flow. Newer gh (2.91+) defaults Copilot installs to .agents/skills/ automatically.
  • VSCode extension's install commands include a Cross-client pick alongside Claude Code, Copilot, and Both, in both the install-script and gh-skill flows.
• Skills-root resolution in canopy-runtime: <skills-root> is the first matching directory containing canopy-runtime/SKILL.md. Recognized roots, in order: .agents/skills/ → .claude/skills/ → .github/skills/. dispatch-schema.json's explicit_target_platform enum gains cross-client.

Changed

• commands/ directory renamed → scripts/ (matches agentskills.io standard).
• ops.md and ops/ moved under references/ (as documentation loaded on demand, per the agentskills.io progressive-disclosure pattern).
• All static resource directories (schemas/, templates/, constants/, checklists/, policies/, verify/) moved under assets/.
• IMPROVE op extended with agentskills.io compliance checks: missing compatibility, missing safety preamble, root-level argument-hint/user-invocable, lowercase skill.md, structured-object compatibility (migrated to spec-compliant free-text). Optionally migrates legacy flat layout to the standard layout.
• CONVERT_TO_REGULAR op now strips compatibility field and safety preamble (regular agentskills.io skills don't require them).
• canopy-runtime category-directory documentation updated for new layout in skill-resources.md, framework-ops.md, runtime-claude.md, runtime-copilot.md.
• canopy-runtime platform detection moved from path-derived to runtime self-identification — the agent identifies itself (Claude Code / Copilot / other) instead of inferring from the skills-root path. runtime-claude.md and runtime-copilot.md use the abstract <skills-root> placeholder so both specs work regardless of install location.
• Marker block content restructured as bulleted (with nested) lists for readability and updated to mention all three skills roots. CI parity check across marker-block.md, install.sh, install.ps1, and the vscode extension's MARKER_BLOCK constant still enforced.
• Marker block canonical file moved from skills/canopy/assets/constants/marker-block.md to skills/canopy-runtime/assets/constants/marker-block.md. Reason: gh skill install canopy-runtime does not transitively pull canopy; the runtime must be self-contained for activation. Authoring ops (/canopy activate) cross-reference the new location via ../canopy-runtime/....

Notes

• Not a breaking change: existing consumer skills using the legacy flat layout continue to execute correctly. canopy-runtime resolves Read references literally; old skills don't need migration. Existing --target claude / copilot / both install flows unchanged. Cross-client is purely additive.
• VSCode extension claude-canopy-vscode updated in lockstep — language ID file patterns rewritten for new layout (commands/*.{ps1,sh} → scripts/*.{ps1,sh}; templates/* → assets/templates/*; etc.) AND extended to also recognize .agents/skills/ paths. Diagnostics flag old-layout skills with a "consider migrating" hint.

---

v0.17.1

Added

• ACTIVATE op (/canopy:canopy activate or /canopy activate): writes the canopy-runtime marker block to the current project's CLAUDE.md and/or .github/copilot-instructions.md. Closes the runtime-activation gap for the two install paths that don't write the block automatically — /plugin install canopy@claude-canopy and manual gh skill install. Fully idempotent: same write contract as install.sh write_marker_block() (create / append / replace / unchanged / refuse-on-malformed). Run once per project after a plugin or gh-skill install; user-authored canopy skills under .claude/skills/ / .github/skills/ then load runtime ambiently. Detection phrases: activate, activate runtime, wire up runtime, install runtime, write marker block, ambient activation, runtime not loading.
• skills/canopy/constants/marker-block.md: canonical source of the marker block content + the idempotent write contract. Documented as needing to stay byte-identical with install.sh build_marker_block() and install.ps1 Build-MarkerBlock.

Notes

• Existing install paths are unchanged. Users who installed via install.sh / install.ps1 (or via the vscode extension's installAsAgentSkill) already have the block — running ACTIVATE on those projects is a safe no-op.

---