pi-matt-pocock 0.2.2 → 0.3.0

package/src/workflow.ts

@@ -2,6 +2,7 @@ import {
   allowedTransitions,
   modelStandaloneCapabilities,
   normalizeProcedureId,
+  userStandaloneCapabilities,
   workflowEntry,
   workflowPlacement,
   workflowRoutes as catalogWorkflowRoutes,
@@ -61,6 +62,12 @@ export function routeEntryState(route: string, workItemId: string): WorkflowStat
 }
 
 export function transitionState(state: WorkflowState, target: string): WorkflowState {
+  const currentPlacement = workflowPlacement(state.route, state.procedure);
+  if (!currentPlacement || currentPlacement.phase !== state.phase) {
+    throw new Error(
+      `Cannot transition ${state.route} from ${state.procedure}: invalid current procedure state.`,
+    );
+  }
   const normalized = normalizeProcedureId(target);
   const allowed = allowedTransitions(state.route, state.procedure);
   if (!allowed.includes(normalized)) {
@@ -75,6 +82,7 @@ export function transitionState(state: WorkflowState, target: string): WorkflowS
     procedure: normalized,
     phase: placement.phase,
     loadedReferences: [],
+    deliveredProcedures: state.deliveredProcedures ?? [],
   };
 }
 
@@ -106,15 +114,19 @@ export function formatReadableWorkflowSubject(route: string, phase: string): str
   return `${readableRouteTitle(route)} · ${readablePhaseTitle(phase)}`;
 }
 
-export function isWorkflowState(value: unknown): value is WorkflowState {
-  if (!value || typeof value !== "object") return false;
+function workflowRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object") return undefined;
   const candidate = value as Record<string, unknown>;
   return candidate.version === WORKFLOW_STATE_VERSION
-    && typeof candidate.workItemId === "string"
+    && typeof candidate.workItemId === "string" && candidate.workItemId.trim().length > 0
     && typeof candidate.route === "string"
     && typeof candidate.procedure === "string"
-    && typeof candidate.phase === "string"
-    && candidate.status === "active"
+    && typeof candidate.phase === "string" ? candidate : undefined;
+}
+
+export function isWorkflowState(value: unknown): value is WorkflowState {
+  const candidate = workflowRecord(value);
+  return candidate !== undefined && candidate.status === "active"
     && Array.isArray(candidate.loadedReferences)
     && candidate.loadedReferences.every((reference) => typeof reference === "string")
     // Absent is tolerated so a workflow persisted before delivery tracking existed still
@@ -130,13 +142,8 @@ export function withDeliveryDefaults(state: WorkflowState): WorkflowState {
 }
 
 export function isTerminalWorkflowState(value: unknown): value is TerminalWorkflowState {
-  if (!value || typeof value !== "object") return false;
-  const candidate = value as Record<string, unknown>;
-  return candidate.version === WORKFLOW_STATE_VERSION
-    && typeof candidate.workItemId === "string"
-    && typeof candidate.route === "string"
-    && typeof candidate.procedure === "string"
-    && typeof candidate.phase === "string"
+  const candidate = workflowRecord(value);
+  return candidate !== undefined
     && (candidate.status === "completed" || candidate.status === "cancelled");
 }
 
@@ -144,7 +151,9 @@ export function latestWorkflowRecord(entries: unknown[]): WorkflowSessionData |
   for (let index = entries.length - 1; index >= 0; index -= 1) {
     const entry = entries[index] as { type?: unknown; customType?: unknown; data?: unknown } | undefined;
     if (entry?.type !== "custom" || entry.customType !== WORKFLOW_STATE_ENTRY) continue;
-    if (isWorkflowState(entry.data) || isTerminalWorkflowState(entry.data)) return entry.data;
+    // The newest entry is authoritative even when incompatible. Never resurrect
+    // an older active workflow by skipping a malformed terminal or future version.
+    return isWorkflowState(entry.data) || isTerminalWorkflowState(entry.data) ? entry.data : undefined;
   }
   return undefined;
 }
@@ -161,17 +170,42 @@ Work item: ${state.workItemId}. Follow the loaded ${state.procedure} procedure.
 
 Drive the current procedure to its end in this turn. A multi-step deliverable is not finished because one step passed: keep implementing, testing and fixing until every step the procedure covers is done, rather than stopping at the first green slice or handing back a plan for the remainder. Do not end the turn to ask whether to continue.
 
-Use matt_pocock_active to transition only to: ${next.join(", ") || "none"}; load an available reference; complete the work; or cancel it with a reason. Available references: ${availableReferences.join(", ") || "none"}. Exact shapes: {"action": "transition", "target": "<allowedNext id>"}; {"action": "load", "reference": "<availableReferences id>"}; {"action": "complete"}; {"action": "cancel", "reason": "<why>"}. Proceed autonomously through non-user-owned work: transition to the next applicable procedure as soon as this one's deliverables are complete, without stopping to ask permission. Ask only for a genuinely user-owned decision, an unavailable fact, or a required external action, and use matt_pocock_ask for those.
+Use matt_pocock_active to transition only to: ${next.join(", ") || "none"}; load an available reference; complete the work; or cancel it with a reason. Available references: ${availableReferences.join(", ") || "none"}. Exact shapes: {"action": "transition", "target": "<allowedNext id>"}; {"action": "load", "reference": "<availableReferences id>"}; {"action": "complete"}; {"action": "cancel", "reason": "<why>"}. Proceed autonomously through non-user-owned work: transition to the next applicable procedure as soon as this one's deliverables are complete, without stopping to ask permission. Ask only for a genuinely user-owned decision, an unavailable fact, or a required external action, and use matt_pocock_ask for those, with the required recommended option its deadline adopts.
 
 Yield only when the remaining work genuinely depends on an external actor, on a teammate result you cannot produce yourself, or on context you no longer have — and when you yield, state plainly what is unfinished rather than implying completion. Never announce completion early: call matt_pocock_active with action complete only once the integrated candidate has applicable verification and all blocking reviews have returned with their findings resolved; a completed review assignment is not itself a PASS verdict, and evidence must match that candidate.`;
 }
 
+/** One terse line per user-invoked capability. The prompt budget governs this
+ *  section, so it names the id and its subject rather than repeating the full
+ *  catalog description the menu and the tool schema already carry. */
+function userCapabilitySummary(definition: { id: string; label: string }): string {
+  return userCapabilitySummaries[definition.id] ?? definition.label;
+}
+
+const userCapabilitySummaries: Record<string, string> = {
+  "grill-me": "relentless one-decision-at-a-time interview; \"grill me\" names it",
+  handoff: "handoff document another agent can pick up cold",
+  retro: "review recent work and record what to change",
+  "improve-codebase-architecture": "rank and improve architecture deepening opportunities",
+  "setup-matt-pocock-skills": "configure the repository tracker and document layout",
+  teach: "teach a concept step by step",
+  "to-questionnaire": "turn a decision blocked on someone else into a questionnaire",
+  "wait-what": "re-pitch the last message with the missing context",
+};
+
 export function availableWorkflowsGuidance(): string {
   const workflows = workflowRoutes()
-    .map((route) => `- ${route.route}: ${route.description}`)
+    .map((route) => `- ${route.route}: ${route.description} Call: ${JSON.stringify({ mode: "workflow", route: route.route })}`)
     .join("\n");
   const capabilities = modelStandaloneCapabilities()
-    .map((capability) => `- ${capability.id}: ${capability.description}`)
+    .map((capability) => `- ${capability.id}: ${capability.description} Call: ${JSON.stringify({ mode: "capability", capability: capability.id })}`)
+    .join("\n");
+  // Without this list the user-invoked capabilities are invisible here, so a request
+  // like "grill me" has no route and the package is silently skipped. The entries stay
+  // terse on purpose: the gateway schema carries the authoritative ids, so the prompt
+  // only has to name them and give one call shape.
+  const userCapabilities = userStandaloneCapabilities()
+    .map((capability) => `- ${capability.id}: ${userCapabilitySummary(capability)}`)
     .join("\n");
   return `## Available Matt Pocock Workflows and Capabilities
 
@@ -190,5 +224,10 @@ ${workflows}
 Model-reachable standalone capabilities:
 ${capabilities}
 
+User-invoked capabilities: the user starts these by name, so run one only when the user explicitly asked for it, and never substitute a different capability. Call: {"mode":"user-capability","capability":"<id>"}.
+${userCapabilities}
+
+For an explicitly requested capability, load its listed call before applying its method. A schema rejection means the capability was not loaded: correct mode and required fields using the exact call above; do not repeat the same rejected arguments or silently claim execution.
+
 Workflow state is deliberate and task-scoped. When relevant, start a workflow first with matt_pocock_workflow (mode: "workflow"); the started workflow carries its procedure and next-step guidance.`;
 }

package/upstream/UPSTREAM.md

@@ -0,0 +1,116 @@
+# Upstream synchronization
+
+## Recorded revisions
+
+- Repository: `mattpocock/skills`
+- Compared commit: `4ae2317ddb22b046e26455e4f9c9b3aaaf62212d`
+- Comparison tag: `v1.3.2`
+- Resolved tag commit: `d1478fcb140db0b93c0c8df17bcfd311844749d0`
+- Latest checked commit: `4ae2317ddb22b046e26455e4f9c9b3aaaf62212d`
+
+These values describe different roles. The compared commit is the content
+baseline, the comparison tag is the human-readable release marker, the resolved
+tag commit records what that tag points to, and the latest checked commit is
+the newest upstream tree reviewed for additions or removals. Two roles may
+legitimately resolve to the same commit when upstream history makes that true;
+the checker validates each role against Git rather than requiring artificial
+distinctions. The newest tag is not necessarily the reviewed tree: when the
+baseline runs ahead of it, the tag names the newest release marker reachable
+from the baseline, and the checked commits between them carry the skills
+changes adopted here. At this revision the checked tree carries three commits
+after `v1.3.2`: fresh-context-window guidance for delegated work, the setup
+procedure's legacy glossary migration and reachable-repo requirement, and the
+new `software-factory` in-progress skill. The full compare always reads the
+checkout at the latest checked commit.
+
+The machine-readable selection is in
+[`upstream-selection.json`](upstream-selection.json). It classifies every
+upstream `SKILL.md` present at the latest checked commit as either promoted or
+intentionally excluded. Each promoted skill names its local catalog capability,
+plain Markdown resource, and upstream invocation mode. Each exclusion carries a
+reason; Claude Code hooks and background-agent commands are identified as
+host-specific rather than silently ignored.
+
+## Harness architecture
+
+Upstream distributes nested `SKILL.md` files. Pi recursively discovers any
+such file under a declared skill root, which exposes generic names such as
+`tdd`, `code-review`, and `research` alongside unrelated installed skills.
+
+This package exposes one extension command, `/matt-pocock`. The extension
+selects and injects plain Markdown procedures from `procedures/`, `references/`
+and `assets/`; none are Pi skills, and the package contains no `SKILL.md` file.
+
+## Sync rules
+
+1. Clone upstream separately and inspect both the compared and latest checked
+   commits before changing local resources.
+2. Run the local metadata check without an upstream checkout:
+
+   ```bash
+   node packages/matt-pocock/upstream/check-upstream-sync.mjs
+   ```
+
+3. Run the complete inventory, invocation, and content comparison against an
+   already-cloned checkout. The checker never clones or fetches:
+
+   ```bash
+   node packages/matt-pocock/upstream/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
+   ```
+
+   To compare a temporary selection fixture without mutating the package
+   metadata, add `--selection /path/to/selection.json`.
+
+4. Copy selected workflows and supporting files into `procedures/`; never
+   overwrite the extension harness wholesale.
+5. Rename copied upstream `SKILL.md` files to their catalog id plus `.md`.
+   Strip frontmatter, and never ship a `SKILL.md` file.
+6. Remove Claude-only frontmatter, tools, paths, and invocation syntax from
+   copied content. Replace cross-procedure calls with relative links.
+7. Preserve the local BDD/TDD split and Pi-specific interaction,
+   collaboration, instruction-file, and git-agent guidance. Follow the upstream
+   typography: adopted text keeps upstream punctuation rather than a local variant.
+   An adapted content
+   result is expected when these local contracts differ from upstream.
+   Four procedures carry such local lines for the task-path policy, which says an
+   explicit task path wins, otherwise the procedure's own default applies.
+   `procedures/pr.md`, `procedures/to-questionnaire.md`, and
+   `procedures/improve-codebase-architecture.md` each state that the deliverable
+   is a written file which must exist before the turn ends, and
+   `procedures/improve-codebase-architecture.md` also states that its survey step
+   writes the report and nothing else. `procedures/implement.md` forbids a
+   defensive default for a value the trusted path cannot miss. A second local
+   policy covers interactive questions: `procedures/grilling.md`,
+   `procedures/grill-me.md`, `procedures/grill-with-docs.md`, and
+   `procedures/to-tickets.md` require a `recommended` option whose deadline
+   adopts it, because `matt_pocock_ask` refuses a question without one; `grilling.md`
+   keeps the upstream design-tree, frontier and rounds model and delivers each
+   frontier question through that tool. A real-upstream
+   comparison that reports `adapted` above zero for these files is therefore
+   expected, not drift. The isolated sync test compares against a fixture
+   generated from the local files, so it stays exact either way. Upstream since
+   `v1.3.1` also asks that delegated work start with a fresh context window;
+   local wording keeps the teammate-or-current-context rule and adds that a
+   delegated teammate starts fresh rather than inheriting parent history. Local
+   procedure text names bun as the default task runner and uses bun-workspace
+   signals instead of upstream's other-package-manager examples. The package's
+   tests, contributor commands, and reproduction notes run on bun only.
+8. Classify every new or removed upstream skill in
+   `upstream-selection.json`, then update the four revision fields together.
+   This tree has 39 `SKILL.md` files: 25 selected, 14 excluded. Promoted `pr`
+   and `retro` are adapted to the Pi catalog. `implement-spec` remains excluded
+   because it requires the upstream Skill tool, a fresh background implementer
+   subagent per ticket in its own worktree, and integration-branch
+   orchestration, which this package's gateway does not implement. The new
+   `software-factory` in-progress skill is excluded because it defines a
+   vocabulary for agent factory infrastructure the gateway does not run. The
+   removed `resolving-merge-conflicts` capability remains locally for
+   compatibility but is no longer claimed as upstream content.
+9. Re-run the harness feature, isolated sync tests, package tests, and package
+   dry-run after a sync.
+10. Supporting references and assets are not classified by
+    `upstream-selection.json`, which records `SKILL.md` files only. Match them to
+    their upstream counterparts by name, keep the local file name and its catalog
+    id, and apply the same content and typography rules. `pr` reproduces the
+    `show-me` visual menu, so it carries that attribution directly instead of
+    upstream's separate `CREDITS.md`, which this package does not ship.

package/{scripts → upstream}/check-upstream-sync.mjs

@@ -9,7 +9,7 @@ const execFileAsync = promisify(execFile);
 import { fileURLToPath } from "node:url";
 
 const packageDirectory = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const selectionPath = resolve(packageDirectory, "upstream-selection.json");
+const selectionPath = resolve(packageDirectory, "upstream/upstream-selection.json");
 
 function fail(message) {
   throw new Error(message);
@@ -54,9 +54,16 @@ function normalizedBody(value) {
 }
 
 function parseArguments(argv) {
-  if (argv.length === 0) return {};
-  if (argv.length === 2 && argv[0] === "--upstream") return { upstream: argv[1] };
-  fail("usage: node scripts/check-upstream-sync.mjs [--upstream <already-cloned-path>]");
+  const options = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = { "--upstream": "upstream", "--selection": "selection" }[argv[index]];
+    const value = argv[index + 1];
+    if (!key || options[key] || !value || value.startsWith("--")) {
+      fail("usage: node upstream/check-upstream-sync.mjs [--upstream <already-cloned-path>] [--selection <metadata-file>]");
+    }
+    options[key] = value;
+  }
+  return options;
 }
 
 async function validateCatalogMappings(metadata) {
@@ -82,13 +89,6 @@ async function validateMetadata(metadata) {
   requireCommit(metadata.resolvedTagCommit, "resolvedTagCommit");
   requireCommit(metadata.latestCheckedCommit, "latestCheckedCommit");
 
-  const revisions = [
-    metadata.comparedCommit,
-    metadata.comparisonTag,
-    metadata.resolvedTagCommit,
-    metadata.latestCheckedCommit,
-  ];
-  if (new Set(revisions).size !== revisions.length) fail("upstream revision fields must be distinct");
   if (!Array.isArray(metadata.selected) || metadata.selected.length === 0) fail("selected must be non-empty");
   if (!Array.isArray(metadata.excluded) || metadata.excluded.length === 0) fail("excluded must be non-empty");
 
@@ -196,7 +196,7 @@ async function compareUpstream(metadata, upstreamArgument) {
 
 try {
   const args = parseArguments(process.argv.slice(2));
-  const metadata = JSON.parse(await readFile(selectionPath, "utf8"));
+  const metadata = JSON.parse(await readFile(args.selection ?? selectionPath, "utf8"));
   await validateMetadata(metadata);
   const comparison = args.upstream ? await compareUpstream(metadata, args.upstream) : {};
   console.log(JSON.stringify({

package/{upstream-selection.json → upstream/upstream-selection.json}

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 1,
   "repository": "mattpocock/skills",
-  "comparedCommit": "6654f6b60cd9d5be8b54c6fafe44346dabeb3b76",
-  "comparisonTag": "v1.2.3",
-  "resolvedTagCommit": "6acc160e4e0cd062dbbbd7a1b26ae92855edf07e",
-  "latestCheckedCommit": "3cca18b368ae95cdbdebbff572ccafa662551015",
+  "comparedCommit": "4ae2317ddb22b046e26455e4f9c9b3aaaf62212d",
+  "comparisonTag": "v1.3.2",
+  "resolvedTagCommit": "d1478fcb140db0b93c0c8df17bcfd311844749d0",
+  "latestCheckedCommit": "4ae2317ddb22b046e26455e4f9c9b3aaaf62212d",
   "selected": [
     { "upstreamSkill": "code-review", "upstreamPath": "skills/engineering/code-review/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "code-review", "localResource": "procedures/code-review.md" },
     { "upstreamSkill": "codebase-design", "upstreamPath": "skills/engineering/codebase-design/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "codebase-design", "localResource": "procedures/codebase-design.md" },
@@ -14,8 +14,9 @@
     { "upstreamSkill": "implement", "upstreamPath": "skills/engineering/implement/SKILL.md", "upstreamInvocation": "user", "localCatalogId": "implement", "localResource": "procedures/implement.md" },
     { "upstreamSkill": "improve-codebase-architecture", "upstreamPath": "skills/engineering/improve-codebase-architecture/SKILL.md", "upstreamInvocation": "user", "localCatalogId": "improve-codebase-architecture", "localResource": "procedures/improve-codebase-architecture.md" },
     { "upstreamSkill": "prototype", "upstreamPath": "skills/engineering/prototype/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "prototype", "localResource": "procedures/prototype.md" },
+    { "upstreamSkill": "retro", "upstreamPath": "skills/engineering/retro/SKILL.md", "upstreamInvocation": "user", "localCatalogId": "retro", "localResource": "procedures/retro.md" },
     { "upstreamSkill": "research", "upstreamPath": "skills/engineering/research/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "research", "localResource": "procedures/research.md" },
-    { "upstreamSkill": "resolving-merge-conflicts", "upstreamPath": "skills/engineering/resolving-merge-conflicts/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "resolving-merge-conflicts", "localResource": "procedures/resolving-merge-conflicts.md" },
+    { "upstreamSkill": "pr", "upstreamPath": "skills/engineering/pr/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "pr", "localResource": "procedures/pr.md" },
     { "upstreamSkill": "setup-matt-pocock-skills", "upstreamPath": "skills/engineering/setup-matt-pocock-skills/SKILL.md", "upstreamInvocation": "user", "localCatalogId": "setup-matt-pocock-skills", "localResource": "procedures/setup-matt-pocock-skills.md" },
     { "upstreamSkill": "tdd", "upstreamPath": "skills/engineering/tdd/SKILL.md", "upstreamInvocation": "model", "localCatalogId": "tdd", "localResource": "procedures/tdd.md" },
     { "upstreamSkill": "to-spec", "upstreamPath": "skills/engineering/to-spec/SKILL.md", "upstreamInvocation": "user", "localCatalogId": "to-spec", "localResource": "procedures/to-spec.md" },
@@ -33,11 +34,12 @@
   ],
   "excluded": [
     { "upstreamSkill": "ask-matt", "upstreamPath": "skills/engineering/ask-matt/SKILL.md", "reason": "Replaced by the single /matt-pocock Pi command and its catalog-backed routing gateway." },
+    { "upstreamSkill": "chief-of-staff", "upstreamPath": "skills/in-progress/chief-of-staff/SKILL.md", "reason": "Experimental in-progress skill that depends on recurring schedules, background subagents, a dated wiki, and reading other skills' SKILL.md files; the Pi v1 gateway implements none of those contracts." },
     { "upstreamSkill": "claude-handoff", "upstreamPath": "skills/in-progress/claude-handoff/SKILL.md", "reason": "Host-specific: launches Claude Code background agents and duplicates the selected host-neutral handoff capability." },
-    { "upstreamSkill": "implement-spec", "upstreamPath": "skills/in-progress/implement-spec/SKILL.md", "reason": "Experimental duplicate of the selected implement capability; the local workflow catalog supplies the sequencing contract." },
+    { "upstreamSkill": "implement-spec", "upstreamPath": "skills/engineering/implement-spec/SKILL.md", "reason": "Requires the upstream Skill tool, a fresh background implementer subagent per ticket in its own worktree, and integration-branch orchestration; this package's Pi v1 gateway does not implement that host contract." },
     { "upstreamSkill": "loop-me", "upstreamPath": "skills/in-progress/loop-me/SKILL.md", "reason": "Experimental stateful Claude skill composition is superseded by the persisted Pi workflow harness." },
-    { "upstreamSkill": "retro", "upstreamPath": "skills/in-progress/retro/SKILL.md", "reason": "Experimental capability is outside the approved promoted engineering and productivity catalog." },
     { "upstreamSkill": "setup-ts-deep-modules", "upstreamPath": "skills/in-progress/setup-ts-deep-modules/SKILL.md", "reason": "Experimental TypeScript-specific setup is narrower than the selected host-neutral codebase-design procedure." },
+    { "upstreamSkill": "software-factory", "upstreamPath": "skills/in-progress/software-factory/SKILL.md", "reason": "Experimental in-progress vocabulary for designing an agent software factory (runners, orchestrators, ticket sources); the Pi v1 gateway implements no factory runtime and this package ships no SKILL.md files." },
     { "upstreamSkill": "writing-beats", "upstreamPath": "skills/in-progress/writing-beats/SKILL.md", "reason": "Experimental editorial workflow is outside this package's engineering workflow scope." },
     { "upstreamSkill": "writing-fragments", "upstreamPath": "skills/in-progress/writing-fragments/SKILL.md", "reason": "Experimental editorial workflow is outside this package's engineering workflow scope." },
     { "upstreamSkill": "writing-shape", "upstreamPath": "skills/in-progress/writing-shape/SKILL.md", "reason": "Experimental editorial workflow is outside this package's engineering workflow scope." },

package/UPSTREAM.md

@@ -1,63 +0,0 @@
-# Upstream synchronization
-
-## Recorded revisions
-
-- Repository: `mattpocock/skills`
-- Compared commit: `6654f6b60cd9d5be8b54c6fafe44346dabeb3b76`
-- Comparison tag: `v1.2.3`
-- Resolved tag commit: `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`
-- Latest checked commit: `3cca18b368ae95cdbdebbff572ccafa662551015`
-
-These values are deliberately separate. The compared commit is the content
-baseline, the comparison tag is the human-readable release marker, the resolved
-tag commit records what that tag pointed to, and the latest checked commit is
-the newest upstream tree reviewed for additions or removals.
-
-The machine-readable selection is in
-[`upstream-selection.json`](upstream-selection.json). It classifies every
-upstream `SKILL.md` present at the latest checked commit as either promoted or
-intentionally excluded. Each promoted skill names its local catalog capability,
-plain Markdown resource, and upstream invocation mode. Each exclusion carries a
-reason; Claude Code hooks and background-agent commands are identified as
-host-specific rather than silently ignored.
-
-## Harness architecture
-
-Upstream distributes nested `SKILL.md` files. Pi recursively discovers any
-such file under a declared skill root, which exposes generic names such as
-`tdd`, `code-review`, and `research` alongside unrelated installed skills.
-
-This package exposes one extension command, `/matt-pocock`. The extension
-selects and injects plain Markdown procedures from `procedures/`; none are Pi
-skills, and the package contains no `SKILL.md` file.
-
-## Sync rules
-
-1. Clone upstream separately and inspect both the compared and latest checked
-   commits before changing local resources.
-2. Run the local metadata check without an upstream checkout:
-
-   ```bash
-   node scripts/check-upstream-sync.mjs
-   ```
-
-3. Run the complete inventory, invocation, and content comparison against an
-   already-cloned checkout. The checker never clones or fetches:
-
-   ```bash
-   node scripts/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
-   ```
-
-4. Copy selected workflows and supporting files into `procedures/`; never
-   overwrite the extension harness wholesale.
-5. Rename copied upstream `SKILL.md` files to their catalog id plus `.md`.
-   Strip frontmatter, and never ship a `SKILL.md` file.
-6. Remove Claude-only frontmatter, tools, paths, and invocation syntax from
-   copied content. Replace cross-procedure calls with relative links.
-7. Preserve the local BDD/TDD split and Pi-specific interaction,
-   collaboration, instruction-file, and git-agent guidance. An adapted content
-   result is expected when these local contracts differ from upstream.
-8. Classify every new or removed upstream skill in
-   `upstream-selection.json`, then update the four revision fields together.
-9. Re-run the harness feature, isolated sync tests, package tests, and package
-   dry-run after a sync.

package/procedures/CONTEXT-FORMAT.md

@@ -1,60 +0,0 @@
-# CONTEXT.md Format
-
-## Structure
-
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
-
-**Order**:
-{A one or two sentence description of the term}
-_Avoid_: Purchase, transaction
-
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
-- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/procedures/issue-tracker-github.md

@@ -1,45 +0,0 @@
-# Issue tracker: GitHub
-
-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
-
-## Conventions
-
-- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
-- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
-- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
-- **Comment on an issue**: `gh issue comment <number> --body "..."`
-- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
-- **Close**: `gh issue close <number> --comment "..."`
-
-Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
-
-## Pull requests as a triage surface
-
-**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; [triage](triage.md) reads this flag.)_
-
-When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
-
-- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
-- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
-- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
-
-GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
-
-## When a skill says "publish to the issue tracker"
-
-Create a GitHub issue.
-
-## When a skill says "fetch the relevant ticket"
-
-Run `gh issue view <number> --comments`.
-
-## Wayfinding operations
-
-Used by [wayfinder](wayfinder.md). The **map** is a single issue with **child** issues as tickets.
-
-- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
-- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
-- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
-- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
-- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
-- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.