develop

Files (11)

• ANALYSIS.md
• BLUEPRINT.md
• REVIEWER.md
• SKILL.md
• SMELL-BASELINE.md
• analysis.md · branches/
• bugfix.md · branches/
• deprecation.md · branches/
• feature.md · branches/
• refactor.md · branches/
• guard-bar.sh · scripts/

SKILL.md (first lines)

# 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](../../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?").

| Branch | When | Execution core | Exit gate |
|--------|------|----------------|-----------|
| **feature** | new code / endpoint / use case | TDD loop (`tdd`) — RED first | tests + build + visual (if UI) → PR |
| **bugfix** | something broken / regression | `diagnose` → RED regression test | regression test green → PR |
| **refactor** | behavior-preserving change | existing tests as the contract | tests still green → PR |
| **deprecation** | remove / rename / migrate away from code, fields, endpoints, flags | `deprecation` (consumer search, expand/contract) | consumers proven at 0, or the expand/contract step declared → PR |
| **analysis** | audit / investigation, no code | discovery + adversarial verification | verified findings report → **no PR** |

**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:

| Premise kind | Source that settles it |
|---|---|
| who emits / consumes an event, who calls an endpoint | grep emitters and callers (all extensions) |
| what exists in prod (endpoint, env var, infra) | deployment config / infra repo / observability |
| whether code is live | callers + production traffic (logs, metrics) |
| what the UI or data allows (sortable, default order…) | the component config / the real query |
| what CI runs | the actual CI definition (don't assume the provider) |

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](../domain-modeling/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](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

From pabloleonalcaide/development-skills, MIT.

More from pabloleonalcaide/development-skills