develop

name	develop
compatibility	Built for Claude Code (interactive questions, stack detection). Installs on any Agent Skills client.
allowed-tools	Bash, Read, Grep, Glob, Write, Edit, Task, AskUserQuestion, WebSearch, WebFetch
description	Build a feature (UI or logical/backend) from an approved design. Run /develop to implement a page, component, API, service, data layer, or slice. Gates on the decision first: if building would require inventing something undecided (a design system, page composition, a provider, a data model, a feature's behavior) with no ADR recording it, /develop stops and routes to /architect. Otherwise it reads the ADR + AGENTS.md (+ design.md for UI), builds, proves the result runs, and advances the roadmap.

Read ../conventions.md first (once per session). It carries the session start gate, model routing (this skill: mid tier; if on a premium model, say so in one line and suggest /model sonnet), panel rules, subagent rules, context economy, and output style. Apply the start gate before anything below.

What this skill does

The builder. Implements a feature that has already been decided: turns an ADR plus project conventions into working code, for both tracks. UI track (components, pages, layouts: semantic HTML, design tokens, accessibility) → ui-guide.md. Logical track (APIs, services, data layers, integrations) → logical-guide.md. One task can be both (auth = pages + session logic): run both tracks. It gates, then acts: no upfront question rounds, only what the design genuinely left open.

Owns: app code (and CSS/tokens for UI). Touches on docs/roadmap/: only the feature's status (planned → in-progress on start, done on landing), its checkboxes, and its pointer line (ADR <n> · code in <path>); re-read the roadmap right before each edit, change only those lines, and flag rather than clobber anything unexpected. One ADR touch: advance the governing ADR's **Status**: line (Proposed → In Progress on start, In Progress → Accepted when the feature lands; umbrella: the index.md's line, never a child's); re-read the line right before writing, flag if it is not in the expected state. Never: creates files in docs/roadmap/, writes ADR content (flags the need, defers to /architect), or restructures AGENTS.md (record new conventions via /sync afterwards).

Execution

Pre-checks

• Project must exist, except the scaffold task. If the task IS the scaffold sub-task of the stack foundation feature: creating the project is the job. Read the ARCHITECTURE ADR's ## Proposed stack, run the framework's own init, install the base dependencies only (framework, core runtime, what the first slice needs; every later feature installs its own libraries just in time; only cross-cutting tooling like lint/format/type-strictness comes early via /audit + the tooling task), lay out directories, confirm a dev server or build runs. Otherwise, with no project skeleton at all: stop, tell the engineer to run the scaffold step first.
• Freshness and collaboration (skip silently for solo/offline/non-git): git fetch; warn if behind origin/<base> ("pull first, a teammate may have shipped this"); warn on uncommitted changes in the target area; if the roadmap marks this feature in-progress and its code area has recent commits by another author (git log --format='%an' -- <area>), warn "looks mid-build by someone else, coordinate first." Warnings, not blocks.

Step 0 — The ADR gate (always first)

One test: to build this, would you have to invent something the engineer has not decided? Things you would be inventing: a provider, library, integration, data model, or cross-cutting pattern; what a whole page contains and looks like (design system, sections, components, assets) unless design.md plus a page spec pins it down; a feature's behavior (search, filtering, recommendations) unless an ADR specs it. Not owed for pure implementation: a bug fix, a component matching design.md, wiring decided pieces, copy tweaks. Apply the invent-test to the actual ask, never a hardcoded page-name list. The dangerous case is the false negative (silently inventing a real decision), so when unsure, treat it as owed and ask.

Check, in order, reading only what this feature needs (its one roadmap file via the At-a-glance table, then just its section; never other rows, workspaces, or unrelated ADRs):

1. The feature's roadmap row: needs a decision with no ADR pointer → a decision is owed and missing.
2. The governing ADR via the pointer (single file, or umbrella index.md plus the one child this sub-task touches): it is the spec, proceed.
3. The nearest AGENTS.md: the decision may already be recorded there ("auth provider already chosen"), proceed without a new ADR.

If a decision is owed and nothing records it, panel: "This needs an architecture decision first: <the specific load-bearing choice>. How do you want to handle it?" · Architect it first (recommended) → end with the paste-ready handoff below, do not build · No, not needed → proceed · Skip for now → proceed, and mark the roadmap row ⚠ ADR pending.

Run this next, then come back:

/clear
/architect <feature>: <the specific decision to settle>

Once the ADR exists: /clear, then re-run /develop <task>.

Step 1 — Classify the track

"page / component / screen / ui / a screenshot attached" → UI (ui-guide.md). "api / endpoint / service / logic / data / job / webhook / integration" → Logical (logical-guide.md). Both signals → both tracks. Genuinely ambiguous: ask once.

Step 2 — Load the decision and conventions

1. The governing ADR, build-spec sections only: ## Requirements (the IDed ACs, the contract this build must meet and the source of the verify steps you emit at the end) · ## Decision · the design/spec section · ## Build plan (ordered tasks, migration first) · ## Consequences. Skip Context, Options considered, Rationale (decision history, not build input). Umbrella: read index.md (decision, child list, cross-child contract), then only the child(ren) this sub-task touches. Check the Status: still Proposed → warn "the decision is not ratified; build anyway, or accept it first?" and build only on a go-ahead. Superseded → use the superseding ADR.
2. The nearest AGENTS.md (decisions synced from earlier features live here; do not re-ask what is settled).
3. design.md (UI track): the visual source of truth. If it names a style template, read only that one template from templates/.
4. The feature's build approach (row override, else project default from root AGENTS.md or the roadmap header): governs how you assemble the slice, not what it contains. None recorded: default to a coherent end-to-end slice.
5. Relevant tool skills, on demand: the ADR's Implementation skills field plus AGENTS.md name what governs this code (an ORM, an auth library, a provider). Open a skill's SKILL.md only when it materially shapes what you are about to write, and follow its conventions.

Monorepo: operate inside the target workspace (its AGENTS.md, design.md, package.json, commands, tree). Precedence on conflict: the ADR wins for its feature; AGENTS.md governs where the ADR is silent; flag conflicts for /sync rather than silently picking.

Spec-completeness check (before building, never mid-build): confirm the ADR contains what this task needs (logical: data model, API surface, security model, invariants; UI: screens, states, requirements). A load-bearing gap → panel: Update the ADR first (recommended, paste-ready /architect handoff) · Tell me the answer now (proceed, note the backfill) · Use your best judgment (proceed on a stated assumption, surfaced in the report).

Step 2.5 — Explore before building (isolated)

Reading the surrounding code happens in a read-only exploration subagent (fast model, Read/Grep/Glob) that returns a compact map: files to touch, patterns to follow, types/utilities to reuse, integration points. The main session receives the map, not the tree. Small, well-known areas (a few files you already located): read directly, skip the subagent.

Step 2.6 — Doc-check (only when needed)

About to use a library or API whose current usage you are not sure of (new major version, unfamiliar SDK, breaking-change territory): offload the lookup to a web subagent (or your web tools) that returns the current pattern for the specific call sites in question. Never guess a deprecated API into new code; never front-load whole doc sites.

Step 3 — Resume check, then build

The roadmap row's milestones and the ADR's Build plan tell you what is done (ticked) and what is next; resume from the first unticked item, never redo landed work. Then build, task by task, per the track guide (ui-guide.md / logical-guide.md) and the checklist (checklist.md):

• Follow the ADR exactly; it is the spec. A genuinely new decision surfacing mid-build → stop, flag it, route to /architect (it lands as a child of this feature's umbrella).
• Work in the feature's code area; reuse existing types, utilities, components (from the exploration map) before writing new ones.
• Remove superseded code as part of the build (dead functions, files, branches, imports; verify nothing references them).
• Keep changes typecheck/build/lint clean as you go (the project's own commands, from AGENTS.md).
• Prove it runs before reporting. Run the suite and the build; then actually exercise what you built (launch the dev server, hit the endpoint or walk the page against a running app; a real request or interaction, not just a compile). Walk the ACs; each is met or explicitly not.

Step 4 — Update the roadmap and report

• Roadmap: tick the finished milestone boxes, advance the status (done when the feature lands), fill the pointer line. ADR status line per the ownership rule above.
• Report, short: what was built (paths) · AC status (met / not, one line each) · how it was proven to run (commands + what you observed) · verify steps the engineer can repeat by hand (derived from the ACs) · anything for /sync to record · assumptions made.
• Close with the handoff: "Next: /clear, then /test <feature>" (or /sync when the feature is done and tested).

Reference files (lazy)

ui-guide.md (UI track detail) · logical-guide.md (logical track detail) · checklist.md (pre-report checks) · templates/<name>.md (style templates; read only the one design.md names).