@hopla/claude-setup 1.1.1 → 1.1.3

package/README.md

@@ -47,6 +47,36 @@ CLAUDE.md (project root)   ← Project-specific rules (created with /hopla-init-
 
 ---
 
+## The Agentic Coding Framework
+
+This system is built on two core concepts from the Agentic Coding Course:
+
+### AI Layer — What guides the agent
+
+| Pillar | What it is | Where it lives |
+|--------|-----------|----------------|
+| **Global Rules** | Always-loaded context: language, git flow, tech defaults, autonomy rules | `~/.claude/CLAUDE.md` |
+| **On-Demand Context** | Task-specific guides loaded when needed (e.g. "how to add an API endpoint") | `.agents/guides/*.md` |
+| **Commands** | Reusable processes that tell the agent *how* to work | `~/.claude/commands/hopla-*.md` |
+
+The key insight: **commands inject on-demand context deterministically** — when you run `/hopla-plan-feature`, it automatically reads the relevant guide from `.agents/guides/` before planning.
+
+### PIV Loop — How you work
+
+```
+Plan → Implement → Validate → (repeat)
+```
+
+- **Plan** (`/hopla-plan-feature`) — Research the codebase, design the approach, create a structured plan
+- **Implement** (`/hopla-execute`) — Delegate coding to the AI, trust but verify at each task
+- **Validate** — AI runs lint → types → tests → integration; human reviews the result
+
+### System Evolution
+
+After each PIV loop, run `/hopla-execution-report` + `/hopla-system-review` to find process improvements. Don't just fix bugs — fix the system that allowed them.
+
+---
+
 ## What Gets Installed
 
 **`~/.claude/CLAUDE.md`** — Global rules applied to every Claude Code session.

package/files/commands/hopla-execute.md

@@ -33,32 +33,41 @@ Work through each task in the plan sequentially. For each task:
 2. **Follow the pattern** referenced in the plan — do not invent new patterns
 3. **Implement** only what the task specifies — nothing more
 4. **Validate** the task using the method specified in the plan's validate field
-5. **Do not proceed** to the next task if the current one fails validation
+5. **Report completion** with a brief status: what was done, what was skipped, any decision made
+6. **Do not proceed** to the next task if the current one fails validation
 
-If you encounter something unexpected (a file doesn't exist, a pattern is different than the plan assumed), **stop and report** before continuing — do not improvise silently.
+**Trust but Verify — pause and report if:**
+- A file referenced in the plan doesn't exist
+- The actual pattern in the code differs from what the plan assumed
+- A task is ambiguous or has multiple valid implementations
+- Something unexpected is discovered that could affect subsequent tasks
+
+Do not improvise silently. When in doubt, stop and ask.
 
 ## Step 4: Run Full Validation Pyramid
 
 After all tasks are complete, run the full validation sequence in order.
 **Do not skip levels. Do not proceed if a level fails.**
 
+Use the exact commands from the plan's **Validation Checklist**. If not specified, read `CLAUDE.md` section "Development Commands" to find the correct commands.
+
 ### Level 1 — Lint & Format
-Run the project's lint and format check.
+Run the project's lint and format check (e.g. `npm run lint`, `uv run ruff check .`).
 Fix any issues before continuing.
 
 ### Level 2 — Type Check
-Run the project's type checker.
+Run the project's type checker (e.g. `npm run type-check`, `uv run mypy .`).
 Fix all type errors before continuing.
 
 ### Level 3 — Unit Tests
-Run the project's unit test suite.
+Run the project's unit test suite (e.g. `npm run test`, `uv run pytest`).
 If tests fail:
 - Investigate the root cause
 - Fix the code (not the tests)
 - Re-run until all pass
 
 ### Level 4 — Integration Tests
-Run integration tests or manual verification as specified in the plan.
+Run integration tests or manual verification as specified in the plan (e.g. `npm run test:e2e`, manual curl).
 Verify the feature works end-to-end.
 
 ### Level 5 — Human Review (flag for user)

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

@@ -125,7 +125,28 @@ Add to `.gitignore` (create if it doesn't exist):
 .agents/system-reviews/
 ```
 
-## Step 5: Confirm and Save
+## Step 5: Create .claude/commands/ (optional but recommended)
+
+Create `.claude/commands/` at the project root for project-specific commands that override or extend the global ones.
+
+Common project-specific commands to create:
+
+**`validate.md`** — runs the full validation sequence for this project:
+```markdown
+---
+description: Run full validation for this project
+---
+Run in order, stop if any level fails:
+1. `[lint command]`
+2. `[type check command]`
+3. `[test command]`
+```
+
+Ask the user: "Do you want me to create a project-specific `/validate` command with the commands from your stack?"
+
+If yes, create `.claude/commands/validate.md` using the dev commands collected in Topic E.
+
+## Step 6: 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?"

package/files/commands/hopla-plan-feature.md

@@ -123,8 +123,8 @@ Run in this order — do not proceed if a level fails:
 Before finishing, review the plan against these criteria:
 
 - [ ] Every task has a specific file path (no vague "update the component")
-- [ ] Every task references an existing pattern to follow
-- [ ] Validation commands match the actual project scripts
+- [ ] Every task has: Action, File, Pattern, Details, Gotcha, Validate — no field left empty
+- [ ] Validation Checklist has **exact commands** from `CLAUDE.md` or `package.json` (not vague "run lint")
 - [ ] The plan is complete enough that another agent can execute it without this conversation
 - [ ] No ambiguous requirements left unresolved
 

package/package.json

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