@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.
- package/.claude-plugin/marketplace.json +20 -0
- package/.claude-plugin/plugin.json +23 -0
- package/README.md +127 -30
- package/agents/code-reviewer.md +62 -0
- package/agents/codebase-researcher.md +41 -0
- package/agents/system-reviewer.md +64 -0
- package/cli.js +45 -14
- package/commands/guides/ai-optimized-codebase.md +70 -0
- package/commands/guides/hooks-reference.md +82 -0
- package/commands/guides/mcp-integration.md +32 -0
- package/commands/guides/remote-coding.md +70 -0
- package/commands/guides/scaling-beyond-engineering.md +54 -0
- package/commands/guides/write-skill.md +78 -0
- package/{files/commands → commands}/hopla-code-review-fix.md +8 -0
- package/commands/hopla-end-to-end.md +67 -0
- package/{files/commands → commands}/hopla-execute.md +2 -0
- package/commands/hopla-guide.md +61 -0
- package/{files/commands → commands}/hopla-plan-feature.md +2 -0
- package/commands/hopla-rca.md +64 -0
- package/{files/commands → commands}/hopla-validate.md +5 -0
- package/{files/CLAUDE.md → global-rules.md} +45 -0
- package/hooks/hooks.json +40 -0
- package/{files/hooks → hooks}/session-prime.js +13 -0
- package/package.json +7 -2
- package/skills/hopla-brainstorm/SKILL.md +89 -0
- package/{files/skills → skills}/hopla-code-review/SKILL.md +2 -1
- package/skills/hopla-debug/SKILL.md +73 -0
- package/{files/skills → skills}/hopla-execution-report/SKILL.md +3 -1
- package/{files/skills → skills}/hopla-git/SKILL.md +1 -1
- package/skills/hopla-parallel-dispatch/SKILL.md +69 -0
- package/{files/skills → skills}/hopla-prime/SKILL.md +3 -1
- package/skills/hopla-subagent-execution/SKILL.md +70 -0
- package/skills/hopla-tdd/SKILL.md +73 -0
- package/skills/hopla-verify/SKILL.md +64 -0
- package/skills/hopla-worktree/SKILL.md +73 -0
- /package/{files/commands → commands}/guides/data-audit.md +0 -0
- /package/{files/commands → commands}/guides/review-checklist.md +0 -0
- /package/{files/commands → commands}/hopla-create-prd.md +0 -0
- /package/{files/commands → commands}/hopla-git-commit.md +0 -0
- /package/{files/commands → commands}/hopla-git-pr.md +0 -0
- /package/{files/commands → commands}/hopla-init-project.md +0 -0
- /package/{files/commands → commands}/hopla-review-plan.md +0 -0
- /package/{files/commands → commands}/hopla-system-review.md +0 -0
- /package/{files/hooks → hooks}/env-protect.js +0 -0
- /package/{files/hooks → hooks}/tsc-check.js +0 -0
- /package/{files/skills → skills}/hopla-git/commit.md +0 -0
- /package/{files/skills → skills}/hopla-git/pr.md +0 -0
package/hooks/hooks.json
ADDED
|
@@ -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.
|
|
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
|
-
"
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|