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

1. Process must be justified. Help the user decide; don't use every capability by default.
2. Small houses, not Eiffel towers. The best solution within the budget.
3. Done means verified. Tests run, axe results, Lighthouse numbers, screenshots.
4. Fresh eyes. Reviewers never see the author's reasoning.
5. Nothing visual by default. Every font, color, radius and animation traces back to DESIGN.md.
6. 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.