sdd-build
Skill256 starsChanged 2 months agoMITView on GitHub
Execution methodology for SDD Phase 3 (Build): turn a completed DESIGN into working, verified code. Covers KB-first knowledge resolution, task extraction from the file manifest, dependency ordering, specialist agent delegation (including the data engineering delegation map), per-file and full-run verification, recording autonomous decisions in the BUILD_REPORT, upstream status transitions, and the handoff to Phase 4. Use when asked to "execute the build", "implement from the design", or run "Phase 3" on a DESIGN_{FEATURE}.md. Not for creating the architecture itself — that is sdd-design — and not for archiving a finished feature — that is sdd-ship.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- waldo1001/waldo.BCObservatorytheir own version, first seen Nov 1, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- waldo1001/waldo.BCObservatory★ 13same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-routerSkill
- component-modelSkill
- create-agentSkill
- create-skillSkill
- excalidraw-diagramSkill
- github-cr-adrSkill
- github-cr-issueSkill
- github-post-issueSkill
- github-review-prSkill
- kb-buildSkill
- meeting-analysisSkill
- sdd-brainstormSkill
- sdd-defineSkill
- sdd-designSkill
- sdd-iterateSkill
- sdd-shipSkill
- sdd-workflowSkill
- standup-reportSkill
- visual-explainerSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Follow this resolution order before and during every task.
- Distinctive: line 128
After all files are created:
- Very specific: line 141
Write .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md.
- Distinctive: line 173
Write to disk and verify
- Distinctive: line 201
When the DESIGN contains pipeline architecture, dbt models, SQL files, DAGs, or Spark jobs, delegate by file type:
- Distinctive: line 225
If a check fails: retry up to 3 times, then treat it as a blocker (see Error Handling).
- Very specific: line 256
Every decision fork resolved without pausing — two valid interpretations, an ambiguous policy, a gap the DESIGN did not pre-decide — gets …
- Distinctive: line 303
When the build completes, suggest Phase 4:
- Very specific: line 309
If the build stopped on blockers, recommend /iterate on the affected document instead (see Error Handling).
- Distinctive: line 316
Before declaring the build complete:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SDD Build — Phase 3 Methodology
The HOW of Phase 3: execute a completed DESIGN into working, verified code with on-the-fly task generation and specialist delegation. The executor is
build-agent(.claude/agents/workflow/build-agent.md); its non-negotiable policies — decide-never-ask and halt-only-on-CRITICAL-risk — govern every step below and are not restated here.
Knowledge Architecture — KB-First Resolution
Follow this resolution order before and during every task. It is mandatory, not optional.
┌─────────────────────────────────────────────────────────────────────┐
│ KNOWLEDGE RESOLUTION ORDER │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. DESIGN LOADING (source of truth for implementation) │
│ └─ Read: .claude/sdd/features/DESIGN_{FEATURE}.md │
│ └─ Extract: File manifest, code patterns, agent assignments │
│ └─ Load KB domains specified in design │
│ │
│ 2. KB PATTERN VALIDATION (before writing code) │
│ └─ Read: .claude/kb/{domain}/patterns/*.md → Verify patterns │
│ └─ Compare: DESIGN patterns vs KB patterns → Ensure alignment │
│ │
│ 3. AGENT DELEGATION (for specialized files) │
│ ├─ @agent-name in manifest → Delegate via Task tool │
│ └─ (general) in manifest → Execute directly from patterns │
│ │
│ 4. CONFIDENCE ASSIGNMENT │
│ ├─ KB pattern + agent specialist → 0.95 → Execute │
│ ├─ KB pattern + general execution → 0.85 → Execute with care │
│ ├─ No KB pattern + agent specialist → 0.80 → Agent handles │
│ └─ No KB pattern + general → 0.70 → Verify after │
│ │
│ 5. DECISION FORKS │
│ └─ Resolve under the executor's decide-never-ask policy and │
│ record per "Recording Autonomous Decisions" below. │
│ │
└─────────────────────────────────────────────────────────────────────┘Execution Loop
Step 1: Load Context
Read(.claude/sdd/features/DESIGN_{FEATURE}.md)
Read(.claude/sdd/features/DEFINE_{FEATURE}.md)
Read(CLAUDE.md)Extract from the DESIGN: the file manifest, code patterns, agent assignments, and the KB domains to load.
Step 2: Extract Tasks from the File Manifest
Convert the manifest to a task list — tasks are generated on-the-fly, not pre-written:
From DESIGN file manifest:
| File | Action | Purpose |
Generate:
- [ ] Create/Modify {file1}
- [ ] Create/Modify {file2}
- [ ] ...Step 3: Order by Dependencies
Analyze imports and dependencies to determine execution order: config first → utilities → handlers → tests.
## Build Order
1. [ ] config.yaml (no dependencies)
2. [ ] utils.py (no dependencies)
3. [ ] main.py (depends on 1, 2)
4. [ ] test_main.py (depends on 3)Step 4: Execute Each Task
For each file, in order:
┌─────────────────────────────────────────────────────┐
│ EXECUTE TASK │
├─────────────────────────────────────────────────────┤
│ 1. Read task from manifest │
│ 2. Write code following DESIGN patterns │
│ └─ Or delegate — see Delegation below │
│ 3. Run verification command │
│ └─ If FAIL → Fix and retry (max 3) │
│ 4. Mark task complete │
│ 5. Move to next task │
└─────────────────────────────────────────────────────┘Code standards for every file: no inline comments, type hints required, self-documenting names, config in YAML over hardcoded values. Verify incrementally — after each file, not only at the end. Fix forward: if something breaks, fix it immediately. Keep each file independently functional.
Step 5: Run Full Validation
After all files are created:
ruff check . # lint
mypy . # types (if configured)
pytest # testsSubstitute the project's configured linter, type checker, and test runner when it is not a Python project.
Step 6: Generate the Build Report
Write .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md. See Output Obligations.
Step 7: Update Statuses and Hand Off
Apply the transitions in Status Transitions, then suggest the next phase per Handoff.
Delegation
Decision flow
Has @agent-name in manifest?
├─ YES → Delegate via Task tool
│ • Provide: file path, purpose, KB domains
│ • Include: code pattern from DESIGN
│ • Agent returns: completed file
│
└─ NO (general) → Execute directly
• Use DESIGN patterns
• Verify against KB
• Handle errors locallyDelegation protocol
- Extract the agent name from the manifest
- Build the delegation prompt with context
- Invoke via Task tool
- Receive the completed file
- Write to disk and verify
Task(
subagent_type: "{agent-name}",
description: "Create {file_path}",
prompt: """
Create file: {file_path}
Purpose: {purpose from manifest}
Code Pattern (from DESIGN):
```
{code pattern}
```
KB Domains: {domains from DEFINE}
Requirements:
- Follow the pattern exactly
- Use type hints (Python)
- No inline comments
- Return complete file content
"""
)Data engineering delegation map
When the DESIGN contains pipeline architecture, dbt models, SQL files, DAGs, or Spark jobs, delegate by file type:
| File Type | Delegate To |
models/**/*.sql (dbt) | dbt-specialist |
dags/**/*.py (Airflow) | pipeline-architect |
jobs/**/*.py (PySpark) | spark-engineer |
contracts/**/*.yaml | data-contracts-engineer |
tests/data/**/*.py (GE) | data-quality-analyst |
schemas/**/*.sql | schema-designer |
Verification
Standard verification (per file)
ruff check {file}
mypy {file}
pytest {test_file} -vIf a check fails: retry up to 3 times, then treat it as a blocker (see Error Handling).
Data engineering verification
Detect DE artifacts in the DESIGN (dbt models, SQL files, DAGs, Spark jobs) and run the DE-specific verification tools:
# dbt models
dbt build --select {model_name}
dbt test --select {model_name}
# SQL linting
sqlfluff lint {sql_file} --dialect {dialect}
sqlfluff fix {sql_file} --dialect {dialect}
# Great Expectations
great_expectations suite run {suite_name}
# Spark (syntax check)
python -c "from pyspark.sql import SparkSession; exec(open('{file}').read())"Recording Autonomous Decisions
The decide-never-ask policy itself belongs to build-agent; this is the
recording mechanic that makes it auditable.
Every decision fork resolved without pausing — two valid interpretations, an
ambiguous policy, a gap the DESIGN did not pre-decide — gets one row in the
BUILD_REPORT ## Autonomous Decisions table:
| # | Decision Point | Options Considered | Chose | Rationale |
- The rationale states why the choice is the safest / smallest-correct default,
consistent with the DESIGN and the
.claude/kb/patterns. - The table is empty only if the DESIGN pre-decided everything.
- This is the post-run audit log that makes autonomous building reviewable — never omit a row to look decisive.
Status Transitions
Contract obligation (.claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml →
status_transitions): the build MUST update upstream document statuses before
completing. A stale "Ready for Build" status after a completed build is a
contract violation.
| File | Field | Value |
DEFINE_{FEATURE}.md | Status | ✅ Complete (Built) |
DESIGN_{FEATURE}.md | Status | ✅ Complete (Built) |
DEFINE_{FEATURE}.md | Next Step | /ship |
DESIGN_{FEATURE}.md | Next Step | /ship |
Output Obligations
| Artifact | Location |
| Code | As specified in the DESIGN file manifest |
| Build report | .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md |
The report's shape is owned by .claude/sdd/templates/BUILD_REPORT_TEMPLATE.md
— follow it, do not re-invent it. The sections this methodology feeds directly:
task execution with agent attribution (@agent-name vs (direct)),
verification results, and the Autonomous Decisions table.
Handoff
When the build completes, suggest Phase 4:
/ship .claude/sdd/features/DEFINE_{FEATURE}.mdIf the build stopped on blockers, recommend /iterate on the affected document
instead (see Error Handling).
Quality Gate
Before declaring the build complete:
PRE-FLIGHT CHECK
├─ [ ] All files from manifest created
├─ [ ] Each file verified (lint, types, tests)
├─ [ ] Full validation passes (lint, types, test suite)
├─ [ ] No TODO comments left in code
├─ [ ] No hardcoded secrets or credentials
├─ [ ] Error cases handled
├─ [ ] Agent attribution recorded in BUILD_REPORT
├─ [ ] Autonomous Decisions table filled (or legitimately empty)
├─ [ ] DEFINE status updated to "✅ Complete (Built)"
├─ [ ] DESIGN status updated to "✅ Complete (Built)"
└─ [ ] BUILD_REPORT generatedAnti-Patterns
| Never Do | Why | Instead |
| Skip DESIGN loading | No patterns to follow | Always load DESIGN first |
| Improvise beyond DESIGN | Scope creep; files not in manifest | Follow patterns exactly |
| Ignore agent assignments | Lose specialization | Delegate as specified |
| Skip verification | Broken code ships | Verify every file, incrementally |
| Leave TODO comments | Incomplete code | Finish or escalate |
| Explain code with inline comments | Noise; code must self-document | Self-documenting names |
Error Handling
A decision fork is not an error. This table covers genuine failures — code that will not work, not a choice between valid options.
| Error Type | Action |
| Syntax error | Fix immediately, retry |
| Import error | Check dependencies, fix |
| Simple bug | Fix immediately and continue |
| Test failure | Debug and fix |
| Decision fork (two valid options) | Not a failure — decide and record per Recording Autonomous Decisions; never stop, never ask |
| Missing requirement (DEFINE gap — DESIGN cannot be executed) | Log a blocker in BUILD_REPORT; recommend /iterate on DEFINE — do not pause to ask |
| Architecture problem (DESIGN pattern is wrong) | Log a blocker in BUILD_REPORT; recommend /iterate on DESIGN — do not pause to ask |
| Blocker (build cannot complete after retries) | Stop, document all blockers in the report, recommend /iterate |
CRITICAL risks (secrets, irreversible deploy, data loss) are the executor's
territory: build-agent owns that halt policy, and this skill never overrides
it.
References
- Executor + policies:
.claude/agents/workflow/build-agent.md - Entrypoint + flags:
.claude/commands/workflow/build.md - Report template:
.claude/sdd/templates/BUILD_REPORT_TEMPLATE.md - Contracts:
.claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml(build block,status_transitions) - Next phase:
.claude/commands/workflow/ship.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

