@hopla/claude-setup 1.10.2 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/.claude-plugin/marketplace.json +20 -0
  2. package/.claude-plugin/plugin.json +23 -0
  3. package/README.md +127 -30
  4. package/agents/code-reviewer.md +62 -0
  5. package/agents/codebase-researcher.md +41 -0
  6. package/agents/system-reviewer.md +64 -0
  7. package/cli.js +45 -14
  8. package/commands/guides/ai-optimized-codebase.md +70 -0
  9. package/commands/guides/hooks-reference.md +82 -0
  10. package/commands/guides/mcp-integration.md +32 -0
  11. package/commands/guides/remote-coding.md +70 -0
  12. package/commands/guides/scaling-beyond-engineering.md +54 -0
  13. package/commands/guides/write-skill.md +78 -0
  14. package/{files/commands → commands}/hopla-code-review-fix.md +8 -0
  15. package/commands/hopla-end-to-end.md +67 -0
  16. package/{files/commands → commands}/hopla-execute.md +2 -0
  17. package/commands/hopla-guide.md +61 -0
  18. package/{files/commands → commands}/hopla-plan-feature.md +2 -0
  19. package/commands/hopla-rca.md +64 -0
  20. package/{files/commands → commands}/hopla-validate.md +5 -0
  21. package/{files/CLAUDE.md → global-rules.md} +45 -0
  22. package/hooks/hooks.json +40 -0
  23. package/{files/hooks → hooks}/session-prime.js +13 -0
  24. package/package.json +7 -2
  25. package/skills/hopla-brainstorm/SKILL.md +89 -0
  26. package/{files/skills → skills}/hopla-code-review/SKILL.md +2 -1
  27. package/skills/hopla-debug/SKILL.md +73 -0
  28. package/{files/skills → skills}/hopla-execution-report/SKILL.md +3 -1
  29. package/{files/skills → skills}/hopla-git/SKILL.md +1 -1
  30. package/skills/hopla-parallel-dispatch/SKILL.md +69 -0
  31. package/{files/skills → skills}/hopla-prime/SKILL.md +3 -1
  32. package/skills/hopla-subagent-execution/SKILL.md +70 -0
  33. package/skills/hopla-tdd/SKILL.md +73 -0
  34. package/skills/hopla-verify/SKILL.md +64 -0
  35. package/skills/hopla-worktree/SKILL.md +73 -0
  36. /package/{files/commands → commands}/guides/data-audit.md +0 -0
  37. /package/{files/commands → commands}/guides/review-checklist.md +0 -0
  38. /package/{files/commands → commands}/hopla-create-prd.md +0 -0
  39. /package/{files/commands → commands}/hopla-git-commit.md +0 -0
  40. /package/{files/commands → commands}/hopla-git-pr.md +0 -0
  41. /package/{files/commands → commands}/hopla-init-project.md +0 -0
  42. /package/{files/commands → commands}/hopla-review-plan.md +0 -0
  43. /package/{files/commands → commands}/hopla-system-review.md +0 -0
  44. /package/{files/hooks → hooks}/env-protect.js +0 -0
  45. /package/{files/hooks → hooks}/tsc-check.js +0 -0
  46. /package/{files/skills → skills}/hopla-git/commit.md +0 -0
  47. /package/{files/skills → skills}/hopla-git/pr.md +0 -0
@@ -0,0 +1,40 @@
1
+ {
2
+ "hooks": {
3
+ "PostToolUse": [
4
+ {
5
+ "matcher": "Write|Edit|MultiEdit",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/tsc-check.js\"",
10
+ "async": false
11
+ }
12
+ ]
13
+ }
14
+ ],
15
+ "PreToolUse": [
16
+ {
17
+ "matcher": "Read|Grep",
18
+ "hooks": [
19
+ {
20
+ "type": "command",
21
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/env-protect.js\"",
22
+ "async": false
23
+ }
24
+ ]
25
+ }
26
+ ],
27
+ "SessionStart": [
28
+ {
29
+ "matcher": "startup|clear|compact",
30
+ "hooks": [
31
+ {
32
+ "type": "command",
33
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-prime.js\"",
34
+ "async": false
35
+ }
36
+ ]
37
+ }
38
+ ]
39
+ }
40
+ }
@@ -40,6 +40,19 @@ async function main() {
40
40
  lines.push(`Project rules (CLAUDE.md excerpt):\n${content}`);
41
41
  }
42
42
 
43
+ // Available skills reminder
44
+ lines.push(`📦 HOPLA Skills Available:
45
+ - hopla-prime: Project orientation (trigger: "orient", "get context", "load project")
46
+ - hopla-git: Git operations (trigger: "commit", "PR", "push")
47
+ - hopla-code-review: Code review (trigger: "review code", "code review")
48
+ - hopla-execution-report: Post-implementation docs (trigger: "generate report")
49
+ - hopla-verify: Completion verification (trigger: any "done"/"listo"/"finished" claim)
50
+ - hopla-brainstorm: Design exploration (trigger: "new feature", "brainstorm", "explore options")
51
+ - hopla-debug: Systematic debugging (trigger: "bug", "error", "debug")
52
+ - hopla-tdd: Test-driven development (trigger: implementing with tests)
53
+
54
+ ⚠️ If a skill applies to the current task, you MUST use it.`);
55
+
43
56
  if (lines.length > 0) {
44
57
  process.stdout.write(lines.join("\n\n"));
45
58
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hopla/claude-setup",
3
- "version": "1.10.2",
3
+ "version": "1.11.0",
4
4
  "description": "Hopla team agentic coding system for Claude Code",
5
5
  "type": "module",
6
6
  "bin": {
@@ -9,7 +9,12 @@
9
9
  },
10
10
  "files": [
11
11
  "cli.js",
12
- "files/"
12
+ "global-rules.md",
13
+ "commands/",
14
+ "skills/",
15
+ "agents/",
16
+ "hooks/",
17
+ ".claude-plugin/"
13
18
  ],
14
19
  "engines": {
15
20
  "node": ">=18"
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: hopla-brainstorm
3
+ description: "Design exploration and brainstorming before planning. Use when the user wants to explore options for a new feature, discuss approaches, design a solution, brainstorm ideas, or evaluate trade-offs. Trigger on: 'new feature', 'brainstorm', 'explore options', 'design', 'how should we', 'what approach', 'trade-offs', 'quiero agregar', 'diseñar', 'explorar opciones'. Do NOT use when the user already has a clear plan or is asking to execute existing work."
4
+ ---
5
+
6
+ # Brainstorming: Design Exploration Before Planning
7
+
8
+ ## Purpose
9
+ Explore the problem space and arrive at a validated design BEFORE creating an implementation plan. Bad planning direction = wasted plans.
10
+
11
+ ## Hard Gate
12
+ **Never jump to planning or implementation before the user has approved a design approach.**
13
+
14
+ ## Process
15
+
16
+ ### Step 1: Explore Context
17
+ - Read the project's CLAUDE.md, README, and relevant source files
18
+ - Understand the existing architecture, patterns, and conventions
19
+ - Identify what already exists that relates to this feature
20
+ - Check `.agents/plans/` for any related previous work
21
+
22
+ ### Step 2: Ask Clarifying Questions
23
+ Ask questions **one at a time** (don't overwhelm with a list):
24
+ - What problem are we solving? Who benefits?
25
+ - What does success look like?
26
+ - Are there constraints (performance, timeline, tech stack)?
27
+ - Are there existing patterns in the codebase we should follow or break from?
28
+
29
+ Wait for the user's answer before asking the next question.
30
+
31
+ ### Step 3: Propose Approaches
32
+ Present **2-3 approaches** with clear trade-offs:
33
+
34
+ For each approach:
35
+ - **Name**: A short descriptive name
36
+ - **How it works**: 2-3 sentences
37
+ - **Pros**: What's good about this approach
38
+ - **Cons**: What's risky or complex
39
+ - **Effort estimate**: Low / Medium / High
40
+ - **Best when**: Under what conditions this is the right choice
41
+
42
+ ### Step 4: Design the Chosen Approach
43
+ Once the user selects an approach:
44
+ - Detail the implementation at a conceptual level (not code)
45
+ - Identify files that will be created or modified
46
+ - Map data flow and component interactions
47
+ - Call out edge cases and potential gotchas
48
+ - If helpful, offer a visual companion (ASCII diagram, flow chart)
49
+
50
+ ### Step 5: Write Design Document
51
+ Save to `.agents/specs/YYYY-MM-DD-<topic>.md` with:
52
+ ```
53
+ # Design: [Feature Name]
54
+
55
+ ## Problem
56
+ What we're solving and why
57
+
58
+ ## Chosen Approach
59
+ Which approach and why
60
+
61
+ ## Design
62
+ Conceptual design details
63
+
64
+ ## Files Affected
65
+ - List of files to create/modify
66
+
67
+ ## Edge Cases & Risks
68
+ - Known edge cases
69
+ - Risk areas
70
+
71
+ ## Open Questions
72
+ - Anything still unclear
73
+
74
+ ## Next Step
75
+ Run `/hopla-plan-feature` to create the implementation plan from this design
76
+ ```
77
+
78
+ ### Step 6: Review Loop
79
+ Present the design document for user review.
80
+ - Accept feedback using the `<? ... >` comment syntax
81
+ - Iterate until the user approves
82
+ - Only then suggest: "Design approved! Ready to create the plan with `/hopla-plan-feature`?"
83
+
84
+ ## Rules
85
+ - Never skip to planning without design approval
86
+ - One question at a time — don't overwhelm
87
+ - Always ground proposals in the existing codebase (not abstract theory)
88
+ - If the feature is trivial (< 30 minutes of work), skip the full process — just confirm approach and proceed
89
+ - In planning mode (non-technical users): focus on product decisions, not technical details
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  name: hopla-code-review
3
- description: Performs a technical code review on recently changed files. Use when the user says "review the code", "code review", "check my code", "look for issues", or asks for feedback on their implementation.
3
+ description: "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'. Also use after completing implementation when validation passes. Do NOT use for reviewing plans or documents — only code."
4
+ allowed-tools: Read, Grep, Glob, Bash
4
5
  ---
5
6
 
6
7
  > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: hopla-debug
3
+ description: "Systematic debugging methodology for finding and fixing bugs. Use when encountering errors, bugs, failures, unexpected behavior, or when the user says 'bug', 'error', 'not working', 'failing', 'debug', 'fix', 'broken', 'falla', 'no funciona', 'error'. Do NOT use for planned feature work or refactoring — only for diagnosing and fixing unexpected problems."
4
+ ---
5
+
6
+ # Systematic Debugging
7
+
8
+ ## Core Principle
9
+ **ALWAYS find the root cause before proposing fixes.** Never guess at solutions.
10
+
11
+ ## Phase 1: Root Cause Investigation
12
+
13
+ 1. **Read the full error** — Don't skim. Read every line of the error message, stack trace, and logs
14
+ 2. **Reproduce** — Can you trigger the error reliably? What are the exact steps?
15
+ 3. **Check recent changes** — `git log --oneline -10` and `git diff` — did something change recently?
16
+ 4. **Gather evidence** — What do logs, test output, and error messages tell you?
17
+ 5. **Narrow the scope** — Which file, function, or line is the actual source?
18
+
19
+ ## Phase 2: Pattern Analysis
20
+
21
+ 1. **Find working examples** — Does similar code work elsewhere in the codebase?
22
+ 2. **Compare** — What's different between working and broken code?
23
+ 3. **Identify the pattern** — Is this a known pattern (race condition, stale closure, off-by-one, null reference)?
24
+ 4. **Check dependencies** — Are versions correct? APIs changed?
25
+
26
+ ## Phase 3: Hypothesis and Testing
27
+
28
+ 1. **Form ONE hypothesis** — "The bug is caused by X because of evidence Y"
29
+ 2. **Test minimally** — Make the smallest possible change to validate the hypothesis
30
+ 3. **Verify** — Did the test confirm or refute the hypothesis?
31
+ 4. **If refuted** — Go back to Phase 1 with new information, don't try another random fix
32
+
33
+ ## Phase 4: Implementation
34
+
35
+ 1. **Write a failing test** — Create a test that reproduces the bug
36
+ 2. **Implement the fix** — One fix only. Don't fix other things at the same time
37
+ 3. **Verify the test passes** — The reproduction test should now be green
38
+ 4. **Run full test suite** — Ensure no regressions
39
+ 5. **Document** — Brief comment or commit message explaining the root cause
40
+
41
+ ## The 3-Strike Rule
42
+
43
+ **If 3 fixes fail, STOP.**
44
+
45
+ After 3 failed attempts:
46
+ - The problem is likely architectural, not a simple bug
47
+ - Present findings to the user: "I've tried X, Y, Z. None worked because..."
48
+ - Ask: "Should we reconsider the approach, or do you have additional context?"
49
+ - Do NOT try a 4th random fix
50
+
51
+ ## Red Flags (You're Doing It Wrong If...)
52
+
53
+ - You're proposing a fix before reading the full error
54
+ - You've tried 3+ things without stopping to reassess
55
+ - You're changing code you don't understand
56
+ - You're fixing symptoms instead of causes
57
+ - You're adding workarounds instead of addressing the root issue
58
+ - You say "let me try this" without explaining WHY it should work
59
+
60
+ ## For Multi-Component Systems
61
+
62
+ When the bug spans multiple components (frontend ↔ backend ↔ database):
63
+ 1. Add diagnostic logging at each component boundary
64
+ 2. Trace the data flow: What goes in? What comes out? Where does it break?
65
+ 3. Isolate: Can you reproduce with just one component?
66
+
67
+ ## Output
68
+
69
+ When the bug is fixed, briefly report:
70
+ - **Root cause**: What was actually wrong
71
+ - **Fix**: What was changed and why
72
+ - **Test**: What test verifies the fix
73
+ - **Prevention**: How to prevent similar bugs (if applicable)
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: hopla-execution-report
3
- description: Generates an implementation report documenting what was built. Use when the user says "generate the report", "genera el reporte", "documenta lo implementado", "execution report", "document what was done", "write the implementation report", or after finishing a feature before committing.
3
+ description: "Post-implementation documentation generator. Use when the user says 'generate report', 'document what was done', 'execution report', 'what changed', or after a feature implementation is complete and validated. Do NOT use during implementation — only after completion."
4
+ allowed-tools: Read, Grep, Glob, Bash
5
+ model: sonnet
4
6
  ---
5
7
 
6
8
  > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: hopla-git
3
- description: Handles git operations: creating commits, making pull requests, pushing branches. Use when the user asks to commit, create a commit, save changes to git, make a PR, create a pull request, push the branch, or any git workflow action.
3
+ description: "Git operations handler for commits and pull requests. Use when the user mentions 'commit', 'save changes', 'create commit', 'PR', 'pull request', 'push', 'merge request', or any git workflow action. Do NOT use for git status checks or branch management — only for commits and PRs."
4
4
  ---
5
5
 
6
6
  > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: hopla-parallel-dispatch
3
+ description: "Parallel agent dispatch for independent tasks. Use when 2+ tasks have no shared state and can run simultaneously, during brainstorming to explore multiple approaches, or when the user says 'in parallel', 'simultaneously', 'at the same time'. Do NOT use when tasks have dependencies or share state."
4
+ ---
5
+
6
+ # Parallel Agent Dispatch
7
+
8
+ ## When to Parallelize
9
+
10
+ **Good candidates:**
11
+ - Researching multiple approaches during brainstorming
12
+ - Reviewing independent modules simultaneously
13
+ - Running tests on separate features
14
+ - Investigating different parts of the codebase
15
+ - Implementing truly independent vertical slices
16
+
17
+ **Never parallelize:**
18
+ - Tasks that modify the same files
19
+ - Tasks with data dependencies (Task B needs Task A's output)
20
+ - Tasks that share database state
21
+ - Tasks where order matters
22
+
23
+ ## How to Dispatch
24
+
25
+ ### Step 1: Identify Independent Tasks
26
+ From the current work, identify tasks that:
27
+ - Don't share files
28
+ - Don't share state
29
+ - Can succeed or fail independently
30
+ - Have clear, isolated scope
31
+
32
+ ### Step 2: Create Agent Prompts
33
+ For each parallel task, define:
34
+ - **Scope**: Exactly what this agent should do (and NOT do)
35
+ - **Goal**: Clear success criteria
36
+ - **Constraints**: Files it can touch, patterns to follow
37
+ - **Expected output**: What to report back
38
+
39
+ ### Step 3: Launch in Parallel
40
+ Use the Agent tool with multiple invocations in a single message.
41
+
42
+ ### Step 4: Collect and Merge
43
+ - Wait for all agents to complete
44
+ - Review each agent's output
45
+ - Resolve any unexpected overlaps
46
+ - Validate the combined result
47
+
48
+ ## Common Parallel Patterns
49
+
50
+ ### Brainstorming (3 approaches)
51
+ ```
52
+ Agent 1: "Research approach A for [feature]. Pros, cons, effort estimate."
53
+ Agent 2: "Research approach B for [feature]. Pros, cons, effort estimate."
54
+ Agent 3: "Research approach C for [feature]. Pros, cons, effort estimate."
55
+ ```
56
+
57
+ ### Code Review (by module)
58
+ ```
59
+ Agent 1: "Review changes in src/auth/ for bugs and security issues"
60
+ Agent 2: "Review changes in src/api/ for bugs and performance issues"
61
+ Agent 3: "Review changes in src/ui/ for accessibility and UX issues"
62
+ ```
63
+
64
+ ### Research (multiple areas)
65
+ ```
66
+ Agent 1: "Find all usages of [function] across the codebase"
67
+ Agent 2: "Research how [library] handles [pattern] in their docs"
68
+ Agent 3: "Check if similar functionality exists in our codebase"
69
+ ```
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: hopla-prime
3
- description: Orients Claude in a project at the start of a session. Use when the user says "orient yourself", "get oriented", "prime yourself", "what is this project", "load context", or asks Claude to familiarize itself with the codebase before starting work.
3
+ description: "Project orientation and context loading. Use when starting a session, onboarding to a project, needing to understand the codebase, or when the user says 'orient', 'get context', 'load project', 'what is this project', 'prime', or 'start'. Do NOT use mid-task when the project is already understood."
4
+ allowed-tools: Read, Grep, Glob, Bash
5
+ model: sonnet
4
6
  ---
5
7
 
6
8
  > 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: hopla-subagent-execution
3
+ description: "Subagent-driven execution for large plans. Use when executing plans with 5+ tasks to maintain context quality, when the user says 'use subagents', 'parallel execution', or when context degradation is a concern in long implementations. Do NOT use for small plans (< 5 tasks) or quick fixes."
4
+ ---
5
+
6
+ # Subagent-Driven Execution
7
+
8
+ ## When to Use
9
+ - Plans with 5+ implementation tasks
10
+ - Complex features spanning multiple files/modules
11
+ - When context quality matters more than speed
12
+
13
+ ## How It Works
14
+
15
+ Instead of executing all tasks in one conversation (where context degrades), dispatch a fresh agent per task.
16
+
17
+ ### Per-Task Flow
18
+
19
+ 1. **Dispatch implementer agent** with:
20
+ - The specific task spec (not the full plan)
21
+ - Relevant file paths from the plan
22
+ - Project CLAUDE.md for conventions
23
+ - Clear success criteria
24
+
25
+ 2. **Agent implements, tests, and reports** with status:
26
+ - `DONE` — Task complete, tests pass
27
+ - `DONE_WITH_CONCERNS` — Complete but flagged issues
28
+ - `NEEDS_CONTEXT` — Missing information, needs clarification
29
+ - `BLOCKED` — Cannot proceed, needs human input
30
+
31
+ 3. **Review the result**:
32
+ - Read the agent's output/report
33
+ - Verify files were created/modified correctly
34
+ - Run validation on the changes
35
+
36
+ 4. **If DONE**: Mark task complete, move to next
37
+ 5. **If issues**: Address them before moving on
38
+
39
+ ### Dispatch Template
40
+
41
+ When launching a subagent for a task:
42
+ ```
43
+ Implement this task from the plan:
44
+
45
+ **Task**: [task description]
46
+ **Files**: [files to create/modify]
47
+ **Pattern**: [reference pattern from codebase]
48
+ **Tests**: [tests to write]
49
+ **Validation**: [command to verify]
50
+
51
+ Project conventions are in CLAUDE.md. Follow them strictly.
52
+ Report your status as DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, or BLOCKED.
53
+ ```
54
+
55
+ ### Model Selection
56
+ - Use the least powerful model that can handle the task
57
+ - Simple file creation: `haiku`
58
+ - Standard implementation: `sonnet`
59
+ - Complex logic/architecture: `opus`
60
+
61
+ ### Commit Strategy
62
+ - Don't commit after every task (too noisy)
63
+ - Commit at phase boundaries (every 3-5 tasks)
64
+ - Always validate before committing
65
+
66
+ ## Integration with /hopla-execute
67
+ This skill is an ALTERNATIVE to inline execution. Suggest it when:
68
+ - The plan has 5+ tasks
69
+ - The user expresses concern about quality in long sessions
70
+ - Previous executions showed context degradation issues
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: hopla-tdd
3
+ description: "Test-driven development workflow using the RED-GREEN-REFACTOR cycle. Use when implementing features that require tests, when the plan specifies test tasks, when the user mentions 'TDD', 'test first', 'write tests', or when working on bug fixes that should have regression tests. Do NOT use for documentation, configuration, or tasks where tests don't apply."
4
+ ---
5
+
6
+ # Test-Driven Development (TDD)
7
+
8
+ ## Principle
9
+ **Write the test first, then the code to make it pass.** This ensures every piece of code has a clear purpose and verifiable behavior.
10
+
11
+ ## The RED-GREEN-REFACTOR Cycle
12
+
13
+ ### 🔴 RED: Write a Failing Test
14
+ 1. Write a test that describes the expected behavior
15
+ 2. Run the test — it MUST fail
16
+ 3. Verify it fails for the **right reason** (not a typo or import error)
17
+ 4. If it passes immediately, the test isn't testing anything new
18
+
19
+ ### 🟢 GREEN: Make It Pass
20
+ 1. Write the **minimum code** to make the test pass
21
+ 2. Don't add extra features, optimizations, or edge cases yet
22
+ 3. Run the test — it MUST pass now
23
+ 4. Run ALL existing tests — they must STILL pass (no regressions)
24
+
25
+ ### 🔵 REFACTOR: Clean Up
26
+ 1. Improve the code without changing behavior
27
+ 2. Remove duplication, improve naming, simplify logic
28
+ 3. Run ALL tests again — everything must still be green
29
+ 4. Only refactor when tests are green
30
+
31
+ ## When to Apply TDD
32
+
33
+ **Strongly recommended for:**
34
+ - New functions, methods, or components
35
+ - Bug fixes (write the reproduction test first)
36
+ - API endpoints and their handlers
37
+ - Data transformations and business logic
38
+ - Utility functions
39
+
40
+ **Optional for:**
41
+ - Configuration files
42
+ - Simple UI layout changes
43
+ - Documentation
44
+ - Boilerplate with no logic
45
+ - Legacy code without existing test infrastructure
46
+
47
+ ## Integration with /hopla-execute
48
+
49
+ When executing a plan with TDD:
50
+ 1. For each implementation task that has associated tests:
51
+ - Write the test FIRST (RED)
52
+ - Then implement the code (GREEN)
53
+ - Then clean up (REFACTOR)
54
+ 2. Validate after each cycle: run the test suite
55
+ 3. Don't skip the RED step — it catches specification errors early
56
+
57
+ ## Common Rationalizations (and why they're wrong)
58
+
59
+ | Rationalization | Why It's Wrong |
60
+ |----------------|---------------|
61
+ | "I'll write tests after" | You'll write tests that match the code, not the spec |
62
+ | "This is too simple to test" | Simple code grows complex. The test documents intent |
63
+ | "It'll be faster without TDD" | Debugging later costs more than testing now |
64
+ | "The test framework isn't set up" | Set it up. It's a one-time cost |
65
+ | "I know this works" | Then the test will pass quickly. Write it anyway |
66
+
67
+ ## Test Quality Guidelines
68
+
69
+ - **One assertion per test** (when practical)
70
+ - **Clear test names**: `test_user_login_with_invalid_password_returns_401`
71
+ - **Test behavior, not implementation**: Don't test private methods directly
72
+ - **Use real objects** when possible; mock only external dependencies
73
+ - **Tests should be independent**: No shared state between tests
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: hopla-verify
3
+ description: "Verification gate that ensures all completion claims are backed by fresh evidence. Use when the agent is about to declare work as done, finished, complete, ready, or implemented. Also use when hearing 'listo', 'terminé', 'ya está', 'done', 'finished', 'all tests pass', 'everything works', or any completion claim. Do NOT use for intermediate progress updates or partial task completion."
4
+ ---
5
+
6
+ # Verification Before Completion
7
+
8
+ ## Iron Law
9
+ **NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
10
+
11
+ Never declare work as done based on memory, assumptions, or previous outputs. Every claim must be backed by a fresh execution right now.
12
+
13
+ ## Gate Process
14
+
15
+ When about to declare any task as complete:
16
+
17
+ 1. **IDENTIFY** — What verification command(s) confirm this claim?
18
+ 2. **EXECUTE** — Run the verification fresh (never reuse previous output)
19
+ 3. **READ** — Read the complete output carefully
20
+ 4. **VERIFY** — Confirm the output actually proves the claim
21
+ 5. **ONLY THEN** — Declare the work complete with evidence
22
+
23
+ ## What Requires What Evidence
24
+
25
+ | Claim | Required Evidence |
26
+ |-------|------------------|
27
+ | "Tests pass" | Fresh `npm test` / `pytest` / test runner output showing all green |
28
+ | "Build succeeds" | Fresh build command output with no errors |
29
+ | "Lint is clean" | Fresh linter output showing 0 errors |
30
+ | "Types check" | Fresh `tsc --noEmit` / type checker output |
31
+ | "Feature works" | Demonstrate the feature running (test or manual verification) |
32
+ | "Bug is fixed" | Test that reproduces the bug now passes |
33
+ | "No regressions" | Full test suite passes, not just new tests |
34
+
35
+ ## Prohibited Phrases Before Verification
36
+
37
+ These phrases are RED FLAGS — never use them without fresh evidence:
38
+
39
+ - "should work" / "debería funcionar"
40
+ - "probably passes" / "probablemente pase"
41
+ - "seems to be fine" / "parece estar bien"
42
+ - "I believe this fixes" / "creo que esto arregla"
43
+ - "this should resolve" / "esto debería resolver"
44
+ - "looks correct" / "se ve correcto"
45
+
46
+ Instead, run the verification and report actual results.
47
+
48
+ ## Integration with Validation Pyramid
49
+
50
+ When completing a feature (not just a single file edit), run the full validation pyramid:
51
+
52
+ 1. **Level 1**: Lint & format
53
+ 2. **Level 2**: Type check
54
+ 3. **Level 3**: Unit tests
55
+ 4. **Level 4**: Integration tests (if applicable)
56
+ 5. **Level 5**: Human review suggestion
57
+
58
+ Reference `/hopla-validate` for project-specific validation commands.
59
+
60
+ ## Scope
61
+
62
+ - **Applies to**: Any declaration of completion, whether mid-conversation or at end of task
63
+ - **Does NOT apply to**: Intermediate progress updates ("I've finished editing file X, moving to file Y")
64
+ - **Partial completion**: You may say "file X is updated" without full validation, but "the feature is complete" requires the full gate
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: hopla-worktree
3
+ description: "Git worktree management for isolated feature development. Use when starting a new feature that benefits from isolation, when the user says 'worktree', 'isolated branch', 'parallel development', or when implementing multiple features simultaneously. Do NOT use for quick fixes or single-file changes."
4
+ ---
5
+
6
+ # Git Worktrees for Isolated Development
7
+
8
+ ## What Are Worktrees?
9
+ Git worktrees create separate working directories for different branches, sharing the same git history. Each worktree is an independent workspace.
10
+
11
+ ## When to Use
12
+ - Starting a feature that should be isolated from other work
13
+ - Developing multiple features in parallel
14
+ - Needing a clean baseline to test against
15
+ - Working on a risky change that might need to be abandoned
16
+
17
+ ## Setup Process
18
+
19
+ ### Step 1: Choose Worktree Directory
20
+ Check in order:
21
+ 1. Existing `.worktrees/` or `worktrees/` directory
22
+ 2. CLAUDE.md preference (if configured)
23
+ 3. Ask the user
24
+
25
+ ### Step 2: Ensure Directory is Gitignored
26
+ ```bash
27
+ # Verify the worktree directory is in .gitignore
28
+ grep -q "worktrees" .gitignore || echo "worktrees/" >> .gitignore
29
+ ```
30
+
31
+ ### Step 3: Create Worktree
32
+ ```bash
33
+ # Create worktree with a new feature branch
34
+ git worktree add worktrees/feature-name -b feature/feature-name
35
+ ```
36
+
37
+ ### Step 4: Setup Project in Worktree
38
+ Auto-detect and run setup:
39
+ - **Node.js**: `npm install` or `yarn install`
40
+ - **Python**: `pip install -r requirements.txt` or `poetry install`
41
+ - **Rust**: `cargo build`
42
+ - **Go**: `go mod download`
43
+
44
+ ### Step 5: Verify Clean Baseline
45
+ ```bash
46
+ cd worktrees/feature-name
47
+ # Run tests to ensure baseline is green
48
+ npm test # or equivalent
49
+ ```
50
+
51
+ If tests fail before any changes, STOP and report — the baseline is broken.
52
+
53
+ ### Step 6: Work in the Worktree
54
+ All work for this feature happens in `worktrees/feature-name/`.
55
+
56
+ ## Cleanup
57
+
58
+ ### After Merge
59
+ ```bash
60
+ git worktree remove worktrees/feature-name
61
+ git branch -d feature/feature-name
62
+ ```
63
+
64
+ ### If Abandoned
65
+ ```bash
66
+ git worktree remove --force worktrees/feature-name
67
+ git branch -D feature/feature-name
68
+ ```
69
+
70
+ ## Integration
71
+ - Use with `/hopla-execute` for isolated feature implementation
72
+ - Use with `/hopla-git-pr` for creating PRs from the worktree branch
73
+ - Combine with parallel dispatch for multiple features simultaneously
File without changes
File without changes
File without changes