@hopla/claude-setup 1.0.8 → 1.0.9
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/README.md +78 -13
- package/files/commands/hopla-init-project.md +138 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,8 +18,7 @@ claude-setup --force
|
|
|
18
18
|
## Update
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
|
-
npm install -g @hopla/claude-setup@latest
|
|
22
|
-
claude-setup --force
|
|
21
|
+
npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --force
|
|
23
22
|
```
|
|
24
23
|
|
|
25
24
|
## Uninstall
|
|
@@ -28,20 +27,86 @@ claude-setup --force
|
|
|
28
27
|
claude-setup --uninstall
|
|
29
28
|
```
|
|
30
29
|
|
|
31
|
-
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## How It Works — Layer 1 Planning
|
|
33
|
+
|
|
34
|
+
The system is built on two levels of context:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
~/.claude/CLAUDE.md ← Global rules (installed by claude-setup)
|
|
38
|
+
└── applies to ALL projects
|
|
39
|
+
|
|
40
|
+
CLAUDE.md (project root) ← Project-specific rules (created with /hopla-init-project)
|
|
41
|
+
└── applies to THIS project only
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Global rules** cover: language preferences, tech defaults (React, TypeScript, Vite), Git Flow, Conventional Commits, and autonomy behavior.
|
|
45
|
+
|
|
46
|
+
**Project rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, and task-specific reference guides.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## What Gets Installed
|
|
32
51
|
|
|
33
|
-
**`~/.claude/CLAUDE.md`** — Global rules
|
|
52
|
+
**`~/.claude/CLAUDE.md`** — Global rules applied to every Claude Code session.
|
|
34
53
|
|
|
35
54
|
**`~/.claude/commands/`** — Reusable commands available in any project:
|
|
36
55
|
|
|
37
56
|
| Command | Description |
|
|
38
57
|
|---|---|
|
|
39
|
-
| `/
|
|
40
|
-
| `/
|
|
41
|
-
| `/create-prd` | Create a Product Requirements Document through guided questions |
|
|
42
|
-
| `/plan-feature` | Research codebase and create a structured implementation plan |
|
|
43
|
-
| `/execute` | Execute a structured plan from start to finish with validation |
|
|
44
|
-
| `/
|
|
45
|
-
| `/code-review
|
|
46
|
-
| `/
|
|
47
|
-
| `/
|
|
58
|
+
| `/hopla-init-project` | Initialize project CLAUDE.md and .agents/ structure |
|
|
59
|
+
| `/hopla-prime` | Load project context at the start of a session |
|
|
60
|
+
| `/hopla-create-prd` | Create a Product Requirements Document through guided questions |
|
|
61
|
+
| `/hopla-plan-feature` | Research codebase and create a structured implementation plan |
|
|
62
|
+
| `/hopla-execute` | Execute a structured plan from start to finish with validation |
|
|
63
|
+
| `/hopla-commit` | Create a Conventional Commit with Git Flow awareness |
|
|
64
|
+
| `/hopla-code-review` | Technical code review on recently changed files |
|
|
65
|
+
| `/hopla-code-review-fix` | Fix issues found in a code review report |
|
|
66
|
+
| `/hopla-execution-report` | Generate an implementation report for system review |
|
|
67
|
+
| `/hopla-system-review` | Analyze implementation against plan to find process improvements |
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Recommended Workflow
|
|
72
|
+
|
|
73
|
+
### Starting a new project
|
|
74
|
+
```
|
|
75
|
+
/hopla-init-project → creates CLAUDE.md + .agents/ structure
|
|
76
|
+
/hopla-create-prd → defines product scope (PRD.md)
|
|
77
|
+
/hopla-commit → saves Layer 1 foundation to git
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Feature development (PIV loop)
|
|
81
|
+
```
|
|
82
|
+
/hopla-prime → load context at session start
|
|
83
|
+
/hopla-plan-feature → research codebase and create plan
|
|
84
|
+
/hopla-execute → implement the plan with validation
|
|
85
|
+
/hopla-code-review → technical review of changes
|
|
86
|
+
/hopla-code-review-fix → fix issues found
|
|
87
|
+
/hopla-commit → save to git
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### After implementation
|
|
91
|
+
```
|
|
92
|
+
/hopla-execution-report → document what was built
|
|
93
|
+
/hopla-system-review → analyze plan vs. actual for process improvements
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Project Structure (after /hopla-init-project)
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
project/
|
|
102
|
+
├── CLAUDE.md ← Project-specific rules
|
|
103
|
+
├── PRD.md ← Product scope (from /hopla-create-prd)
|
|
104
|
+
├── .agents/
|
|
105
|
+
│ ├── plans/ ← Implementation plans (commit these)
|
|
106
|
+
│ ├── guides/ ← On-demand reference guides (commit these)
|
|
107
|
+
│ ├── execution-reports/ ← Post-implementation reports (don't commit)
|
|
108
|
+
│ ├── code-reviews/ ← Code review reports (don't commit)
|
|
109
|
+
│ └── system-reviews/ ← Process improvement reports (don't commit)
|
|
110
|
+
└── .claude/
|
|
111
|
+
└── commands/ ← Project-specific commands (optional)
|
|
112
|
+
```
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Initialize a new project with a CLAUDE.md and .agents/ structure
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
Set up the Layer 1 planning foundation for this project: a project-specific `CLAUDE.md` with rules and architecture decisions, plus the `.agents/` directory structure.
|
|
6
|
+
|
|
7
|
+
> Layer 1 = Global Rules (~/.claude/CLAUDE.md) + Project Rules (CLAUDE.md) + PRD
|
|
8
|
+
|
|
9
|
+
## Step 1: Read Existing Context
|
|
10
|
+
|
|
11
|
+
Before asking anything, check what already exists:
|
|
12
|
+
- Any existing `CLAUDE.md` at project root
|
|
13
|
+
- `README.md` — extract stack and project overview
|
|
14
|
+
- `package.json`, `pyproject.toml`, or equivalent — extract stack and scripts
|
|
15
|
+
- Entry point files (`main.py`, `src/main.ts`, `app.py`, etc.)
|
|
16
|
+
|
|
17
|
+
If a `CLAUDE.md` already exists at the project root, tell the user and ask if they want to update it or start fresh.
|
|
18
|
+
|
|
19
|
+
## Step 2: Conversational Discovery
|
|
20
|
+
|
|
21
|
+
Ask one topic at a time. Wait for each answer before continuing.
|
|
22
|
+
|
|
23
|
+
**Topic A — Tech Stack**
|
|
24
|
+
- What languages, frameworks, and key libraries does this project use?
|
|
25
|
+
- What versions matter? (e.g. Python 3.12, FastAPI 0.118, React 19)
|
|
26
|
+
- What package manager? (npm, bun, uv, pip, etc.)
|
|
27
|
+
|
|
28
|
+
**Topic B — Architecture**
|
|
29
|
+
- How is the project structured? (e.g. layered, vertical slices, feature-based)
|
|
30
|
+
- What are the main layers or modules? (e.g. routes → services → models)
|
|
31
|
+
- Are there naming conventions for files and folders?
|
|
32
|
+
|
|
33
|
+
**Topic C — Code Style**
|
|
34
|
+
- Any strict naming conventions? (e.g. verbose fields like `product_id`, snake_case, camelCase)
|
|
35
|
+
- TypeScript strict mode? Pydantic validation?
|
|
36
|
+
- Linting/formatting tools and configs? (Ruff, ESLint, Biome, Prettier)
|
|
37
|
+
|
|
38
|
+
**Topic D — Testing**
|
|
39
|
+
- Testing framework? (pytest, vitest, jest)
|
|
40
|
+
- Test structure? (mirrors source, separate folder, colocated)
|
|
41
|
+
- Any naming conventions for tests?
|
|
42
|
+
|
|
43
|
+
**Topic E — Development Commands**
|
|
44
|
+
- How do you run the dev server?
|
|
45
|
+
- How do you run tests?
|
|
46
|
+
- How do you lint/format?
|
|
47
|
+
- Any other key commands the AI should know?
|
|
48
|
+
|
|
49
|
+
**Topic F — Reference Guides**
|
|
50
|
+
- Are there specific task types that need extra guidance?
|
|
51
|
+
(e.g. "When adding an API endpoint", "When creating a React component")
|
|
52
|
+
- For each task type: what patterns should the AI always follow?
|
|
53
|
+
|
|
54
|
+
## Step 3: Generate CLAUDE.md
|
|
55
|
+
|
|
56
|
+
Save to `CLAUDE.md` at the project root. Use this structure:
|
|
57
|
+
|
|
58
|
+
```markdown
|
|
59
|
+
# [Project Name] — Development Rules
|
|
60
|
+
|
|
61
|
+
## 1. Core Principles
|
|
62
|
+
|
|
63
|
+
[3-5 non-negotiable rules for this codebase, e.g. naming conventions, logging, type safety]
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 2. Tech Stack
|
|
68
|
+
|
|
69
|
+
[List technologies with versions]
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 3. Architecture
|
|
74
|
+
|
|
75
|
+
[Describe the layer structure, file organization, and key patterns]
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 4. Code Style
|
|
80
|
+
|
|
81
|
+
### [Language/Layer]
|
|
82
|
+
[Naming conventions, formatting rules, with short code examples]
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 5. Testing
|
|
87
|
+
|
|
88
|
+
[Framework, structure, naming conventions, how to run]
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 6. Development Commands
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
[command] # description
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 7. Task-Specific Reference Guides
|
|
101
|
+
|
|
102
|
+
[For each task type:]
|
|
103
|
+
**When to use:** [Trigger condition]
|
|
104
|
+
Read: `.agents/guides/[guide-name].md`
|
|
105
|
+
This guide covers: [bullet list]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Step 4: Create .agents/ Structure
|
|
109
|
+
|
|
110
|
+
Create the following directories (with `.gitkeep` where needed):
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
.agents/
|
|
114
|
+
├── plans/ ← /hopla-plan-feature saves here (commit these)
|
|
115
|
+
├── guides/ ← on-demand reference guides (commit these)
|
|
116
|
+
├── execution-reports/ ← /hopla-execution-report saves here (do NOT commit)
|
|
117
|
+
├── code-reviews/ ← /hopla-code-review saves here (do NOT commit)
|
|
118
|
+
└── system-reviews/ ← /hopla-system-review saves here (do NOT commit)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Add to `.gitignore` (create if it doesn't exist):
|
|
122
|
+
```
|
|
123
|
+
.agents/execution-reports/
|
|
124
|
+
.agents/code-reviews/
|
|
125
|
+
.agents/system-reviews/
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Step 5: Confirm and Save
|
|
129
|
+
|
|
130
|
+
Show the draft `CLAUDE.md` to the user and ask:
|
|
131
|
+
> "Does this accurately reflect the project's rules? Any corrections before I save it?"
|
|
132
|
+
|
|
133
|
+
Once confirmed:
|
|
134
|
+
1. Save `CLAUDE.md` to the project root
|
|
135
|
+
2. Create `.agents/` directory structure
|
|
136
|
+
3. Update `.gitignore`
|
|
137
|
+
4. Tell the user: "Project initialized. Run `/hopla-create-prd` next to define the product scope, or `/hopla-plan-feature` to start planning a feature."
|
|
138
|
+
5. Suggest running `/hopla-commit` to save everything
|