@hopla/claude-setup 1.17.0 → 1.19.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "hopla",
       "description": "Agentic coding system: PIV loop, TDD, debugging, brainstorming, subagent execution, and team workflows",
-      "version": "1.17.0",
+      "version": "1.19.0",
       "source": "./",
       "author": {
         "name": "Hopla Tools",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hopla",
   "description": "Agentic coding system for Claude Code: PIV loop (Plan → Implement → Validate), TDD, debugging, brainstorming, subagent execution, and team workflows",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"

package/README.md

@@ -101,6 +101,8 @@ Removes `~/.claude/CLAUDE.md` plus legacy `hopla-*` files from older installs.
 | `claude-setup --force` | Install without prompts |
 | `claude-setup --migrate` | Remove legacy CLI-installed duplicates only |
 | `claude-setup --uninstall` | Remove global rules + legacy files |
+| `claude-setup status` | Read-only inspection of the current project's `.agents/` workflow state (plans, specs, reviews, suggested next step) |
+| `claude-setup status --json` | Same as above, JSON output for agents to parse |
 | `claude-setup --dry-run` | Preview changes without touching disk (composes with other flags) |
 | `claude-setup --version` | Print package version |
 
@@ -140,14 +142,17 @@ Skills and commands use short names in source (e.g., `prime`, `execute`, `git`).
 
 ## How It Works — Layered Context
 
-The system uses three levels of CLAUDE.md, each scoped differently:
+The system uses three levels of agent context, each scoped differently:
 
 ```
 ~/.claude/CLAUDE.md        ← Machine-level (installed by CLI)
     └── applies to ALL projects on this machine
 
-CLAUDE.md (project root)   ← Project-level (created with /hopla:init-project)
-    └── applies to THIS project only
+AGENTS.md (project root)   ← Project-level (created with /hopla:init-project)
+    └── canonical, tool-agnostic rules — applies to THIS project only
+    └── readable by Cursor, Copilot, Continue, Codex, and Claude Code
+CLAUDE.md (project root)   ← thin alias that imports AGENTS.md via @AGENTS.md
+    └── kept so Claude Code's auto-discovery finds the rules
 
 .claude/CLAUDE.local.md    ← Local overrides (personal, gitignored)
     └── your personal tweaks, not shared with team
@@ -155,7 +160,7 @@ CLAUDE.md (project root)   ← Project-level (created with /hopla:init-project)
 
 **Machine-level rules** cover: language preferences, tech defaults, autonomy behavior, context management tips.
 
-**Project-level rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, task-specific reference guides.
+**Project-level rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, task-specific reference guides. Stored in `AGENTS.md` so the project stays portable across AI assistants. The `CLAUDE.md` stub at the project root is auto-generated and only contains `@AGENTS.md` so Claude Code inlines the canonical file — never edit the stub directly.
 
 **Local overrides** cover: personal preferences that differ from the team (e.g., verbose logging, different editor settings).
 
@@ -207,7 +212,7 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 
 | Command | Description |
 |---|---|
-| `init-project` | Read PRD, recommend stack, create CLAUDE.md and .agents/ structure |
+| `init-project` | Read PRD, recommend stack, create AGENTS.md (+ CLAUDE.md alias) and .agents/ structure |
 | `create-prd` | Create a Product Requirements Document through guided questions |
 | `plan-feature` | Research codebase and create a structured implementation plan |
 | `review-plan` | Review a plan before execution — get a summary and approve |
@@ -215,6 +220,7 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 | `validate` | Run the validation pyramid: lint → types → tests → integration |
 | `code-review-fix` | Fix issues found in a code review report |
 | `rca` | Root Cause Analysis — investigate a bug and generate an RCA doc |
+| `archive` | Close the lifecycle of a completed plan: fold its delta-specs into canonical specs, move artifacts to archive locations |
 | `guide` | 4D Framework walkthrough for non-technical users |
 | `system-review` | Analyze implementation against plan to find process improvements |
 
@@ -238,6 +244,7 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 | `migration` | "migrate", "upgrade", "switch from X to Y", "major version bump" |
 | `subagent-execution` | "use subagents", plans with 5+ tasks |
 | `parallel-dispatch` | "run in parallel", "parallelize this", independent tasks |
+| `hook-audit` | "audit hook", "check hook", "hook review" — mechanical static audit of `src/hooks/use*.ts` files (memoization, stale-id guards, error-match strictness, cache+dedup integrity) |
 
 **Hooks** — Run automatically:
 
@@ -292,6 +299,7 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 "review the code"         → code-review skill runs automatically
 /hopla:code-review-fix    → fix issues found
 "generate the report"     → execution-report skill documents what was built
+/hopla:archive            → fold delta-specs into canonical specs, move plan to done/, drop ephemeral code-review (opt-in — when delta-specs were declared)
 "commit this"             → git skill handles commits and PRs
                            (cleanup including worktree removal happens post-merge)
 ```
@@ -434,12 +442,15 @@ Issues and contributions welcome: https://github.com/HOPLAtools/claude-setup/iss
 ```
 project/
 ├── PRD.md                         ← Product scope (from /hopla:create-prd)
-├── CLAUDE.md                      ← Project rules and stack (from /hopla:init-project)
+├── AGENTS.md                      ← Canonical project rules (tool-agnostic, from /hopla:init-project)
+├── CLAUDE.md                      ← Thin alias: contains @AGENTS.md so Claude Code auto-loads the rules
 ├── .agents/
 │   ├── plans/                     ← Implementation plans (commit)
-│   │   ├── done/                  ← Archived plans after system-review (commit)
+│   │   ├── done/                  ← Plans archived by /hopla:archive (commit)
 │   │   └── backlog/               ← Deferred ideas from Scope Guard (commit)
 │   ├── specs/                     ← Design specs from brainstorming (commit)
+│   │   ├── canonical/             ← "Current behavior" specs by domain — populated incrementally by /hopla:archive (commit; opt-in)
+│   │   └── archived/              ← Completed design specs moved here by /hopla:archive (commit)
 │   ├── guides/                    ← On-demand reference guides (commit)
 │   ├── rca/                       ← Root cause analysis docs (commit)
 │   ├── execution-reports/         ← Post-implementation reports (commit)

package/agents/system-reviewer.md

@@ -22,7 +22,7 @@ You are a System Reviewer. Your job is to analyze how well the implementation ma
 
 | Pattern | Action |
 |---------|--------|
-| Issue appears in ALL features | Update CLAUDE.md |
+| Issue appears in ALL features | Update AGENTS.md (or CLAUDE.md) |
 | Issue appears in one CLASS of features | Update the specific command |
 | Same manual step repeated 3+ times | Create a new command |
 | Plan ambiguous at same point twice | Update planning command |
@@ -47,7 +47,7 @@ Save to `.agents/system-reviews/[feature-name].md`:
 
 ## Recommended Improvements
 
-### CLAUDE.md Updates
+### AGENTS.md / CLAUDE.md Updates
 - [Specific changes to project rules]
 
 ### Command Updates
@@ -65,12 +65,12 @@ Save to `.agents/system-reviews/[feature-name].md`:
 ## Recommendation Tracking
 
 For each recommendation from the 2 most recent system reviews:
-- Was it applied? (Check CLAUDE.md, commands, guides for the suggested change)
+- Was it applied? (Check AGENTS.md / CLAUDE.md, commands, guides for the suggested change)
 - If not applied, why? (Forgotten, deprioritized, or superseded?)
 - **Recurring unapplied recommendations indicate a broken feedback loop** — escalate these by listing them first in "Recommended Improvements" with a ⚠️ prefix
 
 ## Next Step
 
 After the review is saved, suggest:
-> "System review saved to `.agents/system-reviews/[feature]-review.md`. Plan archived. If recurring recommendations were found, consider applying them before the next feature — they represent known gaps in the process."
+> "System review saved to `.agents/system-reviews/[feature]-review.md`. To close the lifecycle of this plan, run `/hopla:archive <plan-path>` — it will fold any delta-specs into the canonical specs and move the plan to `done/`. If recurring recommendations were found, consider applying them before the next feature — they represent known gaps in the process."
 ```

package/cli.js

@@ -4,12 +4,15 @@ 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");
 
 if (VERSION) {
     const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"));
@@ -453,7 +456,145 @@ async function install() {
     await setupPermissions();
 }
 
-const run = UNINSTALL ? uninstall : (MIGRATE ? migrate : install);
+// =====================================================================
+// 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()
+    : (UNINSTALL ? uninstall : (MIGRATE ? migrate : install));
 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

@@ -51,7 +51,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/mcp-integration.md

@@ -6,7 +6,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 +28,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

@@ -59,7 +59,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/validation-pyramid.md

@@ -4,7 +4,7 @@ Shared reference for the full validation sequence. Callers (`commands/execute.md
 
 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/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