Using sdd

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:

1. Requirements and design: brainstorm, deep-interview, spec-driven-development, review-spec, source-driven-development, spec-evolution
2. Planning and coordination: planning-and-task-breakdown, subagent-driven-development, orchestrate, fork-join
3. Investigation and execution: systematic-debugging, test-driven-development, domain implementation skills
4. Review and release: verification-before-completion, code-review, style-review, code-simplification, receiving-code-review, gate-check, release-checklist
5. Skill evolution: learner after 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