@hopla/claude-setup 1.17.1 → 2.1.1

package/cli.js

@@ -4,12 +4,17 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import readline from "readline";
+import { execSync } from "child_process";
 
 const FORCE = process.argv.includes("--force");
 const UNINSTALL = process.argv.includes("--uninstall");
 const MIGRATE = process.argv.includes("--migrate");
 const VERSION = process.argv.includes("--version") || process.argv.includes("-v");
 const DRY_RUN = process.argv.includes("--dry-run");
+const STATUS = process.argv.includes("status");
+const JSON_OUT = process.argv.includes("--json");
+const SETUP_STATUSLINE = process.argv.includes("--setup-statusline");
+const REMOVE_STATUSLINE = process.argv.includes("--remove-statusline");
 
 if (VERSION) {
     const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));
@@ -24,6 +29,10 @@ const HOOKS_DIR = path.join(CLAUDE_DIR, "hooks");
 const AGENTS_DIR = path.join(CLAUDE_DIR, "agents");
 const PLUGINS_DIR = path.join(CLAUDE_DIR, "plugins");
 const MARKETPLACE_CACHE = path.join(PLUGINS_DIR, "marketplaces", "hopla-marketplace");
+const STATUSLINE_SCRIPT = path.join(MARKETPLACE_CACHE, "hooks", "statusline.js");
+// Substring used to identify a statusLine block managed by this plugin.
+// Survives manual renames of the marketplace as long as users keep "hopla" in the path.
+const STATUSLINE_MARKER = "hopla-marketplace";
 const SETTINGS_FILES = [
     path.join(CLAUDE_DIR, "settings.json"),
     path.join(CLAUDE_DIR, "settings.local.json"),
@@ -52,8 +61,9 @@ function safeRm(target, opts = {}) {
 
 // Atomic write: stage to a tmp file and rename over the target.
 // Protects ~/.claude/settings.json from corruption if the process crashes mid-write.
-function safeWrite(target, content) {
-    if (DRY_RUN) return;
+// Exported for testing — when imported as a library, callers can pass dryRun explicitly.
+export function safeWrite(target, content, { dryRun = DRY_RUN } = {}) {
+    if (dryRun) return;
     const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
     try {
         fs.writeFileSync(tmp, content);
@@ -91,7 +101,8 @@ function logRemoved(label) {
 // missing. Warns (and returns null) when the file exists but is not valid JSON
 // — previously these failures were silently swallowed, causing cleanup and
 // permission updates to skip with no signal to the user.
-function parseSettingsFile(settingsPath) {
+// Exported for unit testing.
+export function parseSettingsFile(settingsPath) {
     if (!fs.existsSync(settingsPath)) return null;
     try {
         return JSON.parse(fs.readFileSync(settingsPath, "utf8"));
@@ -144,6 +155,23 @@ const LEGACY_HOOK_COMMANDS = [
     "session-prime.js",
 ];
 
+// Guide files the pre-plugin CLI (≤ v1.11.x) copied to ~/.claude/commands/guides/.
+// The plugin now ships them via commands/guides/, namespaced as /hopla:guides:<name>,
+// so the user-level copies show up as duplicates in autocomplete (no "(hopla)" suffix).
+// Cleanup removes only files whose name matches a plugin-shipped guide, leaving any
+// custom user guides in ~/.claude/commands/guides/ untouched.
+const LEGACY_GUIDE_FILES = [
+    "ai-optimized-codebase.md",
+    "data-audit.md",
+    "hooks-reference.md",
+    "mcp-integration.md",
+    "remote-coding.md",
+    "review-checklist.md",
+    "scaling-beyond-engineering.md",
+    "validation-pyramid.md",
+    "write-skill.md",
+];
+
 // Agents installed directly by v1.11.0 and v1.12.0 (no hopla- prefix)
 // Must be cleaned up so the plugin-provided versions are the only source of truth
 const LEGACY_AGENT_FILES = [
@@ -188,6 +216,26 @@ function removeLegacyFiles() {
         }
     }
 
+    // Legacy guide duplicates in ~/.claude/commands/guides/ (pre-plugin CLI).
+    // Only remove files matching a guide the plugin currently ships; preserve
+    // any custom user-created guides in the same directory.
+    const legacyGuidesDir = path.join(COMMANDS_DIR, "guides");
+    if (fs.existsSync(legacyGuidesDir)) {
+        for (const guideFile of LEGACY_GUIDE_FILES) {
+            const guidePath = path.join(legacyGuidesDir, guideFile);
+            if (fs.existsSync(guidePath)) {
+                safeRm(guidePath);
+                removed.push(`~/.claude/commands/guides/${guideFile}`);
+            }
+        }
+        if (!DRY_RUN) {
+            try {
+                const remaining = fs.readdirSync(legacyGuidesDir);
+                if (remaining.length === 0) fs.rmSync(legacyGuidesDir, { recursive: true });
+            } catch { /* ignore */ }
+        }
+    }
+
     // hopla-* skills
     if (fs.existsSync(SKILLS_DIR)) {
         for (const entry of fs.readdirSync(SKILLS_DIR)) {
@@ -369,6 +417,11 @@ async function uninstall() {
         logRemoved(item);
     }
 
+    const statuslineRemoved = removeStatuslineFromSettings();
+    for (const item of statuslineRemoved) {
+        logRemoved(item);
+    }
+
     log(`\n${GREEN}${BOLD}Done!${RESET} ${DRY_RUN ? "Dry-run complete — no files were changed." : "CLI-managed files removed."}\n`);
 
     if (pluginActive) {
@@ -422,6 +475,82 @@ async function setupPermissions() {
     log(`  ${GREEN}✓${RESET}  Permissions configured.\n`);
 }
 
+async function setupStatusline() {
+    log(`\n${BOLD}@hopla/claude-setup${RESET} — Setup statusline${dryTag()}\n`);
+
+    if (!fs.existsSync(STATUSLINE_SCRIPT)) {
+        log(`${RED}✕${RESET}  Plugin not detected at ${STATUSLINE_SCRIPT}`);
+        log(`   Install the plugin first inside Claude Code:`);
+        log(`   ${CYAN}/plugin marketplace add HOPLAtools/claude-setup${RESET}`);
+        log(`   ${CYAN}/plugin install hopla@hopla-marketplace${RESET}\n`);
+        process.exit(1);
+    }
+
+    const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+    let settings = parseSettingsFile(settingsPath);
+    if (!settings) {
+        if (fs.existsSync(settingsPath)) {
+            log(`  ${YELLOW}↷${RESET}  Skipped — settings.json is not valid JSON. Fix it and re-run.\n`);
+            return;
+        }
+        settings = {};
+    }
+
+    const command = `node ${STATUSLINE_SCRIPT}`;
+    const newBlock = { type: "command", command };
+
+    const existing = settings.statusLine;
+    if (existing && typeof existing === "object") {
+        const isOurs = typeof existing.command === "string" && existing.command.includes(STATUSLINE_MARKER);
+        if (isOurs && existing.command === command) {
+            log(`${GREEN}✓${RESET}  Statusline already configured (idempotent — no changes).\n`);
+            return;
+        }
+        if (!isOurs) {
+            log(`  ${YELLOW}⚠${RESET}  Existing statusLine points elsewhere:`);
+            log(`     ${existing.command || JSON.stringify(existing)}`);
+            const ok = await confirm(`  Overwrite with Hopla statusline? (y/N) `);
+            if (!ok) {
+                log(`  ${YELLOW}↷${RESET}  Kept existing statusLine. No changes.\n`);
+                return;
+            }
+        }
+    }
+
+    settings.statusLine = newBlock;
+    safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    log(`  ${GREEN}✓${RESET}  ${DRY_RUN ? "Would write" : "Wrote"} statusLine to ~/.claude/settings.json:`);
+    log(`     ${CYAN}${command}${RESET}\n`);
+}
+
+function removeStatuslineFromSettings() {
+    const removed = [];
+    const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+    const settings = parseSettingsFile(settingsPath);
+    if (!settings || !settings.statusLine) return removed;
+
+    const cmd = settings.statusLine.command;
+    if (typeof cmd === "string" && cmd.includes(STATUSLINE_MARKER)) {
+        delete settings.statusLine;
+        safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+        removed.push(`statusLine from settings.json`);
+    }
+    return removed;
+}
+
+async function removeStatusline() {
+    log(`\n${BOLD}@hopla/claude-setup${RESET} — Remove statusline${dryTag()}\n`);
+    const removed = removeStatuslineFromSettings();
+    if (removed.length === 0) {
+        log(`${GREEN}✓${RESET}  No Hopla statusline found. Nothing to remove.\n`);
+        return;
+    }
+    for (const item of removed) {
+        logRemoved(item);
+    }
+    log("");
+}
+
 async function install() {
     log(`\n${BOLD}@hopla/claude-setup${RESET} — Global Rules Setup${dryTag()}\n`);
 
@@ -453,8 +582,159 @@ async function install() {
     await setupPermissions();
 }
 
-const run = UNINSTALL ? uninstall : (MIGRATE ? migrate : install);
-run().catch((err) => {
-    console.error("Failed:", err.message);
-    process.exit(1);
-});
+// =====================================================================
+// status — read-only inspection of a project's .agents/ workflow state
+// =====================================================================
+
+// Lists *.md files (and *.draft.md) in a directory. Returns [] if missing
+// or unreadable. Sorted alphabetically for stable output.
+function listMarkdownFiles(dir) {
+    if (!fs.existsSync(dir)) return [];
+    try {
+        return fs.readdirSync(dir)
+            .filter((f) => f.endsWith(".md") && !f.startsWith("."))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+// Best-effort git inspection — silently degrades when git is unavailable
+// or the cwd is not inside a repo. The status command must never fail
+// because of git.
+function readGitState(cwd) {
+    const exec = (cmd) => {
+        try {
+            return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        } catch {
+            return null;
+        }
+    };
+    const insideRepo = exec("git rev-parse --is-inside-work-tree");
+    if (insideRepo !== "true") return { in_repo: false };
+    const branch = exec("git rev-parse --abbrev-ref HEAD");
+    const statusShort = exec("git status --short");
+    const uncommitted = statusShort ? statusShort.split("\n").filter(Boolean).length : 0;
+    return {
+        in_repo: true,
+        branch: branch || "(detached)",
+        uncommitted,
+    };
+}
+
+function readWorkflowState(cwd) {
+    const agentsDir = path.join(cwd, ".agents");
+    const present = fs.existsSync(agentsDir);
+
+    const plansDir = path.join(agentsDir, "plans");
+    const allPlanFiles = listMarkdownFiles(plansDir);
+    const draft = allPlanFiles.filter((f) => f.endsWith(".draft.md"));
+    const active = allPlanFiles.filter((f) => !f.endsWith(".draft.md"));
+
+    return {
+        agents_dir_present: present,
+        plans: {
+            draft,
+            active,
+            done: listMarkdownFiles(path.join(plansDir, "done")),
+            backlog: listMarkdownFiles(path.join(plansDir, "backlog")),
+        },
+        specs: listMarkdownFiles(path.join(agentsDir, "specs")),
+        code_reviews: listMarkdownFiles(path.join(agentsDir, "code-reviews")),
+        execution_reports: listMarkdownFiles(path.join(agentsDir, "execution-reports")),
+        system_reviews: listMarkdownFiles(path.join(agentsDir, "system-reviews")),
+        rca: listMarkdownFiles(path.join(agentsDir, "rca")),
+        audits: listMarkdownFiles(path.join(agentsDir, "audits")),
+    };
+}
+
+function suggestNext(state) {
+    if (!state.agents_dir_present) {
+        return "No .agents/ found — run /hopla:init-project to scaffold the workflow.";
+    }
+    if (state.plans.draft.length > 0) {
+        return `Plan in draft (${state.plans.draft[0]}) — run /hopla:review-plan or finalize it.`;
+    }
+    if (state.plans.active.length > 0) {
+        const plan = state.plans.active[0];
+        const baseName = plan.replace(/\.md$/, "");
+        const hasReport = state.execution_reports.some((r) => r.includes(baseName));
+        const hasReview = state.code_reviews.some((r) => r.includes(baseName));
+        if (!hasReview) return `Active plan (${plan}) — execute it or run code-review skill on changes.`;
+        if (!hasReport) return `Active plan (${plan}) reviewed — run execution-report skill.`;
+        return `Active plan (${plan}) reviewed and reported — consider /hopla:archive or /hopla:system-review.`;
+    }
+    if (state.code_reviews.length > 0) {
+        return `Pending code reviews — run /hopla:code-review-fix on them.`;
+    }
+    return "Workflow clean — start with /hopla:plan-feature.";
+}
+
+function status() {
+    const cwd = process.cwd();
+    const git = readGitState(cwd);
+    const workflow = readWorkflowState(cwd);
+    const next = suggestNext(workflow);
+
+    if (JSON_OUT) {
+        process.stdout.write(JSON.stringify({ cwd, git, ...workflow, next }, null, 2) + "\n");
+        return;
+    }
+
+    log(`\n${BOLD}@hopla/claude-setup${RESET} — status (${cwd})\n`);
+
+    if (git.in_repo) {
+        log(`${CYAN}Git:${RESET}`);
+        log(`  Branch:       ${git.branch}`);
+        log(`  Uncommitted:  ${git.uncommitted} ${git.uncommitted === 1 ? "file" : "files"}`);
+        log("");
+    } else {
+        log(`${YELLOW}Not inside a git repository.${RESET}\n`);
+    }
+
+    if (!workflow.agents_dir_present) {
+        log(`${YELLOW}No .agents/ directory found.${RESET}`);
+        log(`Run ${CYAN}/hopla:init-project${RESET} to scaffold it.\n`);
+        log(`${BOLD}Suggested next:${RESET} ${next}\n`);
+        return;
+    }
+
+    log(`${CYAN}Plans:${RESET}`);
+    log(`  Draft (${workflow.plans.draft.length}):    ${workflow.plans.draft.join(", ") || "—"}`);
+    log(`  Active (${workflow.plans.active.length}):   ${workflow.plans.active.join(", ") || "—"}`);
+    log(`  Done (${workflow.plans.done.length}):     ${workflow.plans.done.join(", ") || "—"}`);
+    log(`  Backlog (${workflow.plans.backlog.length}):  ${workflow.plans.backlog.join(", ") || "—"}`);
+    log("");
+
+    log(`${CYAN}Other artifacts:${RESET}`);
+    log(`  Specs:               ${workflow.specs.length}`);
+    log(`  Code reviews:        ${workflow.code_reviews.length}`);
+    log(`  Execution reports:   ${workflow.execution_reports.length}`);
+    log(`  System reviews:      ${workflow.system_reviews.length}`);
+    log(`  RCAs:                ${workflow.rca.length}`);
+    log(`  Audits:              ${workflow.audits.length}`);
+    log("");
+
+    log(`${BOLD}Suggested next:${RESET} ${next}\n`);
+}
+
+const run = STATUS
+    ? async () => status()
+    : SETUP_STATUSLINE
+    ? setupStatusline
+    : REMOVE_STATUSLINE
+    ? removeStatusline
+    : (UNINSTALL ? uninstall : (MIGRATE ? migrate : install));
+
+// Only invoke the dispatcher when this file is executed directly (e.g. via
+// `node cli.js` or the npm bin). When the file is imported as a library
+// (tests), skip — tests call the exported helpers themselves.
+import { pathToFileURL } from "url";
+const isMainModule = process.argv[1]
+    && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+    run().catch((err) => {
+        console.error("Failed:", err.message);
+        process.exit(1);
+    });
+}

package/commands/archive.md

@@ -0,0 +1,137 @@
+---
+description: Archive a completed plan — fold its delta-specs into canonical specs and move artifacts to archive locations
+argument-hint: "<plan-file-path>"
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+Close the lifecycle of a completed plan: fold its proposed requirement changes into the canonical specs, move the plan and design files to their archive locations, and leave the project in a clean post-feature state.
+
+> Use this command **after** `/hopla:execute` has finished, code-review and execution-report skills have run, and changes are committed (or staged for the merge commit). The command does not write code — it only updates docs and moves files.
+
+## Step 0: Locate Inputs
+
+The first argument `$1` should be the path to the completed plan (e.g. `.agents/plans/add-auth.md`). If the user did not pass a path:
+
+1. Run `node ~/.claude/plugins/marketplaces/hopla-marketplace/cli.js status` — or `claude-setup status` if installed via npm — to list active plans.
+2. Ask the user which one to archive.
+
+Derive the **feature slug** from the filename (e.g. `add-auth.md` → `add-auth`).
+
+Then look for related artifacts:
+
+| Artifact | Expected path |
+|---|---|
+| Plan | `$1` (e.g. `.agents/plans/add-auth.md`) |
+| Design spec | `.agents/specs/<slug>.md` or `.agents/specs/YYYY-MM-DD-<slug>.md` (latest match) |
+| Code review | `.agents/code-reviews/<slug>.md` (ephemeral — do NOT preserve) |
+| Execution report | `.agents/execution-reports/<slug>.md` (preserve) |
+| System review | `.agents/system-reviews/<slug>-review.md` (preserve) |
+
+If the design spec is missing, that's OK — many features start from `/hopla:plan-feature` directly without a brainstorm step. Skip the spec-merge phase.
+
+## Step 1: Read the Spec's Requirements Delta (if any)
+
+If a design spec exists at `.agents/specs/<slug>.md`, read it and look for a `## Requirements Delta` section with subsections:
+
+```markdown
+## Requirements Delta
+
+### ADDED Requirements
+- REQ-AUTH-002: 2FA enrollment
+  - Scenario: enabling 2FA — Given the user is authenticated, When they enable 2FA, Then ...
+
+### MODIFIED Requirements
+- REQ-AUTH-001: User login (replaces previous version)
+  - Now includes 2FA challenge step when the account has 2FA enabled.
+
+### REMOVED Requirements
+- REQ-AUTH-003: SMS-only fallback (deprecated)
+```
+
+If no `## Requirements Delta` section exists, the spec is informational only — skip to Step 4 (archive moves).
+
+## Step 2: Locate Canonical Specs
+
+Canonical specs live at `.agents/specs/canonical/<domain>.md` (one file per domain — e.g. `auth.md`, `payments.md`, `ui.md`). They represent the **current behavior of the system**.
+
+For each ADDED / MODIFIED / REMOVED requirement, determine which canonical file it belongs to. The domain is usually inferable from the requirement ID prefix (`REQ-AUTH-*` → `auth.md`) or from the project's directory structure.
+
+If `.agents/specs/canonical/` does not exist:
+- Ask the user: "No canonical specs directory found. Should I create `.agents/specs/canonical/` and start it with the requirements from this change?"
+- If yes, create `.agents/specs/canonical/<domain>.md` for each domain touched and treat ALL requirements from this change as initial content (no merge needed — bootstrap mode).
+
+## Step 3: Propose the Merge Diff (human approval required)
+
+For each affected canonical file, build the proposed new content **in memory**:
+
+- For each entry under `### ADDED Requirements` → append the requirement (with its scenarios) to the canonical file under `## Requirements`.
+- For each entry under `### MODIFIED Requirements` → find the requirement by ID in the canonical file and **replace** its body with the new version. If the ID is not found, treat as ADDED and warn the user.
+- For each entry under `### REMOVED Requirements` → find the requirement by ID and **delete** its block (heading + body until the next `### ` heading or end of section).
+
+Show the user a summary:
+
+```
+## Archive plan: <slug>
+
+Canonical specs to update:
+  .agents/specs/canonical/auth.md
+    + ADDED:    REQ-AUTH-002 (2FA enrollment)
+    ~ MODIFIED: REQ-AUTH-001 (User login — now requires 2FA step)
+    - REMOVED:  REQ-AUTH-003 (SMS-only fallback)
+
+Files to move:
+  .agents/plans/<slug>.md             → .agents/plans/done/<slug>.md
+  .agents/specs/<slug>.md             → .agents/specs/archived/<slug>.md
+  .agents/code-reviews/<slug>.md      → DELETE (ephemeral)
+
+Files to keep in place:
+  .agents/execution-reports/<slug>.md
+  .agents/system-reviews/<slug>-review.md
+```
+
+Then ask:
+> "Apply these changes? (yes / show diff / cancel)"
+
+- **show diff:** print a unified diff of each canonical file (before vs after) so the user can review the exact merge before approval.
+- **cancel:** abort with no changes.
+- **yes:** proceed to Step 4.
+
+## Step 4: Apply the Changes
+
+Only after explicit `yes`:
+
+1. Write each updated canonical spec file via the Edit tool. Never overwrite blindly — always anchor on the requirement ID heading.
+2. Move (or copy + delete) the plan: `.agents/plans/<slug>.md` → `.agents/plans/done/<slug>.md`. If `.agents/plans/done/` does not exist, create it.
+3. If a design spec exists, move `.agents/specs/<slug>.md` → `.agents/specs/archived/<slug>.md`. Create `archived/` if missing.
+4. Delete the ephemeral code review at `.agents/code-reviews/<slug>.md` (if it exists). Per project policy, code reviews are working state and not committed.
+5. Leave `execution-reports/` and `system-reviews/` untouched — they are part of the cross-session learning loop.
+
+## Step 5: Confirm and Suggest Next
+
+Print a final summary:
+
+```
+✅ Archived <slug>
+
+Canonical specs updated:
+  - .agents/specs/canonical/auth.md (3 changes)
+
+Files moved:
+  - plans/<slug>.md → plans/done/<slug>.md
+  - specs/<slug>.md → specs/archived/<slug>.md
+
+Files removed:
+  - code-reviews/<slug>.md (ephemeral)
+```
+
+Suggest:
+> "Archive complete. The canonical specs now reflect this change. Consider running the `git` skill (say 'commit') to capture the merged specs, and `/hopla:system-review` if you want to mine this implementation for process improvements."
+
+## Notes & Edge Cases
+
+- **No spec, no Requirements Delta:** Step 4 still runs (file moves) but no canonical specs are updated. This is the common case for tactical fixes that do not change documented requirements.
+- **Canonical bootstrap:** if `.agents/specs/canonical/` is empty, this command may be the first to populate it. Use the change's specs as initial content (treat all ADDED entries as initial requirements, ignore MODIFIED/REMOVED — there is nothing to modify).
+- **Conflicting modifications:** if the same REQ-* ID is modified by two parallel plans, the later archive wins. Surface this in the diff with a `⚠ conflict` marker so the user can reconcile manually before approving.
+- **Reverting an archive:** this command is one-way. To revert, restore from git history (`git restore`).
+- **Do not auto-commit:** per global rules, never run `git commit` or `git push` from this command. After archiving, suggest the `git` skill.

package/commands/execute.md

@@ -143,7 +143,7 @@ If the user requests changes that are NOT in the plan during execution:
 
 After all tasks are complete, run **Levels 1–7** from `commands/guides/validation-pyramid.md` (same repo). Do not skip levels. Do not proceed if a level fails.
 
-Use the exact commands from the plan's **Validation Checklist**. If not specified, read `CLAUDE.md` "Development Commands" to find the correct commands.
+Use the exact commands from the plan's **Validation Checklist**. If not specified, read `AGENTS.md` (or `CLAUDE.md` as fallback) "Development Commands" to find the correct commands.
 
 Level 5 triggers the `code-review` skill (not a slash command). Level 6 is the file-drift check specific to plan execution. Level 7 surfaces items for human verification.
 

package/commands/guides/ai-optimized-codebase.md

@@ -1,3 +1,7 @@
+---
+description: Guide for structuring codebases to be navigable and editable by AI agents (file layout, naming, comments, doc placement).
+---
+
 # AI-Optimized Codebase Guide
 
 ## When to Use This Guide
@@ -51,7 +55,7 @@ logger.info("order_created", {
 - Types serve as contracts that AI can read and follow
 
 ### 5. Comprehensive Validation Commands
-Include in CLAUDE.md:
+Include in AGENTS.md (or CLAUDE.md for legacy projects):
 ```markdown
 ## Development Commands
 - `npm run lint` — ESLint check

package/commands/guides/data-audit.md

@@ -1,3 +1,7 @@
+---
+description: Reference for auditing existing data sources (schema, value semantics, null cases, derived value propagation) before implementing data-consuming features.
+---
+
 # Guide: Data Audit and Value Semantics
 
 Use this guide when a feature reads from, calculates with, or references existing data or code patterns. Applies during planning (full audit) and execution (verification of documented findings).

package/commands/guides/hooks-reference.md

@@ -1,3 +1,7 @@
+---
+description: Reference for creating Claude Code hooks — event names, matchers, payload shapes, exit code contracts, and stdout conventions.
+---
+
 # Hooks Reference Guide
 
 ## When to Use This Guide

package/commands/guides/mcp-integration.md

@@ -1,3 +1,7 @@
+---
+description: Reference for integrating Model Context Protocol (MCP) servers with Claude Code projects — config, auth, and common patterns.
+---
+
 # MCP Integration Guide
 
 ## When to Use This Guide
@@ -6,7 +10,7 @@ Reference this guide when planning features that involve external tools or servi
 ## MCP in the PIV Loop
 
 ### During Planning (`/hopla:plan-feature`)
-- Check what MCP servers are configured (listed in CLAUDE.md under "MCP Servers")
+- Check what MCP servers are configured (listed in AGENTS.md or CLAUDE.md under "MCP Servers")
 - For each external integration point, specify which MCP tool to use
 - Example: "Step 3: Use Playwright MCP to verify the component renders correctly"
 
@@ -28,5 +32,5 @@ Reference this guide when planning features that involve external tools or servi
 
 ## Adding MCP to Your Project
 1. Configure MCP servers in `.claude/settings.json` or `.claude/settings.local.json`
-2. List them in your project's CLAUDE.md under the "MCP Servers" section
+2. List them in your project's AGENTS.md (or CLAUDE.md) under the "MCP Servers" section
 3. Pre-approve permissions in settings to avoid repeated prompts

package/commands/guides/remote-coding.md

@@ -1,3 +1,7 @@
+---
+description: Forward-looking guide for remote agentic coding workflows — long-running agents, async coordination, sandboxed execution.
+---
+
 # Remote Agentic Coding Guide (Future)
 
 ## When to Use This Guide
@@ -59,7 +63,7 @@ jobs:
 
 ## Prerequisites
 - HOPLA commands installed in the repo (.claude/commands/)
-- CLAUDE.md configured for the project
+- AGENTS.md (or CLAUDE.md) configured for the project
 - GitHub Actions enabled
 - Claude Code API key in GitHub Secrets
 

package/commands/guides/review-checklist.md

@@ -1,3 +1,7 @@
+---
+description: Guide for creating a project-specific code review checklist (.agents/guides/review-checklist.md) consumed by the code-review skill.
+---
+
 # Guide: Creating a Project-Specific Review Checklist
 
 Use this guide to create a `.agents/guides/review-checklist.md` file in your project with code review checks specific to your tech stack, domain, and known anti-patterns. The the `code-review` skill command loads this file automatically when it exists, applying your custom checks alongside the standard review categories.

package/commands/guides/scaling-beyond-engineering.md

@@ -1,3 +1,7 @@
+---
+description: Guide for applying agentic coding workflows beyond software engineering — operations, content, research, customer support.
+---
+
 # Scaling Agentic Coding Beyond Engineering
 
 ## When to Use This Guide

package/commands/guides/validation-pyramid.md

@@ -1,10 +1,14 @@
+---
+description: Shared reference for the full validation sequence (lint, types, tests, code review, manual smoke). Used by execute, validate, and verify.
+---
+
 # Validation Pyramid
 
 Shared reference for the full validation sequence. Callers (`commands/execute.md`, `commands/validate.md`, `skills/verify/SKILL.md`, plus plans' `Validation Checklist`) pick the levels that apply to their scope.
 
 Run levels **in order**. Do not skip a level. Do not proceed if a level fails — fix it first.
 
-Commands below are generic examples; use the exact commands from the project's `CLAUDE.md` "Development Commands" section or the plan's checklist.
+Commands below are generic examples; use the exact commands from the project's `AGENTS.md` (or `CLAUDE.md` as fallback) "Development Commands" section or the plan's checklist.
 
 ## Level 1 — Lint & Format
 

package/commands/guides/write-skill.md

@@ -1,3 +1,7 @@
+---
+description: Internal guide for authoring new skills in this plugin — SKILL.md frontmatter, naming, triggers, organization, when to add triggers override.
+---
+
 # Writing Skills Guide (Internal)
 
 ## When to Use This Guide