@pavp/wavefront 0.1.0

package/bin/wavefront.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+// wavefront CLI — thin Node wrapper over the bundled install.sh / uninstall.sh.
+// The shell scripts hold the real copy/symlink logic; this only resolves paths,
+// validates args, and forwards them so npm and git-clone installs share one code path.
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const VERSION = require(path.join(PKG_ROOT, 'package.json')).version;
+
+function fail(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function usage() {
+  console.log(`wavefront ${VERSION} — Claude Code frontend-engineering agents
+
+Usage:
+  wavefront install --global <target-app> [--with-hooks]   install to ~/.wavefront and symlink into <target-app>/.claude
+  wavefront install --local  <target-app> [--with-hooks]   copy the surface into <target-app>/.claude
+  wavefront uninstall <target-app> [--purge-home]          remove the surface from <target-app>
+  wavefront help                                           show this help
+  wavefront version                                        print version
+
+<target-app> is a scaffold-nextjs-app project root (the dir containing package.json).
+--with-hooks also installs the quality-gate hooks (eslint/stylelint --fix, tsc on stop).
+Run via npx without a global install: npx @pavp/wavefront install --local <target-app>`);
+}
+
+function runScript(scriptName, args) {
+  const script = path.join(PKG_ROOT, scriptName);
+  if (!fs.existsSync(script)) fail(`bundled ${scriptName} missing from package at ${PKG_ROOT}`);
+  const bash = process.platform === 'win32' ? null : 'bash';
+  if (!bash) fail('wavefront install requires bash (macOS/Linux). On Windows use WSL.');
+  const res = spawnSync(bash, [script, ...args], { stdio: 'inherit' });
+  if (res.error) fail(`failed to run ${scriptName}: ${res.error.message}`);
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+function cmdInstall(rest) {
+  // install.sh expects: <mode> <target> [--with-hooks]  (positional order matters)
+  const mode = rest[0];
+  if (mode !== '--global' && mode !== '--local') {
+    fail('install needs a mode: --global or --local');
+  }
+  const target = rest[1];
+  if (!target) fail('install needs a <target-app> path');
+  const withHooks = rest.includes('--with-hooks');
+  const args = [mode, target];
+  if (withHooks) args.push('--with-hooks');
+  runScript('install.sh', args);
+}
+
+function cmdUninstall(rest) {
+  const target = rest[0];
+  if (!target) fail('uninstall needs a <target-app> path');
+  const args = [target];
+  if (rest.includes('--purge-home')) args.push('--purge-home');
+  runScript('uninstall.sh', args);
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  switch (cmd) {
+    case 'install':
+      return cmdInstall(rest);
+    case 'uninstall':
+      return cmdUninstall(rest);
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log(VERSION);
+      return;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      usage();
+      return;
+    default:
+      usage();
+      fail(`unknown command: ${cmd}`);
+  }
+}
+
+main();

package/commands/wavefront-change.md

@@ -0,0 +1,26 @@
+---
+description: Change an EXISTING feature — intake → map (read-only) → plan → execute in modify mode → verify with mandatory regression → ship. Use for extending/modifying a module that already exists.
+disable-model-invocation: true
+argument-hint: "<prompt | user story | spec describing the change>"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent
+---
+
+# wavefront-change
+
+Change request: $ARGUMENTS
+
+> For modifying existing code. Map-first + regression are mandatory (modifying working code is higher-risk than greenfield).
+
+## Steps
+1. **Intake** — read `requirement-intake` skill; classify as a CHANGE; produce/append the work item in `.claude/.planning/REQUIREMENTS.md` (Type: change). Interactive + proactive: ask blocking questions, suggest gaps (esp. what existing behavior must be preserved).
+2. **Map (mandatory, read-only)** — dispatch the `mapper` agent over the target module(s). It reports current state + a change-plan (ADD/MODIFY/KEEP, layers, blast radius, regression surface). Do NOT skip this. Write the change-plan into `PHASE_PLAN.md`.
+3. **Plan** — turn the change-plan into ordered tasks (each tagged module-builder modify / tester / i18n-tokens / reviewer). Map new acceptance criteria → tests; note the regression set (existing tests that must stay green).
+4. **Execute (modify mode)** — dispatch `module-builder` in MODIFY mode with the mapper change-plan; it edits only the planned files, preserves existing code/public API. Then `tester`: extend tests for new criteria AND confirm the regression set still passes. Then `i18n-tokens` if UI strings/tokens changed. Update `STATE.md` after each task.
+5. **Verify (mandatory regression)** — `/wavefront-verify` style: reviewer in **change-review (diff-aware)** mode + run new tests AND the full module's existing tests (`yarn test --testPathPatterns=<module>`) + tsc + lint. PASS requires: reviewer PASS, new criteria covered, AND no regression (existing tests green).
+6. **Ship** — `/wavefront-ship` (confirm first; verified only).
+
+## Rules
+- Map before edit — always. No modify without a mapper change-plan.
+- Regression is part of the gate, not optional.
+- Touch only what the change-plan lists; preserve public API unless the plan changes it.
+- Stop and ask on Ask-first (new dep, shared-file edit, public-API change).

package/commands/wavefront-execute.md

@@ -0,0 +1,28 @@
+---
+description: Execute a PHASE_PLAN — drive module-builder → tester → i18n-tokens through the tasks in dependency order, updating STATE after each. Resumes from STATE if interrupted.
+disable-model-invocation: true
+argument-hint: "<work item title>"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent
+---
+
+# wavefront-execute
+
+Execute the plan for: $ARGUMENTS
+
+## Steps
+1. Read `.claude/.planning/PHASE_PLAN.md` (item $ARGUMENTS) and `STATE.md`. Resume at the first wave/task not marked done. Check the `parallelization` config flag (default off).
+2. Execute **wave by wave** (a single-module item is just one wave with one item):
+   - **If `parallelization` is on AND the wave has multiple independent items:** dispatch their `module-builder` subagents **in parallel** — multiple Agent calls in ONE message. Each builder gets ONLY its module slice (target files + relevant skills + acceptance criteria). Wait for the whole wave to finish before the next wave.
+   - **Otherwise (default):** run items sequentially.
+   - Within any single module, tasks are always sequential (layer chain): types→api→gateway→repo→store→selector→hook→view→barrels.
+3. Per item, after build: dispatch `tester`, then `i18n-tokens` if UI changed. (These can also run per-item within the wave.)
+4. After EACH task/item: mark done in `PHASE_PLAN.md`, update `STATE.md` (current wave, last step, next step). Resume point.
+5. After a wave: run `tsc --noEmit` + `yarn lint`; fix failures (route to owning agent) before the next wave.
+6. Do NOT run the reviewer here — that's `/wavefront-verify`. Stop after the build/test/i18n tasks and report status + next command (`/wavefront-verify "<title>"`).
+
+## Rules
+- Persist STATE after each task AND each wave (interruption-safe; resume mid-plan).
+- Fresh-context dispatch: each subagent gets only its slice.
+- Parallel only across INDEPENDENT items in the same wave; never parallelize items that touch the same shared file.
+- Within a module, always sequential (dependency chain).
+- Stop and ask on Ask-first (new dep, shared-file edit, breaking change).

package/commands/wavefront-feature.md

@@ -0,0 +1,25 @@
+---
+description: Start a new-feature work item — run interactive intake on a prompt/user-story/spec and produce a REQUIREMENTS spec. First step of the new-feature loop.
+disable-model-invocation: true
+argument-hint: "<prompt | user story | path-to-spec>"
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# wavefront-feature
+
+Intake a new feature: $ARGUMENTS
+
+## Steps
+1. Read the `requirement-intake` skill (`.claude/skills/requirement-intake/SKILL.md`) and follow it.
+2. Read `.claude/.planning/PROJECT.md` for context (run `/wavefront-init` first if missing).
+3. Classify the input ($ARGUMENTS) as prompt / user story / spec. If it's a path, read the file.
+4. Run intake **interactively + proactively**: extract intent/scope/entities/layers, then surface Open questions (blocking) and Suggested additions (edge cases, error states, i18n/a11y, implicit criteria). Ask the blocking questions before finalizing.
+5. **Design intake (if UI work):** if the input references or attaches a design (Figma — live via a configured Figma MCP, else as an export/image; image/screenshot path, HTML, a reference screen, or just a description — or NOTHING), run the `design-intake` skill → produce a design-spec mapped to `@/ui`+tokens. With no design, use the continuity path (`design-system-inventory`). Record the design-spec with the work item; flag any gaps (design elements with no `@/ui` equivalent) as Ask-first.
+6. Write the work item into `.claude/.planning/REQUIREMENTS.md` (append a new section; status: `planned`-ready once questions resolved).
+7. Add it to `ROADMAP.md` (Now/Next) and update `STATE.md` (active item, next step = `/wavefront-plan`).
+8. Report the spec summary (+ design-spec if any) + next command: `/wavefront-plan "<title>"`.
+
+## Rules
+- Do not plan or write feature code here — intake only.
+- Don't finalize with unresolved blocking questions.
+- Acceptance criteria must be testable (they drive the tester later).

package/commands/wavefront-fix.md

@@ -0,0 +1,28 @@
+---
+description: Fix a bug — intake/repro → diagnose+locate (read-only) → regression test RED → patch → GREEN → verify → ship. Use for bug fixes, not new features or feature changes.
+disable-model-invocation: true
+argument-hint: "<bug description or reproduction steps>"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent
+---
+
+# wavefront-fix
+
+Bug: $ARGUMENTS
+
+> Bug-fix posture: smallest change that fixes it, captured by a regression test that fails before and passes after.
+
+## Steps
+1. **Intake / repro** — read `requirement-intake` skill; classify as a FIX. Capture the bug as a work item in `.claude/.planning/REQUIREMENTS.md` (Type: fix): expected vs actual behavior, reproduction steps, affected area. Ask for repro details if missing (a bug you can't reproduce, you can't verify fixed).
+2. **Diagnose + locate (read-only)** — dispatch the `reviewer` agent in **diagnose mode**. It traces the data flow through the layers and reports root cause as `file:line + why wrong + fix direction`. Write the diagnosis into `PHASE_PLAN.md`. No edits yet.
+3. **Regression test RED** — dispatch the `tester` agent (bug regression flow): write a colocated test that reproduces the bug and **fails against current code** (RED). Confirm it's actually red (run it). This captures the bug.
+4. **Patch** — dispatch `module-builder` in **patch mode** (smallest focused change at the diagnosed location; respects surrounding code; touches only what's needed).
+5. **GREEN + regression** — re-run the new test → must PASS. Run the module's existing tests + tsc + lint → no regression.
+6. **Verify** — `reviewer` change-review (diff-aware) mode: confirm the patch is minimal, public API intact, and the regression test + existing tests pass. PASS/FAIL.
+7. **Ship** — `/wavefront-ship` (confirm first; verified only). Commit references the bug.
+8. Update `STATE.md` after each step (resume-safe).
+
+## Rules
+- Test before fix: the regression test must be RED before patching, GREEN after. If it's not RED first, it doesn't capture the bug.
+- Patch posture: minimal change; no refactors/cleanup riding along.
+- The regression test stays permanently (prevents recurrence).
+- Diagnose is read-only; patch is module-builder; never skip the RED step.

package/commands/wavefront-init.md

@@ -0,0 +1,27 @@
+---
+description: Initialize wavefront planning artifacts (.claude/.planning/) for this project. Run once per project before the loop.
+disable-model-invocation: true
+argument-hint: "(no args)"
+allowed-tools: Read, Write, Bash, Glob
+---
+
+# wavefront-init
+
+Set up the planning workspace for the wavefront loop in this project.
+
+## Steps
+1. Create `.claude/.planning/` if missing.
+2. For each of PROJECT, REQUIREMENTS, ROADMAP, STATE — if the file doesn't already exist in `.claude/.planning/`, create it from the wavefront template (the templates live in the installed wavefront surface; if not present locally, write the equivalent skeleton: see structure below). Do NOT overwrite existing planning files.
+3. Fill `PROJECT.md` by inspecting the repo: read `package.json`, `README.md`, `src/` layout, existing `src/modules/*` to describe what the app is, its stack, and domain notes. Ask the user to confirm/correct the PROJECT summary.
+4. Leave REQUIREMENTS/ROADMAP/STATE as empty skeletons (populated by feature/plan runs).
+5. Report what was created and the next command (`/wavefront-feature "<work item>"`).
+
+## Skeleton reference
+- PROJECT.md: what the app is · stack · conventions source (wavefront skills) · domain notes · constraints.
+- REQUIREMENTS.md: per-work-item spec (filled by intake).
+- ROADMAP.md: Now / Next / Done backlog.
+- STATE.md: active item · last step · next step · progress · decisions · blockers.
+
+## Rules
+- Idempotent: never clobber existing planning files.
+- PROJECT facts come from reading the repo, not assumptions — confirm with the user.

package/commands/wavefront-plan.md

@@ -0,0 +1,30 @@
+---
+description: Turn a REQUIREMENTS work item into an executable PHASE_PLAN (which agents, which layers/files, in dependency order).
+disable-model-invocation: true
+argument-hint: "<work item title>"
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# wavefront-plan
+
+Plan the work item: $ARGUMENTS
+
+## Steps
+1. Read the work item from `.claude/.planning/REQUIREMENTS.md` (match by title $ARGUMENTS). If missing, tell the user to run `/wavefront-feature` first.
+2. Read the relevant wavefront skills to size the work: `clean-architecture`, `module-structure`, plus the pattern skills for the layers this touches.
+3. For a **new module**: plan the full bottom-up chain (types/schemas → api → gateway → repository → store → selectors → view+hooks → components → barrels → tests → i18n → review). For a smaller feature, include only the needed tasks.
+4. Map each acceptance criterion to the test(s) that will cover it.
+5. Note risks: shared-file edits (e.g. `@/api/endpoints`), new deps (ask-first), anything that touches existing code.
+6. **Dependency analysis → waves** (if the item spans multiple modules/entities): group them into waves.
+   - Items in the **same wave** are INDEPENDENT (no cross-import, no shared-file edits between them) → parallel-safe.
+   - A later wave depends on an earlier one (e.g. module B imports module A's public API → A in wave 1, B in wave 2).
+   - **Any two items that edit the SAME shared file** (`@/api/endpoints`, global types) go in the same wave-lane SERIALLY, never parallel (avoids write races).
+   - A single-module item = one wave, one item (sequential layer chain inside it). Within a module, tasks are always sequential.
+7. Write `.claude/.planning/PHASE_PLAN.md`: tasks in dependency order per item, each tagged with its agent (module-builder / tester / i18n-tokens / reviewer); annotate waves (`## Wave 1 (parallel): moduleA, moduleB` / `## Wave 2: moduleC`).
+8. Update `STATE.md` (status: planned, next step = `/wavefront-execute`). Report the plan (+ waves) + next command.
+
+## Rules
+- Within a module: sequential (the Clean Arch layer chain is a dependency order).
+- Across independent modules: group into parallel waves (executed concurrently only if config `parallelization` is on; otherwise sequential).
+- Two items touching the same shared file are NOT parallel — serialize them.
+- Every task names its agent and target files. Reviewer is the last task per item (PASS gate).

package/commands/wavefront-ship.md

@@ -0,0 +1,26 @@
+---
+description: Ship a verified work item — create a branch, commit the work, and open a PR. Only runs on a verified item.
+disable-model-invocation: true
+argument-hint: "<work item title>"
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+# wavefront-ship
+
+Ship the verified work item: $ARGUMENTS
+
+## Preconditions
+- `STATE.md` shows the item status = `verified`. If not, stop and tell the user to run `/wavefront-verify` (don't ship unverified work).
+
+## Steps
+1. Confirm the item is verified (STATE). Show the user the changed files (`git status`, `git diff --stat`) and the planned commit message + PR title; **ask for confirmation before any git write** (branch/commit/push/PR are shared-state actions).
+2. On confirm: create a branch following the scaffold convention `feat/<kebab-title>` (or `fix/…` for fixes). Validate the branch name (`yarn validate:branch` if present).
+3. Stage the work item's files (named, not `git add -A` blindly). Commit with a Conventional Commit message derived from the work item (`feat: <intent>`). NEVER add Claude/AI as co-author or in the body.
+4. Push the branch; open a PR with `gh pr create` — body = intent + scope + acceptance criteria checklist + test plan.
+5. Update `STATE.md` (status: shipped) and `ROADMAP.md` (move item to Done). Report the PR URL.
+
+## Rules
+- Never ship unverified work.
+- Branch/commit/push/PR are irreversible/shared — confirm with the user first.
+- No Claude/AI attribution in commits or PRs.
+- Use Conventional Commits + the scaffold's branch-naming convention.

package/commands/wavefront-state.md

@@ -0,0 +1,23 @@
+---
+description: Show the current wavefront loop position (active work item, last/next step, progress, blockers) from .planning/STATE.md.
+argument-hint: "(no args)"
+allowed-tools: Read, Glob
+---
+
+# wavefront-state
+
+Show where the loop stands.
+
+## Steps
+1. Read `.claude/.planning/STATE.md`. If missing, say the project isn't initialized (`/wavefront-init`).
+2. Read `ROADMAP.md` for Now/Next/Done context.
+3. Report concisely:
+   - Active work item + status.
+   - Last step done · next step (the exact command to run).
+   - Execution progress (which PHASE_PLAN tasks done/next).
+   - Any blockers.
+4. If there's a clear next command, name it so the user can continue.
+
+## Rules
+- Read-only. Never edit planning files here.
+- This is the safe "where am I?" command — fine for Claude to invoke automatically (no `disable-model-invocation`).

package/commands/wavefront-verify.md

@@ -0,0 +1,24 @@
+---
+description: Verify executed work — run the reviewer agent + test suite against the work item, check acceptance criteria, and emit a fix plan if anything fails.
+disable-model-invocation: true
+argument-hint: "<work item title>"
+allowed-tools: Read, Bash, Grep, Glob, Agent
+---
+
+# wavefront-verify
+
+Verify the work item: $ARGUMENTS
+
+## Steps
+1. Read the item's `REQUIREMENTS` (acceptance criteria) + `PHASE_PLAN` (what was built).
+2. Dispatch the `reviewer` subagent (code-review mode) over the changed module/files → expect PASS/FAIL with BLOCKER/WARNING/NIT.
+3. Run the tests for the work item (`yarn test --testPathPatterns=<module>`) and `yarn typecheck` + `yarn lint`. Note: a single-module test run trips the 85% global coverage gate (exit 1) even when tests pass — judge by `Tests: N passed`, not the exit code.
+4. Check each **acceptance criterion** is actually covered by a passing test. List any uncovered.
+5. Verdict:
+   - **PASS** (reviewer PASS + tests green + criteria covered) → update `STATE.md` (status: verified, next = `/wavefront-ship`). Report.
+   - **FAIL** → write a concise fix plan (what failed, which file, which agent should fix) into `STATE.md` blockers + report. Do not ship.
+6. Do NOT edit code here — verify is read-only/dispatch. Fixes go back through `/wavefront-execute` or the owning agent.
+
+## Rules
+- Read-only on source (reviewer + test runs). No edits.
+- Acceptance criteria are the bar — reviewer PASS alone isn't enough if a criterion is untested.

package/hooks/lint-after-edit.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# wavefront PostToolUse hook — lint (+autofix) the file Claude just edited/wrote.
+# Warn-only: never blocks (exit 0). The reviewer agent is the real gate.
+# Reads the PostToolUse JSON on stdin; acts only on TS/JS/style files in the project.
+set -uo pipefail
+
+input="$(cat)"
+file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
+
+[ -n "$file_path" ] || exit 0
+[ -f "$file_path" ] || exit 0
+cd "${cwd:-.}" 2>/dev/null || exit 0
+
+# Only run inside a project that has the tooling.
+[ -f package.json ] || exit 0
+
+case "$file_path" in
+  *.ts|*.tsx|*.js|*.jsx)
+    tool="eslint" ;;
+  *.css|*.scss)
+    tool="stylelint" ;;
+  *)
+    exit 0 ;;
+esac
+
+run_bin() {
+  # Prefer local binary; fall back to npx without network install.
+  if [ -x "node_modules/.bin/$1" ]; then "node_modules/.bin/$1" "${@:2}"; else npx --no-install "$@"; fi
+}
+
+if [ "$tool" = "eslint" ]; then
+  out="$(run_bin eslint --fix "$file_path" 2>&1)"; status=$?
+else
+  out="$(run_bin stylelint --fix "$file_path" 2>&1)"; status=$?
+fi
+
+if [ $status -ne 0 ] && [ -n "$out" ]; then
+  # Warn-only: surface to Claude as context, do not block.
+  jq -n --arg msg "wavefront $tool found issues in $file_path (autofixed what it could):"$'\n'"$out" \
+    '{systemMessage: $msg, suppressOutput: true}' 2>/dev/null || true
+fi
+exit 0

package/hooks/typecheck-on-stop.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# wavefront Stop hook — run a project-wide typecheck once when Claude finishes.
+# Warn-only: never blocks the stop (exit 0). tsc is whole-project (needs the @/ path graph),
+# so it runs at end-of-turn, not per-edit.
+set -uo pipefail
+
+input="$(cat)"
+cwd="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
+cd "${cwd:-.}" 2>/dev/null || exit 0
+
+[ -f package.json ] || exit 0
+[ -f tsconfig.json ] || exit 0
+
+# Prefer the project's typecheck script; fall back to tsc directly.
+if grep -q '"typecheck"' package.json 2>/dev/null; then
+  out="$(yarn --silent typecheck 2>&1)"; status=$?
+elif [ -x node_modules/.bin/tsc ]; then
+  out="$(node_modules/.bin/tsc --noEmit --skipLibCheck 2>&1)"; status=$?
+else
+  exit 0
+fi
+
+if [ $status -ne 0 ] && [ -n "$out" ]; then
+  jq -n --arg msg "wavefront typecheck failed:"$'\n'"$out" \
+    '{systemMessage: $msg, suppressOutput: true}' 2>/dev/null || true
+fi
+exit 0

package/install.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# wavefront installer — frontend engineering agents for scaffold-nextjs-app apps.
+# Usage:
+#   ./install.sh --global <target-app> [--with-hooks]   install to ~/.wavefront/ and symlink into <target-app>/.claude
+#   ./install.sh --local  <target-app> [--with-hooks]   copy the surface into <target-app>/.claude
+# --with-hooks also installs the quality-gate hooks (eslint --fix on edit, tsc on stop).
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOME_DIR="${WAVEFRONT_HOME:-$HOME/.wavefront}"
+SURFACE=(agents skills commands planning-templates)
+
+die() { echo "error: $*" >&2; exit 1; }
+
+usage() {
+  cat <<'EOF'
+wavefront installer
+  ./install.sh --global <target-app> [--with-hooks]   install to ~/.wavefront/ and symlink into the app
+  ./install.sh --local  <target-app> [--with-hooks]   copy the surface into the app
+Notes:
+  - <target-app> is a scaffold-nextjs-app project (the app's root, containing package.json).
+  - Override the global dir with WAVEFRONT_HOME.
+  - --with-hooks copies hooks/ into .claude/hooks and writes .claude/settings.wavefront.json
+    (you merge it into .claude/settings.json — installer never overwrites your settings).
+EOF
+}
+
+[ $# -ge 2 ] || { usage; exit 1; }
+MODE="$1"; TARGET="$2"; WITH_HOOKS=""
+[ "${3:-}" = "--with-hooks" ] && WITH_HOOKS=1
+
+[ -d "$TARGET" ] || die "target app dir not found: $TARGET"
+CLAUDE_DIR="$TARGET/.claude"
+mkdir -p "$CLAUDE_DIR"
+
+install_hooks() {
+  [ -n "$WITH_HOOKS" ] || return 0
+  echo "→ installing quality-gate hooks into $CLAUDE_DIR/hooks"
+  rm -rf "${CLAUDE_DIR:?}/hooks"
+  cp -r "$REPO_DIR/hooks" "$CLAUDE_DIR/hooks"
+  chmod +x "$CLAUDE_DIR"/hooks/*.sh
+  cp "$REPO_DIR/settings.template.json" "$CLAUDE_DIR/settings.wavefront.json"
+  echo "  ⚠ merge $CLAUDE_DIR/settings.wavefront.json into $CLAUDE_DIR/settings.json (hooks block)."
+  command -v jq >/dev/null 2>&1 || echo "  ⚠ hooks need 'jq' on PATH."
+}
+
+install_global() {
+  echo "→ installing surface to $HOME_DIR"
+  mkdir -p "$HOME_DIR"
+  for d in "${SURFACE[@]}"; do
+    rm -rf "${HOME_DIR:?}/$d"
+    cp -r "$REPO_DIR/$d" "$HOME_DIR/$d"
+  done
+  echo "→ symlinking into $CLAUDE_DIR"
+  for d in "${SURFACE[@]}"; do
+    local link="$CLAUDE_DIR/$d"
+    if [ -e "$link" ] && [ ! -L "$link" ]; then
+      die "$link exists and is not a symlink — refusing to overwrite. Remove it or use --local."
+    fi
+    rm -f "$link"
+    ln -s "$HOME_DIR/$d" "$link"
+  done
+  echo "✓ global install done. Update later with: git -C \"$REPO_DIR\" pull && ./install.sh --global \"$TARGET\""
+}
+
+install_local() {
+  echo "→ copying surface into $CLAUDE_DIR"
+  for d in "${SURFACE[@]}"; do
+    [ -d "$REPO_DIR/$d" ] || continue
+    rm -rf "${CLAUDE_DIR:?}/$d"
+    cp -r "$REPO_DIR/$d" "$CLAUDE_DIR/$d"
+  done
+  echo "✓ local copy done."
+}
+
+case "$MODE" in
+  --global) install_global; install_hooks ;;
+  --local)  install_local;  install_hooks ;;
+  -h|--help) usage; exit 0 ;;
+  *) usage; die "unknown mode: $MODE" ;;
+esac
+
+echo "Agents available in Claude Code: module-builder, tester, i18n-tokens, reviewer."

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@pavp/wavefront",
+  "version": "0.1.0",
+  "description": "Claude Code frontend-engineering agent framework for scaffold-nextjs-app apps (Next.js/React/MUI/Clean Architecture). Installs agents, skills, and an orchestration loop into a project's .claude/.",
+  "bin": {
+    "wavefront": "bin/wavefront.js"
+  },
+  "scripts": {
+    "prepare": "node -e \"if(process.env.CI !== 'true') require('child_process').execSync('husky', {stdio: 'inherit'})\"",
+    "release": "semantic-release",
+    "release:dry": "semantic-release --dry-run",
+    "validate:commits": "commitlint --from origin/main --to HEAD --verbose",
+    "validate:branch": "node scripts/validate-branch-name.js"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "skills/",
+    "commands/",
+    "planning-templates/",
+    "hooks/",
+    "install.sh",
+    "uninstall.sh",
+    "settings.template.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "agents",
+    "nextjs",
+    "react",
+    "mui",
+    "clean-architecture",
+    "frontend",
+    "scaffold-nextjs-app"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pavp/wavefront.git"
+  },
+  "homepage": "https://github.com/pavp/wavefront#readme",
+  "bugs": {
+    "url": "https://github.com/pavp/wavefront/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "husky": "9.1.7",
+    "semantic-release": "25.0.3"
+  }
+}

package/planning-templates/PHASE_PLAN.md

@@ -0,0 +1,37 @@
+# PHASE_PLAN — <work item>
+
+> Executable plan produced by `/wavefront-plan`. Drives `/wavefront-execute`.
+
+## Work item
+<title> · type: feature|change|fix · ref: REQUIREMENTS § <title>
+
+## Approach
+<1–3 sentences: how this gets built, which modules>
+
+## Waves (multi-module items only; single-module = one wave)
+> Items in the same wave are independent (parallel-safe when config `parallelization` is on).
+> Items touching the same shared file must NOT share a parallel wave.
+- Wave 1 (parallel): <moduleA>, <moduleB>
+- Wave 2: <moduleC depends on A>
+
+## Tasks (dependency order, grouped by wave/item)
+> Each task: agent · target files · status (pending|done). Sequential within a module.
+
+1. [ ] **types+schemas** — module-builder — `modules/<m>/<m>.types.ts`
+2. [ ] **api** — module-builder — `modules/<m>/api/<entity>-api.ts` (+ endpoints, ask-first)
+3. [ ] **gateway** — module-builder — `repositories/<entity>/gateways/`
+4. [ ] **repository** — module-builder — keys/options/queries/mutations/types/index
+5. [ ] **store** — module-builder — (if local state)
+6. [ ] **selectors** — module-builder — (as needed)
+7. [ ] **view + hooks** — module-builder — business + controller split
+8. [ ] **components** — module-builder — `@/ui` + tokens
+9. [ ] **barrels** — module-builder — index.ts
+10. [ ] **tests** — tester — colocated, cover acceptance criteria
+11. [ ] **i18n + tokens** — i18n-tokens — de-hardcode
+12. [ ] **review** — reviewer — PASS gate (lint+tsc+conventions)
+
+## Acceptance criteria → tests map
+- <criterion> → <test it maps to>
+
+## Risks / notes
+<shared-file edits, deps, anything risky>

package/planning-templates/PROJECT.md

@@ -0,0 +1,18 @@
+# PROJECT
+
+> Project-level context for wavefront. Written once by `/wavefront-init`, edited rarely.
+
+## What this app is
+<one paragraph: the product, its users, its purpose>
+
+## Stack
+scaffold-nextjs-app: Next.js 15 · React 19 · MUI 7 · React Query · Zustand · RHF + Zod · next-intl · Jest/RTL · Clean Architecture.
+
+## Conventions source of truth
+wavefront skills in `.claude/skills/` (clean-architecture, module-structure, naming-conventions, + patterns). Scaffold pin: `8edaa0b`.
+
+## Domain notes
+<entities, business rules, external systems the agents should know>
+
+## Constraints
+<perf, a11y, deadlines, things to avoid>

package/planning-templates/REQUIREMENTS.md

@@ -0,0 +1,27 @@
+# REQUIREMENTS
+
+> Per-work-item spec produced by intake (`requirement-intake` skill). One section per active work item.
+
+## Work item: <short title>
+Type: feature | change | fix
+Source: prompt | user story | spec
+Status: intake | planned | in-progress | verified | shipped
+
+### Intent
+<who, what, why — 1–3 sentences>
+
+### Scope
+- In: <included>
+- Out: <excluded>
+
+### Entities & layers touched
+<entities; Clean Arch layers affected>
+
+### Acceptance criteria (→ tests)
+- [ ] <observable criterion>
+
+### Resolved questions
+- <q> → <answer>
+
+### Notes
+<anything the plan/execute steps need>