Workflows
Every task gets a grade and a route. The two together decide how much process it gets.
The route comes from the kind of task. The grade, from 1 to 10, says how big it is. The grade decides how much planning the route needs and whether the agent stops for your approval.
The 6 routes
| Route | When | What happens |
|---|---|---|
| investigate | You asked a question or asked for an explanation. No change. | No edits, no branch, no commit. The answer cites the file and line it is based on. |
| new-project | There is no code yet. | Branch, set up the project files and tests, write the first glossary and status, then stop for review. |
| adopt-existing | The repo has code but no kerby files yet. This is the prepare command. | Reads the code and git history, then proposes context files. Each file is shown as a diff and needs your yes. |
| feature | A new feature, an improvement, a refactor — and every change to a high-stakes file. | Branch, agree on the request, plan, then build in small committed steps, check, and report. |
| bugfix | Something is broken. | Reproduce it, find the cause with evidence, write a failing test, fix the cause, and commit. |
| quick-task | A small, low-risk change: docs, config, one file. | States what will change, makes the change, checks the diff stayed small, commits, and logs. |
When a small change still gets the full route
quick-task needs two things at once: a grade below 4, and a change that passes the fit check — no new logic/refactor, ≤~50 LOC, no schema/contract changes. If either fails, the task takes feature, or bugfix for a bug.
Changes to these kinds of files always take feature or bugfix, even a one-line change:
- Schema migrations
- Authentication / authorization
- Payments / billing
- Infrastructure
- CI/CD
- Production-traffic-shaping values
The reason: on these paths, a one-character change can take down production. The size of the diff says nothing about the risk.
The 1–10 grade
From grade 4, the agent writes a full plan with expected results. From grade 7, it stops and waits for your approval. A project can move the plan line in agent-context.yaml. The approval line is fixed. When a task sits between two grades, the agent picks the higher one.
| Grade | Looks like | What the agent does |
|---|---|---|
| Low (1–3) | Single file, config, typo | Handle directly. Self-review when done. |
| Med (4–6) | Multiple related files, moderate logic | Plan + Expected Outcomes (below), then implement. Self-check when done. |
| High (7–8) | Multi-file, design decisions, new patterns | Plan + Expected Outcomes, get user approval before starting. QA sub-agent when done. |
| Critical (9–10) | Cross-cutting, architectural, breaking | Plan + approval + staged rollout. QA sub-agent when done. |
Pick a task
Four example tasks and what swe does with each. The lines follow swe’s real formats. The grades and file names are made up. A “…” marks the work between the first lines and the final report.
complexity: <N> (trigger: <≤8-word reason>) → route: <investigate | new-project | adopt-existing | feature | bugfix | quick-task> rung: <N> — <≤8-word reason> plan: <files> — <change> — <check> INTENT: code does <X>; the failing check/task expects <Y>; the spec (README/docs/docstring) says <Z> smallest: <the least you can build that fully satisfies the request> deferring: <items, comma-separated> | none outcome: <case> — match | mismatch | not exercised skipped: <what you did not build> — add when <trigger>
Each example below fills these formats.
Fix a typo
Documentation, one file, no logic. It passes the quick-task fit check.
- route
- quick-task
- grade
- 1 (example)
- planning
- One plan line
- approval
- No stop (below 7)
complexity: 1 (trigger: one-word typo in README) → route: quick-task rung: 5 — a one-line change plan: README.md — fix "recieve" to "receive" — re-read the line … skipped: none
It still works on a branch, commits, and writes a log entry.
Fix a bug
A bug takes the bugfix route: reproduce it, find the cause, write a failing test, then fix.
- route
- bugfix
- grade
- 3 (example)
- planning
- One plan line
- approval
- No stop (below 7)
complexity: 3 (trigger: cart total adds tax twice) → route: bugfix rung: 6 — minimum fix at the root cause plan: src/cart/total.ts, total.test.ts — apply tax once to the subtotal — the new failing test passes INTENT: code does add tax per line and again per order; the failing check/task expects tax once per order; the spec (README/docs/docstring) says tax applies once, to the subtotal … skipped: none
The test is written first and fails. Then the fix makes it pass.
Change login
Auth is a high-stakes path, so the change takes the full feature route even though it is small.
- route
- feature
- grade
- 5 (example)
- planning
- A full plan with expected results and test cases
- approval
- No stop (below 7)
complexity: 5 (trigger: session change in auth code) → route: feature rung: 3 — the framework has a session option plan: src/auth/session.ts, LoginForm, session tests — 30-day session when "remember me" is ticked — session tests pass smallest: a "remember me" box that sets a longer session deferring: none
When the agent edits src/auth/, a hook reminds it that this path needs the full workflow.
Build a feature
Several files and design decisions. The grade reaches the approval stop.
- route
- feature
- grade
- 7 (example)
- planning
- A full plan with expected results and test cases
- approval
- Stops and waits for your yes
complexity: 7 (trigger: new endpoint, UI and tests) → route: feature rung: 6 — no existing export to reuse plan: api/reports, ReportsPage, export tests — CSV export of the current report view — export test and a manual download smallest: one CSV export of the current view deferring: Excel format, scheduled exports … your approval, then the work … outcome: download current view — match skipped: Excel format, scheduled exports — add when a user asks for them
The agent shows the full plan and waits. Code starts only after your yes.
UI and design work
When a task changes UI, styling or design tokens, swe adds four rules. They come from references/design-md.md.
Animation has no rule of its own. The decision ladder picks the animation library like any other package: first what the platform already does, such as CSS transitions, View Transitions or CSS scroll-driven animations; then an animation library the project already depends on; and only then a new library, which you must approve before it is installed. An installed animation skill, such as the GSAP skills, is not a reason to use its library.
Find the spec, and ask which one governs
The spec is the file that holds the project’s design tokens, usually DESIGN.md at the repo root. If the root has none, the agent looks in other folders and under other names before it invents any token. When it finds a spec outside the root, it names each one and asks you which one, if any, governs the UI it is changing. It does not decide from the folder or the file name.
It then gives that path to each design skill it uses, because most of them look only at the root.
The spec’s tokens are the authority
The tokens in the spec — colors, type, spacing, radius — are the contract. The agent does not invent other tokens. When nearby code uses a different value, it does not copy it quietly. It tells you about the difference. A token change goes into the spec in the same commit as the code.
One skill edits, the others check
Design skills are split by job. Only one skill edits a given surface. The others read and report back to it. The render is checked after the last edit.
| Job | Today’s pick | What it may do |
|---|---|---|
| Make the change | impeccable | The only skill that edits this surface. |
| Check direction | taste-skill | Measures and reports. It does not edit. |
| Check signal colors | dataviz | Only when the work changes colors. Checks the signal colors as one set (below). |
| Verify the render | screenwright | Runs after the last edit: light and dark, desktop and phone width. It never edits; findings go back to the author. For screenwright this is mode V only, because its other modes edit. |
The jobs are the rule. The skill names are today’s picks, and they change. If a pick is not installed, the agent uses one that is and keeps the same split.
Check signal colors as one set
Signal colors carry a state, such as ok, warn and bad, plus the accent. Each color can pass on its own while two of them still look the same to a color-blind reader. So when the work changes colors, they are checked together, in light and in dark. A pair whose color-blind difference is below ΔE 8, or whose normal difference is below 15, goes back to the author. This holds even when an icon or a word also shows the meaning.