@ikon85/agent-workflow-kit 0.34.6 → 0.36.0

package/.claude/skills/kit-update/SKILL.md

@@ -3,6 +3,14 @@ name: kit-update
 description: "Preview and transactionally apply a parity-verified agent-workflow-kit release without overwriting local modifications or auto-resolving conflicts."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill kit-update --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Kit Update
 
 Update an installed consumer only from the public scoped package
@@ -84,21 +92,34 @@ release contain the same artifact.
    core, and still unresolved capability states. Missing readiness for genuinely
    new behavior does not block a compatible kit update; only that behavior stays
    unavailable. A compatible update must stop if it would make previously
-   available skill core unavailable. `--yes` answers only package reconciliation
-   questions and never supplies a readiness decision. Automated update pull
+   available skill core unavailable. `--yes` answers only actions whose
+   interpretation is already known and never supplies a readiness or ownership
+   decision. An untracked destination at a new Kit path remains
+   `ambiguous-collision` under `--yes`; interactive and automated runs must
+   explicitly choose Project extension, Contribution Bridge, Explicit fork, or
+   clean Core. Diagnostics name only path, ledger/package/extension evidence,
+   and safe routes—never file content. Automated update pull
    requests carry the same availability summary and remain manual-merge only.
 
    For each conflicted kit-shipped file, always ask the user whether the local
    edit is a generic improvement or project-specific; never decide or act
-   automatically. For a generic improvement, offer to file an issue in the
-   public kit repository and keep the local edit in place as a bridge until a
-   kit release containing the improvement lands. Before running
-   `gh issue create --repo <owner>/agent-workflow-kit`, show a sanitized preview
-   of the exact title and body with consumer identifiers and secrets stripped,
-   then require the user's explicit approval. The consumer user does not need
-   to be a kit maintainer. For a project-specific edit, recommend
-   `npx @ikon85/agent-workflow-kit@latest own <path>` so future updates treat
-   that path as consumer-owned.
+   automatically. For a generic improvement retained as a bridge, run
+   `contribute status <path> --surface=pre-update` and follow only its
+   repository-capability routes. Missing, disabled, invalid, or unverifiable
+   configuration is a generic Consumer and receives preserve/Explicit-fork
+   guidance, never maintainer language or an inferred upstream target. A valid
+   capability may add local preparation and may describe an upstream pull
+   request, but the latter still needs a sanitized exact preview and separate
+   explicit approval before any remote command. For a project-specific edit, recommend
+   `npx @ikon85/agent-workflow-kit@latest own <path> --as=explicit-fork` so
+   future updates treat that path as an independent fork. A generic experiment
+   retained only until it returns upstream uses
+   `npx @ikon85/agent-workflow-kit@latest contribute start <path>`. Prepare its
+   bounded local artifact, when the route report permits it, with `contribute prepare <path>
+   --output=.agent-workflow-kit/contributions/<name>.json`. Both commands are
+   local-only; opening an issue/PR or pushing remains a separate explicit
+   approval. A matching released Core version retires the bridge during
+   reimport.
 
 4. If a candidate is interrupted, discard its reported stage directory or
    resume the transaction through the update API's `resumeFrom` option. Do not

package/.claude/skills/local-ci/SKILL.md

@@ -3,6 +3,14 @@ name: local-ci
 description: Run the repo's local CI gate before opening a PR — the stand-in for GitHub required status checks when your plan or repo visibility can't enforce them (a Free-plan private repo has no branch protection). Use before every PR, when a guard/test red is suspected on a branch, or when wiring/repairing the pre-push guard backstop. Triggers — "local ci", "run local ci", "pre-PR check", "why is main red", "did a guard land red".
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill local-ci --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Local CI
 
 A guard only protects if it runs on a **gate**. When your host can't enforce a

package/.claude/skills/memory-lifecycle/SKILL.md

@@ -3,6 +3,14 @@ name: memory-lifecycle
 description: "Preview and apply a consumer-owned memory lifecycle without crossing configured roots or overwriting active, archived, or recovery evidence. Use when a user wants to restore archived memories, inspect memory placement, or run an approved memory recovery."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill memory-lifecycle --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Memory Lifecycle
 
 Coordinate the current repository's memory placement and recovery through the

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -58,8 +58,8 @@ node scripts/readiness.mjs check --skill orchestrate-wave --json
 > `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
 > instructions when the layer is absent. See **Phase 0**.
 >
-> When `projectRecipe` is active, read the filled project layer before applying
-> any phase-specific command below.
+> Before consuming `projectRecipe`, run `node scripts/project-skill-extension.mjs inspect --skill orchestrate-wave --json`: `active` reads its `path`; `inactive` uses Core; `blocked` stops with its diagnostic.
+> Project extensions may specialize Project details, but cannot weaken Core gates; a contradiction blocks and requires an Explicit fork.
 <!-- readiness:end -->
 
 ## Standing rules (all phases)

package/.claude/skills/project-release/SKILL.md

@@ -3,6 +3,14 @@ name: project-release
 description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill project-release --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Project Release
 
 Prepare a consumer-owned multi-package release through the kit's shared

package/.claude/skills/prototype/SKILL.md

@@ -3,6 +3,14 @@ name: prototype
 description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill prototype --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Prototype
 
 A prototype is **throwaway code that answers a question**. The question decides the shape.

package/.claude/skills/research/SKILL.md

@@ -3,6 +3,14 @@ name: research
 description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill research --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 Before dispatch, resolve a provider-neutral Routing intent through
 `src/lib/routeDispatcher.mjs` and require a Dispatch receipt from the shared
 spawn guard. A detected transport is not authorization; AFK dispatch stops

package/.claude/skills/resolving-merge-conflicts/SKILL.md

@@ -3,6 +3,14 @@ name: resolving-merge-conflicts
 description: "Use when you need to resolve an in-progress git merge/rebase conflict."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill resolving-merge-conflicts --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
 
 2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.

package/.claude/skills/retro/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: false
 description: Use when the user explicitly asks for a retro after a session with PR-activity. Analyzes session friction and proposes concrete config mutations (Memory/Skill/CLAUDE.md/Hook) with per-patch approval. No file is written — findings live in the mutated config.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill retro --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Retro — In-Session Deep-Dive
 
 Trigger: user types `/retro` (optionally with a PR/Issue number, e.g. `/retro 274`).
@@ -156,9 +164,17 @@ Before formulating a patch in step 4, place **every** friction point on the thre
 
 **A GitHub issue is NOT a weight tier.** A real follow-up = work to track → `python3 scripts/board-sync.py create` (step-4 table), **orthogonal** to the ladder; its "weight" follows the follow-up scope. The ladder classifies **config patches**, not "turn it into a ticket".
 
-**Kit-repo routing target (always ask; never automatic).** When a finding lands on a kit-shipped file (a consumer-manifest entry with kit origin), ask whether the improvement is generic or project-specific. For a generic improvement, offer to file a lightweight issue against the public kit repo: a title plus a short body that states the finding, affected file, and why it is generic. For a project-specific improvement, recommend `own` (keep it consumer-owned). The consumer user does not need to be the kit maintainer.
-
-Before any `gh issue create --repo <owner>/agent-workflow-kit` runs, show the user a **sanitized preview** of the exact title and body with consumer identifiers and secrets stripped. Create the issue only after the user explicitly approves that exact text; if the title or body changes, show the revised preview and ask again. This approval is additional to the per-patch approval in step 5.
+**Kit-repo routing target (capability-driven; never automatic).** When a finding
+lands on a kit-shipped file (a consumer-manifest entry with kit origin), ask
+whether the improvement is generic or project-specific. If it enters a
+Contribution Bridge, run `agent-workflow-kit contribute status <path>
+--surface=retro` and use only the reported repository-capability routes.
+Missing, disabled, invalid, or unverifiable configuration is a generic Consumer:
+offer preserve or Explicit fork, never infer maintainer status or an upstream
+target from identity. A valid capability may offer local preparation. Before
+any reported remote route runs, show the **sanitized exact preview** and require
+separate explicit approval; changing the preview requires approval again. For a
+project-specific improvement, recommend `own` (keep it consumer-owned).
 
 **Target missing in the project — separate two cases cleanly:**
 - **(a) Tier skill missing entirely** (e.g. a foreign project without `spec-self-critique`): no durable spec-time gate exists. **Memory is NOT a substitute** — passive recall doesn't catch a recurring spec defect before building. Report honestly: *"this project has no durable target for this tier"* + propose a `/setup-workflow` follow-up. **No fake guard via memory.**

package/.claude/skills/scale-check/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Route an undertaking to the right altitude before any planning starts — a short plain-language dialog (3–6 questions) deciding between a Program, a Feature, a single Direct-Slice, or a Bug, then hand back a paste-ready start prompt for the chosen route. Use at the very start of a new build when the size is unclear (a new app, a big cross-cutting feature, or a where-do-I-start question). Owns the altitude criteria catalog; when in doubt it routes to Feature. NOT for slicing a chosen plan (to-issues) and NOT for clustering an existing backlog (board-to-waves)."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill scale-check --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # scale-check — Route an undertaking to its altitude
 
 Answers one question in plain language: **"how big is this, and where do I start?"**

package/.claude/skills/security-audit/SKILL.md

@@ -3,6 +3,14 @@ name: security-audit
 description: Run the whole application's security audit as an independent two-model pass — two AI models audit the same code separately — then harden the remediation plan before any fix lands. Use when the user wants a security audit / security review of the entire app ("audit the app for vulnerabilities", "is the app secure", "security check before release"), before a release, or after the attack surface changes (new endpoint, new input source, auth change, dependency bump). NOT for reviewing a single diff/PR (that is a code review) and NOT for infrastructure hardening (firewall/ports/TLS/SSH/backups — audited separately from the application layer).
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill security-audit --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # security-audit — application-layer security audit (two-model run)
 
 Application-layer security audit of the whole repo. This skill is the **run

package/.claude/skills/setup-pre-commit/SKILL.md

@@ -3,6 +3,14 @@ name: setup-pre-commit
 description: Set up a native, zero-dependency git pre-commit hook (via core.hooksPath) that runs your project's type checks, linting, tests, or formatting before each commit. Use when the user wants to add pre-commit hooks, gate commits on checks, or wire commit-time typecheck/lint/test/format — no Husky or Node deps required.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill setup-pre-commit --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Setup Pre-Commit Hooks (native git, zero-dep)
 
 ## What This Sets Up

package/.claude/skills/setup-workflow/SKILL.md

@@ -4,6 +4,14 @@ description: "Scaffolds the project layer the portable workflow skills assume
 disable-model-invocation: true
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill setup-workflow --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Setup Workflow
 
 Scaffold the **project layer** the portable workflow skills (`to-prd`, `to-issues`, `triage`, `spec-self-critique`, `retro`, `wrapup`, …) read at runtime. The generic skills ship the *how*; this skill writes the project-specific *what* into the consumer repo, where `retro`/`wrapup` then grow it over time.
@@ -48,6 +56,28 @@ Every project-layer file this skill (or `npx init`) creates begins with **one se
 - **CLAUDE.md / AGENTS.md carry no sentinel** (they are not ours) → reconcile **per section** via the block headers `## Workflow` / `## Agent skills` / `## Prod`: add a missing block, never overwrite an existing one or surrounding user content.
 - **Never overwrite filled content.** A re-run only fills what is missing/stub. End with a report: `<file>: created · filled · skipped (already filled / legacy / not-applicable)`.
 
+## Universal Project skill extensions
+
+Every shipped skill can consume an additive Project extension at
+`docs/agents/skills/<skill>.md`. A newly created extension starts with this
+identity and schema marker (after the optional setup-workflow sentinel):
+
+```md
+<!-- agent-workflow-kit: project-extension/v1; skill=<skill> -->
+```
+
+The marker's `<skill>` must match the filename and a canonical or locally
+registered skill identity. Existing non-empty files without a marker remain
+supported as legacy v0 and are never rewritten merely to add the marker.
+Setup and update preserve every extension byte-for-byte unless a future,
+declared schema migration explicitly includes it.
+
+Use an extension for Project language, commands, policy, and capability data
+that the Core skill already knows how to apply. It is additive and cannot
+weaken Core user gates, safety, ownership, or validation. Changes to parsing,
+migration, evaluation, or other executable Core semantics require an
+Explicit fork with a separate identity and update line.
+
 ## Process
 
 ### 1. Explore
@@ -263,7 +293,8 @@ decisions without repository evidence and user confirmation.
 > manifest. It is advisory only: it never blocks, reads the manifest once, uses
 > no network, and silently fails open when the manifest cannot be read. Shell
 > redirection, formatters, and IDE edits are knowingly outside its coverage; the
-> skills remain the rule's primary carrier.
+> skills remain the rule's primary carrier. Its Contribution Bridge follow-up
+> calls the same read-only route resolver with `--surface=guard`.
 
 Activate the shipped hook by reconciling this exact entry into
 `.claude/settings.json`:
@@ -327,6 +358,26 @@ unaffected surfaces, autonomy, and advanced values. Re-read the profile before
 activation and use its fingerprint plus the exclusive profile lock; a
 concurrent user-local change blocks activation and remains byte-preserved.
 
+### 2i. Section A10 — Optional contribution return routing
+
+> Contribution return routing lets a repository advertise a verifiable Kit
+> upstream without guessing who the user is. It controls offered routes, never
+> remote authorization.
+
+Read [contribution-routing.md](./contribution-routing.md) in full. If
+`contributionRouting` is absent, ask whether this repository should advertise
+an upstream contribution route. **Yes** records only the user-confirmed
+owner/repository and local Git remote after verifying that the remote URL
+matches. **Later / No** leaves the section absent or records `enabled: false`
+only when the user requests a durable opt-out. Adopt an existing valid section
+without normalization and preserve every other profile section and unknown key.
+
+Missing, disabled, contradictory, or unverifiable configuration must keep the
+generic preserve/Explicit-fork routes. Never infer capability from username,
+machine, checkout path, repository name, credentials, or current GitHub login.
+Even a valid capability authorizes local preparation only; a pull request,
+push, publish, or merge remains a separate explicit approval.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.

package/.claude/skills/setup-workflow/contribution-routing.md

@@ -0,0 +1,52 @@
+# Contribution return routing
+
+Contribution return is an optional repository capability. It controls which
+routes agents may *offer* for an explicit Contribution Bridge; it never grants
+permission to mutate a remote.
+
+The consumer-owned section in `docs/agents/workflow-capabilities.json` is:
+
+```json contribution-routing-capability
+{
+  "contributionRouting": {
+    "schemaVersion": 1,
+    "enabled": true,
+    "upstream": {
+      "repository": "<owner>/<repository>",
+      "remote": "<local-git-remote>"
+    },
+    "workflows": {
+      "prepareLocal": true,
+      "upstreamPullRequest": {
+        "enabled": true,
+        "requiresExplicitApproval": true
+      }
+    }
+  }
+}
+```
+
+The resolver accepts the maintainer-capable route only when the configured Git
+remote exists and its GitHub owner/repository matches `upstream.repository`.
+It does not inspect usernames, home paths, machine names, the consumer
+repository name, credentials, or GitHub account identity.
+
+- Missing configuration is a generic Consumer: offer preserve or Explicit fork.
+- `enabled: false` is an explicit opt-out with the same generic routes.
+- Invalid, contradictory, or unverifiable configuration fails closed to those
+  generic routes and reports one bounded diagnostic.
+- Valid configuration additionally offers local artifact preparation. It may
+  describe an upstream pull-request route only with
+  `requiresExplicitApproval: true`; this flag documents the gate and does not
+  satisfy it.
+
+Use the same read-only resolver on every surface:
+
+```sh
+agent-workflow-kit contribute status <path> --surface=retro
+agent-workflow-kit contribute status <path> --surface=pre-update
+agent-workflow-kit contribute status <path> --surface=guard
+```
+
+Only `contribute prepare` writes a local bounded artifact. No contribution
+command opens an issue or pull request, pushes, publishes, or merges.

package/.claude/skills/setup-workflow/orchestrate-wave-seed.md

@@ -1,3 +1,4 @@
+<!-- agent-workflow-kit: project-extension/v1; skill=orchestrate-wave -->
 # Project layer — orchestrate-wave
 
 The generic `orchestrate-wave` skill ships the full wave-landing **mechanics**

package/.claude/skills/setup-workflow/spec-self-critique-seed.md

@@ -1,3 +1,4 @@
+<!-- agent-workflow-kit: project-extension/v1; skill=spec-self-critique -->
 # Project layer — spec-self-critique
 
 The generic `spec-self-critique` skill ships the 12-point checklist (the check *intents* + the structure). This file is the **project layer**: it enriches each point with project-specific incidents, grep patterns, conventions, and extra sub-checks. The skill reads it at runtime; with this file present it runs the full pass instead of warning that the layer is absent.

package/.claude/skills/spec-self-critique/SKILL.md

@@ -3,6 +3,14 @@ name: spec-self-critique
 description: "Use AFTER writing or editing a spec (a `SPEC.md`/`PLAN.md` or any spec/design doc), BEFORE asking the user to review — runs a 12-point structural Self-Critique checklist, fixes issues inline, and emits a visible summary. Enriches each check from a project layer if one is present. Triggers right after a spec has been written. NOT for reviewing finished code/diffs (code-review) — this pass runs on the spec text itself."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill spec-self-critique --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Spec Self-Critique
 
 A portable, structural self-review pass over a freshly written spec/plan. The **generic 12-point skeleton** below ships as-is; a **project layer** (if present) enriches each point with project-specific incidents, grep patterns, conventions, and extra sub-checks.

package/.claude/skills/tdd/SKILL.md

@@ -3,6 +3,14 @@ name: tdd
 description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill tdd --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Test-Driven Development
 
 ## Philosophy

package/.claude/skills/to-issues/SKILL.md

@@ -3,6 +3,14 @@ name: to-issues
 description: Break a Feature or Program plan, spec, or PRD into independently-grabbable issues on the project issue tracker. This is the single public Planning facade: explicit Feature identity uses tracer-bullet decomposition; explicit Program identity delegates to the internal graph engine.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill to-issues --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # To Issues
 
 > **Skill identity (don't get confused):** the folder `to-issues` + invocation `/to-issues` map to Matt Pocock's upstream skill **`to-tickets`**. Upstream merged `to-issues` + the short-lived `to-plan` into `to-tickets` (v1.1.0); we deliberately keep the folder name `to-issues` (invocation stability, and issues are this workflow's vocabulary). Content remains our fork, compared against upstream `to-tickets` @ `d574778`. Provenance/rename ledger: `docs/agents/provenance.md` (§Re-Sync-Log), at the project root.

package/.claude/skills/to-prd/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Turn a locked plan (PLAN.md in the worktree, conversation context, or an externally-authored spec) into a Draft-PRD issue on the project board, then run spec-self-critique. Use after a grill (grill-me / grill-with-docs / their -codex variants) when you want to publish the PRD. Three modes — create fresh, reuse an existing cluster/Wave-less issue, or auto-detect a Program-PRD from a plan's Wellenplan chapter. Does NOT decompose into slices (that is to-issues) and does NOT set type:cluster / Wave (that is to-issues promotion)."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill to-prd --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # to-prd — Draft PRD to the Board
 
 > **Skill identity (don't get confused):** the folder `to-prd` + invocation `/to-prd` map to Matt Pocock's upstream skill **`to-spec`**. Upstream renamed `to-prd` → `to-spec` (v1.1.0); we deliberately keep the folder name `to-prd` (invocation stability, and PRD is this workflow's vocabulary). Content remains our fork, compared against upstream `to-spec` @ `d574778`. Provenance/rename ledger: `docs/agents/provenance.md` (§Re-Sync-Log), at the project root.

package/.claude/skills/to-waves/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Internal Program graph engine behind the public to-issues Planning facade. Turns an explicitly identified Program-PRD into execute-ready wave anchors and slice leaves after one complete chat preview. Kept as a disabled compatibility entrypoint for existing explicit invocations; normal routing always selects to-issues."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill to-waves --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # to-waves — Internal Program graph engine
 
 This skill is an **Internal Program graph engine**, selected by `to-issues` only

package/.claude/skills/triage/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: Triage issues through the project board workflow. Use when user wants to triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill triage --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Triage
 
 Move issues on the project issue tracker through the board-driven workflow.

package/.claude/skills/verify-spike/SKILL.md

@@ -3,6 +3,14 @@ name: verify-spike
 description: Answer a single yes/no factual question about reality with a minimal throwaway, read-only harness and output-proof. Use when a plan, ADR, or implementation hinges on an empirically-checkable fact — does a library API exist / behave this way on this version, does the runtime / DB / platform actually have this capability, does an external assumption hold — and you need a proven verdict before locking the decision. NOT for design exploration (prototype), bug root-cause (diagnose), or building a feature (tdd).
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill verify-spike --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Verify Spike
 
 A verify-spike is **throwaway, read-only code that proves a yes/no fact about reality.** The question is binary; the spike makes the answer empirical instead of assumed.

package/.claude/skills/wayfinder/SKILL.md

@@ -4,6 +4,14 @@ description: Plan a huge chunk of work — more than one agent session can hold
 disable-model-invocation: true
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill wayfinder --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its tickets one at a time until the route is clear.
 
 The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.

package/.claude/skills/wrapup/SKILL.md

@@ -14,6 +14,14 @@ description: >-
   push, a conflicting PR, or red (FAILURE) checks.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill wrapup --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # wrapup — land PR & tear down worktree
 
 Trigger: user types `/wrapup` (optionally with a PR number). **Manual only** — `disable-model-invocation: true`, no hook, no auto-invoke.

package/.claude/skills/write-a-skill/SKILL.md

@@ -3,6 +3,14 @@ name: write-a-skill
 description: Create, write, edit, and improve agent skills — the vocabulary and principles that make a skill predictable (invocation, information hierarchy, progressive disclosure, leading words, pruning, failure modes). Use when the user wants to create, write, edit, refactor, or improve a skill.
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill write-a-skill --json` from the Project root. When it returns `active`, read the returned `path` and apply it as additive Project instructions. When it returns `inactive`, continue with Core only. When it returns `blocked`, stop and report its diagnostic.
+
+Project extensions may specialize Project details, but cannot weaken Core user gates, safety, ownership, or validation. A contradiction blocks and requires an Explicit fork.
+<!-- project-extension:protocol-v1:end -->
+
 # Writing Skills
 
 > **Skill identity (don't get confused):** the folder `write-a-skill` + invocation `/write-a-skill` map to Matt Pocock's upstream skill **`writing-great-skills`**. Upstream replaced the old process-/template-based `write-a-skill` with this vocabulary/principles reference and switched it to **user-invoked** (`disable-model-invocation: true`). We keep the folder name `write-a-skill` (invocation stability) **and** deliberately keep it **model-invoked** (auto-fires on "create/write a skill" + `/write-a-skill`, as referenced in CLAUDE.md `## Workflow`). Content = upstream `writing-great-skills` @ `7a83a3a`, locally adapted. Provenance/rename ledger: `docs/agents/provenance.md` (§Re-Sync-Log), at the project root.