agentleFS
luanmorenommacielluanmorenommaciel/agentspec/.claude/skills/sdd-build/SKILL.md

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

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
  1. Distinctive:

    Follow this resolution order before and during every task.

    line 26
  2. Distinctive:

    After all files are created:

    line 128
  3. Very specific:

    Write .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md.

    line 141
  4. Distinctive:

    Write to disk and verify

    line 173
  5. Distinctive:

    When the DESIGN contains pipeline architecture, dbt models, SQL files, DAGs, or Spark jobs, delegate by file type:

    line 201
  6. Distinctive:

    If a check fails: retry up to 3 times, then treat it as a blocker (see Error Handling).

    line 225
  7. Very specific:

    Every decision fork resolved without pausing — two valid interpretations, an ambiguous policy, a gap the DESIGN did not pre-decide — gets …

    line 256
  8. Distinctive:

    When the build completes, suggest Phase 4:

    line 303
  9. Very specific:

    If the build stopped on blockers, recommend /iterate on the affected document instead (see Error Handling).

    line 309
  10. Distinctive:

    Before declaring the build complete:

    line 316

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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              # tests

Substitute 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 locally

Delegation protocol

  1. Extract the agent name from the manifest
  2. Build the delegation prompt with context
  3. Invoke via Task tool
  4. Receive the completed file
  5. 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 TypeDelegate To
models/**/*.sql (dbt)dbt-specialist
dags/**/*.py (Airflow)pipeline-architect
jobs/**/*.py (PySpark)spark-engineer
contracts/**/*.yamldata-contracts-engineer
tests/data/**/*.py (GE)data-quality-analyst
schemas/**/*.sqlschema-designer

Verification

Standard verification (per file)

ruff check {file}
mypy {file}
pytest {test_file} -v

If 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 PointOptions ConsideredChoseRationale
  • 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.

FileFieldValue
DEFINE_{FEATURE}.mdStatus✅ Complete (Built)
DESIGN_{FEATURE}.mdStatus✅ Complete (Built)
DEFINE_{FEATURE}.mdNext Step/ship
DESIGN_{FEATURE}.mdNext Step/ship

Output Obligations

ArtifactLocation
CodeAs 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}.md

If 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 generated

Anti-Patterns

Never DoWhyInstead
Skip DESIGN loadingNo patterns to followAlways load DESIGN first
Improvise beyond DESIGNScope creep; files not in manifestFollow patterns exactly
Ignore agent assignmentsLose specializationDelegate as specified
Skip verificationBroken code shipsVerify every file, incrementally
Leave TODO commentsIncomplete codeFinish or escalate
Explain code with inline commentsNoise; code must self-documentSelf-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 TypeAction
Syntax errorFix immediately, retry
Import errorCheck dependencies, fix
Simple bugFix immediately and continue
Test failureDebug 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.