@hopla/claude-setup 1.10.1 → 1.11.0

package/commands/guides/ai-optimized-codebase.md

@@ -0,0 +1,70 @@
+# AI-Optimized Codebase Guide
+
+## When to Use This Guide
+Reference this guide when initializing a project with `/hopla-init-project` or when optimizing an existing codebase for better AI-assisted development.
+
+## Principles
+
+### 1. Vertical Slice Architecture
+Organize code by feature, not by layer:
+```
+src/
+├── core/           # Universal infrastructure (config, database, logging)
+├── shared/         # Code used by 3+ features (the "three-feature rule")
+└── features/       # Independent vertical slices
+    ├── auth/       # routes + service + models + tests
+    ├── products/   # routes + service + models + tests
+    └── orders/     # routes + service + models + tests
+```
+
+**Why**: AI can load an entire feature in one context window. Layer-based organization scatters context across many files.
+
+### 2. LLM-Friendly Docstrings
+Write docstrings that help AI understand code:
+```typescript
+/**
+ * PURPOSE: Calculate total order cost including tax and discounts
+ * INPUTS: items (OrderItem[]), taxRate (number), discount? (Discount)
+ * OUTPUTS: { subtotal, tax, discount, total } (all in cents)
+ * GOTCHA: All monetary values are in cents to avoid floating point issues
+ * EXAMPLE: calculateTotal([{price: 1000, qty: 2}], 0.08) → {subtotal: 2000, tax: 160, total: 2160}
+ */
+```
+
+### 3. Structured Logging
+Use JSON-structured logs with context for AI parsing:
+```typescript
+logger.info("order_created", {
+  correlation_id: req.id,
+  order_id: order.id,
+  items_count: items.length,
+  total_cents: total,
+  duration_ms: Date.now() - start
+});
+```
+
+**Never**: Log sensitive data, use string formatting, spam in loops
+
+### 4. Strict Type Safety
+- Enable strict TypeScript (`strict: true` in tsconfig)
+- For Python: use mypy (strict) + pyright
+- Types serve as contracts that AI can read and follow
+
+### 5. Comprehensive Validation Commands
+Include in CLAUDE.md:
+```markdown
+## Development Commands
+- `npm run lint` — ESLint check
+- `npm run typecheck` — TypeScript strict check
+- `npm run test` — Unit tests
+- `npm run test:integration` — Integration tests
+- `npm run dev` — Development server
+```
+
+### 6. Test Structure Mirrors Source
+```
+src/features/auth/auth.service.ts
+src/features/auth/__tests__/auth.service.test.ts
+```
+
+AI can find tests by convention, no configuration needed.

package/commands/guides/hooks-reference.md

@@ -0,0 +1,82 @@
+# Hooks Reference Guide
+
+## When to Use This Guide
+Reference this guide when creating custom hooks or troubleshooting existing ones.
+
+## Hook Types
+
+| Hook | When It Fires | Can Block? | Use For |
+|------|---------------|------------|---------|
+| PreToolUse | Before any tool call | Yes (exit 2) | Blocking dangerous operations |
+| PostToolUse | After any tool call | No | Feedback, auto-formatting, validation |
+| Notification | When Claude needs permission or after 60s inactivity | No | Custom notifications |
+| Stop | When Claude finishes responding | No | Post-response automation |
+| SubagentStop | When a subagent finishes | No | Subagent result processing |
+| PreCompact | Before /compact operation | No | Saving context before compaction |
+| UserPromptSubmit | When user submits a prompt | Yes (exit 2) | Input validation, routing |
+| SessionStart | When session begins | No | Context loading, setup |
+| SessionEnd | When session ends | No | Cleanup, logging |
+
+## Hook Configuration
+
+Hooks are configured in settings.json (global, project, or local):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/absolute/path/to/hook.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Hook Input (stdin JSON)
+
+```json
+{
+  "session_id": "...",
+  "transcript_path": "...",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Read",
+  "tool_input": {
+    "file_path": "/code/.env"
+  }
+}
+```
+
+## Exit Codes
+- `0` — Allow operation to proceed
+- `2` — Block operation (PreToolUse only)
+- Stderr output → shown to Claude as feedback when blocking
+
+## Security Best Practices
+- **ALWAYS use absolute paths** for hook scripts (prevents path hijacking)
+- Use `$PWD` placeholders in version control, replace with absolute paths on setup
+- Never run hooks from user-writable directories without verification
+
+## Debugging Hooks
+
+Log all hook data to inspect the structure:
+```json
+"PostToolUse": [{
+  "matcher": "*",
+  "hooks": [{
+    "type": "command",
+    "command": "jq . > /tmp/hook-debug.json"
+  }]
+}]
+```
+
+## HOPLA Installed Hooks
+- **tsc-check.js** (PostToolUse): Runs TypeScript type checking after file edits
+- **env-protect.js** (PreToolUse): Blocks reads of .env files
+- **session-prime.js** (SessionStart): Provides project context at session start

package/commands/guides/mcp-integration.md

@@ -0,0 +1,32 @@
+# MCP Integration Guide
+
+## When to Use This Guide
+Reference this guide when planning features that involve external tools or services available via MCP.
+
+## MCP in the PIV Loop
+
+### During Planning (`/hopla-plan-feature`)
+- Check what MCP servers are configured (listed in 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"
+
+### During Execution (`/hopla-execute`)
+- Before starting, verify MCP servers are available and responsive
+- When a task involves an MCP tool, use it explicitly (don't fall back to manual alternatives)
+- If an MCP server is unavailable, document it and skip that validation step
+
+### During Validation (`/hopla-validate`)
+- Use Playwright MCP for E2E browser validation if configured
+- Use database MCPs to verify data state after migrations
+- Document which validations were done via MCP vs. manual
+
+## Common MCP Patterns
+- **Playwright**: Browser automation for E2E testing and visual verification
+- **Database (Supabase, D1, etc.)**: Schema management, data verification
+- **API testing**: Endpoint verification, response validation
+- **File systems**: Cross-system file operations
+
+## 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
+3. Pre-approve permissions in settings to avoid repeated prompts

package/commands/guides/remote-coding.md

@@ -0,0 +1,70 @@
+# Remote Agentic Coding Guide (Future)
+
+## When to Use This Guide
+Reference this guide when setting up GitHub-based automation for remote code generation.
+
+## Overview
+
+Remote agentic coding moves AI-assisted development from your local terminal to GitHub, enabling:
+- Issue-driven development (create issue → agent implements → PR created)
+- Automated code review on PRs
+- Release note generation from commit history
+- Parallel feature development across multiple agents
+
+## Three Autonomy Levels
+
+### Level 1: Hybrid (Recommended Starting Point)
+- **Agent**: Creates branch, implements, comments on issue
+- **Human**: Reviews PR, makes final decision to merge
+- **Setup**: GitHub Actions + Claude Code CLI
+
+### Level 2: Autonomous
+- **Agent**: Everything including PR creation and merge
+- **Human**: Only monitors
+- **Setup**: GitHub Actions + full permissions
+
+### Level 3: Deterministic
+- **Workflow**: Controls process (branch creation, PR management)
+- **Agent**: Only responsible for code changes
+- **Setup**: Strict GitHub Actions workflow
+
+## GitHub Actions Workflow (Level 1)
+
+```yaml
+name: Claude Code Agent
+on:
+  issues:
+    types: [assigned]
+  issue_comment:
+    types: [created]
+
+jobs:
+  agent:
+    if: contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Claude Code
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          npx claude-code --print "
+            Read issue #${{ github.event.issue.number }}.
+            /hopla-plan-feature based on the issue requirements.
+            /hopla-execute the plan.
+            /hopla-validate
+            Create a PR with the results.
+          "
+```
+
+## Prerequisites
+- HOPLA commands installed in the repo (.claude/commands/)
+- CLAUDE.md configured for the project
+- GitHub Actions enabled
+- Claude Code API key in GitHub Secrets
+
+## Best Practices
+- Start with Level 1 (hybrid) until you trust the system
+- Always require human PR review
+- Use conventional commits for automated changelog generation
+- Set up branch protection rules to prevent direct merges

package/commands/guides/scaling-beyond-engineering.md

@@ -0,0 +1,54 @@
+# Scaling Agentic Coding Beyond Engineering
+
+## When to Use This Guide
+Reference this guide when expanding HOPLA usage to non-technical team members.
+
+## The Opportunity
+
+According to Anthropic's 2026 Agentic Coding Trends Report:
+- Non-technical teams (legal, sales, marketing, ops) are building their own solutions
+- The barrier between "people who code" and "people who don't" is becoming permeable
+- Domain experts implementing solutions directly removes bottlenecks
+
+## HOPLA's Planning Mode
+
+HOPLA already supports non-technical users via `--planning` mode:
+- Restricted command set (planning and review only)
+- Limited git permissions (read-only)
+- Focus on product decisions, not implementation
+
+## Expanding the Model
+
+### Phase 1: Product Planning (Current)
+Non-technical users can:
+- Create PRDs with `/hopla-create-prd`
+- Plan features with `/hopla-plan-feature`
+- Review plans with `/hopla-review-plan`
+- Guide workflow with `/hopla-guide` (4D Framework)
+
+### Phase 2: Assisted Creation (Future)
+Non-technical users could:
+- Create simple automations with guided workflows
+- Generate reports from existing data
+- Build simple dashboards with AI assistance
+- Create documentation from templates
+
+### Phase 3: Domain Expert Development (Future)
+Domain experts could:
+- Implement domain-specific logic with AI guidance
+- Create and modify business rules
+- Build prototype interfaces
+- Automate repetitive workflows
+
+## The 4D Framework for Non-Technical Users
+
+1. **Description**: Communicate clearly what you need (context-rich prompts)
+2. **Discernment**: Evaluate critically what the AI produces
+3. **Delegation**: Choose what AI handles vs. what you handle
+4. **Diligence**: Take responsibility for outputs, test before deploying
+
+## Success Metrics
+- Time to first productive output for new non-technical users
+- Quality of plans produced (review scores)
+- Reduction in engineer bottleneck for planning tasks
+- User satisfaction and confidence scores

package/commands/guides/write-skill.md

@@ -0,0 +1,78 @@
+# Writing Skills Guide (Internal)
+
+## When to Use This Guide
+Reference this guide when creating new skills for the HOPLA system.
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md              (< 500 lines, main instructions)
+├── scripts/              (executable code — only output consumes tokens)
+├── references/           (detailed docs, loaded on-demand)
+└── assets/               (templates, data files)
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: skill-name
+description: "100-150 words. Start with what it does, then 'Use when...' + specific triggers. End with 'Do NOT use for...' anti-triggers."
+allowed-tools: Read, Grep, Glob, Bash  # Optional: restrict tools
+model: sonnet  # Optional: force specific model
+---
+```
+
+## Writing Effective Descriptions
+
+The description is the MOST CRITICAL field — it determines when the skill activates.
+
+### Pattern
+```
+[What the skill does]. Use when [trigger phrases, synonyms, variations in English and Spanish]. Do NOT use for [anti-triggers].
+```
+
+### Good Example
+```
+"Technical code review on changed files. Use when the user says 'review code', 'code review', 'check my code', 'review changes', 'look for bugs', or 'audit code'. Do NOT use for reviewing plans or documents — only code."
+```
+
+### Bad Example
+```
+"A skill for reviewing things."
+```
+
+## Claude Search Optimization (CSO)
+
+Claude uses SEMANTIC matching, not keyword matching. Cover:
+- Different phrasings of the same intent
+- English AND Spanish triggers (for HOPLA's bilingual users)
+- Common misspellings or abbreviations
+- Related verbs and nouns
+
+## Testing Skills
+
+Before shipping a new skill:
+1. **Pressure test**: Does it activate when it should?
+2. **Negative test**: Does it NOT activate when it shouldn't?
+3. **Conflict test**: Does it conflict with existing skills?
+4. **Content test**: Are the instructions clear enough for the agent to follow?
+
+## Rationalization Tables
+
+For skills that enforce discipline (like TDD or verification), include a table of common excuses:
+
+| Rationalization | Counter |
+|----------------|---------|
+| "I'll do it later" | No. Do it now. Later means never. |
+| "This is too simple" | Simple things grow complex. Document intent. |
+
+## Progressive Disclosure
+
+Keep SKILL.md under 500 lines. If you need more:
+- Put detailed reference material in `references/` subdirectory
+- Put executable logic in `scripts/` subdirectory
+- In SKILL.md, reference them: "When doing X, read references/x-guide.md"
+
+Scripts are better than docs when possible — only the OUTPUT consumes tokens, not the script source.

package/{files/commands → commands}/hopla-code-review-fix.md

@@ -19,6 +19,14 @@ 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.
 
+## Pre-Fix Verification
+
+Before fixing each issue:
+1. **Verify the issue is real** — Read the actual code. Is this a genuine bug or a false positive?
+2. **Push back if needed** — If an issue is not real, document WHY it's a false positive instead of "fixing" it
+3. **YAGNI check** — Does the suggested fix add unnecessary complexity? If the fix introduces code that isn't needed for current requirements, skip it and document the reason
+4. **Never use performative agreement** — Don't say "You're absolutely right!" before verifying. Check the codebase first, then respond.
+
 ## Step 2: Fix Issues One by One
 
 For each issue, in order of severity (critical → high → medium → low):

package/commands/hopla-end-to-end.md

@@ -0,0 +1,67 @@
+# End-to-End Feature Implementation
+
+> Execute the complete PIV loop for a feature in one go: prime → brainstorm → plan → review → execute → validate → commit.
+
+> ⚠️ **Advanced**: Only use this command after you've proven each individual command works reliably. Build trust gradually.
+
+## Input
+- `$ARGUMENTS`: Feature description or requirement
+
+## Autonomy Levels
+
+This command represents **Level 3 autonomy**. Make sure you've mastered:
+- Level 1: Manual prompts (writing everything each time)
+- Level 2: Individual commands (/hopla-plan-feature, /hopla-execute, etc.)
+- Level 3: Command chaining (this command)
+
+## Process
+
+### Phase 1: Context Loading
+Load project context:
+- Read CLAUDE.md, README, package.json
+- Check git state (branch, status, pending plans)
+- Identify current development phase
+
+### Phase 2: Brainstorm (if needed)
+If the feature is non-trivial (estimated > 1 hour):
+- Explore 2-3 approaches with trade-offs
+- Get user approval on approach
+- Save design doc to `.agents/specs/`
+
+If trivial: skip to Phase 3.
+
+### Phase 3: Plan
+- Research codebase for related patterns
+- Generate structured implementation plan
+- Save to `.agents/plans/[feature-name].md`
+
+### 🔒 GATE: Plan Review
+**STOP and present the plan to the user.**
+- Show executive summary
+- Wait for explicit approval before proceeding
+- If changes requested: iterate on the plan
+
+### Phase 4: Execute
+- Create feature branch (`feature/[name]` from develop)
+- Execute all plan tasks sequentially
+- Validate after each phase boundary
+
+### Phase 5: Validate
+- Run full validation pyramid (lint → types → tests → integration)
+- Run code review
+- Fix any critical/important issues found
+
+### 🔒 GATE: Human Review
+**STOP and present results to the user.**
+- Show what was built, what was validated
+- Wait for approval before committing
+
+### Phase 6: Commit & PR
+- Create conventional commit(s)
+- Suggest creating a PR if on a feature branch
+
+## Rules
+- Never skip the human gates (plan review, final review)
+- If any phase fails, stop and report — don't push through
+- Each phase should feel like a natural conversation, not a script
+- Adapt: skip brainstorming for small features, skip PR for hotfixes

package/{files/commands → commands}/hopla-execute.md

@@ -3,6 +3,8 @@ description: Execute a structured plan from start to finish with validation
 argument-hint: "<plan-file-path>"
 ---
 
+> 💡 **Tip**: For complex tasks with intricate logic, consider using Extended Thinking mode for better reasoning quality.
+
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
 
 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.

package/commands/hopla-guide.md

@@ -0,0 +1,61 @@
+# HOPLA Guide for Non-Technical Users
+
+> A guided framework for working effectively with your AI coding assistant.
+
+## The 4D Framework
+
+### 📝 Description — Communicate Clearly
+Tell the AI what you need with rich context:
+- What problem are you solving?
+- Who is the user/audience?
+- What does success look like?
+- What constraints exist (budget, timeline, tech)?
+
+**Tip**: The more specific you are, the better the output. "Add a login page" → "Add a login page with email/password, Google OAuth, and a forgot password flow that matches our brand colors."
+
+### 🔍 Discernment — Evaluate Critically
+Don't accept AI output at face value:
+- Does this match what you asked for?
+- Does it make sense for your users?
+- Is the quality acceptable?
+- Would you be comfortable showing this to stakeholders?
+
+**Tip**: Ask the AI to explain its reasoning. If you don't understand the explanation, ask for a simpler one.
+
+### 🤝 Delegation — Choose What AI Does vs. You
+Three categories for every task:
+
+| Category | Examples |
+|----------|---------|
+| **AI handles** | Writing boilerplate, research, first drafts, data analysis |
+| **AI assists, you review** | Feature plans, PRDs, code reviews, documentation |
+| **You handle** | Final decisions, stakeholder communication, business strategy |
+
+### ✅ Diligence — Take Responsibility
+- **Creation diligence**: Verify outputs before sharing
+- **Deployment diligence**: Test before using in production
+- **Transparency diligence**: Document when AI was used
+
+## Your Available Commands
+
+### For Planning & Product
+- `/hopla-create-prd` — Create a Product Requirements Document through guided conversation
+- `/hopla-plan-feature` — Create an implementation plan (AI researches, you approve)
+- `/hopla-review-plan` — Review a plan before execution
+
+### For Oversight
+- `/hopla-system-review` — Analyze how well the AI followed the plan
+- `/hopla-guide` — Show this guide again
+
+## Getting Started
+
+1. Start with `/hopla-create-prd` to define your project scope
+2. Use `/hopla-plan-feature "your feature idea"` to plan each feature
+3. Review the plan with `/hopla-review-plan`
+4. Hand off to a developer for execution, or ask the AI to execute
+
+## Tips for Better Results
+- One request at a time — don't overload with multiple asks
+- Be specific about what you want, not how to build it
+- If the output isn't right, say what's wrong rather than starting over
+- Use the review loop: the AI expects your feedback before proceeding

package/{files/commands → commands}/hopla-plan-feature.md

@@ -3,6 +3,8 @@ description: Research the codebase and create a structured implementation plan f
 argument-hint: "<feature-name-or-description>"
 ---
 
+> 💡 **Tip**: Activate Plan Mode (`Shift+Tab` twice) before running this command for deeper codebase exploration. For complex features, use Extended Thinking for better reasoning.
+
 > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
 
 Transform the requirements discussed in this conversation into a structured plan that another agent can execute without access to this conversation.
@@ -72,6 +74,8 @@ Based on research, define:
 - **Bidirectional data interactions:** If feature A updates data that feature B displays, does B need to react? If adding an item triggers validation, does editing trigger re-validation? Map all data mutation → side effect chains, not just keyboard navigation. Missed bidirectional interactions were a recurring planning blind spot.
 - **AI/LLM prompt tasks:** If the plan involves creating or modifying AI prompts (system prompts, prompt templates, LLM-based features), add an explicit task for testing against real data with 2-3 iteration cycles budgeted. AI prompt engineering rarely works on the first attempt.
 - **User preferences check:** Before specifying UI architecture (modal vs. inline, page vs. panel, dialog vs. drawer), verify against MEMORY.md and conversation history for established preferences. In past implementations, plans that specified modals were rejected because the user preferred inline panels — this caused rework. When no preference exists, note it as a decision point for the user to confirm.
+- **Reuse context analysis:** When a new view reuses an existing component in a different context (e.g., a list component in a "history" view vs. an "active" view), the plan MUST list what's different about the new context's requirements: different columns, different data filters, different interactions, different toolbar layout. Missed context differences caused 40%+ of unplanned work in past implementations.
+- **Multi-phase plan guidance:** For features requiring 3+ phases, create an architectural plan (`backlog/NN-feature.md`) with schema, phase boundaries, and target architecture. When executing each phase, create a standalone plan (`phase-NX-description.md`) with full task-level detail following this template. The architectural plan is the spec; phase plans are the execution instructions. Each phase should have its own feature branch and PR.
 
 ## Phase 5: Generate the Plan
 

package/commands/hopla-rca.md

@@ -0,0 +1,64 @@
+# Root Cause Analysis
+
+> Investigate a bug or issue and produce a structured RCA document.
+
+> 💡 **Tip**: Use Extended Thinking mode for complex bugs with multiple possible causes.
+
+## Input
+- `$ARGUMENTS`: Issue description, error message, or GitHub issue ID/URL
+
+## Process
+
+### Step 1: Gather Information
+- If a GitHub issue: read the full issue, comments, and any linked PRs
+- If an error: read the full error message and stack trace
+- Run `git log --oneline -20` to check recent changes
+- Run `git diff` to see current uncommitted changes
+
+### Step 2: Investigate
+- Search the codebase for the affected code: `grep`, `glob`, `read`
+- Identify the function/component where the error originates
+- Check git blame for recent changes to that area
+- Look for related tests — do they pass? Are they missing?
+
+### Step 3: Root Cause Analysis
+Apply the hopla-debug methodology:
+1. **Reproduce**: Can you trigger the issue?
+2. **Narrow**: Which exact file and line?
+3. **Hypothesize**: What's the most likely cause based on evidence?
+4. **Verify**: Can you confirm the hypothesis?
+
+### Step 4: Generate RCA Document
+Save to `.agents/rca/[issue-name].md`:
+
+```
+# RCA: [Issue Title]
+
+## Symptoms
+What the user sees / what the error is
+
+## Root Cause
+What's actually wrong and why
+
+## Evidence
+- [file:line] — what you found
+- [git commit] — what changed
+
+## Proposed Fix
+What needs to change to resolve this
+
+## Tests Needed
+- Test to reproduce the bug
+- Test to verify the fix
+
+## Prevention
+How to prevent similar issues in the future
+
+## Next Steps
+- [ ] Implement fix (run `/hopla-execute` with a plan, or fix directly if simple)
+- [ ] Add regression test
+- [ ] Validate with `/hopla-validate`
+```
+
+## Output
+The RCA document in `.agents/rca/`, ready for review or execution.

package/{files/commands → commands}/hopla-validate.md

@@ -64,6 +64,11 @@ If everything passes, confirm the project is healthy.
 
 If anything failed and could not be fixed, list the remaining issues and suggest next steps.
 
+## After Validation Passes
+
+- Suggest running `/hopla-code-review` if not already done
+- Remind that completion claims must be backed by this fresh validation evidence (see hopla-verify skill)
+
 ## Next Step
 
 After validation passes, suggest: