wavefront — Frontend Engineering Agents

Claude Code agent framework for apps generated by scaffold-nextjs-app (Next.js 15 · React 19 · MUI 7 · React Query · Zustand · RHF + Zod · next-intl · Jest/RTL · Clean Architecture).

6 specialist agents + 28 self-contained skills + a 10-command orchestration loop, so you describe work items instead of writing boilerplate. Generates responsive, composed UI continuous with your app — from a Figma export, screenshot, description, or nothing — with a colocated test in every layer.

Distilled from real scaffold code, pinned at commit 8edaa0b (modules todo/auth, about-view, test/, src/i18n). Not from docs — from the source. E2E-validated against a generated app.

Documentation

| If you want to… | Read | |---|---| | Get started — install + first module + first feature, copy-paste | docs/USAGE.md | | Understand the model — agents vs skills vs commands, the loop, why self-contained | docs/HOW-IT-WORKS.md | | Fix a problem — symptom → cause → fix (users + contributors) | docs/TROUBLESHOOTING.md | | Author the framework — file-format spec for agents/skills/commands | docs/conventions.md | | See the history — phase plan + roadmap | docs/plan.md · docs/roadmap.md |

New here? Start with USAGE. The rest of this page is a reference.

Install

# via npm (no clone)
npx @pavp/wavefront install --global /path/to/your-next-app --with-hooks   # ~/.wavefront + symlink
npx @pavp/wavefront install --local  /path/to/your-next-app                # copy into the app
npx @pavp/wavefront uninstall /path/to/your-next-app

• Global + symlink (recommended for multiple apps): one source in ~/.wavefront/, re-pull/upgrade once → all projects updated.
• Local: a self-contained copy in the app's .claude/, no global state.
• Needs bash (macOS/Linux or WSL). Claude Code auto-discovers agents/+skills/+commands/ under .claude/ — no build step.
• --with-hooks also installs quality-gate hooks (eslint/stylelint on edit, tsc at end of turn; warn-only). It writes .claude/settings.wavefront.json for you to merge into your settings.json (never clobbers it); needs jq. Details + walkthrough in USAGE.

You can also git clone this repo and run ./install.sh --global|--local <app> directly — same surface.

Agents

| Agent | Use it to | Edits? | |---|---|---| | module-builder | Generate/modify a feature module across the Clean Arch chain (types → api → gateways → repository → store → selectors → hooks → views/components → barrels) | yes | | tester | Write/fix colocated Jest + RTL tests (@test/utils + faker factories) | yes | | i18n-tokens | De-hardcode UI: strings → next-intl, values → tokens, raw MUI → @/ui, next/link → @/i18n/routing | yes | | reviewer | PASS/FAIL gate (naming, layers, dependency inversion, hook split, lint/tsc) — or a skill-drift sync-audit | read-only | | mapper | Map an existing module before a change (ADD/MODIFY/KEEP plan + regression surface) | read-only | | scaffold-sync | Detect drift vs the scaffold and emit a re-distill plan (which skills are stale, what changed) | read-only |

Invoke by name ("use module-builder to add a notifications module"), or let the loop drive them. Recommended by-hand order: module-builder → tester → i18n-tokens → reviewer. Full walkthrough: USAGE §2.

Orchestration loop

Slash commands that drive the agents through a work item with resumable state in .claude/.planning/:

/wavefront-init          scaffold .planning/ (once per project)
/wavefront-feature       intake a prompt/story → REQUIREMENTS
/wavefront-plan          REQUIREMENTS → executable PHASE_PLAN
/wavefront-execute       builder → tester → i18n, STATE after each (resumable)
/wavefront-verify        reviewer + tests + acceptance criteria → PASS/FAIL
/wavefront-ship          branch + commit + PR (verified only, confirms first)
/wavefront-change        modify existing code (map-first, modify mode + regression)
/wavefront-fix           bug fix (diagnose → RED→GREEN → verify)
/wavefront-state         where am I? (read-only)
/wavefront-sync          detect drift vs the scaffold → re-distill plan (read-only)

Resumable, fresh-context per agent, parallel waves across independent modules (off by default). How it all fits together: HOW-IT-WORKS. Step-by-step: USAGE §3–5.

Design → UI

Any design source becomes UI built from @/ui + @/styles/tokens, composed like the rest of the app: live Figma MCP (official Dev Mode or Framelink — exact frames + variables → tokens), Figma export/screenshot/image, pasted HTML, a reference screen, a text description, or nothing (continuity). Responsive is mandatory (mobile-first, theme breakpoints). Details: USAGE §6.

Skills

Knowledge the agents read before acting — one pattern each, distilled from real scaffold code. Every skill carries source + source_version (pinned 8edaa0b) for drift tracking via sync-audit.

• Architecture: clean-architecture · module-structure · naming-conventions
• Code quality (senior, cross-cutting): react-patterns (no inline fns/objects in props, exhaustive deps, memo/keys) · typescript-patterns (no any/!, boundary return types, Zod-inferred types)
• Patterns: data-fetching-react-query · gateway-pattern · repository-pattern · store-zustand · selector-pattern · hook-patterns · forms-rhf-zod · mui-design-tokens
• UI: component-composition · layout-composition · responsive-layouts · responsive-visibility · error-boundary · feedback-states · modal-dialog-toast · design-system-inventory · design-intake
• Cross-cutting: testing-jest-rtl · i18n-next-intl · api-error-handling
• Meta: sync-audit · requirement-intake · authoring-skills

Plus a bundled reference module (reference/module/note-module.md) — a canonical end-to-end Clean-Arch example the agents read to copy idioms, so generation works even after a project deletes the scaffold's example modules. Self-contained: no dependency on src/modules/todo surviving in the target app.

Conventions (hard rules the agents enforce)

• kebab-case files; suffixes *.component.tsx / *.view.tsx / *.hook.ts / *.helper.ts / *.store.ts / *.types.ts.
• Layer direction: View → business hook → repository → gateway → api. Never skip.
• UI from @/ui (not @mui/material); spacing/color from @/styles/tokens.
• Strings via next-intl t(); locale links via @/i18n/routing.
• Tests colocated; import helpers only from @test/utils.
• Zod validates at the api boundary; schemas in *.types.ts.

Format spec: docs/conventions.md.

Contributing

This repo follows Conventional Commits, enforced by commitlint (commit-msg hook) — versioning is automatic. (Full gotcha list: TROUBLESHOOTING § Contributing.)

• Commit format: type(scope): subject — lowercase subject (rejects any uppercase, incl. filenames/acronyms), ≤72 chars.
  • types: feat fix docs chore perf refactor test hotfix
  • scopes (optional): agents skills commands hooks reference planning cli bin install npm ci config husky docs deps
• Branch names: type/description (lowercase + hyphens), e.g. feat/figma-mcp-source. Enforced on pre-push (skipped in CI / on main).
• No Co-Authored-By: Claude or AI-attribution trailers in commits/PRs.
• Releases are automatic: push to main → semantic-release bumps the version (feat→minor, fix→patch, breaking→major), updates CHANGELOG.md, tags + GitHub Release, then OIDC publish to npm. Never bump version/tag/CHANGELOG by hand. After a release, git pull --ff-only before new work (semantic-release commits the bump back to main).
• Setup after clone: npm install (wires husky hooks).

Roadmap

All phases resolved — see docs/roadmap.md.

• ✅ MVP — 6 agents + 27 skills, E2E-validated.
• ✅ F1 — standalone repo + global/local install + npm distribution.
• ✅ F2 — orchestration loop + parallel waves + change/fix flows.
• ✅ F4/F5 — sync-audit drift detection · quality-gate hooks.
• ✅ F6/F7 — design intake (incl. live Figma MCP) + component composition.
• ❌ F3 — per-layer agent subdivision — won't ship (linear layer deps; F2 waves already parallelize across modules).