continuous-improvement 3.8.0 → 3.9.2

package/skills/README.md

@@ -1,79 +1,79 @@
-# Source Skills
-
-This directory holds the **source-of-truth** for the companion skills bundled with the `continuous-improvement` plugin.
-
-> Edit files **here**. The plugin bundle at `plugins/continuous-improvement/skills/<name>/SKILL.md` is **regenerated** every time you run `npm run build` (see [`bin/generate-plugin-manifests.mjs`](../bin/generate-plugin-manifests.mjs)). Edits made directly inside `plugins/continuous-improvement/skills/` will be overwritten.
-
-## Featured companion — installed by default with the plugin
-
-`proceed-with-the-recommendation` is the **recommended pairing** for the 7 Laws. It is the execution arm that turns "do all of it" into a disciplined, verified, one-concern-at-a-time walk through the agent's recommendation list. If you only adopt one companion alongside the core skill, adopt this one.
-
-| Skill | What it does | Source |
-|-------|--------------|--------|
-| **`proceed-with-the-recommendation`** ⭐ | Walks any agent's recommendation list top-to-bottom under the 7 Laws — routes each item to the right specialist (`superpowers:*`, `ralph`, `workspace-surface-audit`, `simplify`, `security-review`, `schedule`, `loop`), falls back to inline behavior when a specialist isn't installed, verifies per item, halts on `needs-approval` | @naimkatiman |
-
-## Tier 1 — recommended pairing for **beginner** mode
-
-These add concrete enforcement to the 7 Laws. Tier-1 skills are the always-on minimum for any user running `npx continuous-improvement install` (default beginner mode).
-
-| Skill | What it does | Pairs with which Law |
-|-------|--------------|----------------------|
-| `para-memory-files` | File-based persistent memory using PARA (Projects/Areas/Resources/Archives) for cross-session context | Law 5 (Reflect), Law 7 (Learn) |
-| `verification-loop` | Six-phase verification (build, types, lint, tests, security, diff) with a structured PASS/FAIL report | Law 4 (Verify Before Reporting) |
-| `gateguard` | PreToolUse fact-forcing gate that blocks Edit/Write/destructive Bash until concrete investigation is presented | Law 1 (Research) |
-| `tdd-workflow` | RED→GREEN→REFACTOR enforcement, 80%+ coverage gate across unit/integration/E2E | Law 3 (One Thing), Law 4 (Verify) |
-
-## Tier 2 — additional skills for **expert** mode
-
-Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover autonomous-mode safety, response-depth control, and context-window discipline that matter once an agent runs longer or more aggressively.
-
-| Skill | What it does | When it pays off |
-|-------|--------------|------------------|
-| `safety-guard` | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory | Autonomous loops, prod systems, `--dangerously-skip-permissions` sessions |
-| `token-budget-advisor` | Heuristic input/output token estimator that offers 25%/50%/75%/100% depth choices before answering | Long sessions where response size matters |
-| `strategic-compact` | PreToolUse hook that suggests `/compact` at logical phase boundaries (research→plan, plan→implement, debug→next) instead of arbitrary auto-compaction | Multi-phase tasks that approach context limits |
-| `wild-risa-balance` | Decision-framing lens that pairs WILD (Wild/Imaginative/Limitless/Disruptive) generation with RISA (Realistic/Important/Specific/Agreeable) execution, used to split recommendation lists into bold pilots above a safe baseline | Multi-item recommendation blocks where bold options keep losing to safe ones in a flat list |
-
-The `/learn-eval` slash command also ships as part of the expert install: extract a session pattern, run a checklist quality gate, and decide global-vs-project save location before writing any skill file.
-
-## Other always-bundled companion skills
-
-These ship in the same plugin bundle regardless of mode and are available the moment you install the `continuous-improvement` plugin from the marketplace.
-
-| Skill | What it does | Source |
-|-------|--------------|--------|
-| `ralph` | Autonomous loop that executes a PRD story-by-story with quality checks between iterations | [snarktank/ralph](https://github.com/snarktank/ralph) |
-| `superpowers` | **Law activator.** Routes tasks to the correct Law-aligned specialist (brainstorming → Law 2, writing-plans → Law 2, TDD → Law 3+4, verification-before-completion → Law 4, etc.) so the right discipline fires automatically. Not a peer skill — a dispatcher for the others. | [obra/superpowers](https://github.com/obra/superpowers) |
-| `workspace-surface-audit` | Audits the active repo, MCP servers, plugins, and env, then recommends high-value skills/workflows | continuous-improvement |
-
-## How they get to your machine
-
-Two paths, you pick:
-
-**Path A — Install the plugin (recommended).** Bundled with the core skill, no per-skill copying. All companions land in one shot:
-
-```bash
-/plugin marketplace add naimkatiman/continuous-improvement
-/plugin install continuous-improvement@continuous-improvement
-```
-
-(The `-dev` suffix is reserved for the in-repo development marketplace at `plugins/continuous-improvement/.claude-plugin/marketplace.json` — only used when iterating on the bundle locally.)
-
-**Path B — Drop a single skill in by hand.** Useful if you want only one companion without the rest of the plugin:
-
-```bash
-SKILL=proceed-with-the-recommendation
-mkdir -p ~/.claude/skills/$SKILL
-curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
-  -o ~/.claude/skills/$SKILL/SKILL.md
-```
-
-Or paste the file's contents directly into your agent's system prompt.
-
-## Pressure-test logs
-
-Adversarial pressure-test logs for skills in this directory live under [`docs/testing/`](../docs/testing/). They are not skills — they are baseline guarantees future edits must preserve.
-
-## Relationship to the core skill
-
-The core [`SKILL.md`](../SKILL.md) at the repo root defines the **7 Laws of discipline**. The skills in this directory are independent execution tools that build on those laws. They do not depend on `SKILL.md` and `SKILL.md` does not depend on them — but `proceed-with-the-recommendation` was written specifically to operationalize the 7 Laws end-to-end, which is why it's the featured pairing.
+# Source Skills
+
+This directory holds the **source-of-truth** for the companion skills bundled with the `continuous-improvement` plugin.
+
+> Edit files **here**. The plugin bundle at `plugins/continuous-improvement/skills/<name>/SKILL.md` is **regenerated** every time you run `npm run build` (see [`bin/generate-plugin-manifests.mjs`](../bin/generate-plugin-manifests.mjs)). Edits made directly inside `plugins/continuous-improvement/skills/` will be overwritten.
+
+## Featured companion — installed by default with the plugin
+
+`proceed-with-the-recommendation` is the **recommended pairing** for the 7 Laws. It is the execution arm that turns "do all of it" into a disciplined, verified, one-concern-at-a-time walk through the agent's recommendation list. If you only adopt one companion alongside the core skill, adopt this one.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| **`proceed-with-the-recommendation`** ⭐ | Walks any agent's recommendation list top-to-bottom under the 7 Laws — routes each item to the right specialist (`superpowers:*`, `ralph`, `workspace-surface-audit`, `simplify`, `security-review`, `schedule`, `loop`), falls back to inline behavior when a specialist isn't installed, verifies per item, halts on `needs-approval` | @naimkatiman |
+
+## Tier 1 — recommended pairing for **beginner** mode
+
+These add concrete enforcement to the 7 Laws. Tier-1 skills are the always-on minimum for any user running `npx continuous-improvement install` (default beginner mode).
+
+| Skill | What it does | Pairs with which Law |
+|-------|--------------|----------------------|
+| `para-memory-files` | File-based persistent memory using PARA (Projects/Areas/Resources/Archives) for cross-session context | Law 5 (Reflect), Law 7 (Learn) |
+| `verification-loop` | Six-phase verification (build, types, lint, tests, security, diff) with a structured PASS/FAIL report | Law 4 (Verify Before Reporting) |
+| `gateguard` | PreToolUse fact-forcing gate that blocks Edit/Write/destructive Bash until concrete investigation is presented | Law 1 (Research) |
+| `tdd-workflow` | RED→GREEN→REFACTOR enforcement, 80%+ coverage gate across unit/integration/E2E | Law 3 (One Thing), Law 4 (Verify) |
+
+## Tier 2 — additional skills for **expert** mode
+
+Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover autonomous-mode safety, response-depth control, and context-window discipline that matter once an agent runs longer or more aggressively.
+
+| Skill | What it does | When it pays off |
+|-------|--------------|------------------|
+| `safety-guard` | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory | Autonomous loops, prod systems, `--dangerously-skip-permissions` sessions |
+| `token-budget-advisor` | Heuristic input/output token estimator that offers 25%/50%/75%/100% depth choices before answering | Long sessions where response size matters |
+| `strategic-compact` | PreToolUse hook that suggests `/compact` at logical phase boundaries (research→plan, plan→implement, debug→next) instead of arbitrary auto-compaction | Multi-phase tasks that approach context limits |
+| `wild-risa-balance` | Decision-framing lens that pairs WILD (Wild/Imaginative/Limitless/Disruptive) generation with RISA (Realistic/Important/Specific/Agreeable) execution, used to split recommendation lists into bold pilots above a safe baseline | Multi-item recommendation blocks where bold options keep losing to safe ones in a flat list |
+
+The `/learn-eval` slash command also ships as part of the expert install: extract a session pattern, run a checklist quality gate, and decide global-vs-project save location before writing any skill file.
+
+## Other always-bundled companion skills
+
+These ship in the same plugin bundle regardless of mode and are available the moment you install the `continuous-improvement` plugin from the marketplace.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| `ralph` | Autonomous loop that executes a PRD story-by-story with quality checks between iterations | [snarktank/ralph](https://github.com/snarktank/ralph) |
+| `superpowers` | **Law activator.** Routes tasks to the correct Law-aligned specialist (brainstorming → Law 2, writing-plans → Law 2, TDD → Law 3+4, verification-before-completion → Law 4, etc.) so the right discipline fires automatically. Not a peer skill — a dispatcher for the others. | [obra/superpowers](https://github.com/obra/superpowers) |
+| `workspace-surface-audit` | Audits the active repo, MCP servers, plugins, and env, then recommends high-value skills/workflows | continuous-improvement |
+
+## How they get to your machine
+
+Two paths, you pick:
+
+**Path A — Install the plugin (recommended).** Bundled with the core skill, no per-skill copying. All companions land in one shot:
+
+```bash
+/plugin marketplace add naimkatiman/continuous-improvement
+/plugin install continuous-improvement@continuous-improvement
+```
+
+(The `-dev` suffix is reserved for the in-repo development marketplace at `plugins/continuous-improvement/.claude-plugin/marketplace.json` — only used when iterating on the bundle locally.)
+
+**Path B — Drop a single skill in by hand.** Useful if you want only one companion without the rest of the plugin:
+
+```bash
+SKILL=proceed-with-the-recommendation
+mkdir -p ~/.claude/skills/$SKILL
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
+  -o ~/.claude/skills/$SKILL/SKILL.md
+```
+
+Or paste the file's contents directly into your agent's system prompt.
+
+## Pressure-test logs
+
+Adversarial pressure-test logs for skills in this directory live under [`docs/testing/`](../docs/testing/). They are not skills — they are baseline guarantees future edits must preserve.
+
+## Relationship to the core skill
+
+The core [`SKILL.md`](../SKILL.md) at the repo root defines the **7 Laws of discipline**. The skills in this directory are independent execution tools that build on those laws. They do not depend on `SKILL.md` and `SKILL.md` does not depend on them — but `proceed-with-the-recommendation` was written specifically to operationalize the 7 Laws end-to-end, which is why it's the featured pairing.

package/skills/deploy-receipt.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/skills/gateguard.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/skills/para-memory-files.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/skills/proceed-with-the-recommendation.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)