ai-dev-workflow-template

Create project-owned agent files (`.claude/agents/<name>.md`). Use when the user explicitly asks to create, add, scaffold, draft, or design a new agent, or when repeated conversation patterns or `git log` activity suggest the same workflow keeps being handled manually and should become an agent.

Audit and improve agent files (`.claude/agents/*.md`). Use when the user asks to check, audit, review, score, or improve agents, mentions "agent maintenance" or "agent quality", wonders which agents are missing or duplicated, wants to tighten tool allowlists, or wants to know if their agent descriptions trigger reliably.

Use when onboarding a repository to the AI workflow, when .ai/project.yaml has project_name: unknown, or when project metadata is incomplete or stale.

Use when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing

Maintain project-specific workflow metadata (project.yaml, memory.md, decisions.md) after bootstrap, CI changes, restructuring, or refresh requests—never alter the immutable core; also use when asked to consolidate, compact, or tighten memory/tokens.

Use when a development task has testable behavior and should be built test-first with independently verified failing-then-passing gates. Default route for medium/large TDD-able code tasks; non-testable tasks belong to the orchestrate skill.

Use when a coding request needs breaking into phases before implementation — any task larger than a tiny local edit (trivial is ~1 file, under 10 lines). Produces a minimal, executable plan with narrow execution packets. Normally dispatched by the orchestrator; invoke directly only when the user wants a plan without execution.

Recover from failed implementation attempts by isolating wrong assumptions and proposing the next narrow experiment. Use when a task has hit repeated failure, unclear regressions, or implementation drift that spans systems — not for a bug localized to a single file.

Use when an implementation is complete and awaiting approval, before merge or wrap-up. Normally dispatched by the orchestrator after the execute phase; where a deterministic gate passed the verdict is advisory, otherwise it is blocking.

Use when the user wants to compose, draft, or route a task through their agent catalog as a multi-agent pipeline. Not for code development tasks — those go to the orchestrate skill. Executor for saved pipelines is the run-pipeline skill.

Use when the user asks to run or execute a saved agent pipeline by name from .ai/local/pipelines/. Drafting new pipelines is the orchestrate-agents skill's job, not this one's.

Synthesize completed agent outputs into the run record's Handoff section. Use only when dispatched by the run-pipeline skill after a pipeline's agents complete; not a standalone or user-invoked skill.

Use when a development task (code or docs) should run end-to-end from one prompt — the default entry point. Route TDD-able medium/large code to the orchestrate-tdd skill and non-code multi-agent pipelines to the orchestrate-agents skill instead.

Use when the user asks for a usage audit, a "how am I using Claude Code" review, or a usage retrospective, or wants to mine past sessions for tool mix, error hotspots, model spend, repeated prompts, or automation candidates. Not for auditing a single live session, and not a substitute for the metrics dashboard.

Use when invoking Claude Code CLI from another tool (e.g. Codex) — either as a workflow executor/reviewer dispatched by the orchestrate skill, or for ad-hoc delegation when you need complex reasoning, planning, architecture decisions, research, or a second opinion.