@hopla/claude-setup 1.12.0 → 1.12.1
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 +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +109 -115
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hopla",
|
|
3
3
|
"description": "Agentic coding system for Claude Code: PIV loop (Plan → Implement → Validate), TDD, debugging, brainstorming, subagent execution, and team workflows",
|
|
4
|
-
"version": "1.12.
|
|
4
|
+
"version": "1.12.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Hopla Tools",
|
|
7
7
|
"email": "julio@hopla.tools"
|
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ Then install the plugin:
|
|
|
18
18
|
/plugin install hopla@hopla-marketplace
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
This installs all commands, skills, agents, and hooks automatically.
|
|
21
|
+
This installs all commands, skills, agents, and hooks automatically.
|
|
22
22
|
|
|
23
23
|
To also install the global rules template (`~/.claude/CLAUDE.md`), run the CLI:
|
|
24
24
|
|
|
@@ -45,7 +45,7 @@ npm install -g @hopla/claude-setup
|
|
|
45
45
|
claude-setup --planning
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
Installs only planning commands: `init-project`, `create-prd`, `plan-feature`, `review-plan`, `guide`, `git-commit`, `git-pr`. Also installs planning skills (`
|
|
48
|
+
Installs only planning commands: `init-project`, `create-prd`, `plan-feature`, `review-plan`, `guide`, `git-commit`, `git-pr`. Also installs planning skills (`prime`, `brainstorm`). No execution or review commands. No bash permission prompts during planning.
|
|
49
49
|
|
|
50
50
|
To overwrite existing files without prompting:
|
|
51
51
|
|
|
@@ -56,12 +56,24 @@ claude-setup --planning --force
|
|
|
56
56
|
|
|
57
57
|
## Update
|
|
58
58
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
59
|
+
### Plugin channel
|
|
60
|
+
|
|
61
|
+
Claude Code caches the marketplace repo locally. To get the latest version:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# Step 1: Update the local marketplace cache
|
|
65
|
+
cd ~/.claude/plugins/marketplaces/hopla-marketplace && git pull
|
|
66
|
+
|
|
67
|
+
# Step 2: Reinstall the plugin in Claude Code
|
|
68
|
+
/plugin uninstall hopla@hopla-marketplace
|
|
69
|
+
/plugin install hopla@hopla-marketplace
|
|
70
|
+
/reload-plugins
|
|
62
71
|
```
|
|
63
72
|
|
|
64
|
-
**
|
|
73
|
+
> **Known issue:** Claude Code does not automatically `git pull` the marketplace when reinstalling a plugin. The manual `git pull` in step 1 is required to pick up new versions.
|
|
74
|
+
|
|
75
|
+
### CLI channel (for global rules)
|
|
76
|
+
|
|
65
77
|
```bash
|
|
66
78
|
npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --force
|
|
67
79
|
```
|
|
@@ -80,6 +92,19 @@ claude-setup --uninstall
|
|
|
80
92
|
|
|
81
93
|
---
|
|
82
94
|
|
|
95
|
+
## Naming Convention
|
|
96
|
+
|
|
97
|
+
Skills and commands use short names in source (e.g., `prime`, `execute`, `git`). Each distribution channel adds its own namespace:
|
|
98
|
+
|
|
99
|
+
| Channel | Skills | Commands |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| **Plugin** | `/hopla:prime`, `/hopla:git` | `/hopla:execute`, `/hopla:plan-feature` |
|
|
102
|
+
| **CLI** | `hopla-prime`, `hopla-git` | `/hopla-execute`, `/hopla-plan-feature` |
|
|
103
|
+
|
|
104
|
+
The plugin channel uses the plugin name (`hopla:`) as namespace. The CLI channel adds a `hopla-` prefix during installation.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
83
108
|
## How It Works — Layered Context
|
|
84
109
|
|
|
85
110
|
The system uses three levels of CLAUDE.md, each scoped differently:
|
|
@@ -88,7 +113,7 @@ The system uses three levels of CLAUDE.md, each scoped differently:
|
|
|
88
113
|
~/.claude/CLAUDE.md ← Machine-level (installed by claude-setup)
|
|
89
114
|
└── applies to ALL projects on this machine
|
|
90
115
|
|
|
91
|
-
CLAUDE.md (project root) ← Project-level (created with /
|
|
116
|
+
CLAUDE.md (project root) ← Project-level (created with /init-project)
|
|
92
117
|
└── applies to THIS project only
|
|
93
118
|
|
|
94
119
|
.claude/CLAUDE.local.md ← Local overrides (personal, gitignored)
|
|
@@ -113,12 +138,12 @@ This system is built on two core concepts from the Agentic Coding Course:
|
|
|
113
138
|
|--------|-----------|----------------|
|
|
114
139
|
| **Global Rules** | Always-loaded context: language, git flow, tech defaults, autonomy rules | `~/.claude/CLAUDE.md` |
|
|
115
140
|
| **On-Demand Context** | Task-specific guides loaded when needed (e.g. "how to add an API endpoint") | `.agents/guides/*.md` |
|
|
116
|
-
| **Commands** | Reusable processes that tell the agent *how* to work | `~/.claude/commands
|
|
117
|
-
| **Skills** | Auto-activate by semantic matching — no slash command needed | `~/.claude/skills
|
|
141
|
+
| **Commands** | Reusable processes that tell the agent *how* to work | `~/.claude/commands/` |
|
|
142
|
+
| **Skills** | Auto-activate by semantic matching — no slash command needed | `~/.claude/skills/` |
|
|
118
143
|
| **Agents** | Specialized subagents for delegation (code review, research, system analysis) | `~/.claude/agents/*.md` |
|
|
119
144
|
| **Hooks** | Run automatically before/after tool use for type checking and protection | `~/.claude/hooks/*.js` |
|
|
120
145
|
|
|
121
|
-
The key insight: **commands inject on-demand context deterministically** — when you run `/
|
|
146
|
+
The key insight: **commands inject on-demand context deterministically** — when you run `/plan-feature`, it automatically reads the relevant guide from `.agents/guides/` before planning.
|
|
122
147
|
|
|
123
148
|
### PIV Loop — How you work
|
|
124
149
|
|
|
@@ -126,13 +151,13 @@ The key insight: **commands inject on-demand context deterministically** — whe
|
|
|
126
151
|
Plan → Implement → Validate → (repeat)
|
|
127
152
|
```
|
|
128
153
|
|
|
129
|
-
- **Plan** (`/
|
|
130
|
-
- **Implement** (`/
|
|
154
|
+
- **Plan** (`/plan-feature`) — Research the codebase, design the approach, create a structured plan
|
|
155
|
+
- **Implement** (`/execute`) — Delegate coding to the AI, trust but verify at each task
|
|
131
156
|
- **Validate** — AI runs lint → types → tests → integration; human reviews the result
|
|
132
157
|
|
|
133
158
|
### System Evolution
|
|
134
159
|
|
|
135
|
-
After each PIV loop, run `/
|
|
160
|
+
After each PIV loop, run `/execution-report` + `/system-review` to find process improvements. Don't just fix bugs — fix the system that allowed them.
|
|
136
161
|
|
|
137
162
|
---
|
|
138
163
|
|
|
@@ -140,43 +165,43 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
|
|
|
140
165
|
|
|
141
166
|
**`~/.claude/CLAUDE.md`** — Global rules applied to every Claude Code session.
|
|
142
167
|
|
|
143
|
-
|
|
168
|
+
**Commands** — Reusable commands available in any project:
|
|
144
169
|
|
|
145
170
|
| Command | Description |
|
|
146
171
|
|---|---|
|
|
147
|
-
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
161
|
-
> **Note:** `
|
|
162
|
-
|
|
163
|
-
|
|
172
|
+
| `init-project` | Read PRD, recommend stack, create CLAUDE.md and .agents/ structure |
|
|
173
|
+
| `create-prd` | Create a Product Requirements Document through guided questions |
|
|
174
|
+
| `plan-feature` | Research codebase and create a structured implementation plan |
|
|
175
|
+
| `review-plan` | Review a plan before execution — get a concise summary and approve |
|
|
176
|
+
| `execute` | Execute a structured plan from start to finish with validation |
|
|
177
|
+
| `validate` | Run the validation pyramid: lint → types → tests → integration |
|
|
178
|
+
| `end-to-end` | Full PIV loop in one command: prime → brainstorm → plan → execute → validate → commit |
|
|
179
|
+
| `git-commit` | Create a Conventional Commit with Git Flow awareness |
|
|
180
|
+
| `git-pr` | Create a GitHub Pull Request with a structured description |
|
|
181
|
+
| `code-review-fix` | Fix issues found in a code review report |
|
|
182
|
+
| `rca` | Root Cause Analysis — investigate a bug systematically and generate an RCA doc |
|
|
183
|
+
| `guide` | 4D Framework guide for non-technical users (Description, Discernment, Delegation, Diligence) |
|
|
184
|
+
| `system-review` | Analyze implementation against plan to find process improvements |
|
|
185
|
+
|
|
186
|
+
> **Note:** `prime`, `code-review`, and `execution-report` are **skills only** (no slash command needed) — they auto-activate when you describe the task in natural language.
|
|
187
|
+
|
|
188
|
+
**Skills** — Auto-activate by semantic matching, no slash command needed:
|
|
164
189
|
|
|
165
190
|
| Skill | Auto-activates when you say... |
|
|
166
191
|
|---|---|
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
|
|
179
|
-
|
|
192
|
+
| `git` | "commit this", "create a PR", "save the changes" |
|
|
193
|
+
| `prime` | "orient yourself", "catch me up", "what is this project" |
|
|
194
|
+
| `code-review` | "review the code", "code review", "check these changes" |
|
|
195
|
+
| `execution-report` | "generate the report", "document what was done", "summarize the work" |
|
|
196
|
+
| `verify` | "verify it works", "make sure it's correct", "check before finishing" |
|
|
197
|
+
| `brainstorm` | "let's brainstorm", "explore approaches", "design this before coding" |
|
|
198
|
+
| `debug` | "debug this", "find the bug", "why is this failing" |
|
|
199
|
+
| `tdd` | "write tests first", "TDD", "red-green-refactor" |
|
|
200
|
+
| `subagent-execution` | "use subagents", "execute with agents", plans with 5+ tasks |
|
|
201
|
+
| `parallel-dispatch` | "run in parallel", "parallelize this", independent tasks |
|
|
202
|
+
| `worktree` | "use a worktree", "isolated branch", "parallel feature work" |
|
|
203
|
+
|
|
204
|
+
**Hooks** — Run automatically before/after tool use (configured in `~/.claude/settings.json`):
|
|
180
205
|
|
|
181
206
|
| Hook | Type | What it does |
|
|
182
207
|
|---|---|---|
|
|
@@ -184,15 +209,15 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
|
|
|
184
209
|
| `env-protect.js` | PreToolUse | Blocks reads/greps targeting `.env` files |
|
|
185
210
|
| `session-prime.js` | SessionStart (opt-in) | Loads git context + CLAUDE.md summary at session start |
|
|
186
211
|
|
|
187
|
-
|
|
212
|
+
**Agents** — Specialized subagents for delegation:
|
|
188
213
|
|
|
189
214
|
| Agent | What it does |
|
|
190
215
|
|---|---|
|
|
191
|
-
| `code-reviewer` | Senior code reviewer (
|
|
192
|
-
| `codebase-researcher` | Fast codebase explorer (
|
|
193
|
-
| `system-reviewer` | System review analyst (
|
|
216
|
+
| `code-reviewer` | Senior code reviewer (read-only). Reviews plan alignment, code quality, architecture, logic, security, performance |
|
|
217
|
+
| `codebase-researcher` | Fast codebase explorer (read-only). Systematic search and structured findings |
|
|
218
|
+
| `system-reviewer` | System review analyst (read-only). Analyzes execution vs plan, classifies divergences |
|
|
194
219
|
|
|
195
|
-
|
|
220
|
+
**Reference guides** — Loaded on-demand:
|
|
196
221
|
|
|
197
222
|
| Guide | What it covers |
|
|
198
223
|
|---|---|
|
|
@@ -205,79 +230,48 @@ After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to f
|
|
|
205
230
|
| `data-audit.md` | Data pipeline audit checklist |
|
|
206
231
|
| `review-checklist.md` | Code review checklist reference |
|
|
207
232
|
|
|
208
|
-
**Installed layout:**
|
|
209
|
-
|
|
210
|
-
```
|
|
211
|
-
~/.claude/
|
|
212
|
-
├── CLAUDE.md ← Global rules
|
|
213
|
-
├── commands/
|
|
214
|
-
│ ├── hopla-*.md ← Slash commands (/hopla-prime, /hopla-execute, etc.)
|
|
215
|
-
│ └── guides/ ← Reference guides (loaded on-demand by commands/skills)
|
|
216
|
-
├── skills/
|
|
217
|
-
│ ├── hopla-git/ ← Auto-activates for commit/PR requests
|
|
218
|
-
│ ├── hopla-prime/ ← Auto-activates for orientation requests
|
|
219
|
-
│ ├── hopla-code-review/ ← Auto-activates for review requests
|
|
220
|
-
│ ├── hopla-execution-report/ ← Auto-activates for report requests
|
|
221
|
-
│ ├── hopla-verify/ ← Auto-activates for verification before completion
|
|
222
|
-
│ ├── hopla-brainstorm/ ← Auto-activates for design exploration
|
|
223
|
-
│ ├── hopla-debug/ ← Auto-activates for systematic debugging
|
|
224
|
-
│ ├── hopla-tdd/ ← Auto-activates for test-driven development
|
|
225
|
-
│ ├── hopla-subagent-execution/ ← Auto-activates for multi-task plans
|
|
226
|
-
│ ├── hopla-parallel-dispatch/ ← Auto-activates for parallel work
|
|
227
|
-
│ └── hopla-worktree/ ← Auto-activates for isolated branch work
|
|
228
|
-
├── agents/
|
|
229
|
-
│ ├── code-reviewer.md ← Senior code review subagent
|
|
230
|
-
│ ├── codebase-researcher.md ← Fast codebase exploration subagent
|
|
231
|
-
│ └── system-reviewer.md ← Execution vs plan analysis subagent
|
|
232
|
-
├── hooks/
|
|
233
|
-
│ ├── tsc-check.js ← TypeScript type checking after edits
|
|
234
|
-
│ ├── env-protect.js ← .env file protection
|
|
235
|
-
│ └── session-prime.js ← Session context loader (opt-in)
|
|
236
|
-
└── settings.json ← Permissions + hooks config (auto-updated)
|
|
237
|
-
```
|
|
238
|
-
|
|
239
233
|
---
|
|
240
234
|
|
|
241
235
|
## Recommended Workflow
|
|
242
236
|
|
|
243
237
|
### Starting a new project
|
|
244
238
|
```
|
|
245
|
-
/
|
|
246
|
-
/
|
|
247
|
-
/
|
|
239
|
+
/create-prd → define what you're building (PRD.md)
|
|
240
|
+
/init-project → reads PRD, recommends stack, creates CLAUDE.md + .agents/
|
|
241
|
+
/git-commit → saves Layer 1 foundation to git
|
|
248
242
|
```
|
|
249
243
|
|
|
250
244
|
### Feature development (PIV loop)
|
|
251
245
|
```
|
|
252
|
-
"catch me up"
|
|
253
|
-
/
|
|
254
|
-
/
|
|
255
|
-
/
|
|
256
|
-
/
|
|
257
|
-
"review the code"
|
|
258
|
-
/
|
|
259
|
-
/
|
|
260
|
-
"generate the report"
|
|
261
|
-
/
|
|
262
|
-
/
|
|
246
|
+
"catch me up" → prime skill auto-loads project context
|
|
247
|
+
/plan-feature → research codebase and create plan
|
|
248
|
+
/review-plan → review plan summary and approve
|
|
249
|
+
/execute → implement the plan with validation
|
|
250
|
+
/validate → run lint → types → tests → integration
|
|
251
|
+
"review the code" → code-review skill runs automatically
|
|
252
|
+
/code-review-fix → fix issues found
|
|
253
|
+
/rca → root cause analysis if a bug is found
|
|
254
|
+
"generate the report" → execution-report skill documents what was built
|
|
255
|
+
/git-commit → save to git
|
|
256
|
+
/git-pr → open pull request on GitHub
|
|
263
257
|
```
|
|
264
258
|
|
|
265
259
|
### Full automation (one command)
|
|
266
260
|
```
|
|
267
|
-
/
|
|
261
|
+
/end-to-end → runs the entire PIV loop: prime → brainstorm → plan → execute → validate → commit
|
|
268
262
|
```
|
|
269
263
|
|
|
270
264
|
### After implementation
|
|
271
265
|
```
|
|
272
|
-
/
|
|
266
|
+
/system-review → analyze plan vs. actual for process improvements
|
|
273
267
|
```
|
|
274
268
|
|
|
275
269
|
### For non-technical users
|
|
276
270
|
```
|
|
277
|
-
/
|
|
271
|
+
/guide → 4D Framework walkthrough (Description, Discernment, Delegation, Diligence)
|
|
278
272
|
```
|
|
279
273
|
|
|
280
|
-
> **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 `
|
|
274
|
+
> **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 the `debug` skill, and "let's brainstorm" triggers the `brainstorm` skill, without typing any slash command.
|
|
281
275
|
|
|
282
276
|
---
|
|
283
277
|
|
|
@@ -289,50 +283,50 @@ Commands are modular — the output of one becomes the input of the next. Some c
|
|
|
289
283
|
|
|
290
284
|
| Command | Argument | Example |
|
|
291
285
|
|---|---|---|
|
|
292
|
-
| `/
|
|
293
|
-
| `/
|
|
294
|
-
| `/
|
|
295
|
-
| `/
|
|
296
|
-
| `/
|
|
286
|
+
| `/execute` | Path to plan file | `/execute .agents/plans/auth-feature.md` |
|
|
287
|
+
| `/end-to-end` | Feature description | `/end-to-end add user authentication` |
|
|
288
|
+
| `/code-review-fix` | Path to review report or description | `/code-review-fix .agents/code-reviews/auth-review.md` |
|
|
289
|
+
| `/rca` | Bug description or error message | `/rca "login fails with 403 after token refresh"` |
|
|
290
|
+
| `/system-review` | Plan file + execution report | `/system-review .agents/plans/auth-feature.md .agents/execution-reports/auth-feature.md` |
|
|
297
291
|
|
|
298
292
|
### Full PIV loop example
|
|
299
293
|
|
|
300
294
|
```
|
|
301
295
|
# 1. Plan
|
|
302
|
-
/
|
|
296
|
+
/plan-feature add user authentication
|
|
303
297
|
→ saves: .agents/plans/add-user-authentication.md
|
|
304
298
|
|
|
305
299
|
# 2. Review plan
|
|
306
|
-
/
|
|
300
|
+
/review-plan .agents/plans/add-user-authentication.md
|
|
307
301
|
|
|
308
302
|
# 3. Execute
|
|
309
|
-
/
|
|
303
|
+
/execute .agents/plans/add-user-authentication.md
|
|
310
304
|
→ implements the plan, runs validation
|
|
311
305
|
|
|
312
306
|
# 4. Validate
|
|
313
|
-
/
|
|
307
|
+
/validate
|
|
314
308
|
→ runs lint → types → tests → integration
|
|
315
309
|
|
|
316
310
|
# 5. Code review (auto-triggered skill — just say "review the code")
|
|
317
311
|
→ saves: .agents/code-reviews/add-user-authentication.md
|
|
318
312
|
|
|
319
313
|
# 6. Fix issues
|
|
320
|
-
/
|
|
314
|
+
/code-review-fix .agents/code-reviews/add-user-authentication.md
|
|
321
315
|
|
|
322
316
|
# 7. Document (auto-triggered skill — just say "generate the report")
|
|
323
317
|
→ saves: .agents/execution-reports/add-user-authentication.md
|
|
324
318
|
|
|
325
319
|
# 8. Commit
|
|
326
|
-
/
|
|
320
|
+
/git-commit
|
|
327
321
|
|
|
328
322
|
# 9. Pull request
|
|
329
|
-
/
|
|
323
|
+
/git-pr
|
|
330
324
|
|
|
331
325
|
# 10. Process improvement (after PR merge)
|
|
332
|
-
/
|
|
326
|
+
/system-review .agents/plans/add-user-authentication.md .agents/execution-reports/add-user-authentication.md
|
|
333
327
|
```
|
|
334
328
|
|
|
335
|
-
> **Or do it all in one command:** `/
|
|
329
|
+
> **Or do it all in one command:** `/end-to-end add user authentication`
|
|
336
330
|
|
|
337
331
|
---
|
|
338
332
|
|
|
@@ -347,12 +341,12 @@ Features under consideration for future versions:
|
|
|
347
341
|
|
|
348
342
|
---
|
|
349
343
|
|
|
350
|
-
## Project Structure (after /
|
|
344
|
+
## Project Structure (after /create-prd + /init-project)
|
|
351
345
|
|
|
352
346
|
```
|
|
353
347
|
project/
|
|
354
|
-
├── PRD.md ← Product scope (from /
|
|
355
|
-
├── CLAUDE.md ← Project rules and stack (from /
|
|
348
|
+
├── PRD.md ← Product scope (from /create-prd)
|
|
349
|
+
├── CLAUDE.md ← Project rules and stack (from /init-project)
|
|
356
350
|
├── .agents/
|
|
357
351
|
│ ├── plans/ ← Implementation plans (commit these)
|
|
358
352
|
│ ├── specs/ ← Design specs from brainstorming (commit these)
|