tranhieutt --- name: using-sdd type: workflow description: "Routes every software-development request through the right SDD workflow before action. Use at session start, before clarifying questions, before edits, and whenever deciding which SDD skill should govern a task." argument-hint: "[user-request-or-current-task]" user-invocable: true allowed-tools: Read, Glob, Grep context: main effort: 2 agent: technical-director when_to_use: "Use at the start of every SDD session and before any non-trivial response, clarification, code edit, review, bug fix, plan, commit, or completion claim."
Using SDD
using-sdd is the router and discipline layer for the Software Development
Department. It does not replace specialist skills. It decides which SDD workflow
must govern the current request before the agent acts.
For phase orientation, use docs/technical/SDD_LIFECYCLE_MAP.md
(DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP). For detailed runtime
stage rules, use docs/technical/CONTROL_PLANE_MAP.md.
Core Rule
Before answering, asking clarifying questions, editing files, spawning agents, or claiming completion, check whether an SDD skill applies.
If a skill applies, use it. Do not rely on memory of the skill. Read the current skill and follow its gates.
Skill Routing
| User intent or situation | Required SDD workflow |
|---|---|
| Codex environment, Codex setup, AGENTS.md, .codex, Claude-to-Codex tool mapping, or SDD outside Claude Code | codex-sdd then route through using-sdd |
| First session, unclear project state | start |
| Vague product idea, ideation, product direction | brainstorm |
| User wants structured requirements or says "ask me", "don't assume", "interview" | deep-interview |
| New feature, behavior change, architectural change | spec-driven-development |
| Existing spec needs readiness review before planning or implementation | review-spec |
| Approved spec conflicts with code, tests, review findings, user feedback, or platform reality | spec-evolution |
| Framework, library, external API, platform behavior, deprecation, migration, or "latest/official/best practice" correctness matters | source-driven-development |
| Epic, multi-step work, large prompt, many files | planning-and-task-breakdown |
| Implementation of one approved task | test-driven-development |
| Execution of approved multi-task sequential plan with review gates | subagent-driven-development |
| Bug, failing test, build failure, CI failure, performance regression, or unexpected behavior | systematic-debugging |
| Complex, intermittent, unfamiliar, or repeatedly failed bug investigation | diagnose |
| Simple obvious bug with clear cause | test-driven-development with a regression test |
| Coordinated multi-agent work across domains | orchestrate |
| Independent parallel workstreams | fork-join |
| UI/frontend architecture or component design | frontend-design or ui-spec |
| API contract or endpoint design | api-design |
| Architecture decision with durable consequences | architecture-decision-records |
| Code quality, PR review, merge readiness | code-review or code-review-checklist |
| Prose quality for specs, ADRs, PR bodies, release notes, or technical docs | style-review |
| Behavior-preserving cleanup, simplification, readability refactor, or complexity reduction after tests pass | code-simplification |
| Review comments, PR feedback, CHANGES_REQUIRED verdict, or reviewer questions need response | receiving-code-review |
| Phase transition or readiness review | gate-check |
| Release or launch preparation | release-checklist or launch-checklist |
| Completion claim, success claim, task done, fixed, passing, ready, clean, merge-ready | verification-before-completion |
| Commit requested | commit |
| Create, update, refine, or evaluate an SDD skill; repeated prompt should become a skill; agent failure suggests missing/broken skill | learner |
| Save reusable lesson or preference | learner or annotate |
| Context is too large or stale | context-engineering or save-state |
When multiple skills apply, use process skills before implementation skills:
- Requirements and design:
brainstorm,deep-interview,spec-driven-development,review-spec,source-driven-development,spec-evolution - Planning and coordination:
planning-and-task-breakdown,subagent-driven-development,orchestrate,fork-join - Investigation and execution:
systematic-debugging,test-driven-development, domain implementation skills - Review and release:
verification-before-completion,code-review,style-review,code-simplification,receiving-code-review,gate-check,release-checklist - Skill evolution:
learnerafter evidence exists, or before edits when the task is explicitly to improve skills.
Mandatory Gates
Before Implementation
Implementation code means any production behavior change in files such as
src/, app/, lib/, services/, components/, migrations, infrastructure,
runtime config, hooks, build scripts, or generated assets that ship with the
product. Tests are only allowed before production code when they are part of a
TDD RED phase.
Do not write implementation code until one of these gate paths is satisfied:
| Gate path | Allowed when | Required before code |
|---|---|---|
| Fast Gate | Small, explicit, low-risk edit; one obvious file; no behavior ambiguity | State the exact file, exact change, risk check, and verification command/check |
| Spec Gate | New feature, behavior change, UI flow, API change, data change, or unclear side effects | Use spec-driven-development; present spec and task sequence; get explicit user approval |
| Spec Review Gate | Existing spec is the source of truth for a plan, review, or implementation | Use review-spec; proceed only if verdict is APPROVED or the plan carries non-blocking notes |
| Spec Evolution Gate | Approved spec and implementation reality disagree | Use spec-evolution; get explicit approval for the selected evolution path before code or plan changes continue |
| Plan Gate | Multi-step work, multiple files, cross-domain changes, or an epic | Use planning-and-task-breakdown; produce atomic tasks; get explicit approval for Task 1 |
| Interview Gate | Vague goal, hidden assumptions, or user asks not to assume | Use deep-interview until requirements are clear enough for a spec |
| Override Gate | User explicitly says to skip planning | Restate the skipped gate, name the risk, and get acknowledgment before code |
If none of these paths is satisfied, stop. Ask for the missing approval or clarification instead of editing files.
For any new feature or behavior change, default to:
spec-driven-development -> planning-and-task-breakdown -> test-driven-development
When the spec or implementation depends on framework, library, platform, or
external API behavior that may be version-sensitive or documented externally,
insert source-driven-development after the spec/review step and before
planning or code:
spec-driven-development -> source-driven-development -> planning-and-task-breakdown
For work from an existing spec, default to:
review-spec -> planning-and-task-breakdown -> test-driven-development
If implementation evidence contradicts the approved spec, pause and route to:
spec-evolution -> review-spec -> planning-and-task-breakdown or test-driven-development
For behavior-preserving cleanup after working implementation or review feedback, use:
test-driven-development -> code-simplification -> verification-before-completion
For bug fixes and failing tests, default to:
systematic-debugging -> test-driven-development -> verification-before-completion
If systematic-debugging cannot establish root cause quickly, escalates to
diagnose.
Pre-Code Checklist
Before the first production edit, verify and state the gate in one line:
Pre-code gate: <Fast|Spec|Plan|Interview|Override> satisfied by <evidence>; next edit: <file>; verification: <command/check>.
Examples:
Pre-code gate: Fast satisfied by explicit user request; next edit: landing-page/index.html; verification: visual/manual HTML check.Pre-code gate: Spec satisfied by approved Task 1; next edit: src/auth/session.ts; verification: npm test -- session.
If the next edit is a test in the RED phase, say that explicitly:
Pre-code gate: Plan satisfied by approved Task 1; next edit is RED test <file>; verification: <failing test command>.
Do not use "I think", "probably", or "should" in the gate line. Either the gate is satisfied or it is not.
Before Multi-Agent Execution
Use subagent-driven-development when an approved implementation plan has
multiple mostly sequential tasks and each task should pass implementation,
spec-compliance review, and code-quality review before the next task begins.
Use orchestrate when work spans multiple domains and has dependencies.
Use fork-join only when work units are independent, touch disjoint files, and
can be merged safely.
Do not spawn agents just because a task is large. Spawn agents when the workflow requires distinct ownership, parallelism, or review separation.
Execution mode selection for approved plans:
| Plan shape | Workflow |
|---|---|
| One small approved task | test-driven-development |
| Multiple sequential tasks needing review gates | subagent-driven-development |
| Multiple specialist domains with wave dependencies | orchestrate |
| Multiple independent disjoint workstreams | fork-join |
Before Completion Claims
Use verification-before-completion before saying work is done, fixed, passing,
safe, ready, merged, or clean.
Do not make the claim unless you have fresh evidence from the relevant command or file check in the current completion context.
If verification cannot be run, say exactly what was not verified and why.
After Review Feedback
Use receiving-code-review after any review returns comments, questions, or a
CHANGES_REQUIRED verdict.
Do not fix review feedback until each finding is classified as fix, reject,
defer, needs clarification, or route to spec-evolution.
Do not mark a review thread resolved until the specific finding has fresh verification evidence.
Anti-Rationalizations
| Thought | Required correction |
|---|---|
| "This is simple; no skill needed." | Simple tasks still need routing. Check the table. |
| "I need to inspect files first." | Use the skill that governs how to inspect. |
| "The user did not type a slash command." | Natural language still triggers skills. |
| "I remember the workflow." | Read the current skill. Skills change. |
| "I can ask clarification first." | Check routing first; some skills define how to ask. |
| "I can write code and test after." | Use test-driven-development. |
| "The plan is obvious." | For multi-step work, write the plan and get approval. |
| "The agent/reviewer said it passed." | Use verification-before-completion and verify independently before claiming completion. |
Minimal Response Pattern
When a routed skill applies, say one short line:
I'm using `<skill-name>` to <purpose>.
Then follow that skill. Do not add ceremony.
For tiny explicit tasks where no separate workflow is needed, state the narrow action and proceed:
I'll update `<file>` to <specific change>, then verify with <command/check>.
Stop Conditions
Stop and ask the user before proceeding when:
- The request can be interpreted in two materially different ways.
- The change affects architecture, data, security, billing, deployment, or release policy without an approved spec.
- Required verification needs a tool, credential, service, or network access the current environment cannot provide.
- The user explicitly overrides an SDD gate and the risk is not yet acknowledged.
Output Discipline
Keep status updates short and factual. Prefer evidence over confidence.
At the end of work, report:
- What changed
- What was verified
- What was not verified, if anything
- The next useful step only when it follows directly from the task