continuous-improvement 3.12.3 → 3.15.0

package/llms.txt

@@ -1,10 +1,10 @@
 # continuous-improvement
 
-> Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.
+> The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.
 
 ## What This Is
 
-An intelligence amplifier for AI coding agents. It makes Claude reason at a higher level on every task, recall the corrections it has already received, and learn from each session so its competence compounds over time — research, plan, execute one thing at a time, verify, reflect, iterate, learn — building behavioral instincts via the Mulahazah learning system, so the same correction never has to be given twice and each run starts smarter than the last.
+The persistent-memory and discipline layer for AI coding agents. It carries the corrections Claude has already received from one session into the next, grounds each edit in real facts before it lands, and learns from every session so its competence compounds over time — research, plan, execute one thing at a time, verify, reflect, iterate, learn — building behavioral instincts via the Mulahazah learning system, so the same correction never has to be given twice and each run starts smarter than the last. Orchestration tools run a task; this is the layer that makes the lessons survive the run.
 
 ## Install
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.12.3",
-  "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
+  "version": "3.15.0",
+  "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",
     "claude-code-skill",
@@ -29,7 +29,8 @@
   "bin": {
     "continuous-improvement": "bin/install.mjs",
     "ci-lint-transcript": "bin/lint-transcript.mjs",
-    "ci": "bin/unified-cli.mjs"
+    "ci": "bin/unified-cli.mjs",
+    "ci-plan-pack": "bin/plan-pack.mjs"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node bin/generate-plugin-manifests.mjs && node -e \"const fs=require('node:fs'); for (const f of fs.readdirSync('bin')) { if (f.endsWith('.mjs')) fs.chmodSync('bin/'+f, 0o755); } for (const f of fs.readdirSync('hooks')) { if (f.endsWith('.mjs')) fs.chmodSync('hooks/'+f, 0o755); } for (const f of fs.readdirSync('lib')) { if (f.endsWith('.mjs')) fs.chmodSync('lib/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/bin')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/bin/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/lib')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/lib/'+f, 0o755); } for (const f of fs.readdirSync('plugins/continuous-improvement/hooks')) { if (f.endsWith('.mjs')) fs.chmodSync('plugins/continuous-improvement/hooks/'+f, 0o755); } for (const f of fs.readdirSync('scripts')) { if (f.endsWith('.mjs')) fs.chmodSync('scripts/'+f, 0o755); } for (const f of fs.readdirSync('synthetic-checks')) { if (f.endsWith('.mjs')) fs.chmodSync('synthetic-checks/'+f, 0o755); } \"",

package/plugins/beginner.json

@@ -1,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.12.3",
+  "version": "3.15.0",
   "mode": "beginner",
-  "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four grounding skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
+  "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
   "tools": [
     {
       "name": "ci_status",

package/plugins/continuous-improvement/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.12.3",
+      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.15.0",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.12.3",
-  "description": "Makes Claude Code reason harder, recall past corrections, and learn from every session so its competence compounds run over run. The Mulahazah engine turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time — no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+  "version": "3.15.0",
+  "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 25 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
   "author": {
     "name": "naimkatiman",
     "url": "https://github.com/naimkatiman"

package/plugins/continuous-improvement/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Naim Katiman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Naim Katiman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/continuous-improvement/README.md

@@ -35,7 +35,7 @@ the trade-off is fallback quality vs dedicated-skill quality.
 - `tdd-workflow` — RED/GREEN/REFACTOR + 80% coverage gate
 - `workspace-surface-audit` — environment + capability audit
 - Tier-1/Tier-2 enforcement skills (`gateguard`, `verification-loop`,
-  `para-memory-files`, `safety-guard`, `token-budget-advisor`,
+  `safety-guard`, `token-budget-advisor`,
   `strategic-compact`, `wild-risa-balance`)
 
 **Optional companions the orchestrator routes to (install separately if

package/plugins/continuous-improvement/bin/backfill.mjs

@@ -27,25 +27,25 @@ const args = process.argv.slice(2);
 const DRY_RUN = args.includes("--dry-run");
 const HELP = args.includes("--help") || args.includes("-h");
 if (HELP) {
-    console.log(`
-backfill — Tag legacy thin-schema observation rows.
-
-Usage:
-  npx continuous-improvement backfill            Tag rows in place
-  npx continuous-improvement backfill --dry-run  Report counts, write nothing
-
-What it does:
-  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
-  schema field ("thin" or "rich") to every row that lacks one. Thin rows
-  came from the legacy bash fallback (jq missing) and have no input_summary;
-  rich rows came from the Node observer and have full tool_input.command /
-  Edit.file_path / etc.
-
-Output:
-  - observations.jsonl rewritten in place (original kept as .bak)
-  - backfill-summary.json with per-project counts
-
-Idempotent. Always exits 0 — failures go to stderr only.
+    console.log(`
+backfill — Tag legacy thin-schema observation rows.
+
+Usage:
+  npx continuous-improvement backfill            Tag rows in place
+  npx continuous-improvement backfill --dry-run  Report counts, write nothing
+
+What it does:
+  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
+  schema field ("thin" or "rich") to every row that lacks one. Thin rows
+  came from the legacy bash fallback (jq missing) and have no input_summary;
+  rich rows came from the Node observer and have full tool_input.command /
+  Edit.file_path / etc.
+
+Output:
+  - observations.jsonl rewritten in place (original kept as .bak)
+  - backfill-summary.json with per-project counts
+
+Idempotent. Always exits 0 — failures go to stderr only.
 `);
     process.exit(0);
 }

package/plugins/continuous-improvement/bin/mcp-server.mjs

@@ -13,15 +13,15 @@
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
 import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
 import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
-import { draftFromCandidate, extractTrajectories, findCandidates, formatCandidates, serializeDraft, } from "../lib/skill-distill.mjs";
-import { MAX_CLEARED_FILES, clearFiles, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+import { draftFromCandidate, draftFromWorkflowRun, extractTrajectories, findCandidates, formatCandidates, serializeDraft, workflowRunFromObservations, } from "../lib/skill-distill.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, resolveInstinctsRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -508,10 +508,11 @@ function handleTool(name, params) {
         }
         case "ci_gateguard_clear": {
             // Beginner-available on purpose: the GateGuard hook fires for every
-            // install, so the clearance action must too. Resolves the session dir via
-            // gateguard-state (canonical), the same way the hook does, so the marker
-            // lands where the hook looks regardless of how each process spelled the
-            // project root.
+            // install, so the clearance action must too. The hook's block reason now
+            // prints state_path (the session-scoped state file); honoring it writes
+            // the marker exactly where the hook looks. Without it the MCP server can't
+            // know the caller's session, so it falls back to the canonical session dir
+            // — correct only on the legacy unscoped path.
             const rawList = Array.isArray(params.file_paths) ? params.file_paths : [];
             const listPaths = rawList.filter((value) => typeof value === "string" && value.length > 0);
             const single = getString(params.file_path).trim();
@@ -519,7 +520,24 @@ function handleTool(name, params) {
             if (paths.length === 0) {
                 return error("file_paths is required — pass the file path(s) named in the GateGuard block reason, e.g. { file_paths: [\"src/x.ts\"] }.");
             }
-            const sessionDir = resolveSessionDir();
+            // state_path is a model-controlled argument, so it could be a traversal
+            // string (`../../etc/...`). dirname leaves `..` segments for the OS to
+            // resolve at write time, so without a bound this is an arbitrary-write
+            // primitive. Resolve + canonicalize, then require containment within the
+            // instincts root (the only tree the hook ever prints a state_path inside).
+            const rawStatePath = getString(params.state_path).trim();
+            let sessionDir;
+            if (rawStatePath) {
+                const resolvedKey = canonicalizeFileKey(resolve(rawStatePath));
+                const rootKey = canonicalizeFileKey(resolveInstinctsRoot());
+                if (resolvedKey !== rootKey && !resolvedKey.startsWith(`${rootKey}/`)) {
+                    return error("state_path must resolve inside ~/.claude/instincts/. Pass it verbatim from the GateGuard block reason.");
+                }
+                sessionDir = dirname(resolve(rawStatePath));
+            }
+            else {
+                sessionDir = resolveSessionDir();
+            }
             const { cleared, skippedForCap } = clearFiles(sessionDir, paths);
             const lines = [
                 "## GateGuard clearance",
@@ -837,6 +855,45 @@ function handleTool(name, params) {
                 "```",
             ].join("\n"));
         }
+        case "ci_distill_from_workflow": {
+            if (MODE !== "expert") {
+                return error("ci_distill_from_workflow requires expert mode");
+            }
+            const run = workflowRunFromObservations(readDistillObservations(project.hash));
+            if (!run) {
+                return text("No completed-and-verified Workflow run found in this project's observations. " +
+                    "A run qualifies when a `Workflow` tool call is followed by a passing verify/test/build in the same feed. " +
+                    "Run a workflow, verify its output, then try `ci_distill_from_workflow` again.");
+            }
+            const draftInstinct = draftFromWorkflowRun(run);
+            if (!isSafeDraftId(draftInstinct.id)) {
+                return error(`Internal error: generated draft id "${draftInstinct.id}" failed the safety check.`);
+            }
+            const draft = serializeDraft(draftInstinct);
+            const draftsDir = join(INSTINCTS_DIR, project.hash, "drafts");
+            const draftPath = join(draftsDir, `${draftInstinct.id}.yaml`);
+            try {
+                mkdirSync(draftsDir, { recursive: true });
+                writeFileSync(draftPath, draft);
+            }
+            catch (err) {
+                return error(`Failed to write draft to ${draftPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return text([
+                "## Draft written from a verified workflow run",
+                "",
+                `**Workflow:** ${run.name}`,
+                `**Path:** ${draftPath}`,
+                "",
+                "Edit the body to capture the real recipe (preconditions, concrete steps, gotchas), then promote with:",
+                "",
+                `  ci_distill_promote id=${draftInstinct.id}`,
+                "",
+                "```yaml",
+                draft.trimEnd(),
+                "```",
+            ].join("\n"));
+        }
         case "ci_distill_promote": {
             if (MODE !== "expert") {
                 return error("ci_distill_promote requires expert mode");

package/plugins/continuous-improvement/commands/continuous-improvement.md

@@ -1,115 +1,115 @@
----
-name: continuous-improvement
-description: "Reflect on the current session, analyze observations for patterns, and show instinct status. Runs on-demand to save tokens."
----
-
-# /continuous-improvement
-
-Run this when you want to reflect and learn — not every session. Three steps in order.
-
-## Step 1: Reflect
-
-Generate a reflection for this session based on what happened:
-
-```
-## Reflection — [Date]
-- What worked:
-- What failed:
-- What I'd do differently:
-- Rule to add:
-- Iteration — Next best recommendations (ranked, top 3):
-  1. <primary — strongest next move>
-  2. <alternative — different angle>
-  3. <alternative — smaller/larger scope>
-```
-
-If there's a "Rule to add", create an instinct YAML file with 0.6 starting confidence in the project's instinct directory.
-
-The "Iteration — Next best recommendations" field is the Law 6 handoff. List the **top 3 ranked** core-development moves — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest; #2 and #3 are alternatives the user can pivot to. NOT git steps (commit, push, PR), NOT verification re-runs, NOT deploy actions — those belong in the end-of-run summary.
-
-Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
-
-Rules: always exactly 3 distinct directions, not padding. If fewer real moves exist, fill remaining slots with `None — goal met from this angle.` If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
-
-## Step 2: Analyze Observations
-
-Check `~/.claude/instincts/` for the current project (detect via git root → SHA-256 first 12 chars).
-
-Look at `~/.claude/instincts/<hash>/observations.jsonl`. If 20+ lines exist:
-
-1. Read the last 500 lines
-2. Read existing instinct `*.yaml` files (project + global)
-3. Detect patterns:
-   - User corrections → "don't do X" instincts
-   - Error→fix sequences → "when X fails, try Y"
-   - Repeated workflows (3+ times) → "for X, do A→B→C"
-   - Tool preferences → "use tool Y for task X"
-4. Create/update instinct YAML files
-5. Be conservative: only create instincts for 3+ observations of the same pattern
-
-If fewer than 20 observations, skip analysis and note the count.
-
-### Multi-Agent Analysis (500+ observations)
-
-When observation backlog is large, parallelize:
-- **Agent 1:** User corrections + error→fix patterns
-- **Agent 2:** Repeated workflows + tool preferences
-- **Agent 3:** Cross-reference existing instincts for updates
-
-Merge results and deduplicate before writing YAML files.
-
-## Step 3: Show Status
-
-Display all instincts for the current project + global:
-
-```
-=== continuous-improvement ===
-
-## Level: [CAPTURE | ANALYZE | SUGGEST | AUTO-APPLY]
-
-## Session Reflection
-- What worked: [from this session]
-- What failed: [from this session]
-- What I'd do differently: [from this session]
-- Rule to add: [captured as instinct]
-- Iteration — Next best recommendations (ranked, top 3):
-  1. [primary core-development move]
-  2. [alternative angle]
-  3. [alternative scope]
-
-## Learning
-  NEW  [instinct-id]        [domain]  [confidence]  (from reflection)
-   ↑   [instinct-id]        [domain]  [old]→[new]   (+N observations)
-
-## Instincts — [project-name] ([hash])
-  ● [0.85] instinct-id       domain   auto-apply
-  ◐ [0.60] instinct-id       domain   suggest
-  ○ [0.35] instinct-id       domain   silent
-
-## Instincts — global
-  ● [0.90] instinct-id       domain   auto-apply
-
-## Next
-- Keep working — hooks capture automatically
-- System auto-levels as instincts gain confidence
-```
-
-If no instincts or observations exist yet, explain this is expected — the system is in CAPTURE level and will create instincts after 20+ observations accumulate.
-
-## Subcommands
-
-### `/continuous-improvement weekly`
-
-Set up a weekly analysis schedule:
-1. Create a cron/loop schedule that runs `/continuous-improvement analyze` every 7 days
-2. Confirm the schedule to the user
-3. Show next scheduled run date
-
-### `/continuous-improvement always-on`
-
-Toggle always-on mode for the current project:
-1. Find project hash
-2. Create/update `~/.claude/instincts/<hash>/config.yaml` with `always_on: true|false`
-3. Confirm the change
-
-**Default is off** — observations accumulate silently, analysis only runs when you ask.
+---
+name: continuous-improvement
+description: "Reflect on the current session, analyze observations for patterns, and show instinct status. Runs on-demand to save tokens."
+---
+
+# /continuous-improvement
+
+Run this when you want to reflect and learn — not every session. Three steps in order.
+
+## Step 1: Reflect
+
+Generate a reflection for this session based on what happened:
+
+```
+## Reflection — [Date]
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary — strongest next move>
+  2. <alternative — different angle>
+  3. <alternative — smaller/larger scope>
+```
+
+If there's a "Rule to add", create an instinct YAML file with 0.6 starting confidence in the project's instinct directory.
+
+The "Iteration — Next best recommendations" field is the Law 6 handoff. List the **top 3 ranked** core-development moves — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest; #2 and #3 are alternatives the user can pivot to. NOT git steps (commit, push, PR), NOT verification re-runs, NOT deploy actions — those belong in the end-of-run summary.
+
+Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
+
+Rules: always exactly 3 distinct directions, not padding. If fewer real moves exist, fill remaining slots with `None — goal met from this angle.` If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
+
+## Step 2: Analyze Observations
+
+Check `~/.claude/instincts/` for the current project (detect via git root → SHA-256 first 12 chars).
+
+Look at `~/.claude/instincts/<hash>/observations.jsonl`. If 20+ lines exist:
+
+1. Read the last 500 lines
+2. Read existing instinct `*.yaml` files (project + global)
+3. Detect patterns:
+   - User corrections → "don't do X" instincts
+   - Error→fix sequences → "when X fails, try Y"
+   - Repeated workflows (3+ times) → "for X, do A→B→C"
+   - Tool preferences → "use tool Y for task X"
+4. Create/update instinct YAML files
+5. Be conservative: only create instincts for 3+ observations of the same pattern
+
+If fewer than 20 observations, skip analysis and note the count.
+
+### Multi-Agent Analysis (500+ observations)
+
+When observation backlog is large, parallelize:
+- **Agent 1:** User corrections + error→fix patterns
+- **Agent 2:** Repeated workflows + tool preferences
+- **Agent 3:** Cross-reference existing instincts for updates
+
+Merge results and deduplicate before writing YAML files.
+
+## Step 3: Show Status
+
+Display all instincts for the current project + global:
+
+```
+=== continuous-improvement ===
+
+## Level: [CAPTURE | ANALYZE | SUGGEST | AUTO-APPLY]
+
+## Session Reflection
+- What worked: [from this session]
+- What failed: [from this session]
+- What I'd do differently: [from this session]
+- Rule to add: [captured as instinct]
+- Iteration — Next best recommendations (ranked, top 3):
+  1. [primary core-development move]
+  2. [alternative angle]
+  3. [alternative scope]
+
+## Learning
+  NEW  [instinct-id]        [domain]  [confidence]  (from reflection)
+   ↑   [instinct-id]        [domain]  [old]→[new]   (+N observations)
+
+## Instincts — [project-name] ([hash])
+  ● [0.85] instinct-id       domain   auto-apply
+  ◐ [0.60] instinct-id       domain   suggest
+  ○ [0.35] instinct-id       domain   silent
+
+## Instincts — global
+  ● [0.90] instinct-id       domain   auto-apply
+
+## Next
+- Keep working — hooks capture automatically
+- System auto-levels as instincts gain confidence
+```
+
+If no instincts or observations exist yet, explain this is expected — the system is in CAPTURE level and will create instincts after 20+ observations accumulate.
+
+## Subcommands
+
+### `/continuous-improvement weekly`
+
+Set up a weekly analysis schedule:
+1. Create a cron/loop schedule that runs `/continuous-improvement analyze` every 7 days
+2. Confirm the schedule to the user
+3. Show next scheduled run date
+
+### `/continuous-improvement always-on`
+
+Toggle always-on mode for the current project:
+1. Find project hash
+2. Create/update `~/.claude/instincts/<hash>/config.yaml` with `always_on: true|false`
+3. Confirm the change
+
+**Default is off** — observations accumulate silently, analysis only runs when you ask.