@hopla/claude-setup 1.17.1 → 2.1.1

package/commands/init-project.md

@@ -1,22 +1,24 @@
 ---
-description: Initialize a new project with a CLAUDE.md and .agents/ structure
+description: Initialize a new project with AGENTS.md (+ CLAUDE.md alias) and .agents/ structure
 ---
 
 > **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
 
-Set up the Layer 1 planning foundation for this project: a project-specific `CLAUDE.md` with rules and architecture decisions, plus the `.agents/` directory structure.
+Set up the Layer 1 planning foundation for this project: a project-specific `AGENTS.md` with rules and architecture decisions (the canonical, tool-agnostic source of truth), a thin `CLAUDE.md` alias so Claude Code auto-loads the rules, plus the `.agents/` directory structure.
 
-> Layer 1 = Global Rules (~/.claude/CLAUDE.md) + Project Rules (CLAUDE.md) + PRD
+> Layer 1 = Global Rules (~/.claude/CLAUDE.md) + Project Rules (AGENTS.md, with CLAUDE.md alias) + PRD
+
+> **Why AGENTS.md as the canonical file:** AGENTS.md is the tool-agnostic convention adopted by most AI coding assistants (Cursor, Copilot, Continue, Codex, etc.). Keeping a thin CLAUDE.md alias preserves Claude Code's auto-discovery without duplicating content. If the project already has an AGENTS.md or CLAUDE.md, treat that as the canonical file and only create the missing alias.
 
 ## Step 1: Read Existing Context
 
 Before asking anything, check what already exists:
-- Any existing `CLAUDE.md` at project root
+- Any existing `AGENTS.md` or `CLAUDE.md` at project root (AGENTS.md takes precedence as canonical; CLAUDE.md without AGENTS.md is treated as canonical until migrated)
 - `README.md` — extract stack and project overview
 - `package.json`, `pyproject.toml`, or equivalent — extract stack and scripts
 - Entry point files (`main.py`, `src/main.ts`, `app.py`, etc.)
 
-If a `CLAUDE.md` already exists at the project root, tell the user and ask if they want to update it or start fresh.
+If an `AGENTS.md` or `CLAUDE.md` already exists at the project root, tell the user and ask if they want to update it or start fresh. If only `CLAUDE.md` exists (legacy layout), offer to migrate: rename to `AGENTS.md` and create a thin `CLAUDE.md` alias.
 
 ## Step 2: Understand the Product
 
@@ -166,11 +168,23 @@ Once the stack is confirmed, ask only what's NOT already known from the PRD or c
 2. **Project description** — skip if already in PRD
 3. **Reference Guides** (optional) — Are there specific task types that need step-by-step guidance? (e.g. "When adding a page", "When creating an API route"). If none, skip — guides can always be added later.
 
-## Step 5: Generate CLAUDE.md
+## Step 5: Generate AGENTS.md (+ CLAUDE.md alias)
+
+Save the full project rules to `AGENTS.md` at the project root (canonical, tool-agnostic source of truth). Then create a thin `CLAUDE.md` alias so Claude Code auto-discovers the rules without duplicating content.
+
+**`CLAUDE.md` alias contents (always identical, regardless of stack):**
+
+```markdown
+# [Project Name] — Project Rules
+
+The canonical project rules live in [`AGENTS.md`](./AGENTS.md). This file is a thin alias kept for Claude Code's auto-discovery.
+
+@AGENTS.md
+```
 
-Save to `CLAUDE.md` at the project root. Use this structure:
+> The `@AGENTS.md` directive instructs Claude Code to inline the AGENTS.md contents into context. Other AI assistants read AGENTS.md directly.
 
-**For default stack projects**, use these pre-filled values:
+**`AGENTS.md` contents — for default stack projects**, use these pre-filled values:
 
 ```markdown
 # [Project Name] — Development Rules
@@ -315,7 +329,9 @@ Read: `.agents/guides/[guide-name].md`
 This guide covers: [bullet list]
 ```
 
-**For custom stack projects**, fill in the values collected during Step 2.2 following the same structure.
+**For custom stack projects**, fill in the values collected during Step 2.2 / Step 3.1 following the same structure.
+
+> Both default and custom flows write to `AGENTS.md`. The `CLAUDE.md` alias is the same in both cases.
 
 ## Step 5.5: Generate Reference Guides
 
@@ -407,7 +423,7 @@ After implementing, verify:
 
 **Important:** Guides must contain concrete, project-specific information — not generic advice. If the user's answers don't have enough detail for a section, ask a follow-up before writing the guide.
 
-Also update the `CLAUDE.md` Section 7 (Task-Specific Reference Guides) to reference each guide created:
+Also update the `AGENTS.md` Section 7 (Task-Specific Reference Guides) to reference each guide created:
 
 ```markdown
 ## 7. Task-Specific Reference Guides
@@ -428,9 +444,11 @@ Create the following directories (with `.gitkeep` where needed):
 ```
 .agents/
 ├── plans/               <- /hopla:plan-feature saves here (commit)
-│   ├── done/            <- /hopla:system-review archives completed plans here (commit)
+│   ├── done/            <- /hopla:archive moves completed plans here (commit)
 │   └── backlog/         <- /hopla:execute Scope Guard defers ideas here (commit)
 ├── specs/               <- brainstorm skill saves design docs here (commit)
+│   ├── canonical/       <- canonical "current behavior" specs by domain (commit; populated incrementally by /hopla:archive)
+│   └── archived/        <- /hopla:archive moves completed design specs here (commit)
 ├── guides/              <- on-demand reference guides (commit)
 ├── rca/                 <- /hopla:rca saves root cause analysis docs here (commit)
 ├── execution-reports/   <- the `execution-report` skill saves here (commit — needed for cross-session learning)
@@ -439,6 +457,8 @@ Create the following directories (with `.gitkeep` where needed):
 └── code-reviews/        <- the `code-review` skill saves here (do NOT commit — ephemeral, consumed by code-review-fix)
 ```
 
+> **`specs/canonical/` is opt-in.** It is populated only as `/hopla:archive` is used. Until the first archive runs, the directory simply stays empty. Projects that prefer to keep all behavior knowledge in code + AGENTS.md can ignore it.
+
 **Policy — `audits/` vs `code-reviews/`:**
 
 - `code-reviews/` is **ephemeral working state**. Every run overwrites/adds files; `code-review-fix` consumes them and they become stale fast. Never commit.
@@ -475,13 +495,14 @@ If yes, create `.claude/commands/validate.md`.
 
 ## Step 8: Confirm and Save
 
-Show the draft `CLAUDE.md` to the user and ask:
+Show the draft `AGENTS.md` to the user and ask:
 > "Does this accurately reflect the project's rules? Any corrections before I save it?"
 
 Once confirmed:
-1. Save `CLAUDE.md` to the project root
-2. Create `.agents/` directory structure
-3. Update `.gitignore`
-4. If no PRD exists yet, tell the user: "Project initialized. Run `/hopla:create-prd` next to define the product scope, or `/hopla:plan-feature` to start planning a feature."
+1. Save `AGENTS.md` to the project root
+2. Create `CLAUDE.md` at the project root with the standard alias content (see Step 5) — skip if a meaningful `CLAUDE.md` already exists; in that case ask the user whether to overwrite with the alias stub or leave it untouched
+3. Create `.agents/` directory structure
+4. Update `.gitignore`
+5. If no PRD exists yet, tell the user: "Project initialized. Run `/hopla:create-prd` next to define the product scope, or `/hopla:plan-feature` to start planning a feature."
    If a PRD already exists, tell the user: "Project initialized. Run `/hopla:plan-feature` to start planning the first feature."
-5. Suggest running the `git` skill (say "commit") to save everything
+6. Suggest running the `git` skill (say "commit") to save everything

package/commands/plan-feature.md

@@ -104,7 +104,7 @@ Based on research, define:
   - **Roles / permissions / multi-tenant access:** `admin` / `member` / `viewer` / `owner`, internal vs external users, buyer vs seller. Anything where access or behavior depends on who the actor is.
   - **Color-coded UI states with semantic meaning:** green=ok / amber=warning / red=error, or any project-specific color → state mapping. The mapping itself is a domain assumption.
   - **Business rules:** "when X happens, then Y is forbidden / required / triggered". Any conditional behavior that encodes a policy decision rather than a technical constraint.
-  - **Project-specific vocabulary harvest:** read the project's root `CLAUDE.md`. If a `Domain`, `Glossary`, `Vocabulary`, or similar section exists, harvest its terms. Any of those terms appearing in the user's request triggers the heuristic. **Fallback when no such section exists:** rely on the category-based triggers above.
+  - **Project-specific vocabulary harvest:** read the project's root `AGENTS.md` (or `CLAUDE.md` as fallback). If a `Domain`, `Glossary`, `Vocabulary`, or similar section exists, harvest its terms. Any of those terms appearing in the user's request triggers the heuristic. **Fallback when no such section exists:** rely on the category-based triggers above.
   - **Sentinel check:** if the planner wrote sentences in the plan that describe behavior using nouns or adjectives that are NOT in the user's verbatim request, those are inferred meanings — surface them as Domain Assumptions.
   - When uncertain, err on inclusion: a `Domain Assumptions` subsection with 1-2 bullets is cheaper than a misaligned implementation surfaced during manual smoke.
 
@@ -144,7 +144,7 @@ Key files the executing agent must read before starting:
 
 ## Domain Assumptions (if applicable)
 
-> Include this section when the feature uses domain vocabulary (entity states, lifecycle, grades/tiers, roles, color-coded states, business rules, or any project-specific terms in the project's CLAUDE.md). **Skip entirely** (do not write "N/A") when no domain semantics are involved.
+> Include this section when the feature uses domain vocabulary (entity states, lifecycle, grades/tiers, roles, color-coded states, business rules, or any project-specific terms in the project's AGENTS.md or CLAUDE.md). **Skip entirely** (do not write "N/A") when no domain semantics are involved.
 
 Each bullet is a user-confirmable assumption the planner made about meaning, behavior, or business rule. The user MUST confirm or correct each bullet BEFORE execution begins.
 
@@ -152,6 +152,23 @@ Each bullet is a user-confirmable assumption the planner made about meaning, beh
 - [Assumption 2 — derived/computed value: e.g., "The `expired` badge shows when `expiresAt < today` AND `status != 'archived'` — confirm formula."]
 - [Assumption 3 — grade / tier / business rule: e.g., "Tier B users have read access to the audit log but cannot export it — confirm boundary."]
 
+## Requirements Delta (if applicable)
+
+> Include this section when the feature **changes documented system behavior** — adds, modifies, or removes a user-visible capability or business rule. Pure refactors, performance fixes, and infrastructure changes can omit this section entirely (do NOT write "N/A"). The delta is consumed by `/hopla:archive` to fold the change into `.agents/specs/canonical/`. If the project does not yet maintain canonical specs, this section is still valuable as a structured summary for the executing agent and reviewers.
+>
+> When a corresponding `.agents/specs/<feature>.md` already includes a `## Requirements Delta` (created by the `brainstorm` skill), reference it here instead of duplicating: `See spec: .agents/specs/<feature>.md`.
+
+### ADDED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title>
+  - Scenario: <name> — Given <state>, When <action>, Then <outcome>
+
+### MODIFIED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (replaces previous version)
+  - <description of how the requirement changes>
+
+### REMOVED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (deprecated — reason)
+
 ## Implementation Tasks
 
 > All fields are required. Use `N/A` if a field does not apply — never leave a field blank.
@@ -245,7 +262,7 @@ Before saving the draft, review the plan against these criteria:
 
 - [ ] Every task has a specific file path (no vague "update the component")
 - [ ] Every task has: Action, File, Pattern, Details, Gotcha, Validate — no field left empty
-- [ ] Validation Checklist has **exact commands** from `CLAUDE.md` or `package.json` (not vague "run lint")
+- [ ] Validation Checklist has **exact commands** from `AGENTS.md` / `CLAUDE.md` or `package.json` (not vague "run lint")
 - [ ] The plan is complete enough that another agent can execute it without this conversation
 - [ ] No ambiguous requirements left unresolved
 - [ ] **Data audit complete:** All data sources audited per `.agents/guides/data-audit.md`, with all findings (null cases, value semantics, derived value propagation) documented in Context References and Gotchas
@@ -263,6 +280,7 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **N+1 query check:** For every task that writes database queries or API calls, verify: is any call inside a loop? Could it be batched? Are there duplicate existence checks before mutations?
 - [ ] **UX iteration budget declared:** If the feature touches UI per the Phase 4 heuristic, the plan includes `Expected UX iterations: N` (with N a positive integer ≥ 1) in Out of Scope or Notes for Executing Agent. If UI is NOT involved, the line is correctly absent (no `N/A`, no empty placeholder).
 - [ ] **Domain Assumptions surfaced:** If the feature uses domain vocabulary per the Phase 4 heuristic, the plan includes a `## Domain Assumptions` subsection BEFORE `## Implementation Tasks`, with each bullet phrased as a user-confirmable statement. If no domain vocabulary is involved, the section is correctly absent (no `N/A`, no empty placeholder).
+- [ ] **Requirements Delta declared (when behavior changes):** If the feature adds, modifies, or removes a user-visible capability or business rule, the plan includes a `## Requirements Delta` subsection with one or more of `### ADDED Requirements`, `### MODIFIED Requirements`, `### REMOVED Requirements`. If the change is a pure refactor/perf/infra fix with no behavior change, the section is correctly absent (no `N/A`, no empty placeholder). Requirement IDs follow the project's `REQ-<DOMAIN>-<NNN>` convention.
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/commands/system-review.md

@@ -22,7 +22,8 @@ ls .agents/system-reviews/
 
 Look for a file that matches the feature name derived from **$1** (the plan filename). If a matching review exists:
 - Skip Steps 1–6
-- Go directly to **Step 7** to archive the plan
+- Notify the user: "✅ A system review already exists at `.agents/system-reviews/[feature]-review.md`. If you haven't closed the lifecycle yet, run `/hopla:archive $1` to fold delta-specs into canonical specs and move the plan to `done/`."
+- Exit.
 
 If no matching review exists, continue with Step 1.
 
@@ -90,7 +91,7 @@ For each bug category in this implementation, check if the same category appeare
 
 ### Unresolved Improvements
 Cross-reference improvement suggestions from previous reviews. If a suggestion was made before and NOT yet applied:
-- Check if the suggested CLAUDE.md update was made
+- Check if the suggested AGENTS.md / CLAUDE.md update was made
 - Check if the suggested command update was made
 - Check if the suggested guide was created
 - List any improvements that were suggested 2+ reviews ago and are still pending
@@ -99,7 +100,7 @@ Cross-reference improvement suggestions from previous reviews. If a suggestion w
 
 Suggest specific actions based on patterns found:
 
-- **CLAUDE.md updates** — universal patterns or anti-patterns to document
+- **AGENTS.md updates** (or `CLAUDE.md` for legacy projects) — universal patterns or anti-patterns to document
 - **Plan command updates** — instructions that need clarification or missing steps
 - **Execute command updates** — steps to add to the execution checklist
 - **New commands** — manual processes repeated 3+ times that should be automated
@@ -136,13 +137,13 @@ root_cause: [unclear plan | missing context | missing validation | other]
 
 ### Pattern Compliance
 - [ ] Followed codebase architecture
-- [ ] Used patterns documented in CLAUDE.md
+- [ ] Used patterns documented in AGENTS.md / CLAUDE.md
 - [ ] Applied testing patterns correctly
 - [ ] Met validation requirements
 
 ### System Improvement Actions
 
-**Update CLAUDE.md:**
+**Update AGENTS.md (or CLAUDE.md for legacy projects):**
 - [ ] [specific addition or change]
 
 **Update Plan Command:**
@@ -175,20 +176,15 @@ After the analysis, use this to prioritize actions:
 
 | Pattern | Action |
 |---|---|
-| Issue happens across ALL features | Update CLAUDE.md |
+| Issue happens across ALL features | Update AGENTS.md (or CLAUDE.md) |
 | Issue happens for a CLASS of features | Update on-demand reference guide or command |
 | Same manual step done 3+ times | Create a new command |
 | Plan was ambiguous in the same spot twice | Update plan-feature command |
 | First time seeing this issue | Note it, don't over-engineer yet |
 
-## Step 7: Archive the Plan
+## Step 7: Suggest Next
 
-Move the completed plan to the archive folder:
+Do **not** move or delete any files. The lifecycle closure (moving the plan to `done/`, folding delta-specs into canonical specs, deleting the ephemeral code review) is the responsibility of `/hopla:archive`.
 
-```bash
-mkdir -p .agents/plans/done
-mv "$1" .agents/plans/done/
-```
-
-Then notify the user:
-> "✅ System review saved to `.agents/system-reviews/[feature]-review.md`. Plan archived to `.agents/plans/done/[plan-name].md` — the active plans folder is now clean."
+Notify the user:
+> "✅ System review saved to `.agents/system-reviews/[feature]-review.md`. To close the lifecycle of this plan, run `/hopla:archive $1` — it will fold any delta-specs into the canonical specs and move the plan to `done/`."

package/commands/validate.md

@@ -16,7 +16,7 @@ If a `.claude/commands/validate.md` exists at the project root, use the commands
 
 Execute levels **1–4** from `commands/guides/validation-pyramid.md` (same repo). Do not skip levels. Do not proceed if a level fails — fix it first.
 
-Use the exact commands from the project's `CLAUDE.md` "Development Commands" section. If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
+Use the exact commands from the project's `AGENTS.md` (or `CLAUDE.md` as fallback) "Development Commands" section. If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
 
 ## Step 3: Summary Report
 

package/hooks/prompt-route.js

@@ -1,94 +1,242 @@
 #!/usr/bin/env node
 // UserPromptSubmit hook: scan the user's prompt for skill keywords and inject
-// a short routing hint. Keeps skill suggestions visible mid-session even after
-// compaction or long conversations where the initial skill list gets buried.
-
-const SKILL_TRIGGERS = [
-    {
-        skill: "git",
-        patterns: [
-            /\bcommit\b/i,
-            /save (my |the )?changes/i,
-            /\bcreate (a )?pr\b/i,
-            /pull request/i,
-            /\bpush\b/i,
-            /merge request/i,
-        ],
-    },
-    {
-        skill: "worktree",
-        patterns: [
-            /\bworktree\b/i,
-            /isolated branch/i,
-            /parallel (feature|development)/i,
-        ],
-    },
-    {
-        skill: "prime",
-        patterns: [
-            /\borient(\b| yourself)/i,
-            /catch me up/i,
-            /get context/i,
-            /load project/i,
-            /what is this project/i,
-        ],
-    },
-    {
-        skill: "brainstorm",
-        patterns: [
-            /\bbrainstorm\b/i,
-            /explore (options|approaches)/i,
-            /how should we/i,
-            /trade[- ]offs?/i,
-        ],
-    },
-    {
-        skill: "debug",
-        patterns: [
-            /\bbug\b/i,
-            /\berror\b/i,
-            /\bdebug\b/i,
-            /not working/i,
-            /\bfailing\b/i,
-            /\bbroken\b/i,
-            /\bno funciona\b/i,
-        ],
-    },
-    {
-        skill: "verify",
-        patterns: [
-            /\bverify\b/i,
-            /all tests? pass/i,
-            /\blisto\b/i,
-            /\bterminé\b/i,
-            /\bya está\b/i,
-        ],
-    },
-    {
-        skill: "code-review",
-        patterns: [
-            /review (the |my )?code/i,
-            /code review/i,
-            /audit (the |my )?code/i,
-        ],
-    },
-    {
-        skill: "execution-report",
-        patterns: [
-            /generate (the |a )?report/i,
-            /document what was done/i,
-            /execution report/i,
-        ],
-    },
-    {
-        skill: "tdd",
-        patterns: [
-            /\btdd\b/i,
-            /test[- ]first/i,
-            /red[- ]green[- ]refactor/i,
-        ],
-    },
-];
+// a short routing hint. Reads skill catalog from disk at runtime — no
+// hardcoded skill list — so adding/removing/renaming a skill needs no edit here.
+//
+// Matching strategy (hybrid):
+//   1. If a SKILL.md declares `triggers: [regex, ...]` in its frontmatter,
+//      use those patterns literally.
+//   2. Otherwise auto-derive patterns from the skill name (word-boundary,
+//      case-insensitive) and the first significant words of the description.
+//
+// Skill discovery walks `../skills/` recursively so nested skills
+// (e.g. skills/guides/<name>/SKILL.md) participate without code changes.
+
+import fs from "fs";
+import path from "path";
+
+const SKILLS_DIR = path.join(import.meta.dirname, "..", "skills");
+const STOPWORDS = new Set([
+    "use", "when", "with", "that", "this", "from", "into", "your", "have",
+    "also", "user", "only", "before", "after", "during", "than", "such",
+    "more", "less", "most", "least", "some", "many", "much", "still", "just",
+    "what", "which", "would", "could", "should", "needs", "need", "make",
+    "made", "does", "done", "doing", "wants", "want", "next", "previous",
+    "very", "really", "always", "never", "must", "may", "might", "shall",
+    "trigger", "triggers", "phrase", "phrases", "skill", "skills", "do",
+    "not", "the", "and", "for", "are", "was", "were", "but", "any", "all",
+]);
+
+// Walk skills/ recursively. Return [{ name, descriptors, triggers, path }].
+// Each entry already exposes either a literal triggers list (from frontmatter)
+// or a derived list (from name + description tokens).
+function loadSkillCatalog(skillsRoot) {
+    if (!fs.existsSync(skillsRoot)) return [];
+    const catalog = [];
+
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const candidate = path.join(fullPath, "SKILL.md");
+                if (fs.existsSync(candidate)) {
+                    const parsed = parseSkillFrontmatter(candidate);
+                    if (parsed) catalog.push(parsed);
+                }
+                // Continue walking — skills may be nested under sub-directories.
+                walk(fullPath);
+            }
+        }
+    }
+
+    walk(skillsRoot);
+    return catalog;
+}
+
+// Extract `name`, `description`, optional `triggers` from a SKILL.md frontmatter.
+// Tolerant parser — handles double/single-quoted scalars and YAML-style array
+// `triggers: [...]` on a single line or with each item on its own line.
+function parseSkillFrontmatter(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    } catch {
+        return null;
+    }
+    if (!content.startsWith("---")) return null;
+    const end = content.indexOf("\n---", 3);
+    if (end === -1) return null;
+    const block = content.slice(3, end);
+
+    const data = {};
+    const lines = block.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!m) { i++; continue; }
+        const key = m[1];
+        let rest = m[2];
+
+        if (key === "triggers") {
+            // Inline form: triggers: [a, b]   or block form across lines.
+            const triggers = parseYamlArray(rest, lines, i);
+            data.triggers = triggers.values;
+            i = triggers.nextIndex;
+            continue;
+        }
+
+        // Strip surrounding quotes if any.
+        if ((rest.startsWith('"') && rest.endsWith('"')) ||
+            (rest.startsWith("'") && rest.endsWith("'"))) {
+            rest = rest.slice(1, -1);
+        }
+        data[key] = rest;
+        i++;
+    }
+
+    if (!data.name) {
+        // Fall back to the parent directory name when frontmatter omits it.
+        data.name = path.basename(path.dirname(filePath));
+    }
+
+    return {
+        name: data.name,
+        description: data.description || "",
+        triggers: Array.isArray(data.triggers) ? data.triggers : null,
+        path: filePath,
+    };
+}
+
+// Parses either `[a, b, c]` on the same line as `triggers:`, or a block form:
+//   triggers:
+//     - "regex one"
+//     - "regex two"
+// Returns { values, nextIndex } so the caller knows where to resume scanning.
+function parseYamlArray(inlineRest, lines, currentIndex) {
+    const inline = inlineRest.trim();
+    if (inline.startsWith("[") && inline.endsWith("]")) {
+        const body = inline.slice(1, -1).trim();
+        if (!body) return { values: [], nextIndex: currentIndex + 1 };
+        const values = splitYamlInlineList(body);
+        return { values, nextIndex: currentIndex + 1 };
+    }
+    // Block form
+    const values = [];
+    let j = currentIndex + 1;
+    while (j < lines.length) {
+        const ln = lines[j];
+        const m = ln.match(/^\s*-\s*(.*)$/);
+        if (!m) break;
+        let item = m[1].trim();
+        if ((item.startsWith('"') && item.endsWith('"')) ||
+            (item.startsWith("'") && item.endsWith("'"))) {
+            item = item.slice(1, -1);
+        }
+        values.push(item);
+        j++;
+    }
+    return { values, nextIndex: j };
+}
+
+// Splits `"a, b", c, "d"` respecting double-quoted strings so commas inside
+// quotes don't break the split.
+function splitYamlInlineList(body) {
+    const out = [];
+    let current = "";
+    let inQuote = null;
+    for (let k = 0; k < body.length; k++) {
+        const ch = body[k];
+        if (inQuote) {
+            if (ch === inQuote) {
+                inQuote = null;
+                continue;
+            }
+            current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === ",") {
+            const item = current.trim();
+            if (item) out.push(item);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    const tail = current.trim();
+    if (tail) out.push(tail);
+    return out;
+}
+
+// Build the regex list a skill matches against. When the SKILL.md provides
+// `triggers:`, use those literal patterns. Otherwise auto-derive from:
+//   1. The skill name (case-insensitive, word boundary).
+//   2. Every single-quoted phrase in the description — descriptions in this
+//      project document trigger phrases as `'commit', 'pull request', ...`,
+//      so this captures idiomatic user wording the skill name alone misses.
+//   3. The first 3 significant tokens of the description (length ≥ 4, not
+//      a stopword) — a fallback when no quoted phrases exist.
+function buildPatterns(skill) {
+    if (skill.triggers && skill.triggers.length > 0) {
+        return skill.triggers.map(toRegex).filter(Boolean);
+    }
+    const patterns = [];
+    const description = skill.description || "";
+
+    if (skill.name) {
+        const escaped = skill.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        patterns.push(new RegExp(`\\b${escaped}\\b`, "i"));
+    }
+
+    // Extract single-quoted phrases like 'commit', 'pull request'. Limited to
+    // 12 to bound the per-prompt regex work.
+    const quoted = [...description.matchAll(/'([^']{2,60})'/g)].map((m) => m[1]);
+    const seenPhrase = new Set();
+    for (const phrase of quoted) {
+        const norm = phrase.toLowerCase().trim();
+        if (!norm || seenPhrase.has(norm)) continue;
+        seenPhrase.add(norm);
+        const escaped = norm.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        patterns.push(new RegExp(`\\b${escaped}\\b`, "i"));
+        if (seenPhrase.size >= 12) break;
+    }
+
+    if (seenPhrase.size === 0) {
+        // Fallback: significant tokens.
+        const tokens = description
+            .toLowerCase()
+            .split(/[^a-z0-9-]+/)
+            .filter((t) => t.length >= 4 && !STOPWORDS.has(t));
+        const seenTok = new Set();
+        for (const tok of tokens) {
+            if (seenTok.has(tok)) continue;
+            seenTok.add(tok);
+            const escaped = tok.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            patterns.push(new RegExp(`\\b${escaped}\\b`, "i"));
+            if (seenTok.size >= 3) break;
+        }
+    }
+    return patterns;
+}
+
+function toRegex(source) {
+    if (!source || typeof source !== "string") return null;
+    try {
+        return new RegExp(source, "i");
+    } catch {
+        return null;
+    }
+}
 
 async function main() {
     const chunks = [];
@@ -106,9 +254,14 @@ async function main() {
     const prompt = (input.prompt || "").slice(0, 4000);
     if (!prompt) process.exit(0);
 
+    const catalog = loadSkillCatalog(SKILLS_DIR);
+    if (catalog.length === 0) process.exit(0);
+
     const matched = [];
-    for (const { skill, patterns } of SKILL_TRIGGERS) {
-        if (patterns.some((p) => p.test(prompt))) matched.push(skill);
+    for (const skill of catalog) {
+        const patterns = buildPatterns(skill);
+        if (patterns.length === 0) continue;
+        if (patterns.some((p) => p.test(prompt))) matched.push(skill.name);
     }
 
     if (matched.length === 0) process.exit(0);

package/hooks/session-prime.js

@@ -97,11 +97,19 @@ async function main() {
         }
     }
 
-    // CLAUDE.md excerpt — cut at a natural boundary, not a fixed line count
+    // Project rules excerpt — prefer canonical AGENTS.md; fall back to CLAUDE.md.
+    // Both paths reuse the same excerpt helper since the format is identical Markdown.
+    const agentsMdPath = path.join(process.cwd(), "AGENTS.md");
     const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
-    if (fs.existsSync(claudeMdPath)) {
-        const excerpt = excerptClaudeMd(fs.readFileSync(claudeMdPath, "utf8"));
-        lines.push(`Project rules (CLAUDE.md excerpt):\n${excerpt}`);
+    let rulesPath = null;
+    if (fs.existsSync(agentsMdPath)) {
+        rulesPath = { path: agentsMdPath, label: "AGENTS.md" };
+    } else if (fs.existsSync(claudeMdPath)) {
+        rulesPath = { path: claudeMdPath, label: "CLAUDE.md" };
+    }
+    if (rulesPath) {
+        const excerpt = excerptClaudeMd(fs.readFileSync(rulesPath.path, "utf8"));
+        lines.push(`Project rules (${rulesPath.label} excerpt):\n${excerpt}`);
     }
 
     // Auto-discover available skills

package/hooks/statusline.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 // Hopla statusline: branch · worktree indicator · uncommitted count · active plan.
-// Wire it up by adding to ~/.claude/settings.json:
-//   "statusLine": {
-//     "type": "command",
-//     "command": "node ~/.claude/plugins/marketplaces/hopla-marketplace/hooks/statusline.js"
-//   }
+// Wire it up by running:
+//   hopla-claude-setup --setup-statusline
+// Remove with: hopla-claude-setup --remove-statusline
 
 import { execSync } from "child_process";
 import fs from "fs";