continuous-improvement 3.8.0 → 3.9.2

package/plugins/continuous-improvement/instinct-packs/react.json

@@ -1,58 +1,58 @@
-[
-  {
-    "id": "react-check-existing-components",
-    "trigger": "when creating a new React component",
-    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
-    "confidence": 0.65,
-    "domain": "workflow"
-  },
-  {
-    "id": "react-prefer-server-components",
-    "trigger": "when creating components in Next.js App Router",
-    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-key-prop-lists",
-    "trigger": "when rendering lists with .map()",
-    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-effect-cleanup",
-    "trigger": "when writing useEffect with subscriptions or timers",
-    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-memo-expensive",
-    "trigger": "when a component re-renders with expensive calculations",
-    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-form-validation",
-    "trigger": "when building forms",
-    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
-    "confidence": 0.65,
-    "domain": "tooling"
-  },
-  {
-    "id": "react-error-boundary",
-    "trigger": "when adding a new page or route",
-    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-test-user-behavior",
-    "trigger": "when writing React component tests",
-    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
-    "confidence": 0.65,
-    "domain": "testing"
-  }
-]
+[
+  {
+    "id": "react-check-existing-components",
+    "trigger": "when creating a new React component",
+    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
+    "confidence": 0.65,
+    "domain": "workflow"
+  },
+  {
+    "id": "react-prefer-server-components",
+    "trigger": "when creating components in Next.js App Router",
+    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-key-prop-lists",
+    "trigger": "when rendering lists with .map()",
+    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-effect-cleanup",
+    "trigger": "when writing useEffect with subscriptions or timers",
+    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-memo-expensive",
+    "trigger": "when a component re-renders with expensive calculations",
+    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-form-validation",
+    "trigger": "when building forms",
+    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
+    "confidence": 0.65,
+    "domain": "tooling"
+  },
+  {
+    "id": "react-error-boundary",
+    "trigger": "when adding a new page or route",
+    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-test-user-behavior",
+    "trigger": "when writing React component tests",
+    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
+    "confidence": 0.65,
+    "domain": "testing"
+  }
+]

package/plugins/continuous-improvement/lib/plugin-metadata.mjs

@@ -1,5 +1,9 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 export const PACKAGE_NAME = "continuous-improvement";
-export const VERSION = "3.8.0";
+const PKG_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+export const VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
 export const PLUGIN_MODES = ["beginner", "expert"];
 const REPOSITORY_URL = "https://github.com/naimkatiman/continuous-improvement";
 const HOMEPAGE_URL = `${REPOSITORY_URL}#readme`;
@@ -23,11 +27,17 @@ const KEYWORDS = [
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
 const SHARED_PLUGIN_DESCRIPTION = "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 13 enforcement skills, gating hooks, and the Mulahazah auto-leveling instinct engine.";
-// Five vendored upstream companions registered alongside the CI plugin.
+// Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
 // OUR_NOTES.md for integration scope and overlap matrices. The unified
-// /superpowers dispatcher (skills/superpowers.md) routes across all five.
+// /superpowers dispatcher (skills/superpowers.md) routes across all four.
+// Product-management coverage is supplied by phuryn/pm-skills as an
+// out-of-band marketplace install — see docs/THIRD_PARTY.md for the
+// `claude plugin marketplace add phuryn/pm-skills` recipe and the eight
+// installable plugins (pm-toolkit, pm-product-strategy, pm-product-discovery,
+// pm-market-research, pm-data-analytics, pm-marketing-growth,
+// pm-go-to-market, pm-execution).
 const THIRD_PARTY_COMPANIONS = [
     {
         name: "superpowers",
@@ -75,18 +85,6 @@ const THIRD_PARTY_COMPANIONS = [
         category: "orchestration",
         homepage: "https://github.com/Yeachan-Heo/oh-my-claudecode",
     },
-    {
-        name: "pm-skills",
-        description: "Product management skills for AI agents — 41 skills + 47 commands across the full product lifecycle (discover, define, develop, deliver, measure, iterate). Includes Meeting Skills Family v2.11.0 (5 cross-cutting skills under a shared contract with enforcing CI), OKR Skills v2.12.0 (foundation-okr-writer + measure-okr-grader for the quarterly OKR write-and-score cycle), lean canvas, persona, JTBD, PRD, user stories, acceptance criteria, hypothesis, experiment design, retrospective, launch checklist, release notes, and pm-skill-builder for authoring new skills. Follows the agentskills.io specification. Vendored snapshot at third-party/pm-skills/ pinned to upstream SHA 8d23508 (v2.13.1).",
-        version: "2.13.1",
-        source: "./third-party/pm-skills",
-        author: {
-            name: "product-on-purpose",
-            url: "https://github.com/product-on-purpose",
-        },
-        category: "product",
-        homepage: "https://github.com/product-on-purpose/pm-skills",
-    },
 ];
 export function isPluginMode(value) {
     return value === "beginner" || value === "expert";
@@ -358,6 +356,11 @@ export function getClaudePluginManifest() {
     };
 }
 export function getPluginHooksConfig() {
+    const gateguardCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gateguard.mjs\"",
+        timeout: 5,
+    };
     const observeCommand = {
         type: "command",
         command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
@@ -374,9 +377,13 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
         hooks: {
-            PreToolUse: [{ hooks: [observeCommand] }],
+            // gateguard runs FIRST so its block decision short-circuits before
+            // observe.sh records the tool call. observe.sh stays in PreToolUse for
+            // the observation feed; the Claude Code host runs both regardless of
+            // gateguard's decision.
+            PreToolUse: [{ hooks: [gateguardCommand, observeCommand] }],
             PostToolUse: [{ hooks: [observeCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
@@ -409,7 +416,7 @@ export function getClaudePluginMarketplaceManifest() {
 export function getClaudeRepoMarketplaceManifest(extraPlugins = []) {
     return {
         name: PACKAGE_NAME,
-        description: "Marketplace for the Continuous Improvement Claude Code plugin and five vendored upstream companions (Obra superpowers, addyosmani/agent-skills, ruflo-swarm, oh-my-claudecode, product-on-purpose/pm-skills). All five companions are pinned-SHA snapshots in third-party/ — see third-party/MANIFEST.md for refresh recipes and per-snapshot OUR_NOTES.md for integration scope.",
+        description: "Marketplace for the Continuous Improvement Claude Code plugin and four vendored upstream companions (Obra superpowers, addyosmani/agent-skills, ruflo-swarm, oh-my-claudecode). All four companions are pinned-SHA snapshots in third-party/ — see third-party/MANIFEST.md for refresh recipes and per-snapshot OUR_NOTES.md for integration scope. Product-management coverage is provided out-of-band by phuryn/pm-skills via Claude Code's plugin marketplace — see docs/THIRD_PARTY.md.",
         owner: {
             name: AUTHOR.name,
         },

package/plugins/continuous-improvement/skills/README.md

@@ -23,12 +23,15 @@ skill set on disk.
 - `verification-loop` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. A comprehensive verification system for agent coding sessions covering build, types, lint, tests, security, and diff with a PASS/FAIL report.
 
 ## Tier 2 — expert-mode add-ons
+- `recovery-classification` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. After any failure in the verification ladder or auto-loop, classify the failure class before retrying — provider, tool-schema, deterministic-policy, git, worktree, runtime — so retry-vs-pause-vs-self-heal-vs-stop is an intentional decision, not a generic 'try again'.
 - `safety-guard` — Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
+- `state-reconciliation` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: reconcile DB-vs-disk-vs-memory state before any unit runs, so a stale flag, missing artifact, or out-of-sync row never re-dispatches a unit that already completed or never started.
 - `strategic-compact` — Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline at phase boundaries. Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
 - `token-budget-advisor` — Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline by making token-budget tradeoffs explicit before the response is composed. Offers the user an informed choice about how much response depth to consume before answering. Use this skill when the user explicitly wants to control response length, depth, or token budget. TRIGGER when: "token budget", "token count", "token usage", "token limit", "response length", "answer depth", "short version", "brief answer", "detailed answer", "exhaustive answer", "respuesta corta vs larga", "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión corta", "quiero controlar cuánto usas", or clear variants where the user is explicitly asking to control answer size or depth. DO NOT TRIGGER when: user has already specified a level in the current session (maintain it), the request is clearly a one-word answer, or "token" refers to auth/session/payment tokens rather than response size.
 - `wild-risa-balance` — Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Decision-framing lens that pairs WILD generation with RISA execution when emitting recommendation lists. Not a runtime hook.
+- `worktree-safety` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: validate worktree root before any source-writing tool call. Catches missing .git, fallback path-only creation, stale leases, foreign-session ownership, and non-worktree git operations before they corrupt history.
 
 ## Always-bundled companions
 - `ralph` — Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress.
-- `superpowers` — Law activator for the 7 Laws of AI Agent Discipline. Unified five-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode, pm-skills) so the right discipline fires automatically instead of the agent skipping a step. Not a peer skill — a dispatcher for the others.
+- `superpowers` — Law activator for the 7 Laws of AI Agent Discipline. Unified four-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode) so the right discipline fires automatically instead of the agent skipping a step. Product-management coverage comes from phuryn/pm-skills via an out-of-band marketplace install (see docs/THIRD_PARTY.md). Not a peer skill — a dispatcher for the others.
 - `workspace-surface-audit` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Audits the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommends the highest-value continuous-improvement-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their environment.

package/plugins/continuous-improvement/skills/deploy-receipt/SKILL.md

@@ -101,6 +101,50 @@ After running verification:
 
 A `COMPLETE` receipt is the only state that lets the merge be reported as `done`. `INCOMPLETE` receipts surface a single named operator-action item (e.g. "Railway last deploy is older than the merge — re-trigger from dashboard or `railway up`").
 
+## On-Incomplete Modes
+
+The default behavior on `INCOMPLETE` is **report-only** — the receipt block names the gap, the operator decides recovery. A second mode is available for projects that want the skill to also stage a recovery branch and a failing repro test, without ever executing rollback or merge.
+
+### Mode A — `report-only` (default)
+
+The current behavior. Print the receipt block, surface the named operator-action item, hand off. No branch creation, no PR opened. Use this mode when the operator is at the keyboard and will react to the receipt directly. No flag required.
+
+### Mode B — `open-hotfix-pr` (opt-in)
+
+Use this mode when the receipt is `INCOMPLETE` AND a documented recovery window has elapsed without the deploy self-correcting (default 10 minutes from merge; tunable per project via `verify-ladder.json` `deploy_receipt_recovery_window_seconds`). The skill then stages a recovery branch *for the operator to review*, but never merges or rolls back on its own.
+
+Activate with the explicit invocation:
+
+```
+deploy-receipt --on-incomplete=open-hotfix-pr
+```
+
+When triggered, this mode performs four steps in order, halting on the first failure:
+
+1. **Branch.** `git checkout -b hotfix/<merge-sha-short>-<symptom-slug> origin/<deploy-branch>`. The symptom slug is derived from the named gap on the receipt — `sha-mismatch`, `health-non-200`, `version-endpoint-stale`, or `no-provider-source`. If the slug cannot be derived, halt and revert to report-only.
+2. **Failing repro test.** Write a single test file at `tests/regressions/deploy-<merge-sha-short>.test.<ext>` that asserts the gap (e.g. `expect(deployedSha).toEqual(mergeSha)` or `expect(healthResponse.status).toBe(200)`). The test MUST currently fail when run against production. The skill writes the assertion against the receipt's recorded values, not against speculation. If the test cannot be made to fail deterministically, halt and revert to report-only.
+3. **Open PR.** `gh pr create --base <deploy-branch> --head hotfix/... --draft` with body that cites the receipt block verbatim, the merge SHA, the deployed SHA, the named gap, and the documented rollback command for the detected provider (a one-line shell snippet from the table below). Draft state is mandatory — never open as ready-for-review without operator approval.
+4. **Hand off.** Print a single-line operator-action item naming the new branch, the PR URL, and the documented rollback command. Stop. Do not modify production. Do not merge the PR. Do not run the rollback.
+
+### Documented rollback commands (cited in the PR body, never executed)
+
+| Provider | Documented rollback command |
+|---|---|
+| Railway | `railway redeploy --service <service-id> --commit <previous-good-sha>` |
+| Cloudflare Workers | `wrangler rollback --message "deploy-receipt: <merge-sha-short> failed health/SHA gate"` |
+| Vercel | `vercel rollback <previous-good-deployment-url>` |
+| Netlify | `netlify rollback` (interactive — operator picks the prior deploy) |
+| Fly.io | `fly releases rollback <previous-good-version>` |
+
+The rollback command is **printed**, not run. The skill's job is to give the operator a complete recovery packet (branch + failing test + cited command) without taking the irreversible step itself.
+
+### When NOT to use Mode B
+
+- The deploy is mid-rolling-restart or mid-canary — the receipt is INCOMPLETE because the deploy is still in progress, not because it failed. Wait for the recovery window first.
+- Branch protection on the deploy branch denies hotfix branches by name pattern — the PR will fail to open and the skill should fall back to report-only with a named operator action ("hotfix branch denied by protection — recovery requires direct console access").
+- The previous-good SHA cannot be determined from `git log origin/<deploy-branch>` alone — the rollback command in the PR body would be a guess. Fall back to report-only and name the gap as "previous-good SHA unverifiable — operator must select".
+- The operator has already started a manual recovery (a fresh deploy is running, the dashboard shows a rollback in progress). Detect via Route A or Route B and skip Mode B for this receipt cycle.
+
 ## Anti-Patterns
 
 - **"Eventually consistent" excuse.** Reporting done with `Deployed SHA: not retrieved` and a comment like "deploy will pick up shortly" is exactly the failure mode this skill prevents. There is no eventually — there is COMPLETE or INCOMPLETE.
@@ -108,6 +152,9 @@ A `COMPLETE` receipt is the only state that lets the merge be reported as `done`
 - **Skipping for "small changes."** A docs-only commit still needs a receipt if the deploy branch auto-deploys — small changes have caused stale-build incidents on every provider in the table above.
 - **Recommending the CLI install mid-receipt.** If Route A is unavailable, fall through to B then C. Adding tooling is a separate decision the operator makes outside the receipt loop.
 - **Treating absence of evidence as evidence of success.** If none of the three routes produce a SHA, the receipt is `INCOMPLETE — no provider source available`, not `COMPLETE (assumed)`.
+- **Auto-merging the hotfix PR.** Mode B opens the PR as draft and stops. Auto-merge, `--admin` overrides, and `gh pr merge` calls are refused inside this skill. The hotfix is the operator's decision; the skill stages it but never lands it.
+- **Force-pushing or rewriting the hotfix branch.** Mode B branches off `origin/<deploy-branch>` once and pushes once. If the failing test needs changes, the skill writes a new commit on the branch — never `--force` and never `git rebase --interactive`.
+- **Executing the rollback command.** The rollback command is cited in the PR body for operator review. Mode B never runs `railway redeploy`, `wrangler rollback`, `vercel rollback`, etc. on its own. If the operator wants execution, they run it themselves or they wire a separate runner; that is a different skill.
 
 ## Pairs With
 

package/plugins/continuous-improvement/skills/gateguard/SKILL.md

@@ -7,7 +7,9 @@ origin: community
 
 # GateGuard — Fact-Forcing Pre-Action Gate
 
-A PreToolUse hook that forces the agent to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.
+A runtime PreToolUse hook + skill pair that forces the agent to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.
+
+> **Implementation status:** GateGuard ships as a **runtime PreToolUse hook** at `hooks/gateguard.mjs`, wired as the first PreToolUse entry in the plugin bundle. The hook physically blocks Edit / Write / MultiEdit and every destructive Bash on stdin/stdout JSON, returning `{decision: "block", reason: "..."}` until the agent presents facts and retries with the per-session clearance signal. This skill file is the human-readable spec the hook implements. Originally tracked in [issue #106](https://github.com/naimkatiman/continuous-improvement/issues/106) (closed; landed as PR #108).
 
 ## When to Activate
 
@@ -124,18 +126,24 @@ This gate is what catches the squash-merge / ahead-of-origin trap recorded in th
 
 ## Quick Start
 
-### Option A: Use the continuous-improvement hook (zero install)
+### Today: runtime hook + skill (zero install beyond the plugin)
 
-The hook at `scripts/hooks/gateguard-fact-force.js` is included in this plugin. Enable it via hooks.json.
+`hooks/gateguard.mjs` is bundled with this plugin and wired as the first PreToolUse hook in `plugins/continuous-improvement/hooks/hooks.json`. When you install the plugin, the runtime gate is live — no extra config, no opt-in. The hook reads tool input from stdin, classifies it through a data-driven routing table (Read/Grep/Glob → allow, Write/Edit/MultiEdit → mutating-file gate, Bash → destructive-pattern check), and emits `{decision, reason?}` on stdout. Per-session state lives at `~/.claude/instincts/<project-hash>/gateguard-session.json` (override via `GATEGUARD_SESSION_DIR` for tests) and caps cumulative clearances at `MAX_CLEARED_FILES = 50`.
 
-### Option B: Full package with config
+Smoke-test the runtime gate after install: ask Claude to write a throwaway file with no research first. The hook should return a `block` decision with a fact-list reason; Claude should pause rather than write.
 
-```bash
-pip install gateguard-ai
-gateguard init
-```
+### V1 honest limitations (not mitigated, documented)
+
+- **Honor system.** Once the agent flips `_gateguard_facts_presented: true` in `tool_input`, the hook can't verify the investigation actually happened. The 50-file cap bounds damage from stuck loops or rogue agents.
+- **State-file deletion.** `rm`-ing the session state resets every gate. Acceptable because the session itself is the trust boundary.
+- **Parallel-hook race.** Two simultaneous hook invocations can race the read+write of the state file. Acceptable trade-off vs Windows atomic-rename complexity.
+- **MultiEdit V1.** Currently gates on `edits[0].file_path` only. Per-file batching is a TODO.
+
+All four documented in `src/hooks/gateguard.mts` and `src/lib/gateguard-state.mts` headers.
+
+### Future: third-party `gateguard-ai` package
 
-This adds `.gateguard.yml` for per-project configuration (custom messages, ignore paths, gate toggles).
+The standalone `gateguard-ai` Python/CLI package referenced in earlier drafts of this skill is not currently part of this plugin and not a published package. It may ship later with `.gateguard.yml` per-project config; for now, treat it as design notes only.
 
 ## Anti-Patterns
 

package/plugins/continuous-improvement/skills/para-memory-files/SKILL.md

@@ -1,108 +1,108 @@
----
-name: para-memory-files
-tier: "1"
-description: >
-  Enforces Law 5 (Reflect After Every Session) and Law 7 (Learn From Every Session)
-  of the 7 Laws of AI Agent Discipline by giving the agent a durable file-based
-  memory it can read on resume and write at session end.
-  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
-  you need to store, retrieve, update, or organize knowledge across sessions. Covers
-  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
-  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
-  handles planning files, memory decay, weekly synthesis, and recall via qmd.
-  Trigger on any memory operation: saving facts, writing daily notes, creating
-  entities, running weekly synthesis, recalling past context, or managing plans.
----
-
-# PARA Memory Files
-
-Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
-
-## Three Memory Layers
-
-### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
-
-Entity-based storage. Each entity gets a folder with two tiers:
-
-1. `summary.md` -- quick context, load first.
-2. `items.yaml` -- atomic facts, load on demand.
-
-```text
-$AGENT_HOME/life/
-  projects/          # Active work with clear goals/deadlines
-    <name>/
-      summary.md
-      items.yaml
-  areas/             # Ongoing responsibilities, no end date
-    people/<name>/
-    companies/<name>/
-  resources/         # Reference material, topics of interest
-    <topic>/
-  archives/          # Inactive items from the other three
-  index.md
-```
-
-**PARA rules:**
-
-- **Projects** -- active work with a goal or deadline. Move to archives when complete.
-- **Areas** -- ongoing (people, companies, responsibilities). No end date.
-- **Resources** -- reference material, topics of interest.
-- **Archives** -- inactive items from any category.
-
-**Fact rules:**
-
-- Save durable facts immediately to `items.yaml`.
-- Weekly: rewrite `summary.md` from active facts.
-- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
-- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
-
-**When to create an entity:**
-
-- Mentioned 3+ times, OR
-- Direct relationship to the user (family, coworker, partner, client), OR
-- Significant project or company in the user's life.
-- Otherwise, note it in daily notes.
-
-For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
-
-### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
-
-Raw timeline of events -- the "when" layer.
-
-- Write continuously during conversations.
-- Extract durable facts to Layer 1 during heartbeats.
-
-### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
-
-How the user operates -- patterns, preferences, lessons learned.
-
-- Not facts about the world; facts about the user.
-- Update whenever you learn new operating patterns.
-
-## Write It Down -- No Mental Notes
-
-Memory does not survive session restarts. Files do.
-
-- Want to remember something -> WRITE IT TO A FILE.
-- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
-- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
-- Make a mistake -> document it so future-you does not repeat it.
-- On-disk text files are always better than holding it in temporary context.
-
-## Memory Recall -- Use qmd
-
-Use `qmd` rather than grepping files:
-
-```bash
-qmd query "what happened at Christmas"   # Semantic search with reranking
-qmd search "specific phrase"              # BM25 keyword search
-qmd vsearch "conceptual question"         # Pure vector similarity
-```
-
-Index your personal folder: `qmd index $AGENT_HOME`
-
-Vectors + BM25 + reranking finds things even when the wording differs.
-
-## Planning
-
-Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.
+---
+name: para-memory-files
+tier: "1"
+description: >
+  Enforces Law 5 (Reflect After Every Session) and Law 7 (Learn From Every Session)
+  of the 7 Laws of AI Agent Discipline by giving the agent a durable file-based
+  memory it can read on resume and write at session end.
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md

@@ -160,14 +160,7 @@ Rows whose **Preferred skill** is not bundled with the `continuous-improvement`
 | Visual regression / browser-level diff | `oh-my-claudecode:visual-verdict` | Playwright screenshot diff against staging baseline. (Reference behavior — does not require `oh-my-claudecode`.) |
 | Multi-session retrospective across a sprint | `oh-my-claudecode:retrospective` → `learn-eval` | What worked / what failed / what to do differently / 3 ranked next moves. (Reference behavior — does not require `oh-my-claudecode`.) |
 | Long autonomous run with quality gates | `oh-my-claudecode:ultrawork` → `ralph` | PRD-shaped autonomous loop with verify-between-iterations. (Reference behavior — does not require `oh-my-claudecode`.) |
-| Draft a PRD before implementation | `pm-skills:prd` | Problem → user → goal → metric → scope. Engineering plan is a separate doc. (Reference behavior — does not require `pm-skills`.) |
-| Decompose feature into user stories + acceptance criteria | `pm-skills:user-stories` + `pm-skills:acceptance-criteria` | "As <role> I want <action> so that <benefit>" + Given/When/Then per story. (Reference behavior — does not require `pm-skills`.) |
-| Write or grade quarterly OKRs | `pm-skills:okr-writer` + `pm-skills:okr-grader` | Objective + 3-5 measurable key results; grade 0.0-1.0 at end of cycle. (Reference behavior — does not require `pm-skills`.) |
-| Design hypothesis-driven experiment | `pm-skills:experiment-design` + `pm-skills:hypothesis` | "We believe <X> will produce <Y>; we'll know if <Z> moves by <delta>." (Reference behavior — does not require `pm-skills`.) |
-| Discovery framework: persona / JTBD / lean canvas | `pm-skills:persona` / `pm-skills:jtbd-canvas` / `pm-skills:lean-canvas` | Pick the framework that matches the gap; do not run all three. (Reference behavior — does not require `pm-skills`.) |
-| Market sizing or competitive analysis | `pm-skills:market-sizing` / `pm-skills:competitive-analysis` | TAM/SAM/SOM bottom-up; competitive matrix on 5 axes. (Reference behavior — does not require `pm-skills`.) |
-| Meeting agenda / brief / recap / synthesize | `pm-skills:meeting-agenda` / `pm-skills:meeting-brief` / `pm-skills:meeting-recap` / `pm-skills:meeting-synthesize` | Cross-cutting Meeting Skills Family v2.11.0 with shared contract. (Reference behavior — does not require `pm-skills`.) |
-| Product launch checklist | `pm-skills:launch-checklist` | Marketing + ops + analytics + comms gates. Engineering uses `finishing-a-development-branch` + `deploy-receipt`. (Reference behavior — does not require `pm-skills`.) |
+| Product-management work (PRD, user stories, acceptance criteria, OKRs, experiments, personas, JTBD, lean canvas, market sizing, competitive analysis, meetings family, launch checklist) | Install phuryn/pm-skills via Claude Code marketplace — see docs/THIRD_PARTY.md | Out-of-band install (`claude plugin marketplace add phuryn/pm-skills` + the eight `pm-*@pm-skills` plugins). Inline fallback: keep the work shape (problem → user → goal → metric → scope; Given/When/Then per story; objective + 3-5 measurable KRs; we-believe / we'll-know hypothesis; TAM/SAM/SOM bottom-up; cross-cutting meetings agenda/brief/recap/synthesize) without depending on a specific routing target. |
 
 ## Phase 4: Verify (Law 4 — Verify Before Reporting)