develop

A thin router that gives every piece of work the same backbone — align before coding — while delegating the middle to the right specialized skill.

Governing principle (read first)

This skill owns the PROCESS. Each repo owns its CONVENTIONS in .context/. Never hardcode repo-specific rules (test patterns, CI commands, architecture) here. At every step that needs conventions, read the repo's .context/ (testing.md, architecture*.md, good_practices.md, styling.md, and CLAUDE.md/AGENTS.md). If a needed convention file is missing, say so and ask — never invent it.

This framework is opinionated: it assumes DDD + hexagonal architecture + strict TDD. See PHILOSOPHY.md. Framework- and project-specific detail (naming, layering, DI wiring) lives in the repo's .context/architecture.md, not here.

Step 0 — Detect the branch (infer + confirm)

Infer the work type from the request and the impact analysis, then confirm in one line before proceeding ("I'll treat this as a bugfix, ok?").

One primary branch per task. If work of a different nature appears mid-flight, it is a scope signal → see Checkpoints. Don't mix it in (separate branch/PR).

See branches/<branch>.md for each execution core. Read it when you enter that branch.

The flow (phases A–E)

A · Discovery — always, depth scales

Map what the work touches before anchoring. Use Plan/Explore subagents. Scale by signals: one Explore for a small bugfix; several in parallel (by subsystem) for wide impact. When grepping, cover every source extension in play — a mixed codebase hides callers in files a single-extension sweep misses. Output: files, utilities, patterns, cross-cutting concerns affected.

Premises — verify before aligning. Read the ticket itself before any related memory or recent-session context. Then list the premises the work rests on, each with the source that settles it, and mark it verified (with evidence) or assumed:

A premise that comes from memory or from earlier work, not from the ticket or the code, counts as assumed. The grilling starts from the assumed ones.

B · Alignment — grill almost always

Suggest a grilling to fix scope, needs and the decision tree, for anything but trivial-mechanical work. Infer + confirm in one line (like Step 0), then invoke the core skills — not the user-only wrappers:

• Does this work touch the domain? — i.e. does it introduce or redefine a business noun (order, customer, invoice, subscription…)? → confirm ("This touches the domain, I'll grill with domain modeling to sharpen the glossary, ok?"), then run /grilling + /domain-modeling so the glossary in .context/glossary.md gets fed in-flight.
• Purely technical / mechanical (internal endpoint, cache, wiring, no new concept named)? → confirm, then run /grilling alone (no docs).

Use the model-invocable cores (/grilling, /domain-modeling), not grill-me/grill-with-docs — those are user-only entry points (disable-model-invocation) and are invisible to the router. .context/glossary.md is kept alive only through this step — the alignment grilling is the sole mechanism that maintains it. For risky decisions (state machines, data models), suggest a throwaway scratchpad prototype first (/prototype, if installed). Grilling: confirm in one line → on your "yes", run.

Mark the hard decisions. When the grilling closes, flag the decisions that meet all three criteria in domain-modeling's DECISIONS-FORMAT.md — hard to reverse, surprising without context, the result of a real trade-off. Nothing is written yet: they carry their reasoning into the blueprint and the tracker task, and /domain-modeling (when running) records the durable ones as decision records. Settle any new seam under test (see C) here too — it is a design decision, not a blueprint detail.

C · Blueprint — the single human approval gate

Produce the plan via plan mode (BLUEPRINT.md): context, decisions (hard ones flagged, with their reasoning), numbered steps, file table, seams under test, compatibility, verification. Declare the impacts here (yes/no each) so the later checkpoints and skills are predictable: visual, data, security, API contract, observability. Each yes among the last three means its skill (security-hardening, api-design, observability) runs before the blueprint is final — its decisions go into Decisions and its Verification checklist into the hardening's Standards input. If signals warrant (many slices, dependency ordering), suggest /to-tickets for vertical tracer-bullet slices. This is the only mandatory human approval; D–E then run autonomously except for the Checkpoints below.

Approving the blueprint is the durable authorization for the whole task: writing tests and code, RED→GREEN without pausing, atomic commits, push, and opening the PR with /create-pr. Don't ask again for any of these — only a Checkpoint stops the flow. This overrides any "show me / wait for" RED rule in a repo's local agent instructions and the confirmation steps of /tdd's planning section.

Seams under test are the public interfaces through which each behavior will be observed — an endpoint, a use case, a rendered page. Prefer existing seams and the highest level that reaches the behavior. The ideal number of new seams is zero: inventing one here means the design was not closed in B — go back rather than patch it into the plan.

D · Registration — after approval only

1. Read the registration convention: the repo's .context/work-registration.md if it has one (tracker, list/labels, task prefix, branch naming); otherwise the issue tracker in docs/agents/issue-tracker.md (GitHub by default — run /setup once per repo if it isn't configured). Never invent a list, prefix or naming scheme — ask once if neither exists.
2. Adopt, don't duplicate: if the request already points to a task, use it; otherwise create one. Its description carries the reasoning of the hard decisions from B.
3. Create the branch by hand, before any commit, following that convention. Commits must never land on the main branch.
4. Keep the blueprint in the scratchpad, linked from the tracker task — never scattered .md in the repo tree.

E · Implementation loop

1. Build = run the branch's execution core (branches/<branch>.md). For feature/bugfix this is the TDD loop, RED-first — non-skippable, not "build then test". Every test goes through a seam named in the blueprint; behavior that reaches none is not a license to test internals → Checkpoint 3. Print the RED summary (tests, failure reason) and continue to GREEN in the same turn — the RED gate enforces order, not approval.

2. Hardening — two axes in parallel + mechanical. Freeze the diff (git diff <base>...HEAD) and launch two fresh subagents in parallel (general-purpose, never a fork), each prompt starting with REVIEWER.md pasted in, then its own input and a capped report (~400 words):

   • Standards — input: the diff + the repo's .context/ + SMELL-BASELINE.md pasted into the prompt, not linked (a smell named without its definition finds different things on each run). Real tests through the named seams? Value objects over primitives? Ports/adapters respected? Defensive smells? Documented repo conventions outrank the heuristic smells.
   • Spec — input: the diff + the approved blueprint + the tracker task. Does the diff implement what was actually asked for? Missing requirements, scope creep, or requirements implemented wrong.

   Report the results under ## Standards and ## Spec without re-ranking across axes — kept apart, a clean Standards pass can't hide a Spec failure (clean code that builds the wrong thing still fails).

   • Mechanical — run scripts/guard-bar.sh <base>: it lists added suppressions (@ts-ignore, eslint-disable, biome-ignore, coverage ignores), skipped or focused tests, loose assertions, stubs, deleted tests/assertions and quality-bar changes in config. Classify every hit: unjustified → fix; justified → keep and say why in the closing. Tightening the bar is silent; loosening it is loud. Add any repo-specific cheap checks (e.g. raw literals in tests) per conventions.

   Fix what review finds before the gate.

3. Verification gate — discover the repo's CI commands (package.json / CI / .context), don't hardcode. Run in order, stop at first failure. Ask once if undiscoverable. Preflight (only on a fresh worktree or after switching branch): rebuild the workspace's internal dependencies (stale builds from another branch fail the gate falsely), check the container runtime when the gate needs it, and warn if free disk is low. A preflight failure is reported as environment, not as a failure of the change.
4. Deliver with /create-pr without asking — the blueprint authorized it (the branch already exists): short PR (what/why + tracker link), full detail in the task.

5. Closing — report by exception. The approved blueprint is already shared context: don't repeat it. Print only:

   • PR: the URL, on one line.
   • Deviations: what changed with respect to the blueprint — unplanned work that got in, decisions taken along the way and why.
   • Risks and findings discovered during implementation (including the out-of-scope work noted at Checkpoint 2, which did not make it into the PR).
   • Pending: what was left out and why (including a data notice parked at Checkpoint 4 and the out-of-scope notes from Checkpoint 2). Offer to create them as tracker tasks in one line; create them only on your yes.

   If there is none of that, the closing is a single line with the URL plus "no deviations from the blueprint". Don't print: a ticket/branch/PR table, a list of changed files, or a verification checklist — the gate already ran, and its detail is mentioned only if it failed or something was skipped (that one is mandatory to report).

Checkpoints (hard stops, by trigger — not by phase)

D–E run autonomously except when a trigger fires:

1. Visual impact declared → confirm in the browser before /create-pr (green typecheck/lint ≠ correct render).
2. Out-of-scope work appears → stop & ask if it blocks the main work; otherwise note it and continue, report at the end (never fold it into this PR).
3. Genuine design gap → stop & ask. This includes behavior that reaches no seam named in the blueprint: a missing seam is a design finding, not permission to test internals.
4. Data impact — the diff changes the shape of persisted data (which paths count — schemas, models, migrations — is the repo's .context/ call; decide from the diff paths, not from memory) → draft a notice for the downstream data consumers the repo documents: collections or tables and fields as they appear in storage, what is added / renamed / retyped / deleted, and whether existing records are backfilled or left as-is. You approve the draft before it goes out. If the repo names no consumers or channel, ask once; if there is nowhere to send it yet, park it and list it under Pending in the closing.
5. RED for the wrong reason (compile/import error, passes on first run) that you can't fix in the test itself → stop & ask.
6. Gate fails and the fix is outside the blueprint's scope → stop & ask.

Nothing else stops the flow: printing the RED, committing, pushing and opening the PR are not checkpoints.

Delegation

Two kinds. Cores (grilling, domain-modeling) are model-invocable — the router confirms in one line, then invokes them directly (they are not the user-only grill-me/grill-with-docs wrappers). Entry-points (the rest) are direct user skills: the router suggests them; on your explicit "yes" it runs the full skill (never a diluted inline version, never silently).

When NOT to use

• Trivial edits (a typo, a one-line config change) — just do them.
• Pure questions about the code — answer them; use the analysis branch only when a verified report is the deliverable.
• Inside a subagent — the router runs in the main conversation, where the human gate lives.

Common Rationalizations

Red Flags

• A commit exists before the blueprint was approved, or on the main branch.
• A test reaches no seam named in the blueprint.
• The hardening ran on a moving diff (code changed while reviewers were reading).
• The closing repeats the blueprint, lists files, or hides a skipped/failed gate.
• Out-of-scope changes folded into the PR instead of noted.

Verification

• Blueprint approved, branch created by hand, no commits on main
• Ticket premises listed and marked verified/assumed before the grilling
• RED observed for each behavior before its GREEN
• Both hardening axes (+ mechanical) reported; findings fixed or justified
• Gate commands discovered and run; output green (or failure reported)
• Every checkpoint that fired was resolved; parked items listed under Pending

Where things live (two homes)

• Process → this skills framework. One source of truth for how we work.
• Conventions → <repo>/.context/ (per repo). What's specific to each repo.
• Ephemeral (blueprint, analysis report) → scratchpad, linked from the tracker. Never scattered .md in the repo tree.