@hopla/claude-setup 1.0.7 → 1.0.9

package/README.md

@@ -18,8 +18,7 @@ claude-setup --force
 ## Update
 
 ```bash
-npm install -g @hopla/claude-setup@latest
-claude-setup --force
+npm install -g @hopla/claude-setup@latest --prefer-online && claude-setup --force
 ```
 
 ## Uninstall
@@ -28,20 +27,86 @@ claude-setup --force
 claude-setup --uninstall
 ```
 
-## What gets installed
+---
+
+## How It Works — Layer 1 Planning
+
+The system is built on two levels of context:
+
+```
+~/.claude/CLAUDE.md        ← Global rules (installed by claude-setup)
+    └── applies to ALL projects
+
+CLAUDE.md (project root)   ← Project-specific rules (created with /hopla-init-project)
+    └── applies to THIS project only
+```
+
+**Global rules** cover: language preferences, tech defaults (React, TypeScript, Vite), Git Flow, Conventional Commits, and autonomy behavior.
+
+**Project rules** cover: specific stack versions, architecture patterns, naming conventions, logging, testing, dev commands, and task-specific reference guides.
+
+---
+
+## What Gets Installed
 
-**`~/.claude/CLAUDE.md`** — Global rules: language, tech preferences, Git Flow, Conventional Commits, autonomy behavior.
+**`~/.claude/CLAUDE.md`** — Global rules applied to every Claude Code session.
 
 **`~/.claude/commands/`** — Reusable commands available in any project:
 
 | Command | Description |
 |---|---|
-| `/prime` | Load project context at the start of a session |
-| `/commit` | Create a Conventional Commit with Git Flow awareness |
-| `/create-prd` | Create a Product Requirements Document through guided questions |
-| `/plan-feature` | Research codebase and create a structured implementation plan |
-| `/execute` | Execute a structured plan from start to finish with validation |
-| `/code-review` | Technical code review on recently changed files |
-| `/code-review-fix` | Fix issues found in a code review report |
-| `/execution-report` | Generate an implementation report for system review |
-| `/system-review` | Analyze implementation against plan to find process improvements |
+| `/hopla-init-project` | Initialize project CLAUDE.md and .agents/ structure |
+| `/hopla-prime` | Load project context at the start of a session |
+| `/hopla-create-prd` | Create a Product Requirements Document through guided questions |
+| `/hopla-plan-feature` | Research codebase and create a structured implementation plan |
+| `/hopla-execute` | Execute a structured plan from start to finish with validation |
+| `/hopla-commit` | Create a Conventional Commit with Git Flow awareness |
+| `/hopla-code-review` | Technical code review on recently changed files |
+| `/hopla-code-review-fix` | Fix issues found in a code review report |
+| `/hopla-execution-report` | Generate an implementation report for system review |
+| `/hopla-system-review` | Analyze implementation against plan to find process improvements |
+
+---
+
+## Recommended Workflow
+
+### Starting a new project
+```
+/hopla-init-project   → creates CLAUDE.md + .agents/ structure
+/hopla-create-prd     → defines product scope (PRD.md)
+/hopla-commit         → saves Layer 1 foundation to git
+```
+
+### Feature development (PIV loop)
+```
+/hopla-prime          → load context at session start
+/hopla-plan-feature   → research codebase and create plan
+/hopla-execute        → implement the plan with validation
+/hopla-code-review    → technical review of changes
+/hopla-code-review-fix → fix issues found
+/hopla-commit         → save to git
+```
+
+### After implementation
+```
+/hopla-execution-report  → document what was built
+/hopla-system-review     → analyze plan vs. actual for process improvements
+```
+
+---
+
+## Project Structure (after /hopla-init-project)
+
+```
+project/
+├── CLAUDE.md                      ← Project-specific rules
+├── PRD.md                         ← Product scope (from /hopla-create-prd)
+├── .agents/
+│   ├── plans/                     ← Implementation plans (commit these)
+│   ├── guides/                    ← On-demand reference guides (commit these)
+│   ├── execution-reports/         ← Post-implementation reports (don't commit)
+│   ├── code-reviews/              ← Code review reports (don't commit)
+│   └── system-reviews/            ← Process improvement reports (don't commit)
+└── .claude/
+    └── commands/                  ← Project-specific commands (optional)
+```

package/cli.js

@@ -154,6 +154,58 @@ async function install() {
         log(`  ${CYAN}/${name}${RESET}`);
     }
     log(`\nRun with ${BOLD}--force${RESET} to overwrite all files without prompting.\n`);
+
+    await setupPermissions();
+}
+
+const HOPLA_PERMISSIONS = [
+    "Bash(git *)",
+    "Bash(ls *)",
+    "Bash(find *)",
+    "Bash(cat *)",
+    "Bash(head *)",
+    "Bash(tail *)",
+];
+
+async function setupPermissions() {
+    const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+
+    // Read existing settings
+    let settings = { permissions: { allow: [] } };
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        } catch {
+            // If parsing fails, keep defaults
+        }
+    }
+    if (!settings.permissions) settings.permissions = {};
+    if (!settings.permissions.allow) settings.permissions.allow = [];
+
+    // Find permissions not yet added
+    const existing = new Set(settings.permissions.allow);
+    const toAdd = HOPLA_PERMISSIONS.filter((p) => !existing.has(p));
+
+    if (toAdd.length === 0) {
+        log(`${GREEN}✓${RESET}  Permissions already configured.\n`);
+        return;
+    }
+
+    log(`${CYAN}Configuring permissions...${RESET}`);
+    log(`  The following will be added to ~/.claude/settings.json:\n`);
+    for (const p of toAdd) {
+        log(`  ${CYAN}+${RESET}  ${p}`);
+    }
+
+    const ok = await confirm(`\n  Add these permissions? (y/N) `);
+    if (!ok) {
+        log(`  ${YELLOW}↷${RESET}  Skipped — you can add them manually to ~/.claude/settings.json\n`);
+        return;
+    }
+
+    settings.permissions.allow = [...settings.permissions.allow, ...toAdd];
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    log(`  ${GREEN}✓${RESET}  Permissions added.\n`);
 }
 
 const run = UNINSTALL ? uninstall : install;

package/files/commands/hopla-init-project.md

@@ -0,0 +1,138 @@
+---
+description: Initialize a new project with a CLAUDE.md and .agents/ structure
+---
+
+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.
+
+> Layer 1 = Global Rules (~/.claude/CLAUDE.md) + Project Rules (CLAUDE.md) + PRD
+
+## Step 1: Read Existing Context
+
+Before asking anything, check what already exists:
+- Any existing `CLAUDE.md` at project root
+- `README.md` — extract stack and project overview
+- `package.json`, `pyproject.toml`, or equivalent — extract stack and scripts
+- Entry point files (`main.py`, `src/main.ts`, `app.py`, etc.)
+
+If a `CLAUDE.md` already exists at the project root, tell the user and ask if they want to update it or start fresh.
+
+## Step 2: Conversational Discovery
+
+Ask one topic at a time. Wait for each answer before continuing.
+
+**Topic A — Tech Stack**
+- What languages, frameworks, and key libraries does this project use?
+- What versions matter? (e.g. Python 3.12, FastAPI 0.118, React 19)
+- What package manager? (npm, bun, uv, pip, etc.)
+
+**Topic B — Architecture**
+- How is the project structured? (e.g. layered, vertical slices, feature-based)
+- What are the main layers or modules? (e.g. routes → services → models)
+- Are there naming conventions for files and folders?
+
+**Topic C — Code Style**
+- Any strict naming conventions? (e.g. verbose fields like `product_id`, snake_case, camelCase)
+- TypeScript strict mode? Pydantic validation?
+- Linting/formatting tools and configs? (Ruff, ESLint, Biome, Prettier)
+
+**Topic D — Testing**
+- Testing framework? (pytest, vitest, jest)
+- Test structure? (mirrors source, separate folder, colocated)
+- Any naming conventions for tests?
+
+**Topic E — Development Commands**
+- How do you run the dev server?
+- How do you run tests?
+- How do you lint/format?
+- Any other key commands the AI should know?
+
+**Topic F — Reference Guides**
+- Are there specific task types that need extra guidance?
+  (e.g. "When adding an API endpoint", "When creating a React component")
+- For each task type: what patterns should the AI always follow?
+
+## Step 3: Generate CLAUDE.md
+
+Save to `CLAUDE.md` at the project root. Use this structure:
+
+```markdown
+# [Project Name] — Development Rules
+
+## 1. Core Principles
+
+[3-5 non-negotiable rules for this codebase, e.g. naming conventions, logging, type safety]
+
+---
+
+## 2. Tech Stack
+
+[List technologies with versions]
+
+---
+
+## 3. Architecture
+
+[Describe the layer structure, file organization, and key patterns]
+
+---
+
+## 4. Code Style
+
+### [Language/Layer]
+[Naming conventions, formatting rules, with short code examples]
+
+---
+
+## 5. Testing
+
+[Framework, structure, naming conventions, how to run]
+
+---
+
+## 6. Development Commands
+
+```bash
+[command]  # description
+```
+
+---
+
+## 7. Task-Specific Reference Guides
+
+[For each task type:]
+**When to use:** [Trigger condition]
+Read: `.agents/guides/[guide-name].md`
+This guide covers: [bullet list]
+```
+
+## Step 4: Create .agents/ Structure
+
+Create the following directories (with `.gitkeep` where needed):
+
+```
+.agents/
+├── plans/          ← /hopla-plan-feature saves here (commit these)
+├── guides/         ← on-demand reference guides (commit these)
+├── execution-reports/   ← /hopla-execution-report saves here (do NOT commit)
+├── code-reviews/        ← /hopla-code-review saves here (do NOT commit)
+└── system-reviews/      ← /hopla-system-review saves here (do NOT commit)
+```
+
+Add to `.gitignore` (create if it doesn't exist):
+```
+.agents/execution-reports/
+.agents/code-reviews/
+.agents/system-reviews/
+```
+
+## Step 5: Confirm and Save
+
+Show the draft `CLAUDE.md` to the user and ask:
+> "Does this accurately reflect the project's rules? Any corrections before I save it?"
+
+Once confirmed:
+1. Save `CLAUDE.md` to the project root
+2. Create `.agents/` directory structure
+3. Update `.gitignore`
+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."
+5. Suggest running `/hopla-commit` to save everything

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {