continuous-improvement 3.1.0 → 3.8.0

package/plugins/continuous-improvement/lib/observe-event.mjs

@@ -0,0 +1,128 @@
+// observe-event.mts — Pure parsers for the Mulahazah observation hook.
+//
+// These functions have NO I/O. They turn raw stdin text and tool input/output
+// payloads into shaped data the entrypoint (src/bin/observe.mts) writes to
+// observations.jsonl. Pure separation lets the unit tests cover schema edge
+// cases (malformed JSON, missing fields, oversized payloads) without ever
+// touching the filesystem or computing project hashes.
+//
+// Truncation budgets match the prior bash/jq behavior to preserve the existing
+// privacy contract: input head ≤500 chars, output head ≤200 chars.
+const INPUT_TRUNCATE = 500;
+const OUTPUT_TRUNCATE = 200;
+/**
+ * Parse the raw JSON stdin payload from a Claude Code PreToolUse/PostToolUse
+ * hook event. Returns null for any unparseable or schema-invalid input —
+ * never throws. Empty/null/array payloads are rejected (the harness only
+ * sends objects).
+ *
+ * Field-name normalisation: Claude Code's PostToolUse payload uses
+ * `tool_response`. Older mocks and some third-party harnesses emit
+ * `tool_output` or `toolOutput`. We accept all three at the boundary and
+ * expose a single `tool_response` field downstream so the discriminator and
+ * `summariseOutput` only have to know one name.
+ */
+export function parseHookPayload(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    if (typeof obj.tool_name !== "string" || obj.tool_name.length === 0) {
+        return null;
+    }
+    const toolResponse = obj.tool_response !== undefined
+        ? obj.tool_response
+        : obj.tool_output !== undefined
+            ? obj.tool_output
+            : obj.toolOutput;
+    return {
+        tool_name: obj.tool_name,
+        session_id: typeof obj.session_id === "string" ? obj.session_id : "",
+        tool_input: obj.tool_input,
+        tool_response: toolResponse,
+    };
+}
+/**
+ * Extract a tool-aware short summary from `tool_input`. Tool-specific cases
+ * cover the high-frequency surfaces the linter/analyser reads (Bash command
+ * head, Edit/Write/Read file_path, Grep/Glob pattern). Unknown tools fall
+ * back to JSON.stringify(input) capped at INPUT_TRUNCATE.
+ *
+ * Returns an empty string when the expected field is missing on a known tool
+ * or when input is null/undefined — never returns "undefined" or "null"
+ * literals to the caller.
+ */
+export function summariseInput(toolName, input) {
+    if (input === null || input === undefined)
+        return "";
+    switch (toolName) {
+        case "Bash": {
+            const cmd = readStringField(input, "command");
+            return cmd === null ? "" : truncate(cmd, INPUT_TRUNCATE);
+        }
+        case "Edit":
+        case "Write":
+        case "Read":
+        case "NotebookEdit": {
+            const path = readStringField(input, "file_path");
+            return path === null ? "" : truncate(path, INPUT_TRUNCATE);
+        }
+        case "Grep":
+        case "Glob": {
+            const pattern = readStringField(input, "pattern");
+            return pattern === null ? "" : truncate(pattern, INPUT_TRUNCATE);
+        }
+        default: {
+            // Unknown tool: stringify input so we record *something* useful for
+            // future analysis. Truncate to keep observations.jsonl row size bounded.
+            let serialised;
+            try {
+                serialised = JSON.stringify(input);
+            }
+            catch {
+                serialised = "";
+            }
+            return truncate(serialised ?? "", INPUT_TRUNCATE);
+        }
+    }
+}
+/**
+ * Extract a short summary from `tool_response`. Strings pass through (capped
+ * at OUTPUT_TRUNCATE); numbers/booleans coerce to string; objects
+ * JSON-stringify. Null/undefined collapse to "".
+ */
+export function summariseOutput(output) {
+    if (output === null || output === undefined)
+        return "";
+    if (typeof output === "string")
+        return truncate(output, OUTPUT_TRUNCATE);
+    if (typeof output === "number" || typeof output === "boolean") {
+        return String(output);
+    }
+    let serialised;
+    try {
+        serialised = JSON.stringify(output);
+    }
+    catch {
+        serialised = "";
+    }
+    return truncate(serialised ?? "", OUTPUT_TRUNCATE);
+}
+function readStringField(input, field) {
+    if (input === null || typeof input !== "object")
+        return null;
+    const value = input[field];
+    return typeof value === "string" ? value : null;
+}
+function truncate(value, max) {
+    return value.length > max ? value.slice(0, max) : value;
+}

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

@@ -0,0 +1,432 @@
+export const PACKAGE_NAME = "continuous-improvement";
+export const VERSION = "3.8.0";
+export const PLUGIN_MODES = ["beginner", "expert"];
+const REPOSITORY_URL = "https://github.com/naimkatiman/continuous-improvement";
+const HOMEPAGE_URL = `${REPOSITORY_URL}#readme`;
+const AUTHOR = {
+    name: "naimkatiman",
+    url: "https://github.com/naimkatiman",
+};
+const KEYWORDS = [
+    "claude-code",
+    "claude-code-skill",
+    "ai-agent",
+    "agent-skill",
+    "ai-discipline",
+    "mulahazah",
+    "instinct",
+    "hooks",
+    "mcp",
+    "mcp-server",
+    "github-action",
+    "transcript-linter",
+];
+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.
+// 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.
+const THIRD_PARTY_COMPANIONS = [
+    {
+        name: "superpowers",
+        description: "Obra's core skills library: TDD, debugging, brainstorming, writing-plans, executing-plans, dispatching-parallel-agents, using-git-worktrees, finishing-a-development-branch, subagent-driven-development, requesting-code-review, receiving-code-review, systematic-debugging, verification-before-completion, writing-skills, using-superpowers. Vendored snapshot at third-party/superpowers/ pinned to upstream SHA f2cbfbe (v5.1.0). Companion to the /superpowers dispatcher in continuous-improvement plugin.",
+        version: "5.1.0",
+        source: "./third-party/superpowers",
+        author: {
+            name: "Jesse Vincent",
+            email: "jesse@fsck.com",
+        },
+        category: "workflow",
+        homepage: "https://github.com/obra/superpowers",
+    },
+    {
+        name: "agent-skills",
+        description: "Addy Osmani's production-grade engineering skills for AI coding agents — 21 skills covering the full software development lifecycle: spec-driven-development, source-driven-development, context-engineering, idea-refine, incremental-implementation, test-driven-development, code-review-and-quality, code-simplification, security-and-hardening, debugging-and-error-recovery, performance-optimization, api-and-interface-design, frontend-ui-engineering, browser-testing-with-devtools, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, git-workflow-and-versioning, planning-and-task-breakdown, shipping-and-launch, using-agent-skills. Vendored snapshot at third-party/addy-agent-skills/ pinned to upstream SHA 742dca5 (v1.0.0).",
+        version: "1.0.0",
+        source: "./third-party/addy-agent-skills",
+        author: {
+            name: "Addy Osmani",
+        },
+        category: "workflow",
+        homepage: "https://github.com/addyosmani/agent-skills",
+    },
+    {
+        name: "ruflo-swarm",
+        description: "Agent teams, swarm coordination, Monitor streams, and worktree isolation. Wraps 4 swarm_* + 8 agent_* MCP tools (12 total) plus 6 topologies (hierarchical, mesh, hierarchical-mesh, ring, star, adaptive). Slash commands /swarm and /watch. Skills swarm-init and monitor-stream. Cherry-picked from ruvnet/ruflo monorepo (the other 31 plugins are explicitly out of scope). Vendored snapshot at third-party/ruflo-swarm/ pinned to upstream SHA addb5cd (v0.2.0). Activation note: assets reference unpinned npx @claude-flow/cli@latest — supply-chain risk inert until installed.",
+        version: "0.2.0",
+        source: "./third-party/ruflo-swarm",
+        author: {
+            name: "ruvnet",
+            url: "https://github.com/ruvnet",
+        },
+        category: "orchestration",
+        homepage: "https://github.com/ruvnet/ruflo",
+    },
+    {
+        name: "oh-my-claudecode",
+        description: "Multi-agent orchestration system for Claude Code — 39 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
+        version: "4.13.6",
+        source: "./third-party/oh-my-claudecode",
+        author: {
+            name: "Yeachan-Heo",
+        },
+        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";
+}
+const BEGINNER_TOOL_ENTRIES = [
+    {
+        name: "ci_status",
+        description: "Show current level, instinct count, and observation count for this project. Good starting point to see what the system has learned.",
+        manifestWhat: "See what the system has learned about your project",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "ci_instincts",
+        description: "List all learned instincts for this project with their confidence levels and behaviors.",
+        manifestWhat: "List all learned behaviors with confidence levels",
+        inputSchema: {
+            type: "object",
+            properties: {
+                min_confidence: {
+                    type: "number",
+                    description: "Minimum confidence to show (default: 0)",
+                    default: 0,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "ci_reflect",
+        description: "Generate a structured reflection for the current session. Provide a summary of what you worked on.",
+        manifestWhat: "Reflect on what you did this session",
+        inputSchema: {
+            type: "object",
+            properties: {
+                summary: {
+                    type: "string",
+                    description: "Brief summary of what was done this session",
+                },
+            },
+            required: ["summary"],
+        },
+    },
+];
+const EXPERT_TOOL_ENTRIES = [
+    {
+        name: "ci_reinforce",
+        description: "Accept or reject an instinct suggestion. Adjusts confidence: +0.15 for accept, -0.1 for reject.",
+        manifestWhat: "Accept or reject instinct suggestions to tune confidence",
+        inputSchema: {
+            type: "object",
+            properties: {
+                instinct_id: { type: "string", description: "The instinct ID to reinforce" },
+                accepted: {
+                    type: "boolean",
+                    description: "true = accept (+0.15), false = reject (-0.1)",
+                },
+            },
+            required: ["instinct_id", "accepted"],
+        },
+    },
+    {
+        name: "ci_create_instinct",
+        description: "Manually create a new instinct with a trigger, body, and starting confidence.",
+        manifestWhat: "Manually create instincts with custom triggers and confidence",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Unique instinct ID (kebab-case)" },
+                trigger: { type: "string", description: "When this instinct applies" },
+                body: { type: "string", description: "The behavior to follow" },
+                confidence: {
+                    type: "number",
+                    description: "Starting confidence 0.0-0.9 (default: 0.6)",
+                    default: 0.6,
+                },
+                domain: {
+                    type: "string",
+                    description: "Domain: workflow|tooling|testing|patterns|code-style",
+                    default: "workflow",
+                },
+                scope: {
+                    type: "string",
+                    description: "Scope: project|global",
+                    default: "project",
+                },
+            },
+            required: ["id", "trigger", "body"],
+        },
+    },
+    {
+        name: "ci_observations",
+        description: "View recent tool call observations captured by hooks.",
+        manifestWhat: "View raw tool call observations captured by hooks",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Number of recent observations to return (default: 20)",
+                    default: 20,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "ci_export",
+        description: "Export all instincts as a JSON array for sharing or backup.",
+        manifestWhat: "Export instincts as JSON for sharing or backup",
+        inputSchema: {
+            type: "object",
+            properties: {
+                scope: {
+                    type: "string",
+                    description: "Which instincts: project|global|all (default: all)",
+                    default: "all",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "ci_import",
+        description: "Import instincts from a JSON array. Skips duplicates by ID.",
+        manifestWhat: "Import instincts from JSON (skip duplicates)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                instincts_json: {
+                    type: "string",
+                    description: "JSON array of instinct objects to import",
+                },
+                scope: {
+                    type: "string",
+                    description: "Import to: project|global (default: project)",
+                    default: "project",
+                },
+            },
+            required: ["instincts_json"],
+        },
+    },
+    {
+        name: "ci_plan_init",
+        description: "Create task_plan.md, findings.md, and progress.md in the project root for persistent file-based planning.",
+        manifestWhat: "Create project-root planning files for persistent task memory",
+        inputSchema: {
+            type: "object",
+            properties: {
+                goal: { type: "string", description: "Goal for the planning workflow" },
+                phases: {
+                    type: "array",
+                    description: "Optional ordered phase names. Defaults to Research, Plan, Execute, Verify, Reflect.",
+                    items: { type: "string" },
+                },
+                force: {
+                    type: "boolean",
+                    description: "Overwrite existing planning files",
+                    default: false,
+                },
+            },
+            required: ["goal"],
+        },
+    },
+    {
+        name: "ci_plan_status",
+        description: "Summarize the status of task_plan.md, findings.md, and progress.md in the project root.",
+        manifestWhat: "Summarize task_plan.md, findings.md, and progress.md status",
+        inputSchema: {
+            type: "object",
+            properties: {
+                include_contents: {
+                    type: "boolean",
+                    description: "Include raw file contents in the response",
+                    default: false,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "ci_dashboard",
+        description: "Visual dashboard showing instinct health, observation stats, confidence distribution, and learning progress.",
+        manifestWhat: "Visual dashboard showing instinct health, confidence distribution, and learning progress",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+        name: "ci_load_pack",
+        description: "Load a starter instinct pack (react, python, go) into the current project.",
+        manifestWhat: "Load starter instinct packs (react, python, go) into the current project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                pack: { type: "string", description: "Pack name: react, python, or go" },
+            },
+            required: ["pack"],
+        },
+    },
+];
+const MODE_METADATA = {
+    beginner: {
+        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four discipline skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default.",
+        hooks: ["PreToolUse", "PostToolUse"],
+        hookDescription: "Silently captures every tool call as observations. Lightweight and non-blocking.",
+    },
+    expert: {
+        description: "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay disciplined and learnings survive context resets.",
+        hooks: ["PreToolUse", "PostToolUse", "SessionStart", "SessionEnd"],
+        hookDescription: "Full hook suite: observation capture + session-level instinct loading and auto-reflection.",
+    },
+};
+function getToolCatalog(mode) {
+    return mode === "expert"
+        ? [...BEGINNER_TOOL_ENTRIES, ...EXPERT_TOOL_ENTRIES]
+        : [...BEGINNER_TOOL_ENTRIES];
+}
+export function getToolDefinitions(mode) {
+    return getToolCatalog(mode).map(({ name, description, inputSchema }) => ({
+        name,
+        description,
+        inputSchema,
+    }));
+}
+export function getToolNames(mode) {
+    return getToolCatalog(mode).map((tool) => tool.name);
+}
+export function getPluginManifest(mode) {
+    const modeMetadata = MODE_METADATA[mode];
+    const mcpServerConfig = {
+        command: "node",
+        args: ["<install-path>/bin/mcp-server.mjs", "--mode", mode],
+    };
+    return {
+        name: PACKAGE_NAME,
+        version: VERSION,
+        mode,
+        description: modeMetadata.description,
+        tools: getToolCatalog(mode).map((tool) => ({
+            name: tool.name,
+            what: tool.manifestWhat,
+        })),
+        setup: {
+            claude_desktop: {
+                mcpServers: {
+                    [PACKAGE_NAME]: mcpServerConfig,
+                },
+            },
+            claude_code: {
+                mcpServers: {
+                    [PACKAGE_NAME]: mcpServerConfig,
+                },
+            },
+        },
+        hooks: {
+            included: [...modeMetadata.hooks],
+            description: modeMetadata.hookDescription,
+        },
+    };
+}
+export function getClaudePluginManifest() {
+    return {
+        name: PACKAGE_NAME,
+        version: VERSION,
+        description: SHARED_PLUGIN_DESCRIPTION,
+        author: AUTHOR,
+        homepage: HOMEPAGE_URL,
+        repository: REPOSITORY_URL,
+        license: "MIT",
+        keywords: [...KEYWORDS],
+    };
+}
+export function getPluginHooksConfig() {
+    const observeCommand = {
+        type: "command",
+        command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
+        timeout: 5,
+    };
+    const sessionCommand = {
+        type: "command",
+        command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session.sh\"",
+        timeout: 5,
+    };
+    const threeSectionCloseCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/three-section-close.mjs\"",
+        timeout: 5,
+    };
+    return {
+        description: "Observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
+        hooks: {
+            PreToolUse: [{ hooks: [observeCommand] }],
+            PostToolUse: [{ hooks: [observeCommand] }],
+            SessionStart: [{ hooks: [sessionCommand] }],
+            SessionEnd: [{ hooks: [sessionCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand] }],
+        },
+    };
+}
+export function getClaudePluginMarketplaceManifest() {
+    return {
+        name: `${PACKAGE_NAME}-dev`,
+        description: "Development marketplace for the Continuous Improvement Claude Code plugin.",
+        owner: {
+            name: AUTHOR.name,
+        },
+        plugins: [
+            {
+                name: PACKAGE_NAME,
+                description: SHARED_PLUGIN_DESCRIPTION,
+                version: VERSION,
+                source: "./",
+                author: {
+                    name: AUTHOR.name,
+                },
+                category: CLAUDE_PLUGIN_CATEGORY,
+                homepage: REPOSITORY_URL,
+            },
+        ],
+    };
+}
+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.",
+        owner: {
+            name: AUTHOR.name,
+        },
+        plugins: [
+            {
+                name: PACKAGE_NAME,
+                description: SHARED_PLUGIN_DESCRIPTION,
+                version: VERSION,
+                source: `./plugins/${PACKAGE_NAME}`,
+                author: {
+                    name: AUTHOR.name,
+                },
+                category: CLAUDE_PLUGIN_CATEGORY,
+                homepage: REPOSITORY_URL,
+            },
+            ...THIRD_PARTY_COMPANIONS,
+            ...extraPlugins,
+        ],
+    };
+}

package/plugins/continuous-improvement/lib/resolve-home-dir.mjs

@@ -0,0 +1,43 @@
+// resolve-home-dir.mts — Single source of truth for the telemetry home dir
+// resolution rule shared by hooks/three-section-close.mjs and bin/hook-stats.mjs.
+//
+// Previously this 20-line function lived in three byte-equivalent copies; this
+// module collapses them. Behavior is unchanged.
+import { homedir } from "node:os";
+/**
+ * Resolve the home directory used to locate `.claude/hook-telemetry/`.
+ *
+ * Contract (AND-semantic opt-out):
+ *   - If BOTH `HOME` and `USERPROFILE` are explicitly set to the empty string
+ *     (set, not merely undefined), return `""`. This is the operator/test
+ *     opt-out signal: telemetry is intentionally disabled.
+ *   - Otherwise return the first truthy value from, in order:
+ *     `process.env.HOME`, `process.env.USERPROFILE`, `os.homedir()`.
+ *   - If none yields a truthy path, return `""`.
+ *
+ * The AND-semantic is deliberate: an OR-semantic would silently disable
+ * telemetry whenever a shell happened to clear one variable while the other
+ * still pointed at a valid path.
+ *
+ * Never throws. `os.homedir()` is wrapped in try/catch because it can throw
+ * in pathological env conditions.
+ */
+export function resolveHomeDir() {
+    const home = process.env.HOME;
+    const userProfile = process.env.USERPROFILE;
+    if (home === "" && userProfile === "")
+        return "";
+    if (home)
+        return home;
+    if (userProfile)
+        return userProfile;
+    try {
+        const fromOs = homedir();
+        if (fromOs)
+            return fromOs;
+    }
+    catch {
+        // os.homedir() can throw in pathological env conditions
+    }
+    return "";
+}

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

@@ -0,0 +1,34 @@
+# Bundled Skills (generated)
+
+> **Do not edit anything in this directory.** It is regenerated by `npm run build`
+> from the source skill files in the repo root (SKILL.md and skills/*.md).
+> Any local edits here will be lost on the next build.
+
+Each skill below declares its own tier via the `tier:` field in its source
+frontmatter. The build groups them into sections; this file is rendered from
+those declarations so the table of contents cannot drift from the actual
+skill set on disk.
+
+## Core skill
+- `continuous-improvement` — Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. On-demand or weekly analysis to save tokens. Supports multi-agent parallel analysis.
+
+## Featured companion
+- `proceed-with-the-recommendation` ⭐ — Orchestrator for all 7 Laws of AI Agent Discipline. Walks an agent-emitted recommendation list top-to-bottom under the 7 Laws — restate, route per item, verify before advancing, reflect at the end, close with the mandatory three-section block. Standalone with inline fallbacks; trigger phrases are matched by the companion hook, not enumerated here.
+
+## Tier 1 — beginner-mode pairing
+- `deploy-receipt` — Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline at the deploy seam. A merge into a branch that auto-deploys is not "done" until the deploy provider reports the merged commit SHA running and a healthcheck endpoint returns 200. Companion to the vendored `finishing-a-development-branch` skill — does not replace it, runs after it for projects on Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, or any other auto-deploy target.
+- `gateguard` — Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Fact-forcing gate that blocks Edit/Write/Bash (including MultiEdit) and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.
+- `para-memory-files` — 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.
+- `tdd-workflow` — Enforces Law 3 (One Thing at a Time) and Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
+- `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
+- `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.
+- `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.
+
+## 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.
+- `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.