@hopla/claude-setup 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @hopla/claude-setup
+
+Hopla team agentic coding system for Claude Code. Installs global rules and commands to `~/.claude/`.
+
+## Install
+
+```bash
+npx @hopla/claude-setup
+```
+
+To overwrite existing files without prompting:
+
+```bash
+npx @hopla/claude-setup --force
+```
+
+## What gets installed
+
+**`~/.claude/CLAUDE.md`** — Global rules: language, tech preferences, Git Flow, Conventional Commits, autonomy behavior.
+
+**`~/.claude/commands/`** — Reusable commands available in any project:
+
+| Command | Description |
+|---|---|
+| `/prime` | Load project context at the start of a session |
+| `/commit` | Create a Conventional Commit with Git Flow awareness |
+| `/create-prd` | Create a Product Requirements Document through guided questions |
+| `/plan-feature` | Research codebase and create a structured implementation plan |
+| `/execute` | Execute a structured plan from start to finish with validation |
+| `/code-review` | Technical code review on recently changed files |
+| `/code-review-fix` | Fix issues found in a code review report |
+| `/execution-report` | Generate an implementation report for system review |
+| `/system-review` | Analyze implementation against plan to find process improvements |
+
+## Update
+
+Re-run the install command to update to the latest version:
+
+```bash
+npx @hopla/claude-setup@latest
+```

package/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import readline from "readline";
+
+const FORCE = process.argv.includes("--force");
+const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
+const FILES_DIR = path.join(import.meta.dirname, "files");
+
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+function log(msg) {
+    console.log(msg);
+}
+
+async function confirm(question) {
+    if (FORCE) return true;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+        });
+    });
+}
+
+async function installFile(src, dest, label) {
+    const exists = fs.existsSync(dest);
+
+    if (exists && !FORCE) {
+        const overwrite = await confirm(
+            `  ${YELLOW}⚠${RESET}  ${label} already exists. Overwrite? (y/N) `
+        );
+        if (!overwrite) {
+            log(`  ${YELLOW}↷${RESET}  Skipped: ${label}`);
+            return;
+        }
+    }
+
+    fs.copyFileSync(src, dest);
+    log(`  ${GREEN}✓${RESET}  ${exists ? "Updated" : "Installed"}: ${label}`);
+}
+
+async function main() {
+    log(`\n${BOLD}@hopla/claude-setup${RESET} — Agentic Coding System\n`);
+
+    // Create directories if needed
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    fs.mkdirSync(COMMANDS_DIR, { recursive: true });
+
+    log(`${CYAN}Installing global rules...${RESET}`);
+    await installFile(
+        path.join(FILES_DIR, "CLAUDE.md"),
+        path.join(CLAUDE_DIR, "CLAUDE.md"),
+        "~/.claude/CLAUDE.md"
+    );
+
+    log(`\n${CYAN}Installing commands...${RESET}`);
+    const commandFiles = fs.readdirSync(path.join(FILES_DIR, "commands"));
+    for (const file of commandFiles.sort()) {
+        await installFile(
+            path.join(FILES_DIR, "commands", file),
+            path.join(COMMANDS_DIR, file),
+            `~/.claude/commands/${file}`
+        );
+    }
+
+    log(`\n${GREEN}${BOLD}Done!${RESET} Commands available in any Claude Code session:\n`);
+    for (const file of commandFiles.sort()) {
+        const name = file.replace(".md", "");
+        log(`  ${CYAN}/${name}${RESET}`);
+    }
+    log(`\nRun with ${BOLD}--force${RESET} to overwrite all files without prompting.\n`);
+}
+
+main().catch((err) => {
+    console.error("Installation failed:", err.message);
+    process.exit(1);
+});

package/files/CLAUDE.md

@@ -0,0 +1,87 @@
+# Global Rules — Agentic Coding System
+
+## 1. Communication
+
+- **Always respond in the same language the user writes in** — if the user writes in Spanish, respond in Spanish; if in English, respond in English
+- Code, comments, variable names, and commit messages always in **English** regardless of the conversation language
+- Be concise — avoid unnecessary filler text
+- When reporting results, use ✅/❌ for clarity
+
+---
+
+## 2. Tech Preferences
+
+- **Frontend:** React with functional components and hooks (no class components)
+- **Language:** TypeScript over JavaScript always
+- **Bundler:** Vite as default for frontend projects
+- Keep solutions simple — avoid over-engineering and premature abstractions
+- Prefer editing existing files over creating new ones
+
+---
+
+## 3. Behavior & Autonomy
+
+**Always ask before:**
+- Running `git commit`
+- Running `git push`
+- Installing new dependencies (`npm install <pkg>`, `pip install <pkg>`, etc.)
+- Deleting files or directories
+- Any destructive or hard-to-reverse operation
+
+**Proactively suggest commits** at logical save points:
+- After completing a feature or fix
+- Before starting a risky refactor
+- After passing all validation checks
+- Explain WHY it's a good moment to commit so the team understands
+
+**Never:**
+- Auto-commit or auto-push without explicit approval
+- Skip validation steps to save time
+- Add features, refactors, or improvements beyond what was asked
+
+---
+
+## 4. Git Workflow (Git Flow)
+
+### Branch Strategy
+- `main` → production only, never commit directly
+- `develop` / `dev` → active development branch
+- Feature branches: `feature/short-description`
+- Bug fix branches: `fix/short-description`
+- Hotfix branches: `hotfix/short-description`
+
+### Commit Format — Conventional Commits
+```
+<type>(<optional scope>): <short description>
+
+[optional body]
+```
+
+**Types:**
+- `feat:` — new feature
+- `fix:` — bug fix
+- `refactor:` — code restructure without behavior change
+- `docs:` — documentation only
+- `test:` — adding or fixing tests
+- `chore:` — build, config, dependencies
+- `style:` — formatting, no logic change
+
+**Examples:**
+```
+feat(auth): add JWT token validation
+fix(api): handle null response from products endpoint
+chore: update dependencies to latest versions
+```
+
+### When to Suggest a Commit
+Explain in plain language when suggesting a commit, adapting to the user's language, e.g.:
+> "This would be a good moment to commit — we finished feature X and all tests pass. Should we commit before continuing?"
+
+---
+
+## 5. Code Quality
+
+- Validate before considering anything done (lint → types → tests)
+- Write tests alongside implementation, not after
+- Flag security issues immediately — never leave them for later
+- If the same validation failure repeats, signal it as a system improvement opportunity

package/files/commands/code-review-fix.md

@@ -0,0 +1,46 @@
+---
+description: Fix issues found in a code review report
+argument-hint: "<review-file-or-description> [scope]"
+---
+
+Fix the issues identified in a code review.
+
+## Inputs
+
+- **$1** — Path to a code review report file OR a natural language description of the issues to fix
+- **$2** (optional) — Scope: focus only on a subset of issues (e.g., "security issues only", "critical and high severity only")
+
+## Step 1: Load the Review
+
+If $1 is a file path, read the entire file first to understand all issues before starting any fixes.
+If $1 is a description, treat it as the list of issues to fix.
+
+If $2 is provided, filter to only the issues within that scope.
+
+## Step 2: Fix Issues One by One
+
+For each issue, in order of severity (critical → high → medium → low):
+
+1. **Explain** what was wrong and why it's a problem
+2. **Implement** the fix
+3. **Verify** — create and run a relevant test or check to confirm the fix works
+
+Do not move to the next issue until the current one is verified.
+
+## Step 3: Run Full Validation
+
+After all fixes are complete, run the project's validation suite.
+
+If a `/validate` command exists in `.claude/commands/validate.md`, run it.
+Otherwise, run the standard checks for the project stack:
+- Linting
+- Type checking
+- Test suite
+
+## Step 4: Summary Report
+
+Provide a summary of:
+- Issues fixed (with file and line reference)
+- Issues skipped and why (if $2 scope was used)
+- Validation result ✅/❌
+- Any issues that could not be fixed automatically and require human review

package/files/commands/code-review.md

@@ -0,0 +1,77 @@
+---
+description: Technical code review on recently changed files
+argument-hint: "[optional: branch or commit range, defaults to HEAD]"
+---
+
+Perform a technical code review focused on finding real bugs and issues.
+
+## Step 1: Load Context
+
+Read `CLAUDE.md` or `AGENTS.md` to understand project standards and patterns.
+
+## Step 2: Identify Changed Files
+
+```bash
+git diff --stat HEAD
+git diff HEAD
+git ls-files --others --exclude-standard
+```
+
+Read each changed or new file in its entirety — not just the diff.
+
+## Step 3: Analyze for Issues
+
+For each changed file, look for:
+
+**1. Logic Errors**
+- Off-by-one errors, incorrect conditionals
+- Missing error handling, unhandled edge cases
+- Race conditions or async issues
+
+**2. Security Issues**
+- Exposed secrets or API keys
+- SQL/command injection vulnerabilities
+- Insecure data handling or missing input validation
+- XSS vulnerabilities (frontend)
+
+**3. Performance Problems**
+- Unnecessary re-renders (React)
+- N+1 queries or redundant API calls
+- Memory leaks
+
+**4. Code Quality**
+- DRY violations
+- Poor naming or overly complex functions
+- Missing TypeScript types or `any` usage
+
+**5. Pattern Adherence**
+- Follows project conventions from CLAUDE.md
+- Consistent with existing codebase style
+
+## Step 4: Verify Issues Are Real
+
+Before reporting, confirm each issue is legitimate:
+- Run relevant tests if applicable
+- Check if the pattern is intentional based on context
+
+## Step 5: Output Report
+
+Save to `.agents/code-reviews/[descriptive-name].md`
+
+**Format for each issue:**
+```
+severity: critical | high | medium | low
+file: path/to/file.ts
+line: 42
+issue: [one-line description]
+detail: [why this is a problem]
+suggestion: [how to fix it]
+```
+
+If no issues found: "Code review passed. No technical issues detected."
+
+**Rules:**
+- Be specific — line numbers, not vague complaints
+- Focus on real bugs, not style preferences (linting handles that)
+- Flag security issues as `critical`
+- Suggest fixes, don't just identify problems

package/files/commands/commit.md

@@ -0,0 +1,60 @@
+---
+description: Create a conventional commit with Git Flow awareness
+argument-hint: "[optional: commit message or scope]"
+---
+
+Review the current git state and create an appropriate commit.
+
+## Step 1: Gather Context
+
+Run these commands to understand what changed:
+
+```bash
+git status
+git diff --staged
+git diff
+git log --oneline -5
+```
+
+## Step 2: Analyze Changes
+
+- Identify what was added, modified, or deleted
+- Determine the appropriate commit type: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`
+- Identify the scope if relevant (e.g., `auth`, `api`, `ui`)
+- Check current branch — confirm it follows Git Flow naming (`feature/`, `fix/`, `hotfix/`, `develop`, `dev`)
+
+## Step 3: Stage Files
+
+Stage only the relevant files for this commit (avoid `git add -A` unless all changes belong together):
+
+```bash
+git add <specific files>
+```
+
+## Step 4: Propose Commit
+
+Present the proposed commit message to the user **before executing**:
+
+> "Proposed commit:
+> `feat(products): add price filter to search endpoint`
+>
+> Files included: [list files]
+> Shall I proceed?"
+
+Wait for explicit approval before running `git commit`.
+
+## Step 5: Execute Commit
+
+Once approved, create the commit:
+
+```bash
+git commit -m "<type>(<scope>): <description>"
+```
+
+## Step 6: Push Reminder
+
+After committing, remind the user:
+
+> "Commit created locally. Do you want to push to `origin/<branch>`?"
+
+**Never push automatically** — wait for explicit confirmation.

package/files/commands/create-prd.md

@@ -0,0 +1,85 @@
+---
+description: Create a Product Requirements Document (PRD) for a project through guided questions
+---
+
+Create a PRD for this project by gathering the necessary information through a structured conversation.
+
+## Step 1: Gather Context
+
+Before asking questions, read what already exists:
+- `CLAUDE.md` or `AGENTS.md` — extract product name, tech stack, and any business context
+- `README.md` — extract any existing product description
+
+Use this to avoid asking questions that are already answered.
+
+## Step 2: Ask Key Questions
+
+Ask the following questions **one section at a time** — do not dump all questions at once. Wait for the answer before continuing.
+
+**Section A — The Product**
+1. In 1-2 sentences, what does this product do?
+2. What problem does it solve? What was happening before this product existed?
+
+**Section B — The Users**
+3. Who are the primary users? (role, context, technical level)
+4. How do they use it? (daily, weekly, ad-hoc?)
+
+**Section C — Scope**
+5. What are the 3-5 most important features the product must have?
+6. What is explicitly OUT of scope? (things users might expect but won't be built)
+
+**Section D — Success**
+7. How do you know the product is working well? (key outcomes or metrics)
+
+## Step 3: Generate the PRD
+
+Once all questions are answered, generate the PRD and save it to `PRD.md` at the project root.
+
+Use this structure:
+
+---
+
+```markdown
+# PRD — [Product Name]
+
+## What is it?
+
+[2-3 sentence executive summary. What it does, who it's for, and why it exists.]
+
+## Problem
+
+[What problem does this solve? What was the situation before this product?]
+
+## Users
+
+**Primary users:** [Role and context]
+**Usage pattern:** [How often and in what context they use it]
+
+## Core Features (In Scope)
+
+- [Feature 1 — one line description]
+- [Feature 2 — one line description]
+- [Feature 3 — one line description]
+[Add as many as needed]
+
+## Out of Scope
+
+These are explicitly NOT part of this product:
+- [Thing 1 — why it's excluded]
+- [Thing 2 — why it's excluded]
+
+## Success Criteria
+
+The product is working well when:
+- [Measurable outcome 1]
+- [Measurable outcome 2]
+```
+
+---
+
+## Step 4: Confirm and Save
+
+Show the draft PRD to the user and ask:
+> "Does this accurately reflect the product? Any corrections before I save it?"
+
+Once confirmed, save to `PRD.md` and suggest running `/commit` to add it to the repository.

package/files/commands/execute.md

@@ -0,0 +1,103 @@
+---
+description: Execute a structured plan from start to finish with validation
+argument-hint: "<plan-file-path>"
+---
+
+Execute the implementation plan provided. You are the executing agent — you have not seen the planning conversation. The plan is your only source of truth.
+
+## Step 1: Load Context
+
+Read in this order:
+1. **$1** — The plan file (read it entirely before writing a single line of code)
+2. `CLAUDE.md` or `AGENTS.md` at project root — rules and patterns to follow
+3. All files listed in the plan's **Context References** section
+
+Do not start implementing until you have read everything above.
+
+## Step 2: Confirm Understanding
+
+Before executing, summarize:
+- What you are about to build
+- How many tasks are in the plan
+- Any constraints or gotchas flagged in the plan
+- Anything unclear that needs clarification before proceeding
+
+If anything in the plan is ambiguous or contradictory, **stop and ask** before writing code.
+
+## Step 3: Execute Tasks in Order
+
+Work through each task in the plan sequentially. For each task:
+
+1. **Announce** the task you are starting (e.g., "Starting Task 2: Create the filter component")
+2. **Follow the pattern** referenced in the plan — do not invent new patterns
+3. **Implement** only what the task specifies — nothing more
+4. **Validate** the task using the method specified in the plan's validate field
+5. **Do not proceed** to the next task if the current one fails validation
+
+If you encounter something unexpected (a file doesn't exist, a pattern is different than the plan assumed), **stop and report** before continuing — do not improvise silently.
+
+## Step 4: Run Full Validation Pyramid
+
+After all tasks are complete, run the full validation sequence in order.
+**Do not skip levels. Do not proceed if a level fails.**
+
+### Level 1 — Lint & Format
+Run the project's lint and format check.
+Fix any issues before continuing.
+
+### Level 2 — Type Check
+Run the project's type checker.
+Fix all type errors before continuing.
+
+### Level 3 — Unit Tests
+Run the project's unit test suite.
+If tests fail:
+- Investigate the root cause
+- Fix the code (not the tests)
+- Re-run until all pass
+
+### Level 4 — Integration Tests
+Run integration tests or manual verification as specified in the plan.
+Verify the feature works end-to-end.
+
+### Level 5 — Human Review (flag for user)
+List what the user should manually verify:
+- Specific behaviors to test in the browser or CLI
+- Edge cases to check
+- Any decisions made during implementation that the user should review
+
+## Step 5: Completion Report
+
+Provide a summary of what was done:
+
+```
+## Execution Summary
+
+**Plan:** [path to plan file]
+**Status:** ✅ Complete | ⚠️ Partial | ❌ Blocked
+
+### Tasks Completed
+- [x] Task 1: [description]
+- [x] Task 2: [description]
+- [ ] Task 3: [description — if skipped, explain why]
+
+### Validation Results
+- Level 1 Lint:       ✅ / ❌
+- Level 2 Type Check: ✅ / ❌
+- Level 3 Unit Tests: ✅ [X passed] / ❌ [X failed]
+- Level 4 Integration:✅ / ❌
+- Level 5 Human:      🔍 See items below
+
+### For Human Review
+- [specific thing to verify manually]
+
+### Deviations from Plan
+- [anything that differed from the plan and why]
+```
+
+## Step 6: Suggest Next Steps
+
+After the summary, suggest:
+1. Run `/execution-report` to document this implementation for system review
+2. Run `/code-review` for a technical quality check
+3. Run `/commit` once everything is approved

package/files/commands/execution-report.md

@@ -0,0 +1,67 @@
+---
+description: Generate an implementation report for system review
+---
+
+Review and document the implementation you just completed. Run this immediately after finishing a feature — before committing or starting the next task.
+
+## Step 1: Gather Implementation Data
+
+```bash
+git diff HEAD --stat
+git diff HEAD
+git ls-files --others --exclude-standard
+```
+
+## Step 2: Generate Report
+
+Save to: `.agents/execution-reports/[feature-name].md`
+
+Use the following structure:
+
+---
+
+### Meta Information
+
+- **Plan file:** [path to the plan that guided this implementation]
+- **Files added:** [list with paths]
+- **Files modified:** [list with paths]
+- **Lines changed:** +X -Y
+
+### Validation Results
+
+- Syntax & Linting: ✓/✗ [details if failed]
+- Type Checking: ✓/✗ [details if failed]
+- Unit Tests: ✓/✗ [X passed, Y failed]
+- Integration Tests: ✓/✗ [X passed, Y failed]
+
+### What Went Well
+
+List specific things that worked smoothly:
+- [concrete examples]
+
+### Challenges Encountered
+
+List specific difficulties encountered:
+- [what was difficult and why]
+
+### Divergences from Plan
+
+For each divergence from the original plan:
+
+**[Divergence Title]**
+- **Planned:** [what the plan specified]
+- **Actual:** [what was implemented instead]
+- **Reason:** [why this divergence occurred]
+- **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
+
+### Skipped Items
+
+List anything from the plan that was not implemented:
+- [what was skipped] — Reason: [why]
+
+### Recommendations
+
+Based on this implementation, what should change for next time?
+- Plan command improvements: [suggestions]
+- Execute command improvements: [suggestions]
+- CLAUDE.md additions: [suggestions]

package/files/commands/plan-feature.md

@@ -0,0 +1,136 @@
+---
+description: Research the codebase and create a structured implementation plan from requirements
+argument-hint: "<feature-name-or-description>"
+---
+
+Transform the requirements discussed in this conversation into a structured plan that another agent can execute without access to this conversation.
+
+## Phase 1: Understand the Requirements
+
+Review the current conversation to extract:
+- What feature or change is being requested?
+- What is the expected behavior from the user's perspective?
+- Are there any explicit constraints or preferences mentioned?
+- What is out of scope?
+
+If anything is ambiguous, ask clarifying questions **before** proceeding to research.
+
+## Phase 2: Load Project Context
+
+Read the following to understand the project:
+
+1. `CLAUDE.md` or `AGENTS.md` at project root — architecture rules, patterns, constraints
+2. `README.md` — project overview and setup
+3. `package.json` or `pyproject.toml` — stack, dependencies, scripts
+
+Then run:
+
+```bash
+git branch --show-current
+git log --oneline -10
+git status
+```
+
+## Phase 3: Research the Codebase
+
+Investigate the areas of the codebase relevant to this feature:
+
+- Find existing files and modules related to the feature
+- Identify the patterns already used (naming, structure, data flow)
+- Locate similar features already implemented to use as reference
+- Find the entry points that will need to be modified or extended
+- Identify potential conflicts or dependencies
+
+```bash
+git ls-files | grep -i <relevant-keyword>
+```
+
+Read the key files in their entirety — not just the parts that seem relevant.
+
+## Phase 4: Design the Approach
+
+Based on research, define:
+- What files will be created vs. modified
+- What pattern to follow (based on existing codebase conventions)
+- What the data flow looks like end-to-end
+- Any risks, edge cases, or gotchas to flag
+- What tests are needed
+
+## Phase 5: Generate the Plan
+
+Save the plan to: `.agents/plans/[kebab-case-feature-name].md`
+
+Use this structure:
+
+---
+
+```markdown
+# Plan: [Feature Name]
+
+## Overview
+[2-3 sentences describing what this feature does and why]
+
+## Requirements Summary
+- [Bullet list of requirements extracted from the discussion]
+
+## Out of Scope
+- [Anything explicitly excluded]
+
+## Context References
+Key files the executing agent must read before starting:
+- `[path/to/file]` — [why it's relevant]
+- `[path/to/file]` — [why it's relevant]
+
+## Implementation Tasks
+
+### Task 1: [Action verb + what]
+- **Action:** [Specific action: create / modify / delete]
+- **File:** `[exact file path]`
+- **Pattern:** Follow the same pattern as `[reference file]`
+- **Details:** [Exact description of what to implement]
+- **Gotcha:** [Known pitfall or constraint to watch for]
+- **Validate:** [How to verify this task is done correctly]
+
+### Task 2: [Action verb + what]
+[Same structure]
+
+[Continue for all tasks...]
+
+## Validation Checklist
+
+Run in this order — do not proceed if a level fails:
+
+- [ ] **Level 1 — Lint & Format:** `[project lint command]`
+- [ ] **Level 2 — Type Check:** `[project type check command]`
+- [ ] **Level 3 — Unit Tests:** `[project unit test command]`
+- [ ] **Level 4 — Integration Tests:** `[project integration test or manual curl/check]`
+- [ ] **Level 5 — Human Review:** Verify behavior matches requirements above
+
+## Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+## Notes for Executing Agent
+[Any important context, warnings, or decisions made during planning that the executing agent needs to know]
+```
+
+---
+
+## Phase 6: Verify the Plan
+
+Before finishing, review the plan against these criteria:
+
+- [ ] Every task has a specific file path (no vague "update the component")
+- [ ] Every task references an existing pattern to follow
+- [ ] Validation commands match the actual project scripts
+- [ ] The plan is complete enough that another agent can execute it without this conversation
+- [ ] No ambiguous requirements left unresolved
+
+## Final Output
+
+Confirm to the user:
+- Plan saved to: `.agents/plans/[feature-name].md`
+- Summary of tasks included
+- Any open questions or decisions that require human confirmation before execution
+- Suggest running `/commit` to save the plan to the repository

package/files/commands/prime.md

@@ -0,0 +1,43 @@
+---
+description: Load project context at the start of a session
+---
+
+Get oriented in this project before doing any work.
+
+## Step 1: Project Structure
+
+```bash
+git ls-files | head -60
+```
+
+```bash
+find . -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "README.md" | head -10
+```
+
+## Step 2: Read Key Files
+
+Read in this order:
+1. `CLAUDE.md` or `AGENTS.md` at project root (project-specific rules)
+2. `README.md` (project overview)
+3. `package.json` or `pyproject.toml` (dependencies and scripts)
+
+## Step 3: Understand Git State
+
+```bash
+git branch --show-current
+git log --oneline -10
+git status
+```
+
+## Step 4: Summary Report
+
+Provide a concise summary with:
+
+**Project:** [name and purpose in one sentence]
+**Stack:** [languages, frameworks, key libraries]
+**Current branch:** [branch name and what it's for]
+**Key structure:** [main folders and their purpose]
+**Useful commands:** [how to run, test, build]
+**Git status:** [clean / changes pending / uncommitted files]
+
+Keep it scannable — this is for human review in under 30 seconds.

package/files/commands/system-review.md

@@ -0,0 +1,139 @@
+---
+description: Analyze implementation against plan to find process improvements
+argument-hint: "<plan-file> <execution-report-file>"
+---
+
+Perform a meta-level analysis of how well the implementation followed the plan. This is NOT code review — you're looking for bugs in the process, not the code.
+
+## Inputs
+
+- **$1** — Path to the structured plan file
+- **$2** — Path to the execution report file
+
+## Step 1: Load All Context
+
+Read these four artifacts in order:
+
+1. `.claude/commands/plan-feature.md` — understand how plans are created
+2. **$1** (the plan) — what the agent was supposed to do
+3. `.claude/commands/execute.md` — understand how execution is guided
+4. **$2** (the execution report) — what the agent actually did and why
+
+## Step 2: Understand the Planned Approach
+
+From the plan ($1), extract:
+- What features were planned?
+- What architecture was specified?
+- What validation steps were defined?
+- What patterns or constraints were referenced?
+
+## Step 3: Understand the Actual Implementation
+
+From the execution report ($2), extract:
+- What was actually implemented?
+- What diverged from the plan?
+- What challenges were encountered?
+- What was skipped and why?
+
+## Step 4: Classify Each Divergence
+
+For each divergence, classify as:
+
+**Good Divergence ✅** (justified):
+- Plan assumed something that didn't exist in the codebase
+- Better pattern discovered during implementation
+- Performance optimization was needed
+- Security issue required a different approach
+
+**Bad Divergence ❌** (problematic):
+- Ignored explicit constraints from the plan
+- Created new architecture instead of following existing patterns
+- Took shortcuts that introduce tech debt
+- Misunderstood requirements
+
+## Step 5: Trace Root Causes
+
+For each problematic divergence, identify the root cause:
+- Was the plan unclear? Where and why?
+- Was context missing? Where and why?
+- Was a validation step missing?
+- Was a manual step repeated that should be automated?
+
+## Step 6: Generate Process Improvements
+
+Suggest specific actions based on patterns found:
+
+- **CLAUDE.md updates** — 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
+
+## Output Format
+
+Save to: `.agents/system-reviews/[feature-name]-review.md`
+
+---
+
+### Meta Information
+- Plan reviewed: [path to $1]
+- Execution report: [path to $2]
+- Date: [current date]
+
+### Overall Alignment Score: __/10
+
+- **10** — Perfect adherence, all divergences justified
+- **7–9** — Minor justified divergences
+- **4–6** — Mix of justified and problematic divergences
+- **1–3** — Major problematic divergences
+
+### Divergence Analysis
+
+For each divergence:
+```yaml
+divergence: [what changed]
+planned: [what plan specified]
+actual: [what was implemented]
+reason: [agent's stated reason]
+classification: good ✅ | bad ❌
+root_cause: [unclear plan | missing context | missing validation | other]
+```
+
+### Pattern Compliance
+- [ ] Followed codebase architecture
+- [ ] Used patterns documented in CLAUDE.md
+- [ ] Applied testing patterns correctly
+- [ ] Met validation requirements
+
+### System Improvement Actions
+
+**Update CLAUDE.md:**
+- [ ] [specific addition or change]
+
+**Update Plan Command:**
+- [ ] [specific addition or change]
+
+**Update Execute Command:**
+- [ ] [specific addition or change]
+
+**Create New Command:**
+- [ ] `/[command-name]` — [what it automates]
+
+### Key Learnings
+
+**What worked well:** [specific things]
+**What needs improvement:** [specific process gaps]
+**For next implementation:** [concrete changes to try]
+
+---
+
+## Decision Framework — When to Update What
+
+After the analysis, use this to prioritize actions:
+
+| Pattern | Action |
+|---|---|
+| Issue happens across ALL features | Update 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 |

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hopla/claude-setup",
+  "version": "1.0.0",
+  "description": "Hopla team agentic coding system for Claude Code",
+  "type": "module",
+  "bin": {
+    "claude-setup": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "files/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agentic",
+    "hopla"
+  ],
+  "author": "Hopla Tools",
+  "license": "MIT"
+}