🐙 octopus-frontend

Fractal, refactor-first, component-isolated frontend skill for Claude Code · Codex CLI · GitHub Copilot · Cursor · Windsurf.

The system is the octopus. Every component is also an octopus. Every page is composed of component-octopuses. Every refactor is one tentacle at a time.

Builds one component at a time, gates each with hard checks (visual diff, a11y, Web Vitals, types, tests, responsive, themes, i18n), only advances when acceptance criteria pass, then composes up. Refactor is a separate, mandatory step before feature work on over-budget files. Optional Playwright visual capture (screenshots + videos) ships with the package.

Install in your project

# All agents at once
npx octopus-frontend init

# Or pick one
npx octopus-frontend init --agent=claude
npx octopus-frontend init --agent=codex
npx octopus-frontend init --agent=copilot
npx octopus-frontend init --agent=cursor
npx octopus-frontend init --agent=windsurf

# Add the Playwright visual-capture runner
npx octopus-frontend init --agent=all --with-playwright

# Specify target directory
npx octopus-frontend init --agent=claude --target=./my-app

# Overwrite existing files
npx octopus-frontend init --agent=copilot --force

What gets installed (per agent):

| Agent | Files written | |---|---| | Claude Code | .claude/skills/component-loop/SKILL.md, .claude/skills/refactor/SKILL.md, .claude/commands/octopus.md, .claude/commands/octopus-build.md, .claude/commands/octopus-refactor.md, .claude/commands/octopus-capture.md, .claude/commands/octopus-vitals.md, .claude-plugin/plugin.json, .claude-plugin/marketplace.json | | Codex CLI | AGENTS.md | | GitHub Copilot | .github/copilot-instructions.md, .github/instructions/{component,refactor,tests,a11y,web-vitals,visual-capture}.instructions.md | | Cursor | .cursor/rules/octopus-{core,component,refactor,visual-capture,a11y-perf}.mdc | | Windsurf | .windsurf/rules/octopus-{core,component,refactor,visual-capture,a11y-perf}.md | | --with-playwright | playwright/octopus/{octopus.config.ts, capture.spec.ts, vitals.spec.ts, octopus.components.json, reports/.gitkeep, README.md} |

Use

Once installed, the agent auto-loads the rules. Ask:

• "Build me a MilestoneCard component matching ./design.png."
• "Refactor MilestoneCard.tsx — it's over budget."
• "Capture screenshots for all components."

In Claude Code:

/octopus                                       # parent dispatcher (menu)
/octopus-build ./design.png                    # component build loop (asks Mode first run)
/octopus-refactor src/components/Card.tsx      # refactor over-budget file
/octopus-capture all --videos                  # Playwright visual capture
/octopus-vitals http://localhost:5173/         # Web Vitals audit → reports/

First /octopus-build run asks: Minimal / Optimal / All-In / À la carte. Selection saved to octopus.config.json. Future runs skip the prompt.

What it covers (all gated per component)

Atomicity & composition

• Renders alone with only props (no app shell, router, store, theme provider, network)
• Side effects injected as props
• Headless logic in useX hook (or signal store / Angular service)
• forwardRef, merged className/style, ...rest passthrough
• Compound components, slots, render props, polymorphic as/asChild
• useId(), controlled OR uncontrolled, pure render

Build loop

• Atomic decomposition (atoms → molecules → organisms → templates → pages)
• Build leaves first, gate each, compose up
• 5-attempt fix cap then surface delta to user

Quality gates

• Types strict, no any
• Lint clean
• Unit + interaction tests, NO providers, < 100ms each
• axe-core 0 violations, keyboard, focus, ARIA, contrast WCAG AA
• Visual diff vs reference (Playwright toHaveScreenshot, threshold ≤ 0.1) — matrix of states × themes × viewports
• Responsive 375 / 768 / 1024 / 1440 / 1920, mobile-first, logical properties (RTL)
• States: default / hover / focus / active / disabled / loading / error / empty / success
• Themes light + dark, prefers-color-scheme
• prefers-reduced-motion honored
• i18n-ready, no hardcoded strings, RTL-safe

Web Vitals

• Per-component: bundle delta, JS execution, INP-safe handlers, CLS-safe dims, LCP candidate optimizations, no layout thrash, no third-party in atoms, listener cleanup
• Page root: LCP < 2.5s · CLS < 0.1 · INP < 200ms (5-int avg) · TTFB < 800ms · FCP < 1.8s · TBT < 200ms · SI < 3.4s
• Asset budgets: HTML < 30kb gz · CSS < 60kb gz · JS < 170kb gz above-fold
• Long-task audit, memory-leak check (10× nav, ±10% heap)
• Critical CSS inline, defer/async, route-split, preload LCP image + critical fonts, preconnect

Refactor (separate command)

• One step at a time. Behavior unchanged. Tests stay green between steps.
• Surface plan first. Auto-stop if any step fails gates.
• Extractions: subcomponent, hook, utility, type, variant, story split, test split, effect() → computed(), NgModule → standalone.

Visual capture (optional)

• Playwright screenshots per state × viewport × theme
• Optional videos (5–10s walkthrough)
• Stable workshop URLs: /__workshop/<name>?state=<state>&theme=<theme>
• Pre-capture: wait for document.fonts.ready, disable animations
• Update references only after human approval

Hard limits (X-rules — defaults)

| Concern | Limit | |---|---:| | Component file lines | 200 | | Hook / Angular service lines | 150 | | Pure utility module lines | 120 | | Story file lines | 250 | | Test file lines | 300 | | Function lines | 50 | | Cyclomatic complexity | 10 | | Component props | 8 | | useEffect / effect() per component | 3 | | JSX/template nesting | 5 | | Folder depth from src/ | 6 | | Bundle delta per PR | +20 KB gz |

Override per project via octopus.config.json:

{
  "mode": "optimal",
  "framework": "react",
  "limits": { "componentLines": 250, "props": 10 },
  "workshop": "storybook",
  "testRunner": "vitest",
  "visualRegression": "playwright",
  "stylingSystem": "tailwind",
  "stateMatrixRequired": ["Default", "Loading", "Empty", "Error", "Mobile", "KeyboardFocus"]
}

Modes

• Minimal — prototypes, single-component asks. Skips visual regression, E2E, observability, i18n.
• Optimal (default) — day-to-day. Core tentacles + Web Vitals + tests.
• All-In — design systems, critical flows. Everything: visual regression, E2E, security, observability, i18n, bundle.

Frameworks (first-class)

• React — Vite, Next.js (App Router + RSC), Remix, Astro
• Angular 17+ — standalone, signals, new control flow (@if/@for/@switch/@defer), OnPush, inject()
• Vue 3 / Svelte 5 — supported with notes (Composition API + <script setup> / runes, Histoire or Storybook)

Philosophy

• Leaves before parents
• Refactor before feature, one step at a time
• Gates non-negotiable; failing a gate fails the component
• Five-attempt fix cap, then surface to human
• Screenshot IS the spec when user provides one
• No invented content, no lorem unless asked
• No big-bang generation. No "I'll fix the focus ring later."

Special thanks — 3 ninjas of frontend

• Anuroop Joy — Guru
• Arun Jose — Deadly Discipline
• Abhilash Pillai — Bullet Train

License

MIT