Sumitsubo Workflow

Process must be justified by the request. Small things get done; uncertain things get investigated; large things get a plan. Never apply heavy process to a light task, and never improvise a large task without a written plan.

1. Classify the request (always, silently)

Re-classify when you learn something. A T0 that turns out to touch auth or payments becomes T1 at minimum.

1b. Right-size before you plan (scope check)

Your job is to help the user decide, not to use every capability. Before writing a plan, compare it with the literal request:

• Would the plan exceed 3 slices, or add subsystems the user did not mention (i18n, a content pipeline, server/API routes, auth, a CMS, search, generated pages, a token generator)?
• Is there a materially simpler version that satisfies the literal request?

If yes, STOP and present two options before planning in detail: Minimal (what was literally asked) and Extended (what you would add and why), each with slices, rough line count and what it costs in time and review. Recommend one. The user chooses; record the choice as a decision. A deliberate "go big" from the user is valid — the point is that it is a choice, not a drift.

Re-run this check whenever the plan grows during work (new phase, new subsystem): growth needs the user's OK, not just a process-log line.

Process weight follows the same rule: small sites and simple changes get T0/T1, a single --quick review and no feature file. Heavy process on light work is a defect, not rigor.

2. Refute uncertainty before acting

Before writing code for anything non-trivial, list what you are assuming and try to disprove the risky assumptions with evidence: read the code, check versions in lockfiles, run the existing tests, query the docs. Only unresolved, decision-level unknowns go to the user.

• Diagnose in the main thread so the orchestrator owns the context it needs to delegate well.
• Ask questions in one batch, each with a recommended default and the trade-off in one line. Never ask what the repo can answer.
• If the user is not available, take the recommended default and record it under "Decisions" in the feature file.

3. The feature file (T2 only)

One file per feature at .sumi/tasks/<yyyy-mm-dd>-<slug>.md, created from ${CLAUDE_PLUGIN_ROOT}/templates/feature.md (or /sumi:feature). It replaces multi-document spec workflows: one organic file that grows with the work.

It contains: goal and why, scope and explicit non-goals (what must NOT be built — your main defense against over-engineering), decisions, constraints, phases with tasks, acceptance criteria, a process log and evidence.

Rules:

• Mirror the tasks into the session todo list and keep both in sync as you go.
• Every acceptance criterion must be checkable (a command, a test, a measurable value, a screenshot).
• Append to the process log at each meaningful step, one or two lines each: what changed, what you learned, what is next. Anyone must be able to resume from the file alone; it is a log, not a report.
• Evidence is mandatory to tick a task: test output, a command result, a Lighthouse/axe number, or a screenshot path. "Should work" is not evidence.
• Set status: in the frontmatter (active, blocked, done). The session-start hook surfaces active files.

4. Line budget: small houses, not Eiffel towers

Before implementing a slice, forecast its size in changed lines. The budget is ~400 changed lines per slice — the range where review stays effective.

• Over budget: split into slices that each leave the codebase working and are independently reviewable. Each slice = one commit (or one PR on teams).
• Work inside the budget as a constraint, not a suggestion: the best solution that fits, not the most impressive one. Exceeding it requires a one-line written justification in the feature file. When you cut scope to fit, mark each seam with a ponytail: note (sumi:code-quality) instead of half-building the extension.
• Generated files, lockfiles and snapshots do not count.

5. Delegation briefs

Route by role (sumi:model-routing): facts → sumi:scout, decisions → sumi:architect, implementation → sumi:builder, passing the model for the project's profile on every call.

A subagent starts with zero context. Every brief contains: goal, exact files/paths, constraints and conventions that apply (name the skills), the acceptance check it must run, and the output you expect back (diff summary + evidence). Prefer one well-briefed subagent over several vague ones. Run independent subagents in parallel.

6. Pre-commit risk assessment

Before each commit, classify the change:

Review per slice, not per micro-task — and never several slices at once: if a range exceeds ~1.5× the line budget, review it slice by slice (/sumi:review enforces this).

7. Shipping

• Commits: Conventional Commits, imperative, English, one concern per commit.
• If a feature exceeds one reviewable unit, plan chained PRs: each PR builds on the previous one and ends in a final tracker PR that merges to main; or, for small fast-moving work, each slice merges to main independently. Record the choice in the feature file.
• Use /sumi:ship to run the final checks and draft the PR description.

Companions (installed as dependencies of sumi)

Sumitsubo owns the process (tiers, feature file, budgets, reviews). Companion skills are called at specific moments; they never replace the tier decision.

Deliberately NOT included from superpowers: its session bootstrap, brainstorming, writing/executing plans, subagent-driven development and branch finishing. Sumitsubo's tiers, feature file, /sumi:review and /sumi:ship cover those, and two competing workflows in one session degrade both.

Anti-patterns

• Creating a feature file for a one-line fix, or skipping it for a migration.
• Delegating before diagnosing (the subagent re-discovers everything, badly).
• Asking the user things the codebase answers.
• Ticking tasks without evidence; "done" with failing or unrun tests.
• Scope creep: refactoring adjacent code nobody asked about. Note it under "Follow-ups" instead.