@hopla/claude-setup 1.17.1 → 2.1.1

package/.claude-plugin/marketplace.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "hopla-marketplace",
   "description": "Hopla Tools plugin marketplace for Claude Code",
   "owner": {
@@ -9,7 +10,7 @@
     {
       "name": "hopla",
       "description": "Agentic coding system: PIV loop, TDD, debugging, brainstorming, subagent execution, and team workflows",
-      "version": "1.17.1",
+      "version": "2.1.1",
       "source": "./",
       "author": {
         "name": "Hopla Tools",

package/.claude-plugin/plugin.json

@@ -1,13 +1,14 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "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.1",
+  "version": "2.1.1",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"
   },
-  "homepage": "https://github.com/hopla-tools/claude-setup",
-  "repository": "https://github.com/hopla-tools/claude-setup",
+  "homepage": "https://github.com/HOPLAtools/claude-setup#readme",
+  "repository": "https://github.com/HOPLAtools/claude-setup",
   "license": "MIT",
   "keywords": [
     "claude",

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to **@hopla/claude-setup** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [2.1.1] - 2026-05-12
+
+### Fixed
+- `hopla-claude-setup --migrate` and `--uninstall` now clean up legacy guide duplicates left in `~/.claude/commands/guides/` by pre-plugin CLI versions (≤ v1.11.x). Removes only files whose name matches a plugin-shipped guide — custom user guides in the same directory are preserved. Empty `guides/` directories are then removed.
+
+### Notes
+- This addresses the duplicate `/guides:*` entries (marked `(user)`) that appeared alongside `/hopla:guides:*` (marked `(hopla)`) in the slash-command autocomplete after upgrading from a pre-plugin install.
+
+## [2.1.0] - 2026-05-12
+
+### Added
+- `hopla-claude-setup --setup-statusline` and `--remove-statusline` flags: the CLI now wires the Hopla statusline into `~/.claude/settings.json` automatically. `uninstall` removes it. Manual JSON snippet is documented as a fallback only.
+- `node:test` test suite (`npm test`) — 34 unit + integration tests covering `cli.js` helpers (`parseSettingsFile`, `safeWrite`, the new `setupStatusline`/`removeStatusline`) and the three core hooks (`env-protect`, `tsc-check`, `prompt-route`). Zero external dependencies — uses Node's built-in test runner.
+- GitHub Actions CI (`.github/workflows/ci.yml`): runs on every PR and push to main — JSON validation, version sync check, `npm test`, CLI dry-runs, and the `hook-audit` manual smoke test.
+- `CONTRIBUTING.md` with local development, testing, and PR guidelines.
+- `SECURITY.md` with the vulnerability disclosure process and the plugin's threat model (which hooks intercept which tool calls).
+- `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1).
+- `.github/PULL_REQUEST_TEMPLATE.md` and `.github/ISSUE_TEMPLATE/{bug_report,feature_request}.md`.
+- Frontmatter `description:` on the 9 guides in `commands/guides/` so they appear with hints in the slash-command autocomplete.
+
+### Changed
+- **i18n cleanup** — the plugin is now language-agnostic. Spanish trigger phrases removed from the descriptions of `brainstorm`, `verify`, `performance`, `debug` skills. Users configure their preferred response language in their own `~/.claude/CLAUDE.md`.
+- **`hooks/prompt-route.js` refactored to a hybrid matcher**: the hardcoded `SKILL_TRIGGERS` array is gone. The hook discovers skills at runtime by reading `SKILL.md` files; matching uses an optional `triggers:` frontmatter override, falling back to auto-derive from the skill name and quoted phrases in the description. New skills are matched without code changes.
+- **`hooks/tsc-check.js` filters by file extension**: editing a `.md` file no longer triggers `tsc --noEmit`. Only `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` files invoke the check.
+- `cli.js`: `parseSettingsFile` and `safeWrite` are now exported for testing. The main dispatcher is gated by an `isMainModule` check so the file can be imported as a library by tests.
+- `hooks/statusline.js` header comment points users at the new CLI flag rather than a hardcoded JSON snippet.
+- README "Optional: Hopla statusline" section recommends the CLI flag; manual JSON setup kept as a fallback note.
+- `CLAUDE.md` §5 (Testing) and §6 (Release flow) now describe `npm test` and the CI verification step.
+- `hooks/prompt-route.js` `triggers:` override added to `skills/code-review/SKILL.md` so phrases like "review my code" (with words between "review" and "code") match the skill.
+
+### Removed
+- Temporary `.DS_Store` artifact at repo root (already in `.gitignore`).
+
+### Notes for plugin authors
+- Skill discovery in Claude Code v1.24 does **not** support nested `skills/<subdir>/<name>/SKILL.md` paths. The 9 reference guides remain in `commands/guides/*.md` and ship with `description:` frontmatter. A future migration to `skills/` will revisit this if the platform adds support.
+
+## [2.0.0] - 2026-05-12
+
+### Added
+- `LICENSE` (MIT) in repo root for legal clarity in npm + GitHub.
+- `description`, `repository`, `homepage`, `bugs` fields in `package.json` for proper npm registry display.
+- `$schema` field in `plugin.json` and `marketplace.json` for JSON Schema validation in editors.
+- This `CHANGELOG.md` (full history back to 1.13.0 below).
+- `LICENSE` and `CHANGELOG.md` are now included in the published npm tarball via `files[]`.
+
+### Changed
+- **Breaking:** repository slug in `plugin.json` corrected from `hopla-tools/claude-setup` (404) to `HOPLAtools/claude-setup` (the real GitHub org).
+- `plugin.json` `homepage` differentiated from `repository`: now points to `#readme` anchor.
+- README install snippet simplified: `/plugin marketplace add HOPLAtools/claude-setup` (one argument — the canonical form per Anthropic docs).
+- All CLI references in README updated from `claude-setup` to `hopla-claude-setup`.
+
+### Removed
+- **Breaking:** bin alias `claude-setup` removed from `package.json`. The package now exposes only `hopla-claude-setup`. Migration: replace any script that calls `claude-setup` with `hopla-claude-setup` — same flags, same behavior. Rationale: the generic name risked colliding with other npm packages distributed publicly.
+
+## [1.19.0] - 2026-05-11
+
+### Added
+- New `hopla:hook-audit` skill — mechanical pre-commit checks for new React hooks against 4 documented bug classes (P-5 memoization, S-8 stale-id guard, E-1 error matching, D-1 cache + dedup integrity).
+
+### Changed
+- Documentation aligned with the canonical `/plugin marketplace update <name>` flow introduced in Claude Code v1.24+. The older `cd … && git pull` dance is no longer prescribed.
+
+## [1.18.0] - 2026-05-11
+
+### Added
+- OpenSpec wave 1: `AGENTS.md` (canonical project rules) with a CLAUDE.md alias path.
+- `.agents/specs/canonical/` for living requirements documents.
+- `/hopla:archive` command — folds delta-specs from completed plans into canonical specs and moves artifacts to archive locations.
+- `claude-setup status` subcommand — read-only inspection of the current project's `.agents/` workflow (plans, specs, reviews, suggested next step). JSON output available via `--json`.
+
+## [1.17.1] - 2026-05-01
+
+### Changed
+- `plan-feature` now enforces UX iteration budget declaration when the feature touches a visible UI surface.
+- `plan-feature` now requires a `## Domain Assumptions` section when the feature uses project-specific vocabulary.
+
+## [1.17.0] - 2026-04-17
+
+### Added
+- New skills: `refactoring`, `performance`, `migration`.
+- Spec linking — plans can reference and update canonical specs.
+- `.agents/audits/` directory for audit artifacts.
+
+## [1.16.0] - 2026-04-17
+
+### Changed
+- Refactor: progressive disclosure across skills, shared references between skills (e.g. `worktree` cites `git/flow-detection.md`), cleaner telemetry.
+
+## [1.15.0] - 2026-04-17
+
+### Added
+- MCP server template (`.mcp.json.template`).
+- New hooks: `UserPromptSubmit` (skill routing hints), `PreCompact` (session state snapshot).
+- Optional statusline renderer (`hooks/statusline.js`) showing branch · worktree indicator · uncommitted count · active plan.
+
+## [1.14.1] - 2026-04-17
+
+### Fixed
+- 7 critical audit findings (see commit `69c025b` for the full list).
+
+## [1.14.0] - 2026-04-17
+
+### Added
+- CLI `--dry-run` flag that composes with any other flag.
+- CLI cleans legacy agents (`code-reviewer.md`, `codebase-researcher.md`, `system-reviewer.md`) and legacy `PLANNING_PERMISSIONS` from older installs.
+- CLI prints an advisory when the plugin or marketplace cache is still present (the CLI cannot remove those — the user does).
+
+## [1.13.0] - 2026-04-17
+
+### Added
+- `git` skill integrated with `worktree` skill via centralized Git Flow detection in `flow-detection.md`.
+
+---
+
+For releases prior to 1.13.0, see the git history (`git log --oneline`).

package/LICENSE

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

package/README.md

@@ -24,7 +24,7 @@ The full setup is **plugin + CLI** — they deliver different layers:
 **Step 1 — Register the marketplace and install the plugin** (inside Claude Code):
 
 ```
-/plugin marketplace add hopla-marketplace HOPLAtools/claude-setup
+/plugin marketplace add HOPLAtools/claude-setup
 /plugin install hopla@hopla-marketplace
 ```
 
@@ -32,11 +32,15 @@ The full setup is **plugin + CLI** — they deliver different layers:
 
 ```bash
 npm install -g @hopla/claude-setup
-claude-setup --force
+hopla-claude-setup --force
 ```
 
 That's it. Commands show as `/hopla:<name>`, skills auto-trigger when relevant.
 
+**Recommended — enable auto-update for the marketplace** (one-time, inside Claude Code):
+
+Open `/plugin` → **Marketplaces** tab → select `hopla-marketplace` → enable auto-update. From then on, new releases are fetched automatically at session start; Claude Code will prompt you to run `/reload-plugins` when an update is ready. Skip this step and you'll need to refresh manually (see [Update](#update) below).
+
 ### Plugin only (skip global rules)
 
 If you don't want the machine-wide `~/.claude/CLAUDE.md`, just do Step 1. The plugin works on its own.
@@ -51,28 +55,25 @@ If you only want the global rules and not the plugin's commands/skills, just do
 
 ### Plugin channel
 
-Claude Code caches the marketplace repo locally. To pick up new versions:
-
-```bash
-cd ~/.claude/plugins/marketplaces/hopla-marketplace && git pull
-```
+**If auto-update is enabled** (see Quick Start Step 2.5): nothing to do. Claude Code fetches new releases at session start and prompts you to run `/reload-plugins`. That's it.
 
-Then inside Claude Code:
+**Manual refresh** (when auto-update is off, or you want to pull immediately):
 
 ```
-/plugin uninstall hopla@hopla-marketplace
-/plugin install hopla@hopla-marketplace
+/plugin marketplace update hopla-marketplace
+/plugin disable hopla@hopla-marketplace
+/plugin enable hopla@hopla-marketplace
 /reload-plugins
 ```
 
-> **Known issue:** Claude Code does not automatically `git pull` the marketplace when reinstalling a plugin. The manual `git pull` above is required.
+`/plugin marketplace update` refreshes the cached marketplace listing. `disable`/`enable` cycles the plugin so the new files are picked up — faster than a full `uninstall`/`install` because no scope re-selection is needed. `/reload-plugins` ensures hooks and commands are re-registered in the current session.
 
-If the `cd` path does not exist, you never installed the marketplace — do Step 1 of Quick Start instead.
+> The older `cd ~/.claude/plugins/marketplaces/hopla-marketplace && git pull` workflow still works but is no longer recommended — the built-in `/plugin marketplace update` is the canonical path since Claude Code v1.24.
 
 ### CLI channel (global rules)
 
 ```bash
-npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --force
+npm install -g @hopla/claude-setup@latest --prefer-online && hopla-claude-setup --force
 ```
 
 ---
@@ -88,7 +89,7 @@ npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --forc
 **CLI:**
 
 ```bash
-claude-setup --uninstall
+hopla-claude-setup --uninstall
 ```
 
 Removes `~/.claude/CLAUDE.md` plus legacy `hopla-*` files from older installs.
@@ -97,12 +98,14 @@ Removes `~/.claude/CLAUDE.md` plus legacy `hopla-*` files from older installs.
 
 | Flag | Purpose |
 |---|---|
-| `claude-setup` | Interactive install of global rules + permissions |
-| `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 --dry-run` | Preview changes without touching disk (composes with other flags) |
-| `claude-setup --version` | Print package version |
+| `hopla-claude-setup` | Interactive install of global rules + permissions |
+| `hopla-claude-setup --force` | Install without prompts |
+| `hopla-claude-setup --migrate` | Remove legacy CLI-installed duplicates only |
+| `hopla-claude-setup --uninstall` | Remove global rules + legacy files |
+| `hopla-claude-setup status` | Read-only inspection of the current project's `.agents/` workflow state (plans, specs, reviews, suggested next step) |
+| `hopla-claude-setup status --json` | Same as above, JSON output for agents to parse |
+| `hopla-claude-setup --dry-run` | Preview changes without touching disk (composes with other flags) |
+| `hopla-claude-setup --version` | Print package version |
 
 ---
 
@@ -110,21 +113,33 @@ Removes `~/.claude/CLAUDE.md` plus legacy `hopla-*` files from older installs.
 
 The plugin ships a statusline script that shows your branch, worktree indicator, uncommitted count, and active plan file (`📋 plan-name`) in Claude Code's status bar.
 
-Enable it by adding to `~/.claude/settings.json`:
+**Enable it (one-time):**
 
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "node ~/.claude/plugins/marketplaces/hopla-marketplace/hooks/statusline.js"
-  }
-}
+```bash
+hopla-claude-setup --setup-statusline
 ```
 
-Then run `/reload-plugins` or restart Claude Code.
+This writes the right `statusLine` block to `~/.claude/settings.json`, pointing at the installed plugin's `statusline.js`. Run `/reload-plugins` (or restart Claude Code) to see it.
+
+**Disable it:**
+
+```bash
+hopla-claude-setup --remove-statusline
+```
 
 Sample output: ` feature/auth · 3M · 📋 add-authentication`
 
+> **Manual setup (fallback):** if you don't have the CLI installed, add this to `~/.claude/settings.json` yourself:
+> ```json
+> {
+>   "statusLine": {
+>     "type": "command",
+>     "command": "node ~/.claude/plugins/marketplaces/hopla-marketplace/hooks/statusline.js"
+>   }
+> }
+> ```
+> Replace `hopla-marketplace` with the actual marketplace name if you registered it differently.
+
 ---
 
 ## Naming Convention
@@ -140,14 +155,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 +173,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 +225,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 +233,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 +257,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 +312,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)
 ```
@@ -371,7 +392,7 @@ Commands are modular — the output of one becomes the input of the next. Some a
 ### `/plugin install` doesn't show the `hopla` plugin
 
 - Run `/plugin marketplace list` — confirm `hopla-marketplace` is registered
-- If missing, re-run `/plugin marketplace add hopla-marketplace HOPLAtools/claude-setup`
+- If missing, re-run `/plugin marketplace add HOPLAtools/claude-setup`
 - Restart Claude Code after registering a new marketplace
 
 ### Commands appear as both `hopla-*` and `hopla:*`
@@ -379,7 +400,7 @@ Commands are modular — the output of one becomes the input of the next. Some a
 You have legacy CLI-installed files from before the plugin refactor. Clean up:
 
 ```bash
-claude-setup --migrate
+hopla-claude-setup --migrate
 ```
 
 This removes `hopla-*` duplicates from `~/.claude/commands/` and `~/.claude/skills/` without touching your global rules.
@@ -393,7 +414,7 @@ cd ~/.claude/plugins/marketplaces/hopla-marketplace && git pull
 
 You never registered the marketplace. Run Quick Start Step 1 first.
 
-### `claude-setup: command not found`
+### `hopla-claude-setup: command not found`
 
 The npm global bin is not on your PATH. Check with:
 
@@ -404,6 +425,8 @@ npm config get prefix
 
 Alternatively, run via npx: `npx @hopla/claude-setup --force`.
 
+> **Migrating from v1.x?** The `claude-setup` bin alias was removed in v2.0.0. Replace any script that calls `claude-setup` with `hopla-claude-setup` (same flags, same behavior).
+
 ### Changes to skills/commands don't take effect
 
 Claude Code caches plugin content. After a plugin update:
@@ -434,12 +457,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."
 ```