pi-matt-pocock 0.1.0 → 0.2.0

package/procedures/code-review.md

@@ -1,36 +1,34 @@
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+Two-axis review of a task-scoped candidate against an explicit baseline:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / PRD / spec? If the spec contains Gherkin scenarios (from [bdd](bdd.md)), those are the authoritative acceptance criteria.
 
-When the teammate facility is available, delegate the two independent axes to separate teammates and aggregate their findings. Otherwise, perform the Standards review first, preserve its report, then perform the Spec review in the current context so the axes remain separate.
+For a bounded change, one fresh reviewer can assess both axes and return separate verdicts. Use separate reviewers only when scale, distinct expertise, or repository policy justifies them. Without delegation, assess Standards then Spec and preserve the reports separately. Agent count is not evidence of independence or quality.
 
-The issue tracker should have been provided to you — run [setup-matt-pocock-skills](setup-matt-pocock-skills.md) if `docs/agents/issue-tracker.md` is missing.
+Use the confirmed requirements already available; an issue tracker is optional. Read repository issue-tracker guidance only when the spec actually lives there. Missing tracker setup is not a reason to start setup work for a local review.
+
+**Review-only scope:** For a standalone review request or bounded reviewer assignment, return the report with separate verdicts and findings, including REWORK, without editing the implementation and without waiting for repairs. Remediation and implementation-delivery conditions below belong to the Leader or implementation owner; they do not extend a review-only assignment. If access or evidence prevents the review itself, report that execution blocker rather than presenting unperformed checks as findings.
 
 ## Process
 
-### 1. Pin the fixed point
+### 1. Pin the baseline and candidate
 
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+Record what the review judges before delegation or verification:
 
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+- **Committed comparison:** honor a supplied ref and verify it resolves. Use `git diff <fixed-point>...HEAD` and the relevant commit list for that comparison.
+- **Current uncommitted task:** use the recorded task-start baseline or a scoped patch/snapshot. Include untracked files; exclude pre-existing dirty work and other Agents' unrelated changes. A plain `git diff HEAD` is insufficient when it mixes tasks. Ask only when the intended scope or baseline cannot be established from context.
 
-Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not during either review.
+Name the candidate revision or content fingerprint and provide the reviewer its exact delta, requirements and safe verification scope. Review and integration checks inspect that same candidate. Keep it stable while those checks run, or mark affected evidence stale when files change. Do not claim a result from an older candidate proves a newer one, and do not create a commit merely to identify the candidate.
 
 ### 2. Identify the spec source
 
-Look for the originating spec, in this order:
-
-1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
-2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
-4. If nothing is found, ask the user directly in the conversation where the spec is (in the repo / linked from the issue or PR / external document / no spec exists) and wait for the reply. If there isn't one, skip the **Spec** review and report "no spec available".
+Use the originating spec, explicit path or linked issue when supplied. For a local task, confirmed conversation requirements and its Given/When/Then scenarios are a valid spec; include those in the review brief rather than asking for a redundant artifact. Consult repository PRDs or issue references when context points there. Ask only for genuinely missing or conflicting requirements. If no spec exists, report the Spec axis as unavailable instead of inventing acceptance criteria or silently treating it as PASS.
 
 ### 3. Identify the standards sources
 
 Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
 
-On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+On top of whatever the repo documents, the Standards axis always carries the **smell and AI slop baselines** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) plus cross-language AI slop patterns that applies even when a repo documents nothing. Two rules bind them:
 
 - **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
 - **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
@@ -50,20 +48,32 @@ Each smell reads *what it is* → *how to fix*; match it against the diff:
 - **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
 - **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
 
+### AI slop baseline
+
+Language-model-generated code tends to emit low-evidence, low-signal patterns regardless of language. The smell baseline's two binding rules apply unchanged: the repo overrides, and skip any pattern that tooling already enforces (for example, a repository running dedicated anti-slop lint rules). Each pattern reads *what it is* → *how to fix it*:
+
+- **Fabricated evidence** — casts or suppressions that assert a type or invariant the code never established: chained `as`/`as unknown as`, `cast(Any, x)`, `# type: ignore`, unjustified `@ts-ignore`, `unsafe` blocks or `.unwrap()` standing in for real handling. → parse at the boundary or guard the type; require a written invariant justification for any suppression.
+- **Evidence widening** — known precise values funneled into `unknown`/`any`/`object`/`interface{}`/open dictionaries, or finite records degraded to open maps. → preserve the precise type end to end; widen only at an unparsed boundary.
+- **Defensive clutter** — `try/except: pass`, redundant null checks in trusted codepaths, conditional empty-spread omission tricks, silent fallbacks. → delete the check; validate at the boundary once.
+- **Mock patching** — tests that mock or monkey-patch the module's own internals instead of exercising real seams. → test through an injected adapter or the public interface.
+- **Vacuous names** — symbols named after their type or shape (`data`, `info`, `obj`, `helper`, `manager`, `*Shape`) instead of their domain meaning. → rename to the domain concept; no honest name means the design is murky.
+
+Match each pattern against the diff the same way as the smell baseline: labelled judgement calls, hard only when a documented standard forbids them, and skipped when repository tooling enforces the pattern.
+
 ### 4. Run the two independent reviews
 
-If the teammate facility is available, give each teammate one brief below and wait for both reports. Otherwise, run the Standards brief and then the Spec brief sequentially in the current context. Keep their notes separate until aggregation.
+Give the reviewer both briefs for bounded work, or one brief per reviewer when separate expertise is justified. Each brief carries the same candidate and task baseline. Workers run assigned local checks; one integration owner owns shared verification. Verify the commands' safety and isolation before execution. Continue unrelated work while required reports are outstanding; otherwise yield with the workflow active, without declaring completion. Keep the two axes separate until aggregation.
 
 **Standards review brief** — include:
 
-- The full diff command and commit list.
-- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the reviewer needs this material to evaluate the diff.
-- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+- The baseline, exact candidate, scoped diff or snapshot, and commit list if applicable.
+- The list of standards-source files you found in step 3, **plus the smell and AI slop baselines from step 3** pasted in full — the reviewer needs this material to evaluate the diff.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell or AI slop pattern you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells and AI slop patterns are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
 
 **Spec review brief** — include:
 
-- The diff command and commit list.
-- The path or fetched contents of the spec.
+- The same baseline, candidate and scoped delta, with a commit list if applicable.
+- The spec or confirmed conversation requirements and scenarios.
 - The brief: "Report: (a) Gherkin scenarios (Given/When/Then) in the spec that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. If the spec contains Gherkin scenarios, those are the authoritative acceptance criteria. Quote the spec line for each finding. Under 400 words."
 
 If the spec is missing, skip the Spec review and note this in the final report.
@@ -74,6 +84,18 @@ Present the two reports under `## Standards` and `## Spec` headings, verbatim or
 
 End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
+### 5.3 Owner remediation and recheck handoff
+
+The Leader or implementation owner applies this section after receiving the review; a review-only caller proceeds to its verdict and report. A completed review Work Item means a report was delivered, not that the implementation passed. Group findings by root cause, add adjacent-case regressions, and repair the affected behavior as one bounded correction where possible. Identify the new candidate and rerun affected checks; retain unaffected evidence with its scope explicit.
+
+Before a bounded recheck, preserve the prior findings and candidate identity in a durable review artifact. Prepare a refreshed brief with the retained baseline, new candidate fingerprint, correction delta, prior findings, and safe check scope. A reviewer must read that authoritative brief and validate the fingerprint before inspecting the candidate.
+
+With Agent Teams, reopening does not update the description, forward prior findings, or use the reopen reason as a new assignment prompt; it clears the old result. If the original description already directs the reviewer to an authoritative brief for the current attempt, update that referenced brief before reopening, then assign an available exact session. Keep the prior report separate and the refreshed brief stable during the attempt. If the old description pins a conflicting candidate or has no such reference, use `work create` for bounded follow-up Work with the full refreshed description and `dependsOn` pointing to the completed review, then assign it. This is a linked correction check, not a new broad review. Never rewrite board files to simulate a description update.
+
+Sending a message to a closed assignment does not restart review. If Work is still active, follow release/reassignment authority before changing its brief. Request a new broad review only when scope or risk materially changes.
+
+The implementation owner finishes delivery only when every required report has returned, blocking findings are resolved, and verification plus review verdicts apply to the final candidate. An unrelated failing check is disclosed as a limitation, not silently turned into a pass. Outstanding required results keep the implementation workflow active; yield instead of sending a premature final delivery.
+
 ### 5.4 Memory read-before (Standards axis)
 
 Before scoring, load the project's known traps: `Glob docs/memory/*.md`, then read every file whose frontmatter `category` is `pitfall` or `convention` and whose `summary` is topically related to this review (the diff's files, patterns, or stack). These are evaluator-verified failure modes this repo already paid for.

package/procedures/deslop.md

@@ -0,0 +1,56 @@
+# De-slop
+
+Remove AI slop from a bounded change set without changing behavior. AI slop is the set of low-evidence, low-signal patterns that language-model-generated code tends to emit under completion pressure: fabricated evidence, discarded type information, defensive clutter, test-cheating seams, and vacuous names. The categories are language-neutral — this capability applies them to whatever stack the change set touches, not just TypeScript.
+
+Run this as a focused pass over a diff, an uncommitted change set, or named files. It never adds features, never changes public behavior, and never trades a working product for cleanup. Tests and types must stay green; if the change set has no test coverage, report that and stop before rewriting anything.
+
+## The five slop categories
+
+Each category reads *what it is* → *how to fix it*. Match them against the change set:
+
+- **Fabricated evidence** — casts, suppressions, or unsafe escapes that assert a type or invariant the code never established: chained `as`/`as unknown as`, `cast(Any, x)`, `# type: ignore`, `@ts-ignore`/`@ts-expect-error` without justification, `unsafe` blocks or `.unwrap()` standing in for real handling, non-null `!` assertions on nullable values. → Replace with boundary parsing, type guards, or pattern matching; when a suppression is genuinely required, pair it with a non-empty invariant justification.
+- **Evidence widening** — known, precise values funneled into top types or open dictionaries: parameters and returns typed `object`/`unknown`/`any`/`interface{}`/`dict[str, Any]`, finite records degraded to open maps, `as any` to silence a mismatch. → Preserve the precise type end to end; widen only at an unparsed boundary and parse there.
+- **Defensive clutter** — no-op protection against cases a trusted codepath cannot produce: `try/except: pass`, redundant null checks inside internal call chains where the value is guaranteed, conditional empty-object spreads and similar omission tricks, silent fallback defaults. → Delete the check; validate at the boundary once instead of everywhere.
+- **Mock patching** — tests that monkey-patch or mock a module's internals to force the code under test to pass: `patch("module.path")` on the subject's own collaborators, `vi.mock`/`jest.mock` on internal modules, snapshots derived from the implementation. → Test through real seams: inject an adapter, point the code at an in-memory implementation, or exercise the public interface.
+- **Vacuous names** — symbols named after their type or shape instead of their domain meaning: `data`, `info`, `item`, `result`, `obj`, `helper`, `manager`, `*Shape`, `handleX`. → Rename to the domain concept the symbol carries; if no honest name exists, the design is murky and that is a finding, not a rename.
+
+Two binding rules:
+
+- **Repo tooling overrides.** If the repository enforces a category through lint or CI (for example vendored anti-slop Oxlint rules), skip it here — tooling already rejects it, and duplicating it wastes effort.
+- **Behavior is frozen.** Every rewrite must keep observable behavior, public interfaces, and test outcomes identical. A de-slop pass that requires a behavior change is out of scope — record it as a finding instead.
+
+## Process
+
+### 1. Pin the scope
+
+Resolve the change set before touching anything:
+
+- If the user named a diff base, files, or a review request, use that.
+- Otherwise use the uncommitted change set (`git status` plus `git diff`).
+- An empty scope is a stop: report that there is nothing to de-slop.
+
+### 2. Inventory findings
+
+Scan the scope once per category. Produce a findings list: category, location (file plus hunk), the offending line quoted, and the replacement plan. A finding without a concrete replacement plan is not ready to fix — leave it as a reported finding.
+
+### 3. Rewrite
+
+Apply the plans in one pass, category by category. For each rewrite:
+
+1. Replace the slop with the typed, seam-based, or renamed equivalent.
+2. Keep tests green after each category batch; run the repository's test suite or the affected subset between batches.
+3. Stop and report when a planned rewrite cannot keep tests green — the slop was load-bearing, which is itself a finding.
+
+### 4. Verify
+
+Run the verification the repository already uses — tests, typecheck, and lint. A de-slop pass ends green or it has not ended.
+
+### 5. Verdict
+
+Report under three headings:
+
+- **Removed** — each rewrite as `category → file:line → one-line replacement summary`.
+- **Findings** — slop that could not be removed without a behavior change, test coverage, or a design decision, each with the reason.
+- **Skipped** — categories skipped because repository tooling already enforces them.
+
+End with a binary verdict: **CLEAN** only if every planned rewrite landed and verification is green; **PARTIAL** when findings remain. Never report CLEAN with unverified skips.

package/procedures/domain.md

@@ -8,7 +8,7 @@ How the engineering skills should consume this repo's domain documentation when
 - **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
 - **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
 
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The [domain-modeling](domain-modeling.md) skill (reached via [grill-with-docs](grill-with-docs.md) and [improve-codebase-architecture](improve-codebase-architecture.md)) creates them lazily when terms or decisions actually get resolved.
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The [domain-modeling](domain-modeling.md) capability (bundled with [grill-with-docs](grill-with-docs.md), disclosed by [improve-codebase-architecture](improve-codebase-architecture.md)) creates them lazily when terms or decisions actually get resolved.
 
 ## File structure
 

package/procedures/grill-with-docs.md

@@ -1,5 +1,5 @@
-Run a [grilling](grilling.md) session, using the [domain-modeling](domain-modeling.md) skill.
+Run a [grilling](grilling.md) session, with [domain-modeling](domain-modeling.md) bundled as a required dependency. These are package procedures, not Pi skills.
 
-## CRITICAL: Grill with the docs skills loaded
+## CRITICAL: Grill with grilling and domain-modeling bundled
 
-Run the [grilling](grilling.md) session with the [domain-modeling](domain-modeling.md) skill active. Every sharpened term and locked decision lands in `CONTEXT.md` or an ADR as it crystallises — the paper trail is what distinguishes this skill from [grill-me](grill-me.md). Ask interview questions using the `matt_pocock_ask` interactive tool, one at a time, with suggested options, recommendations, timeout, and custom response support. Wait for each reply as [grilling](grilling.md) dictates.
+Run the [grilling](grilling.md) session with the bundled [domain-modeling](domain-modeling.md) procedure. Every sharpened term and locked decision lands in `CONTEXT.md` or an ADR as it crystallises — the paper trail is what distinguishes this procedure from [grill-me](grill-me.md). Ask interview questions using the `matt_pocock_ask` interactive tool, one at a time, with suggested options, recommendations, timeout, and custom response support. Wait for each reply as [grilling](grilling.md) dictates.

package/procedures/grilling.md

@@ -1,6 +1,6 @@
 Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
-Ask each question using the `matt_pocock_ask` interactive selection tool, one at a time, and wait for the reply before continuing. Give 2–4 concise alternatives, put your recommended option first marked "(Recommended)", specify a timeout, and explicitly welcome a different answer via custom input. A timeout or unavailable UI leaves the decision pending; a recommendation is never authorization to choose for the user. Asking multiple questions at once is bewildering.
+Ask each question using the `matt_pocock_ask` interactive selection tool, one at a time, and wait for the reply before continuing. Give 2–4 concise alternatives, put your recommended option first marked "(Recommended)", specify a timeout, and explicitly welcome a different answer via custom input. When a recommended option is provided, a timeout automatically adopts the recommendation and continues the workflow; when no recommended option is provided, the selection has no timeout and waits for the user's decision. Asking multiple questions at once is bewildering.
 
 If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me via `matt_pocock_ask` and wait for my answer.
 
@@ -8,4 +8,4 @@ Do not act on it until I confirm we have reached a shared understanding. Once th
 
 ## CRITICAL: One question at a time — facts you look up, decisions the user makes
 
-Ask each question using `matt_pocock_ask`, one at a time, and wait for the reply before continuing; multiple questions at once is bewildering. Put the recommended option first, marked "(Recommended)", specify a timeout, and leave room for a different answer via custom typing. A timeout or unavailable UI leaves the decision pending; it does not select the recommendation. If a fact can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking. The decisions are the user's — put each one to them, and do not act until they confirm shared understanding. After shared understanding is confirmed, proceed directly to the next applicable workflow work rather than asking whether to continue.
+Ask each question using `matt_pocock_ask`, one at a time, and wait for the reply before continuing; multiple questions at once is bewildering. Put the recommended option first, marked "(Recommended)", specify a timeout, and leave room for a different answer via custom typing. When a recommended option is provided, timeout automatically adopts it; without a recommendation, the selection has no timeout and waits for the user. If a fact can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking. The decisions are the user's — put each one to them, and do not act until they confirm shared understanding. After shared understanding is confirmed, proceed directly to the next applicable workflow work rather than asking whether to continue.

package/procedures/implement.md

@@ -1,13 +1,14 @@
 Implement the work described by the user in the spec or tickets.
 
-Use [bdd](bdd.md) where possible, at pre-agreed seams. During the Automation phase, load [tdd](tdd.md) (BDD-driven) for test quality, seams, and mocking guidance.
+Use [bdd](bdd.md) at the agreed seams, one red-green slice at a time. The bundled [tdd](tdd.md) owns Automation-phase test quality, seams, and mocking guidance.
 
-Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+## Verification and integration
 
-Once done, use [code-review](code-review.md) to review the work.
+- Establish which checks are safe before execution; use isolated home, credentials and test data where needed. Do not assume local commands have no production access.
+- Give implementers bounded local checks and appoint one integration owner for shared checks. Keep dependent changes ordered and conflicting writes under one owner; use the host's dependency and resource primitives when available.
+- Record the task baseline, including untracked files and unrelated dirty work to exclude. After integration and local checks, identify the candidate revision or scoped snapshot. Review and final verification must inspect the same candidate; a Git commit is not required to identify it.
+- Run affected tests during implementation. The integration owner runs applicable type, lint, build and broad regression checks after integration, not redundantly per Agent. Later edits invalidate affected evidence; rerun the checks and review conclusions those edits can change. Repository-required verification still applies.
 
-## CRITICAL: BDD at pre-agreed seams, review before commit
-
-Use [bdd](bdd.md) where possible, one red-green slice at a time at pre-agreed seams. Load [tdd](tdd.md) (BDD-driven) during the Automation phase for test quality, seams, and mocking guidance. When the work is done, run [code-review](code-review.md) over it — a change without the two-axis review is not finished work.
+Then use [code-review](code-review.md). Delivery requires the integrated candidate's applicable verification, returned blocking reviews, and findings resolved. If only required Agent results remain outstanding, yield with the workflow active; do not announce completion while waiting. A completed review assignment is evidence to assess, not automatically a PASS on the implementation.
 
 When the user asks to commit, follow the repository's git-agent workflow rather than staging or committing directly.

package/procedures/improve-codebase-architecture.md

@@ -4,7 +4,7 @@ Surface architectural friction and propose **deepening opportunities** — refac
 
 This command is _informed_ by the project's domain model and built on a shared design vocabulary:
 
-- Run the [codebase-design](codebase-design.md) skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- Follow the bundled [codebase-design](codebase-design.md) procedure for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
 - The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
 
 ## Process
@@ -59,11 +59,11 @@ Decide where to look before looking: follow the user's direction, or walk the co
 
 ### 3. Grilling loop
 
-Once the user picks a candidate, run the [grilling](grilling.md) skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+Once the user picks a candidate, load the [grilling](grilling.md) reference with `matt_pocock_active` (`action: "load"`, from available references) to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
 
-Side effects happen inline as decisions crystallize — run the [domain-modeling](domain-modeling.md) skill to keep the domain model current as you go:
+Side effects happen inline as decisions crystallize — load the [domain-modeling](domain-modeling.md) reference with `matt_pocock_active` (`action: "load"`, from available references) to keep the domain model current as you go:
 
 - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
 - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
-- **Want to explore alternative interfaces for the deepened module?** Run the [codebase-design](codebase-design.md) skill and use its Design It Twice pattern with teammates when the teammate facility is available, or compare designs sequentially in the current context.
+- **Want to explore alternative interfaces for the deepened module?** Follow the bundled [codebase-design](codebase-design.md) procedure and use its Design It Twice pattern with teammates when the teammate facility is available, or compare designs sequentially in the current context.

package/procedures/tdd.md

@@ -1,14 +1,14 @@
 # BDD-Driven TDD (Automation)
 
-BDD cycles through three phases: **Discovery** (conversations → examples), **Formulation** (Gherkin scenarios), **Automation** (red-green-refactor, driven by BDD). This skill is the **BDD-driven Automation** reference — the how of test implementation, once [bdd](bdd.md) has defined the what.
+BDD cycles through three phases: **Discovery** (conversations → examples), **Formulation** (Gherkin scenarios), **Automation** (red-green-refactor, driven by BDD). This procedure is the **BDD-driven Automation** reference — the how of test implementation, once [bdd](bdd.md) has defined the what.
 
-When invoked during [implement](implement.md) or [bdd](bdd.md), use this skill as the test-writing authority. The [bdd](bdd.md) skill governs the scenario design and Iron Law; this skill governs the test code quality under BDD discipline.
+When invoked during [implement](implement.md) or [bdd](bdd.md), use this procedure as the test-writing authority. The bundled [bdd](bdd.md) procedure governs the scenario design and Iron Law; this procedure governs the test code quality under BDD discipline.
 
 ## CRITICAL: BDD scenarios come first
 
-If you reached this skill directly (not via [bdd](bdd.md) or [implement](implement.md)), inspect the repository and conversation for Gherkin scenarios first.
+If you reached this procedure directly (not via [bdd](bdd.md) or [implement](implement.md)), inspect the repository and conversation for Gherkin scenarios first.
 
-- If scenarios are absent → invoke [bdd](bdd.md) to define them, then return here for Automation.
+- If scenarios are absent → follow the bundled [bdd](bdd.md) to define them, then return here for Automation.
 - If scenarios exist in `.feature` files or equivalent → proceed with the red-green loop below.
 - Ask the user only if the behavior itself is genuinely unresolved; do not ask for confirmation of facts that repository exploration can establish.
 
@@ -24,7 +24,7 @@ A **seam** is the public boundary you test at: the interface where you observe b
 
 **Test at the highest established seam.** Record the public boundary under test and select the highest existing seam that expresses the confirmed behavior. Not everything can be tested — choosing the critical public seam deliberately is how effort lands on complex behavior instead of every edge case. Ask only when the public contract is genuinely ambiguous.
 
-When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — use the [codebase-design](codebase-design.md) skill for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — load the [codebase-design](codebase-design.md) reference with `matt_pocock_active` (`action: "load"`, from available references) for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
 
 ## Anti-patterns
 
@@ -40,21 +40,21 @@ When the shape of that interface is itself in question — how deep the module i
 
 ## CRITICAL: BDD-Driven — not standalone TDD
 
-This skill is the **Automation** phase of the BDD lifecycle. It always runs under [bdd](bdd.md) or [implement](implement.md) as **BDD-driven TDD**. If invoked directly, see the CRITICAL check at the top of this file — confirm scenarios exist before writing test code.
+This procedure is the **Automation** phase of the BDD lifecycle. It always runs under [bdd](bdd.md) or [implement](implement.md) as **BDD-driven TDD**. If invoked directly, see the CRITICAL check at the top of this file — confirm scenarios exist before writing test code.
 
 1. **Discovery** (what behavior matters) — owned by [bdd](bdd.md) via Gherkin scenarios
 2. **Formulation** (scenario as specification) — owned by [bdd](bdd.md) via `.feature` files
-3. **Automation** (this skill) — the red-green loop that makes the scenario pass
+3. **Automation** (this procedure) — the red-green loop that makes the scenario pass
 
 ## When to invoke
 
-Invoke this skill explicitly when:
+Load this capability (`matt_pocock_workflow`, `mode: "capability"`) explicitly when:
 - The user asks "how should I test this?" during BDD implementation
 - The user asks about mocking, seams, or test structure
 - The user writes a test that looks implementation-coupled
 - The user asks about mocking strategy at system boundaries
 - The user is unsure whether a test is good or tautological
 
-When invoked directly, first check if Gherkin scenarios exist (see the CRITICAL check at the top). If not, redirect to [bdd](bdd.md) before proceeding with Automation.
+When invoked directly, first check if Gherkin scenarios exist (see the CRITICAL check at the top). If not, follow the bundled [bdd](bdd.md) before proceeding with Automation.
 
-The [bdd](bdd.md) and [implement](implement.md) skills load this automatically during the Automation phase — you do not need to invoke it separately in those flows.
+The [implement](implement.md) procedure bundles this automatically as a required dependency during the Automation phase — you do not need to invoke it separately in that flow. From [bdd](bdd.md), load this capability (`matt_pocock_workflow`, `mode: "capability"`) when Automation begins.

package/procedures/to-spec.md

@@ -1,6 +1,6 @@
-This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
+This procedure takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
 
-The issue tracker and triage label vocabulary should have been provided to you — run [setup-matt-pocock-skills](setup-matt-pocock-skills.md) if not.
+The issue tracker and triage label vocabulary should have been provided to you — load [setup-matt-pocock-skills](setup-matt-pocock-skills.md) with `matt_pocock_active` (`action: "load"`, from available references) if not. It is a package procedure, not a Pi skill.
 
 ## CRITICAL: No interview — synthesize what you already know
 

package/procedures/to-tickets.md

@@ -2,7 +2,7 @@
 
 Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. If the spec contains Gherkin scenarios (from [bdd](bdd.md)), each ticket should map to one or more scenarios; the scenarios are the authoritative acceptance criteria.
 
-The issue tracker and triage label vocabulary should have been provided to you — run [setup-matt-pocock-skills](setup-matt-pocock-skills.md) if not.
+The issue tracker and triage label vocabulary should have been provided to you — load [setup-matt-pocock-skills](setup-matt-pocock-skills.md) with `matt_pocock_active` (`action: "load"`, from available references) if not. It is a package procedure, not a Pi skill.
 
 ## Process
 

package/procedures/triage.md

@@ -38,7 +38,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run [setup-matt-pocock-skills](setup-matt-pocock-skills.md) if not.
+These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - load [setup-matt-pocock-skills](setup-matt-pocock-skills.md) with `matt_pocock_active` (`action: "load"`, from available references) if not. It is a package procedure, not a Pi skill.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 
@@ -71,7 +71,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the [grilling](grilling.md) and [domain-modeling](domain-modeling.md) skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, follow the bundled [grilling](grilling.md) and [domain-modeling](domain-modeling.md) procedures together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

package/procedures/wayfinder.md

@@ -1,4 +1,4 @@
-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 **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
+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 procedure charts the way as a **shared map** on the repo's issue tracker, then works its **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — 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.
 
@@ -16,7 +16,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run [setup-matt-pocock-skills](setup-matt-pocock-skills.md) if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — load [setup-matt-pocock-skills](setup-matt-pocock-skills.md) with `matt_pocock_active` (`action: "load"`, from available references) if not. It is a package procedure, not a Pi skill. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 
@@ -69,8 +69,8 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
 - **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Delegate it to a teammate when the teammate facility is available; otherwise research it sequentially. Use when knowledge outside the current working directory is required.
-- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the [prototype](prototype.md) skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
-- **Grilling** (HITL): Conversation via the [grilling](grilling.md) and [domain-modeling](domain-modeling.md) skills, one question at a time. The default case.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code by transitioning to the [prototype](prototype.md) procedure. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation with the bundled [grilling](grilling.md) and [domain-modeling](domain-modeling.md) procedures, one question at a time. The default case.
 - **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
 ## Fog of war
@@ -119,7 +119,7 @@ User invokes with a map (URL or number). A ticket is **optional** — without on
 
 1. Load the **map** — the low-res view, not every ticket body.
 2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
-3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use [grilling](grilling.md) and [domain-modeling](domain-modeling.md).
+3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the procedures the `## Notes` block names. If in doubt, follow the bundled [grilling](grilling.md) and [domain-modeling](domain-modeling.md).
 4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
 5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
 6. Re-query the frontier and immediately claim and resolve the next unblocked AFK ticket. Continue this loop until the frontier is empty or its next ticket is HITL. A closed decision ticket is a trigger to advance the map, not a stopping point or a prompt for user confirmation.

package/procedures/writing-for-agents.md

@@ -2,6 +2,20 @@ Reference for writing any document an agent consumes — a skill, an `AGENTS.md`
 
 When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
 
+## Model-aware instruction audit
+
+Apply these core principles from the supplied article, **Rethinking skills and prompts for GPT-6 Astra**, when authoring or auditing skills, `AGENTS.md`, and task prompts. Treat its model comparisons as context for revisiting instructions, not a guarantee of any model's judgment or safety.
+
+- **Narrow triggers.** Keep skill descriptions as short as possible while naming the actual workflow. Prefer “Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout” over a trigger for all database work. Many long descriptions compete for context and may be shortened by the host; overlapping or contradictory triggers load irrelevant guidance.
+- **Minimal routing.** For a multi-workflow skill, make the root a minimal router to supporting docs and scripts, with clear conditions for loading each. Load only the branch needed for the task; unnecessary guidance spends context and brings compaction closer.
+- **Outcomes over itineraries.** Specify constraints and completion criteria, leaving implementation choices to the agent unless a particular sequence is essential. Evaluate instructions against the models used by contributors, rather than assuming scaffolding that helped one model helps all of them.
+- **Contextual repository guidance.** Revisit always-loaded `AGENTS.md` instructions regularly and after model upgrades. Replace blanket pre-reading with pointers such as “Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.” Keep targets current and reading proportional to the task; a typo fix needs no full repository tour.
+- **Evidence-based pruning.** Remove stale workarounds, conflicting guidance, and reminders already satisfied by the target model's default behavior. Generic demands to keep testing can cause redundant work; retain task-specific verification requirements and explicit repository contracts rather than assuming testing is unnecessary.
+- **Safe autonomy and decision boundaries.** State what may proceed without repeated approval and where approval is required. For example, only when verified true: “The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.” Review inherited ask-first language that blocks safe work, while retaining explicit approval boundaries for production writes, destructive operations, and external publication. Perceived model capability does not grant permission.
+- **Persistence with a finish line.** Define completion before work begins. If delivery includes running it, inspecting the result, fixing failures, and rerunning affected checks, say so; a first implementation is not that finish line. Keep a stop-for-review gate only when a human decision is genuinely needed. For work beyond the first pass, name the exploration scope and stopping condition so persistence stays bounded.
+
+Use the sections below to apply this audit; preserve instructions that encode real project constraints rather than deleting them solely because a newer model is available.
+
 ## Context pointers
 
 A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.