---
name: software-development-workflow
description: Routes software-development requests to the smallest relevant set of installed specialist skills. Use for command-style requests such as /spec, /plan, /architect, /build, /test, /debug, /review, /code-simplify, /webperf, or /ship; also routes frontend design, motion, mobile, and ADHD-friendly output requests without embedding upstream skill content.
---

# Software Development Workflow

Interpret a leading command as a workflow intent. The command is a routing hint, not a fixed alias: inspect the request, repository context, risk, and requested outcome before selecting skills.

## Discovery and delegation

1. Resolve candidates against the active skill catalog first. Match the `name` in each candidate's `SKILL.md`, not a display label, directory nickname, or an obsolete routing reference.
2. If no active match exists, perform a global discovery pass before calling the capability unavailable. Inspect the configured global skill roots and the standard global locations that exist on the machine: `$CODEX_HOME/skills` (when set), `~/.codex/skills`, and `~/.agents/skills`. Search for `SKILL.md` and match its frontmatter `name` exactly.
3. A globally installed skill can be in one of three states: active and model-invocable (select it); installed but explicit-only (`disable-model-invocation: true`, tell the user it is available only through their explicit invocation and select an invocable equivalent when one exists); or not discoverable in the current session (ask for a skill-catalog refresh/restart, then use an invocable equivalent or a proportionate general workflow). Do not call any of these states “not installed.”
4. For a multi-skill route, resolve every candidate independently before beginning work. A missing or explicit-only secondary skill must not abort the command or hide the already resolved skills.
5. Select the smallest resolved set that materially improves the work. Do not load unrelated lifecycle stages.
6. Read and follow each selected skill's current `SKILL.md`; this router never copies, summarizes, or overrides specialist instructions.
7. State the selected skills briefly when doing meaningful work, then perform the request.

When a command is explicit, read only its matching reference before routing:

- `/spec`: [references/spec.md](references/spec.md)
- `/plan`: [references/plan.md](references/plan.md)
- `/architect`: [references/architect.md](references/architect.md)
- `/build`: [references/build.md](references/build.md)
- `/test`: [references/test.md](references/test.md)
- `/debug`: [references/debug.md](references/debug.md)
- `/review`: [references/review.md](references/review.md)
- `/code-simplify`: [references/code-simplify.md](references/code-simplify.md)
- `/webperf`: [references/webperf.md](references/webperf.md)
- `/ship`: [references/ship.md](references/ship.md)

If no command is supplied, infer the best workflow stage from the actual request, then read that stage's reference. The references contain routing signals and candidate names only; specialist implementation guidance remains upstream.

## Resolution fallback

After the active and global discovery passes, do not fail the user request solely because a candidate cannot be selected. State whether it is absent, explicit-only, or undiscoverable in this session; continue with a proportionate general workflow; and use an available equivalent when one exists. Suggest installation only when the capability is truly absent and materially limits the result. Never invent a skill or claim a non-selected skill was used.

Ask a focused question only when a missing decision would materially change the work.

## Verification evidence

For user-visible or interactive changes, and for high-risk behavior involving authentication, authorization, payments, or data changes, require targeted evidence in addition to implementation and review. Evidence is conditional; do not add it to routine backend-only work without a user-visible or high-risk behavior claim.

- Use the existing selected test, browser, review, and Git skills. This router introduces no recorder, screenshot service, upload, package, or specialist dependency.
- When a trustworthy baseline exists, compare matched before/after screenshots from the same route, state, and viewport. Otherwise, capture after-state proof and state why a valid baseline is unavailable.
- Report the revision or deployment, environment, testable claim, proof source, and a `passed`, `failed`, or `untested` result for each checked behavior.
- Mark missing-prerequisite checks `untested`; never present them as passed. Do not upload evidence or post it to a pull request without the user's explicit authorization.
- `git-workflow-and-versioning` remains the sole authority for branches and worktrees. Do not add a competing worktree policy here.

## Interface and visual-work routing

For user-facing interface work, use `impeccable` as the broad default for shaping, auditing, polishing, or optimizing an interface. Add one specialized skill only when its focus is clearly needed; do not stack competing visual-direction skills.

| Request | Preferred skill | Use instead / add only when needed |
|---|---|---|
| Build or redesign a web page, landing page, portfolio, or product UI | `design-taste-frontend` | `redesign-existing-projects` for an existing interface; `high-end-visual-design` for visual-direction constraints; `minimalist-ui` or `industrial-brutalist-ui` only when that named aesthetic fits |
| Turn a visual reference into working web UI | `image-to-code` | Generate new section references with `imagegen-frontend-web` when the design source is incomplete |
| Create an original website visual concept | `imagegen-frontend-web` | It generates design references; use a frontend implementation skill afterward to build them |
| Create a mobile-app visual concept | `imagegen-frontend-mobile` | Image generation only; use implementation tooling separately |
| Produce a brand system, identity board, or visual-world deck | `brandkit` | Use only for brand deliverables, not routine product UI |
| Document a premium design system for Google Stitch | `stitch-design-taste` | Prefer it only when Stitch or `DESIGN.md` is the stated target |
| Need complete, unabridged generated code | `full-output-enforcement` | Use sparingly; it governs delivery completeness rather than architecture |
| Need the legacy Taste Skill behavior | `design-taste-frontend-v1` | Default to the current `design-taste-frontend` otherwise |

## Motion and platform routing

- Use `animate` to design and implement web motion. Use `animate-expo` for React Native/Expo motion, gestures, transitions, or haptics.
- Use `review-animations` for a specific motion implementation, `improve-animations` for a read-only codebase-wide motion roadmap, and `find-animation-opportunities` for read-only suggestions of where motion belongs.
- Use `animation-vocabulary` only to name a described effect. Use `apple-design` when physical, gesture-led, or Apple-like interaction principles are central.
- Use `prototype` only when the user explicitly wants several live-comparable UI directions. Use `pick-ui-library` only when explicitly requested to select a frontend library.
- Use `ask-sonner` for Sonner toast integration or troubleshooting. Use `write-swift` for Swift implementation, review, migrations, concurrency, or performance work.
- `gpt-taste` is an intentionally opinionated GSAP/editorial direction; choose it only when its visual language and motion approach match the brief.

## Output accessibility

When the user explicitly invokes `/i-have-adhd`, use `i-have-adhd` and keep that mode active until they say to stop it. Lead with the next action, number multi-step work, restate state across turns, suppress tangents, include concrete time estimates, and make completed progress visible. Do not activate it implicitly.

## Skill sources

- `i-have-adhd` comes from `ayghri/i-have-adhd`.
- The visual and frontend-direction skills above come from `leonxlnx/taste-skill`.
- The motion, interaction, Swift, toast, and explicit-invocation skills above come from `emilkowalski/skills`.
- `impeccable` comes from `pbakaus/impeccable` and is the broad frontend craft default.