Sumitsubo 墨壺
Mark the line before you cut.
A Claude Code framework for web design and development: direction first, then the work.
Documentation · Reference · Documentación en español · Guía en español · Roadmap
A sumitsubo is the Japanese carpenter's ink line: it snaps the true line onto the wood before any cut is made. This framework does the same for AI-assisted web work. It encodes how a senior design engineer works — process that scales with the request, code without slop, accessibility and performance as acceptance criteria — and, above all, design that doesn't look like every other AI-generated site.
Short name and command prefix: sumi (墨, ink).
Install
You need Claude Code and git. No SSH keys, no global config changes.
1. One command (recommended)
npx sumitsubo
Run it inside a project and it installs the core, the design layer, every companion and the stack pack it detects (Nuxt, Next.js, Shopify or WordPress), then checks the installed files on disk rather than trusting the success message. Needs Node 18+.
npx sumitsubo --stack nuxt,wordpress # choose stack packs instead of detecting them
npx sumitsubo doctor # check the installation
npx sumitsubo update # update everything, repairing damaged installs
npx sumitsubo uninstall # remove it all
npx sumitsubo doctor --json # one JSON result line on stdout, for CI and scripts
2. Inside Claude Code
/plugin marketplace add kurodaSensei/sumitsubo
/plugin install sumi-design@sumitsubo core + design + all companions
/plugin install sumi-nuxt@sumitsubo plus the stack pack(s) you use
3. From a clone (offline copies, forks, editing the framework)
git clone https://github.com/kurodaSensei/sumitsubo.git
claude plugin marketplace add ./sumitsubo
claude plugin install sumi-design@sumitsubo
Plugins from a local marketplace load in place, so edits in the clone apply at the next session. Update with git pull.
Restart Claude Code after installing; plugins load at startup.
Other agents (Cursor, Codex)
npx sumitsubo rules # .cursor/rules + AGENTS.md, in the current project
npx sumitsubo rules --target cursor # or codex
Writes the same always-on rules and standards for Cursor (.cursor/rules/*.mdc) and for Codex or any agent that reads AGENTS.md, with the skills, templates and scripts in .sumitsubo/. Your own rules and AGENTS.md content are left alone; re-run it after updating. Commands, hooks, subagents and model routing are Claude Code features and don't carry over.
npx sumitsubo --sandbox # throwaway Claude profile, your config is never touched
npx sumitsubo --sandbox --no-ssh # same, on a simulated machine without GitHub SSH keys
The sandbox prints how to open Claude Code inside it and how to delete it.
Quick start
In a project:
/sumi:init set up .sumi/, the managed CLAUDE.md block and the model profile
/sumi-design:direction brief → three divergent directions → DESIGN.md
/sumi:feature <idea> plan large work in one feature file
/sumi:review review the current slice with context-free lenses
/sumi:ship final gate and PR draft
/sumi:doctor read-only check of the install and this project
How it works
flowchart LR
A["/sumi:init"] --> B["/sumi-design:direction<br/>DESIGN.md"]
B --> C{"Size of the request"}
C -->|small| D["Direct change"]
C -->|medium| E["Delegated to a builder"]
C -->|large| F["/sumi:feature<br/>feature file + slices"]
D --> G["/sumi:review"]
E --> G
F --> G
G --> H["/sumi-design:critique"]
H --> I["/sumi:ship"]
- Direction before pixels. A brief with brand tensions, explicit anti-references, three directions that differ on at least five axes, and a
DESIGN.md whose contrast is verified by script. A cross-project design ledger keeps you from repeating fonts, palettes and layouts across clients.
- Process proportional to the request. Small things get done directly; large work gets one organic feature file with acceptance criteria and evidence. A scope check stops and asks Minimal or Extended? when a plan outgrows what you asked for.
- Small houses, not Eiffel towers. About 400 changed lines per slice. Deliberate simplifications are marked with
ponytail: comments that say when to extend them.
- Fresh eyes, on a budget. Reviews run as subagents that see a frozen diff and the check results, never the author's reasoning. At most three lenses per review, each with a hard tool budget.
Model routing
Opus only where it changes the outcome:
| Role | Model (balanced) | Does |
|---|
scout | Haiku | Finds files, reads versions and docs, summarizes |
builder | Sonnet | Implements briefed tasks and slices, runs checks |
architect | Opus | Architecture, data models, migrations, slicing, trade-offs |
| Review lenses | Sonnet · Opus for high-risk security | Context-free reviews |
| Session | opusplan | Opus while planning, Sonnet while executing |
Switch per project with /sumi:models balanced | economy | performance. → Model routing reference
What's inside
| Plugin | | What it gives you |
|---|
sumi | core | Adaptive workflow, scope check, line budgets, risk gates, budgeted receipt-based reviews, model routing, standards for HTML, CSS, JS/TS, accessibility (WCAG 2.2 AA) and performance (Core Web Vitals), git and secret guard hooks |
sumi-design | core | Creative direction, anti-slop catalog, design ledger, DESIGN.md tokens with contrast checker, motion rules, design lens, Claude Design bridge |
sumi-nuxt | stack | Nuxt 4, Vue 3.5, Firebase/Firestore, Tailwind v4 |
sumi-react | stack | React 19: Next.js App Router, caching, Server Actions, and Vite SPAs with React Router, Zustand and TanStack Query; testing |
sumi-shopify | stack | Online Store 2.0 themes: Liquid, sections and blocks, storefront JS, e-commerce accessibility |
sumi-wordpress | stack | Native block themes with no build step: theme.json design system, dynamic blocks, core APIs over plugins, token audit |
| Command | Purpose |
|---|
/sumi:init | Detect the stack, create .sumi/, write the managed CLAUDE.md block, set the model profile |
/sumi:feature | Explore, check scope, refute uncertainty and write the feature file |
/sumi:review | Budgeted review of the current slice; --quick for small changes |
/sumi:ship | Checks, evidence, deliberate simplifications and the PR draft |
/sumi:models | Show or switch the model profile and session model |
/sumi:sync | Update the managed CLAUDE.md block and config to the installed version |
/sumi:doctor | Read-only: marketplace source, version drift, companions, project config |
/sumi-design:direction | The full creative-direction process |
/sumi-design:critique | Critique screens against DESIGN.md and the anti-slop catalog |
|
Companions
Installing sumi and sumi-design also installs curated pieces of Impeccable, Ponytail, Taste, Emil Kowalski's skills and Superpowers as dependencies. They are referenced from their upstream repositories, never copied, so they keep their licenses and update from their authors. Sumitsubo decides when each one runs; the full install adds about 6k tokens of always-on context. See THIRD-PARTY.md.
Principles
- Process must be justified. Help the user decide; don't use every capability by default.
- Small houses, not Eiffel towers. The best solution within the budget.
- Done means verified. Tests run, axe results, Lighthouse numbers, screenshots.
- Fresh eyes. Reviewers never see the author's reasoning.
- Nothing visual by default. Every font, color, radius and animation traces back to
DESIGN.md.
- Deterministic where possible. Hooks and scripts handle what should never depend on a model's mood.
Repository layout
.claude-plugin/marketplace.json 6 plugins + 15 upstream companions
bin/sumitsubo.mjs the npx installer (wraps `claude plugin`, no dependencies)
plugins/<plugin>/
.claude-plugin/plugin.json
skills/<skill>/SKILL.md (+ references/, scripts/)
agents/ commands/ hooks/ templates/
scripts/validate.mjs
docs/GUIA.md Spanish guide
docs/ARCHITECTURE.md layers, project state, roadmap
Development
node scripts/validate.mjs # structure, versions, companion sources, references
node scripts/check-companions.mjs # do the 15 companions still resolve upstream?
claude plugin validate . # official marketplace validation
npm run test:install # install this checkout in a sandbox, without SSH
npm run evals -- -- --tag trigger # skill evals: do the right skills fire? (costs tokens)
npm run evals -- sumi-design -- --tag slop --ablation with-without --allow-tools Write
# slop rate with and without the design layer
CI runs validate.mjs and a clean install (no SSH keys, no HTTPS rewrite, all four stack packs) on every push, and check-companions.mjs on pull requests and weekly on a schedule. The schedule is the point — the companions live in repositories this project does not control, so an author renaming a folder breaks /plugin install for everyone on a day nobody here pushed anything.
Releasing is one command and one merge:
npm run release 0.7.0 # bumps every version (plugins, marketplace, installer, managed block) and validates
Merging that PR to main runs release.yml: the clean install test, the vX.Y.Z tag, the npm package, a GitHub release and a re-sync request to the docs site. npm holds a new version for review (staged publishing); it goes live when a maintainer approves it under npmjs.com → sumitsubo → Staged Packages (or npm stage approve <id>) with 2FA. See CHANGELOG.md.
The documentation site (source) renders its reference pages from this repository; re-sync it after changing skills or commands.
Credits
Concepts inspired by Gentle AI (Gentleman Programming). Companions are independent projects with their own licenses. Contributions welcome — see CONTRIBUTING.md. Sumitsubo is MIT licensed, by Alfredo Romero.
