@ikon85/agent-workflow-kit 0.34.6 → 0.36.0

package/.agents/skills/ask-matt/SKILL.md

@@ -4,6 +4,14 @@ description: "Ask which skill or flow fits your situation. A router over the ski
 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 ask-matt --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 -->
+
 # Ask Matt
 
 > **Homage + Router.** Adopted from Matt Pocock's `ask-matt` (MIT, github.com/mattpocock/skills @ `7a83a3a`) — the name stays as a nod to upstream, the content is adapted to *this* repo's skill set (the plan→execute→land→learn line plus our gates, cross-model review, and land/learn skills). Provenance: `docs/agents/provenance.md`. Folder↔upstream-name note: `/diagnose` = upstream `diagnosing-bugs`, `/write-a-skill` = upstream `writing-great-skills` (renamed upstream, local names kept).

package/.agents/skills/audit-skills/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Audit the project's own skills for drift from code/doc reality and fix it — the anti-drift learn step. Run at retro, periodically, or when a drift-hint warns a skill's declared source moved since its last touch. Fans out one read-only research subagent per skill, re-verifies each reported drift before editing (the auditor produces false positives), and fixes by content type. Triggers: audit the skills, skill drift, stale skill, skill points at a dead path or renamed symbol."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill audit-skills --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 -->
+
 # audit-skills — Skill freshness audit (anti-drift)
 
 A reusable recipe for checking the project's own skills against code/doc reality

package/.agents/skills/board-to-waves/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: false
 "description": "Use when sweeping/grooming the GitHub backlog board to cluster open issues into thematic waves (Wellen) — \"lass uns das Board durchgehen\", \"was ist offen und passt zusammen\", \"clustern wir den Backlog\", \"welche Wellen stecken da drin\" — or to spot candidate waves before planning. Reads all open issues, groups them by the Gate+Booster+Splitter heuristic, estimates size/risk + grill-needed per candidate, and after the user confirms creates cluster/Wave-less candidate STUB issues with a To-Do checklist. STOPS at stubs: no PRD, no slicing, no sub-issue links, no promotion (downstream: to-prd matures the stub, to-issues slices + promotes). NOT for maturing/slicing ONE already-chosen candidate (to-prd/to-issues), NOT for per-issue triage labelling (triage), NOT for code comprehension — this is board-WIDE thematic affinity grouping, not per-issue and not code-reading."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill board-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 -->
+
 # board-to-waves
 
 **Survey the board → cluster open issues by theme → anchor stub issues.** Systematizes how Welle F came about: first look at what's open and what fits together, then form thematic waves. Result lands durably as an anchor issue on the board (GitHub = SSOT), not as a chat list.

package/.agents/skills/census-update/SKILL.md

@@ -3,6 +3,14 @@ name: census-update
 description: "Build, refresh, or check an optional project-local census. Use when a user invokes census-update, asks to establish a counted surface census, or needs to reconcile census drift; scan facts in the current repository, guide only ambiguous decisions, and activate a verified candidate transactionally."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill census-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 -->
+
 # Census Update
 
 Build and maintain the current repository's consumer-owned census through the

package/.agents/skills/code-review/SKILL.md

@@ -3,6 +3,14 @@ name: code-review
 description: Review a diff, branch, or PR against two separate axes — Standards (this repo's own conventions plus a Fowler-smell baseline) and Spec (does the diff faithfully implement the originating issue/PRD) — reported side by side, never merged or re-ranked. Runs a three-dot merge-base preflight before either axis starts. Use when asked to review a diff/branch/PR, or when a review needs to answer both "does this follow our standards" and "does this match the spec" without one masking the other. NOT for a pre-code plan review (that reviews a plan before any code exists), NOT for root-causing a known bug (`diagnose`), and NOT a pure reuse/simplification/efficiency pass (narrower, no bug-hunting).
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill code-review --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 -->
+
 # Code Review
 
 A code-review compares one diff against **two independent axes** — Standards and Spec — and reports them **separately**. A diff can pass one axis and fail the other: code that satisfies every convention but builds the wrong thing is a Standards-pass/Spec-fail; code that nails the issue but breaks conventions is a Spec-pass/Standards-fail. Merge or re-rank the two and one axis silently masks the other — that is the exact failure mode this method exists to prevent.

package/.agents/skills/codebase-design/SKILL.md

@@ -3,6 +3,14 @@ name: codebase-design
 description: "Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill codebase-design --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 -->
+
 # Codebase Design
 
 Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.

package/.agents/skills/codex-adapter-sync/SKILL.md

@@ -3,6 +3,14 @@ name: codex-adapter-sync
 description: "Use to audit and update the Codex adapter after changes to CLAUDE.md, package CLAUDE.md files, .claude/skills, .claude/agents, or Codex setup. Checks AGENTS.md, .agents/skills, .codex/config.toml, .codex/agents, and .gitignore for drift."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill codex-adapter-sync --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 -->
+
 # Codex Adapter Sync
 
 Use this skill when the user asks for a Codex adapter sync, Codex drift check,

package/.agents/skills/decision-gate/SKILL.md

@@ -3,6 +3,14 @@ name: decision-gate
 "description": "Resolve a bounded trade-off choice or a targeted research gap with read-only investigation, a documented weigh-up, and a reasoned decision. Use when a plan or slice hinges on a concrete \"which option\" choice or a \"need to research this first\" gap that is above a binary yes/no fact (verify-spike) but below a high-stakes, hard-to-reverse, ADR-worthy decision (grill-with-docs-codex). Output is a trade-off table plus a justified pick sunk into an ADR/issue/comment. NOT for binary fact-checks (verify-spike), open-ended design feel (prototype), or bug root-cause (diagnose)."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill decision-gate --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 -->
+
 # Decision Gate
 
 A decision-gate resolves **a bounded "which option" choice — or a targeted research gap — with evidence, not a hunch.** You have two or more candidate approaches (or one approach you cannot yet commit to), the call is small enough that a full design-grill is overkill, but it is more than a single yes/no fact. The gate makes the choice **documented and defensible** instead of decided in your head.

package/.agents/skills/diagnose/SKILL.md

@@ -3,6 +3,14 @@ name: diagnose
 description: "Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says \"diagnose this\" / \"debug this\", reports a bug, says something is broken/throwing/failing, or describes a performance regression."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill diagnose --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 -->
+
 # Diagnose
 
 > **Skill identity (don't get confused):** the folder `diagnose` + invocation `/diagnose` map to Matt Pocock's upstream skill **`diagnosing-bugs`**. Upstream renamed `diagnose` → `diagnosing-bugs`; we deliberately keep the folder name `diagnose` (invocation stability `/diagnose`). Content = upstream `diagnosing-bugs` @ `7a83a3a`, locally adapted (description kept with full trigger coverage). Provenance/rename ledger: `docs/agents/provenance.md` (§Re-Sync-Log), at the project root.

package/.agents/skills/domain-modeling/SKILL.md

@@ -3,6 +3,14 @@ name: domain-modeling
 description: "Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill domain-modeling --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 -->
+
 # Domain Modeling
 
 > **In this repo (if present):** `CONTEXT.md` + `docs/adr/` already exist (lazily created via `/grill-with-docs`). The **ADR conventions are SSOT in `docs/adr/README.md`** (project root; status lifecycle, template, numbering) — use that convention when creating an ADR, don't shadow it with the generic [ADR-FORMAT.md](./ADR-FORMAT.md). `/grill-with-docs`(-codex) maintains CONTEXT.md + ADRs in operation; this skill is the vocabulary underneath. Provenance: `docs/agents/provenance.md`.

package/.agents/skills/git-worktree-recover/SKILL.md

@@ -3,6 +3,14 @@ name: git-worktree-recover
 description: "Recovery skill for git branch mix-ups — a commit landed on the wrong branch, the branch switched unexpectedly, or work appears lost. Uses git reflog to find the misplaced commit, moves it to the right branch (git branch -f), optionally resets the wrong branch, and sets up a clean worktree. Triggers: commit on the wrong branch, branch switched on its own, this commit doesn't belong here, my work is gone, I committed to main by accident."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill git-worktree-recover --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 -->
+
 # git-worktree-recover
 
 Recovery skill for branch mix-ups. When two processes share one checkout's global

package/.agents/skills/grill-me/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions \"grill me\"."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill grill-me --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 -->
+
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
 Ask the questions one at a time.

package/.agents/skills/grill-with-docs/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill grill-with-docs --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 -->
+
 <what-to-do>
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

package/.agents/skills/implement/SKILL.md

@@ -4,6 +4,14 @@ description: "Implement a piece of work based on a PRD or set of issues."
 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 implement --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 -->
+
 Implement the work described by the user in the PRD or issues.
 
 ## Pickup — claim the issue first

package/.agents/skills/improve-codebase-architecture/SKILL.md

@@ -4,6 +4,14 @@ disable-model-invocation: true
 description: "Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill improve-codebase-architecture --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 -->
+
 # Improve Codebase Architecture
 
 Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

package/.agents/skills/kit-release/SKILL.md

@@ -3,6 +3,14 @@ name: kit-release
 description: "Prepare, integrate and publish a verified agent-workflow-kit release: one confirmed Semver authorizes the annotated version tag, then monitor npm/GitHub parity to released."
 ---
 
+<!-- project-extension:protocol-v1:start -->
+## Project extension
+
+Before applying this Core skill, run `node scripts/project-skill-extension.mjs inspect --skill kit-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 -->
+
 # Kit Release
 
 Prepare a release deterministically. This skill owns the shipped-delta decision,

package/.agents/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/.agents/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/.agents/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/.agents/skills/orchestrate-wave/SKILL.md

@@ -50,8 +50,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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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.