software-development-workflow

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
• /plan: references/plan.md
• /architect: references/architect.md
• /build: references/build.md
• /test: references/test.md
• /debug: references/debug.md
• /review: references/review.md
• /code-simplify: references/code-simplify.md
• /webperf: references/webperf.md
• /ship: 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.

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.