@hopla/claude-setup 1.10.2 → 1.11.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "hopla-marketplace",
+  "description": "Hopla Tools plugin marketplace for Claude Code",
+  "owner": {
+    "name": "Hopla Tools",
+    "email": "julio@hopla.tools"
+  },
+  "plugins": [
+    {
+      "name": "hopla",
+      "description": "Agentic coding system: PIV loop, TDD, debugging, brainstorming, subagent execution, and team workflows",
+      "version": "1.11.0",
+      "source": "./",
+      "author": {
+        "name": "Hopla Tools",
+        "email": "julio@hopla.tools"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "hopla",
+  "description": "Agentic coding system for Claude Code: PIV loop (Plan → Implement → Validate), TDD, debugging, brainstorming, subagent execution, and team workflows",
+  "version": "1.11.0",
+  "author": {
+    "name": "Hopla Tools",
+    "email": "julio@hopla.tools"
+  },
+  "homepage": "https://github.com/hopla-tools/claude-setup",
+  "repository": "https://github.com/hopla-tools/claude-setup",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "agentic-coding",
+    "piv-loop",
+    "tdd",
+    "debugging",
+    "brainstorming",
+    "code-review",
+    "workflows",
+    "skills"
+  ]
+}

package/README.md

@@ -1,17 +1,42 @@
 # @hopla/claude-setup
 
-Hopla team agentic coding system for Claude Code. Installs global rules and commands to `~/.claude/`.
+Hopla team agentic coding system for Claude Code. Installs commands, skills, agents, hooks, and reference guides — available as a **Claude Code plugin** or via **npm CLI**.
 
 ## Install
 
-### Full install — for the implementer (Julio)
+### Option A: Claude Code Plugin (recommended)
+
+First, register the HOPLA marketplace (only needed once):
+
+```
+/plugin marketplace add hopla-marketplace https://github.com/HOPLAtools/claude-setup.git
+```
+
+Then install the plugin:
+
+```
+/plugin install hopla@hopla-marketplace
+```
+
+This installs all commands, skills, agents, and hooks automatically. Updates are detected when the plugin version changes — update manually with `/plugin update hopla@hopla-marketplace`.
+
+To also install the global rules template (`~/.claude/CLAUDE.md`), run the CLI:
+
+```bash
+npm install -g @hopla/claude-setup
+claude-setup --force
+```
+
+> **Note:** The global rules (`~/.claude/CLAUDE.md`) can only be installed via the CLI because the plugin system doesn't have access to write machine-level files.
+
+### Option B: npm CLI only
 
 ```bash
 npm install -g @hopla/claude-setup
 claude-setup
 ```
 
-Installs all commands: planning + execution + review.
+Installs everything including `~/.claude/CLAUDE.md`. Use this if you don't want the plugin channel or need the `--planning` mode.
 
 ### Planning-only install — for the planner/non-technical role (Robert)
 
@@ -20,7 +45,7 @@ npm install -g @hopla/claude-setup
 claude-setup --planning
 ```
 
-Installs only planning commands: `init-project`, `prime`, `create-prd`, `plan-feature`, `review-plan`, `git-commit`, `git-pr`. No execution or review commands. No bash permission prompts during planning.
+Installs only planning commands: `init-project`, `create-prd`, `plan-feature`, `review-plan`, `guide`, `git-commit`, `git-pr`. Also installs planning skills (`hopla-prime`, `hopla-brainstorm`). No execution or review commands. No bash permission prompts during planning.
 
 To overwrite existing files without prompting:
 
@@ -31,33 +56,50 @@ claude-setup --planning --force
 
 ## Update
 
+**Plugin channel:** updates automatically when the plugin version changes, or manually:
+```
+/plugin update hopla@hopla-marketplace
+```
+
+**CLI channel (for global rules):**
 ```bash
 npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --force
 ```
 
 ## Uninstall
 
+**Plugin:**
+```
+/plugin uninstall hopla@hopla-marketplace
+```
+
+**CLI:**
 ```bash
 claude-setup --uninstall
 ```
 
 ---
 
-## How It Works — Layer 1 Planning
+## How It Works — Layered Context
 
-The system is built on two levels of context:
+The system uses three levels of CLAUDE.md, each scoped differently:
 
 ```
-~/.claude/CLAUDE.md        ← Global rules (installed by claude-setup)
-    └── applies to ALL projects
+~/.claude/CLAUDE.md        ← Machine-level (installed by claude-setup)
+    └── applies to ALL projects on this machine
 
-CLAUDE.md (project root)   ← Project-specific rules (created with /hopla-init-project)
+CLAUDE.md (project root)   ← Project-level (created with /hopla-init-project)
     └── applies to THIS project only
+
+.claude/CLAUDE.local.md    ← Local overrides (personal, gitignored)
+    └── your personal tweaks, not shared with team
 ```
 
-**Global rules** cover: language preferences, tech defaults (React, TypeScript, Vite), Git Flow, Conventional Commits, and autonomy behavior.
+**Machine-level rules** cover: language preferences, tech defaults, Git Flow, Conventional Commits, autonomy behavior, context management, and available commands/skills reference.
+
+**Project-level rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, and task-specific reference guides.
 
-**Project rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, and task-specific reference guides.
+**Local overrides** cover: personal preferences that differ from the team (e.g., verbose logging, different editor settings).
 
 ---
 
@@ -73,6 +115,7 @@ This system is built on two core concepts from the Agentic Coding Course:
 | **On-Demand Context** | Task-specific guides loaded when needed (e.g. "how to add an API endpoint") | `.agents/guides/*.md` |
 | **Commands** | Reusable processes that tell the agent *how* to work | `~/.claude/commands/hopla-*.md` |
 | **Skills** | Auto-activate by semantic matching — no slash command needed | `~/.claude/skills/hopla-*/SKILL.md` |
+| **Agents** | Specialized subagents for delegation (code review, research, system analysis) | `~/.claude/agents/*.md` |
 | **Hooks** | Run automatically before/after tool use for type checking and protection | `~/.claude/hooks/*.js` |
 
 The key insight: **commands inject on-demand context deterministically** — when you run `/hopla-plan-feature`, it automatically reads the relevant guide from `.agents/guides/` before planning.
@@ -102,18 +145,21 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 | Command | Description |
 |---|---|
 | `/hopla-init-project` | Read PRD, recommend stack, create CLAUDE.md and .agents/ structure |
-| `/hopla-prime` | Load project context at the start of a session |
 | `/hopla-create-prd` | Create a Product Requirements Document through guided questions |
 | `/hopla-plan-feature` | Research codebase and create a structured implementation plan |
 | `/hopla-review-plan` | Review a plan before execution — get a concise summary and approve |
 | `/hopla-execute` | Execute a structured plan from start to finish with validation |
+| `/hopla-validate` | Run the validation pyramid: lint → types → tests → integration |
+| `/hopla-end-to-end` | Full PIV loop in one command: prime → brainstorm → plan → execute → validate → commit |
 | `/hopla-git-commit` | Create a Conventional Commit with Git Flow awareness |
 | `/hopla-git-pr` | Create a GitHub Pull Request with a structured description |
-| `/hopla-code-review` | Technical code review on recently changed files |
 | `/hopla-code-review-fix` | Fix issues found in a code review report |
-| `/hopla-execution-report` | Generate an implementation report for system review |
+| `/hopla-rca` | Root Cause Analysis — investigate a bug systematically and generate an RCA doc |
+| `/hopla-guide` | 4D Framework guide for non-technical users (Description, Discernment, Delegation, Diligence) |
 | `/hopla-system-review` | Analyze implementation against plan to find process improvements |
 
+> **Note:** `hopla-prime`, `hopla-code-review`, and `hopla-execution-report` are **skills only** (no slash command needed) — they auto-activate when you describe the task in natural language.
+
 **`~/.claude/skills/`** — Auto-activate by semantic matching, no slash command needed:
 
 | Skill | Auto-activates when you say... |
@@ -122,6 +168,13 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 | `hopla-prime` | "orient yourself", "ponte al día", "what is this project" |
 | `hopla-code-review` | "review the code", "code review", "analiza los cambios" |
 | `hopla-execution-report` | "generate the report", "genera el reporte", "document what was done" |
+| `hopla-verify` | "verify it works", "make sure it's correct", "check before finishing" |
+| `hopla-brainstorm` | "let's brainstorm", "explore approaches", "design this before coding" |
+| `hopla-debug` | "debug this", "find the bug", "why is this failing" |
+| `hopla-tdd` | "write tests first", "TDD", "red-green-refactor" |
+| `hopla-subagent-execution` | "use subagents", "execute with agents", plans with 5+ tasks |
+| `hopla-parallel-dispatch` | "run in parallel", "parallelize this", independent tasks |
+| `hopla-worktree` | "use a worktree", "isolated branch", "parallel feature work" |
 
 **`~/.claude/hooks/`** — Run automatically before/after tool use (configured in `~/.claude/settings.json`):
 
@@ -131,18 +184,51 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 | `env-protect.js` | PreToolUse | Blocks reads/greps targeting `.env` files |
 | `session-prime.js` | SessionStart (opt-in) | Loads git context + CLAUDE.md summary at session start |
 
+**`~/.claude/agents/`** — Specialized subagents for delegation:
+
+| Agent | What it does |
+|---|---|
+| `code-reviewer` | Senior code reviewer (model: sonnet, read-only). Reviews plan alignment, code quality, architecture, logic, security, performance |
+| `codebase-researcher` | Fast codebase explorer (model: haiku, read-only). Systematic search and structured findings |
+| `system-reviewer` | System review analyst (model: sonnet, read-only). Analyzes execution vs plan, classifies divergences |
+
+**`~/.claude/commands/guides/`** — Reference guides loaded on-demand:
+
+| Guide | What it covers |
+|---|---|
+| `mcp-integration.md` | How to integrate MCP servers into the PIV loop |
+| `ai-optimized-codebase.md` | Vertical slice architecture, LLM-friendly docstrings, strict types |
+| `hooks-reference.md` | All hook types, configuration, input JSON, exit codes, debugging |
+| `write-skill.md` | How to create new skills with CSO, testing, progressive disclosure |
+| `remote-coding.md` | GitHub-based remote agentic coding with autonomy levels |
+| `scaling-beyond-engineering.md` | Expanding HOPLA to non-technical teams with 4D Framework |
+| `data-audit.md` | Data pipeline audit checklist |
+| `review-checklist.md` | Code review checklist reference |
+
 **Installed layout:**
 
 ```
 ~/.claude/
 ├── CLAUDE.md              ← Global rules
 ├── commands/
-│   └── hopla-*.md         ← Slash commands (/hopla-prime, /hopla-execute, etc.)
+│   ├── hopla-*.md         ← Slash commands (/hopla-prime, /hopla-execute, etc.)
+│   └── guides/            ← Reference guides (loaded on-demand by commands/skills)
 ├── skills/
 │   ├── hopla-git/         ← Auto-activates for commit/PR requests
 │   ├── hopla-prime/       ← Auto-activates for orientation requests
 │   ├── hopla-code-review/ ← Auto-activates for review requests
-│   └── hopla-execution-report/ ← Auto-activates for report requests
+│   ├── hopla-execution-report/ ← Auto-activates for report requests
+│   ├── hopla-verify/      ← Auto-activates for verification before completion
+│   ├── hopla-brainstorm/  ← Auto-activates for design exploration
+│   ├── hopla-debug/       ← Auto-activates for systematic debugging
+│   ├── hopla-tdd/         ← Auto-activates for test-driven development
+│   ├── hopla-subagent-execution/ ← Auto-activates for multi-task plans
+│   ├── hopla-parallel-dispatch/  ← Auto-activates for parallel work
+│   └── hopla-worktree/    ← Auto-activates for isolated branch work
+├── agents/
+│   ├── code-reviewer.md   ← Senior code review subagent
+│   ├── codebase-researcher.md ← Fast codebase exploration subagent
+│   └── system-reviewer.md ← Execution vs plan analysis subagent
 ├── hooks/
 │   ├── tsc-check.js       ← TypeScript type checking after edits
 │   ├── env-protect.js     ← .env file protection
@@ -163,23 +249,35 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
 
 ### Feature development (PIV loop)
 ```
-/hopla-prime            → load context at session start
+"ponte al día"          → hopla-prime skill auto-loads project context
 /hopla-plan-feature     → research codebase and create plan
 /hopla-review-plan      → review plan summary and approve
 /hopla-execute          → implement the plan with validation
-/hopla-code-review      → standalone review of changes
+/hopla-validate         → run lint → types → tests → integration
+"review the code"       → hopla-code-review skill runs automatically
 /hopla-code-review-fix  → fix issues found
-/hopla-execution-report → document what was built
+/hopla-rca              → root cause analysis if a bug is found
+"genera el reporte"     → hopla-execution-report skill documents what was built
 /hopla-git-commit       → save to git
 /hopla-git-pr           → open pull request on GitHub
 ```
 
+### Full automation (one command)
+```
+/hopla-end-to-end       → runs the entire PIV loop: prime → brainstorm → plan → execute → validate → commit
+```
+
 ### After implementation
 ```
 /hopla-system-review    → analyze plan vs. actual for process improvements
 ```
 
-> **Tip:** `hopla-prime`, `hopla-git-commit`, `hopla-git-pr`, `hopla-code-review`, and `hopla-execution-report` also exist as skills — they auto-activate when you describe what you want in natural language, without typing the slash command.
+### For non-technical users
+```
+/hopla-guide            → 4D Framework walkthrough (Description, Discernment, Delegation, Diligence)
+```
+
+> **Tip:** Many commands also exist as skills — they auto-activate when you describe what you want in natural language. For example, saying "debug this" triggers `hopla-debug`, and "let's brainstorm" triggers `hopla-brainstorm`, without typing any slash command.
 
 ---
 
@@ -192,7 +290,9 @@ Commands are modular — the output of one becomes the input of the next. Some c
 | Command | Argument | Example |
 |---|---|---|
 | `/hopla-execute` | Path to plan file | `/hopla-execute .agents/plans/auth-feature.md` |
+| `/hopla-end-to-end` | Feature description | `/hopla-end-to-end add user authentication` |
 | `/hopla-code-review-fix` | Path to review report or description | `/hopla-code-review-fix .agents/code-reviews/auth-review.md` |
+| `/hopla-rca` | Bug description or error message | `/hopla-rca "login fails with 403 after token refresh"` |
 | `/hopla-system-review` | Plan file + execution report | `/hopla-system-review .agents/plans/auth-feature.md .agents/execution-reports/auth-feature.md` |
 
 ### Full PIV loop example
@@ -209,36 +309,41 @@ Commands are modular — the output of one becomes the input of the next. Some c
 /hopla-execute .agents/plans/add-user-authentication.md
 → implements the plan, runs validation
 
-# 4. Code review
-/hopla-code-review
+# 4. Validate
+/hopla-validate
+→ runs lint → types → tests → integration
+
+# 5. Code review (auto-triggered skill — just say "review the code")
 → saves: .agents/code-reviews/add-user-authentication.md
 
-# 5. Fix issues
+# 6. Fix issues
 /hopla-code-review-fix .agents/code-reviews/add-user-authentication.md
 
-# 6. Document
-/hopla-execution-report
+# 7. Document (auto-triggered skill — just say "genera el reporte")
 → saves: .agents/execution-reports/add-user-authentication.md
 
-# 7. Commit
+# 8. Commit
 /hopla-git-commit
 
-# 8. Pull request
+# 9. Pull request
 /hopla-git-pr
 
-# 9. Process improvement (after PR merge)
+# 10. Process improvement (after PR merge)
 /hopla-system-review .agents/plans/add-user-authentication.md .agents/execution-reports/add-user-authentication.md
 ```
 
+> **Or do it all in one command:** `/hopla-end-to-end add user authentication`
+
 ---
 
 ## Roadmap
 
 Features under consideration for future versions:
 
-- **Custom subagents** (`.claude/agents/`) — Define specialized agents with their own instructions and skills for large projects with isolated domains (e.g. frontend agent, backend agent)
+- **Domain-specific agents** — Project-level custom agents beyond the 3 built-in ones (e.g. frontend agent, backend agent, database agent)
 - **Hook templates** — Installable hook patterns beyond tsc-check and env-protect (e.g. query deduplication, notification hooks)
-- **GitHub Actions integration** — Automated PR reviews and `@claude` mentions via GitHub App
+- **GitHub Actions integration** — Automated PR reviews and `@claude` mentions via GitHub App (see `guides/remote-coding.md`)
+- **Team dashboards** — Aggregate execution reports and system reviews across team members
 
 ---
 
@@ -250,7 +355,9 @@ project/
 ├── CLAUDE.md                      ← Project rules and stack (from /hopla-init-project)
 ├── .agents/
 │   ├── plans/                     ← Implementation plans (commit these)
+│   ├── specs/                     ← Design specs from brainstorming (commit these)
 │   ├── guides/                    ← On-demand reference guides (commit these)
+│   ├── rca/                       ← Root cause analysis docs (commit these)
 │   ├── execution-reports/         ← Post-implementation reports (don't commit)
 │   ├── code-reviews/              ← Code review reports (don't commit)
 │   └── system-reviews/            ← Process improvement reports (don't commit)

package/agents/code-reviewer.md

@@ -0,0 +1,62 @@
+---
+name: code-reviewer
+description: "Senior code reviewer agent for thorough code quality analysis. Use this agent to review completed code changes with fresh context, catching issues the implementer might miss."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+You are a Senior Code Reviewer. Your job is to review code changes thoroughly and provide actionable feedback.
+
+## Your Review Process
+
+1. **Plan Alignment**: Does the code match what was planned? Are there unexplained deviations?
+2. **Code Quality**: Is the code clean, readable, and following project conventions?
+3. **Architecture & Design**: Do the patterns fit? Is the abstraction level appropriate?
+4. **Logic & Correctness**: Are there bugs, edge cases, or race conditions?
+5. **Security**: Any secrets, injection vectors, missing validation, or XSS risks?
+6. **Performance**: Any obvious N+1 queries, unnecessary re-renders, or memory leaks?
+
+## Issue Categories
+
+Classify every issue as:
+- **Critical**: Must fix before merge. Bugs, security issues, data loss risks
+- **Important**: Should fix before merge. Logic errors, missing validation, poor patterns
+- **Suggestion**: Nice to have. Style improvements, minor optimizations
+
+## Communication Rules
+
+- **Start with what's good** — Always acknowledge well-done work before listing issues
+- **Be specific** — Include file path, line number, and exact suggestion
+- **Explain WHY** — Don't just say "this is wrong", explain the impact
+- **Suggest fixes** — Don't just complain, propose a solution
+- **Stay objective** — Review the code, not the coder
+
+## Output Format
+
+Save your review to `.agents/code-reviews/[feature-name].md` with:
+```
+# Code Review: [Feature Name]
+
+## Summary
+[1-2 sentences: overall assessment]
+
+## What's Done Well
+- [positive observations]
+
+## Issues Found
+
+### Critical
+| File | Line | Issue | Suggestion |
+|------|------|-------|------------|
+
+### Important
+| File | Line | Issue | Suggestion |
+|------|------|-------|------------|
+
+### Suggestions
+| File | Line | Issue | Suggestion |
+|------|------|-------|------------|
+
+## Verdict
+[APPROVE / REQUEST CHANGES / NEEDS DISCUSSION]
+```

package/agents/codebase-researcher.md

@@ -0,0 +1,41 @@
+---
+name: codebase-researcher
+description: "Fast codebase exploration agent for research tasks. Use this agent to investigate code, find patterns, map dependencies, or gather context without polluting the main conversation."
+model: haiku
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+You are a Codebase Researcher. Your job is to quickly explore a codebase and report findings.
+
+## Your Process
+
+1. Understand the research question
+2. Search the codebase systematically (Glob for files, Grep for patterns, Read for content)
+3. Organize findings clearly
+4. Report back with specific file paths, line numbers, and code examples
+
+## Output Format
+
+Always structure your findings as:
+```
+# Research: [Topic]
+
+## Files Found
+- path/to/file.ts — [what it contains and why it's relevant]
+
+## Patterns Observed
+- [pattern 1 with code example]
+- [pattern 2 with code example]
+
+## Key Findings
+[Most important discoveries, ordered by relevance]
+
+## Recommendations
+[How this information should be used]
+```
+
+## Rules
+- Be thorough but fast — check all relevant directories
+- Include specific line numbers when referencing code
+- Report what you DON'T find too — negative results are valuable
+- Don't modify any files — you are read-only

package/agents/system-reviewer.md

@@ -0,0 +1,64 @@
+---
+name: system-reviewer
+description: "System review agent that analyzes execution reports against plans to identify process improvements. Use after feature completion to find patterns and improve the development system."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+You are a System Reviewer. Your job is to analyze how well the implementation matched the plan and suggest process improvements.
+
+## Your Process
+
+1. **Read the plan** — Understand what was intended
+2. **Read the execution report** — Understand what actually happened
+3. **Identify divergences** — Where did reality differ from the plan?
+4. **Classify divergences**:
+   - **Good divergence**: Found a better approach, justified deviation
+   - **Bad divergence**: Missed requirements, ignored constraints, skipped steps
+5. **Trace root causes** — Why did each divergence happen?
+6. **Suggest improvements** — What should change to prevent bad divergences?
+
+## Improvement Decision Matrix
+
+| Pattern | Action |
+|---------|--------|
+| Issue appears in ALL features | Update 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 |
+| First occurrence | Document, don't over-engineer |
+
+## Output Format
+
+Save to `.agents/system-reviews/[feature-name].md`:
+```
+# System Review: [Feature Name]
+
+## Alignment Score: [X/10]
+
+## Good Divergences
+- [What changed and why it was better]
+
+## Bad Divergences
+- [What was missed and why]
+
+## Root Causes
+- [Why each bad divergence happened]
+
+## Recommended Improvements
+
+### CLAUDE.md Updates
+- [Specific changes to project rules]
+
+### Command Updates
+- [Specific changes to commands]
+
+### New Commands/Skills Needed
+- [Gaps in the current system]
+
+### Process Changes
+- [Workflow improvements]
+
+## Key Learnings
+- [Insights worth remembering]
+```