Brownfield skills reference

Brownfield skills enable SDD adoption in existing projects by extracting artifacts from code, documentation, or detecting project state.

onboarding

Diagnoses project state and generates a customized SDD adoption plan.

Invocation

/sdd:onboarding                                       # Full diagnostic
/sdd:onboarding --quick                               # Quick scan (skip deep analysis)
/sdd:onboarding --reassess                            # Re-evaluate after partial adoption

Detection phases

Phase 1

phase

Environment checkDetects: project root, language/framework, package manager, CI/CD, containerization, git history

Phase 2

phase

SDD artifact scanScans: pipeline-state.json, all SDD directories, key files, cross-references, modification dates

Phase 3

phase

Non-SDD documentation scanFinds: README, docs/, API specs (OpenAPI, GraphQL), external tool exports (Jira, Notion), architecture docs

Phase 4

phase

Code & test analysisAnalyzes: file counts, architectural layers, design patterns, test framework, test coverage, code quality signals

Phase 5

phase

Scenario classificationClassifies into 1 of 8 scenarios using weighted signal matrix

Phase 6

phase

Health score estimationScores (0-100): requirements coverage, specification coverage, test coverage, architecture docs, traceability, code quality, pipeline state

Phase 7

phase

Action plan generationGenerates step-by-step plan with effort estimates and health score progression

8 scenarios

Scenario 1

scenario

Greenfield — No code, no docsAction: Standard pipeline from requirements-engineer

Scenario 2

scenario

Brownfield bare — Code exists, no docs, no testsAction: reverse-engineer full

Scenario 3

scenario

SDD drift — SDD artifacts + code divergedAction: reconcile

Scenario 4

scenario

Partial SDD — Some SDD artifacts, incomplete pipelineAction: Resume pipeline from gap

Scenario 5

scenario

Brownfield with docs — Code + non-SDD docsAction: import → reverse-engineer → reconcile

Scenario 6

scenario

Tests-as-spec — Good tests, poor/no docsAction: reverse-engineer with test-first strategy

Scenario 7

scenario

Multi-team — Monorepo/microservices, mixed statesAction: Per-module assessment, phased adoption

Scenario 8

scenario

Fork/migration — Forked from another projectAction: Assess upstream, import/reverse-engineer delta

Health score dimensions

Requirements coverage

dimension

0=none, 10=informal docs, 20=SDD format

Specification coverage

dimension

0=none, 10=partial specs, 20=full spec/

Test coverage

dimension

0=none, 8=some tests, 15=good coverage+plan

Architecture documentation

dimension

0=none, 8=README/diagrams, 15=SDD plan/

Traceability

dimension

0=none, 8=partial refs, 15=full chain

Code quality signals

dimension

0=none, 5=linter, 10=types+linter+CI

Pipeline state

dimension

0=none, 3=partial, 5=complete pipeline-state.json

Output artifacts

onboarding/ONBOARDING-REPORT.md

file

Diagnostic reportSections:

Executive summary (scenario, health score, recommendation)
Environment profile
Current state assessment
Scenario classification with evidence
Health score breakdown
Action plan (step-by-step with effort estimates)
Risk factors and next steps

reverse-engineer

Extracts SDD artifacts from existing codebase.

Invocation

/sdd:reverse-engineer                                 # Full reverse engineering
/sdd:reverse-engineer --scope=src/api,src/models      # Scope to paths
/sdd:reverse-engineer --inventory-only                # Quick assessment
/sdd:reverse-engineer --findings-only                 # Document code health only

Execution phases

Phase 1

phase

Pre-flightValidates environment, checks for existing SDD artifacts, detects language/framework, identifies scope

Phase 2

phase

Scan & inventoryBuilds complete codebase map: files by language, module dependency graph, architectural layers, design patterns, database schema, test structure

Phase 3

phase

Code analysisExtracts: entities, routes/endpoints, state machines, invariants, dependencies, dead code, tech debt, workarounds, implicit rules, infrastructure patterns

Phase 4

phase

Test analysisParses test files: structure, assertions → invariants, setup/teardown → preconditions, mocks → external contracts, test data → boundaries

Phase 5

phase

Requirements extractionGenerates EARS-format requirements from: routes → functional requirements, validations → constraints, auth patterns → security requirements, performance configs → NFRs

Phase 6

phase

Specification generationGenerates complete spec/ directory: domain model, use cases, workflows, API contracts, NFRs, ADRs

Phase 7

phase

Test plan mappingMaps existing tests to requirements, identifies coverage gaps, generates test/TEST-PLAN.md

Phase 8

phase

Plan reconstructionGenerates plan/ARCHITECTURE.md and plan/PLAN.md from detected architecture

Phase 9

phase

Task reconstructionGenerates retroactive task files documenting already-implemented features with [RETROACTIVE] markers

Phase 10

phase

Traceability mapping & findingsBuilds full traceability chain, compiles findings report with markers

Findings markers

[DEAD-CODE]

marker

Unreachable or unused codeSeverity: INFO — MEDIUM

[TECH-DEBT]

marker

Suboptimal implementation requiring future workSeverity: LOW — HIGH

[WORKAROUND]

marker

Temporary fix or hackSeverity: MEDIUM — HIGH

[INFRASTRUCTURE]

marker

Cross-cutting concern patternSeverity: INFO

[ORPHAN]

marker

Code with no traceable requirementSeverity: LOW — MEDIUM

[INFERRED]

marker

Artifact derived from code patterns, not explicit docsSeverity: INFO

[IMPLICIT-RULE]

marker

Business rule embedded in code without documentationSeverity: MEDIUM — HIGH

Output artifacts

requirements/REQUIREMENTS.md

file

Extracted requirements in EARS format with [INFERRED] tags

spec/

directory

Complete specification directory generated from code

test/

directory

Test plan and matrices

plan/

directory

Reconstructed architecture and plans

task/

directory

Retroactive task files with [RETROACTIVE] markers

findings/FINDINGS-REPORT.md

file

Code health report with dead code, tech debt, workarounds catalogued by marker

reverse-engineering/

directory

Intermediate outputs: INVENTORY.md, ANALYSIS.md, TEST-ANALYSIS.md

reconcile

Detects drift between specifications and code, then aligns specs to match reality.

Invocation

/sdd:reconcile                                        # Full reconciliation
/sdd:reconcile --dry-run                              # Detect only, no changes
/sdd:reconcile --scope=src/api,src/models             # Scope to paths
/sdd:reconcile --code-wins                            # All divergences → update specs

Divergence types

NEW_FUNCTIONALITY

divergence

Code exists without spec; has tests or is actively usedResolution: Auto — Update specs (code wins)

REMOVED_FEATURE

divergence

Spec exists without code; no recent commitsResolution: Auto — Deprecate in specs (code wins)

BEHAVIORAL_CHANGE

divergence

Both exist but behavior differsResolution: Ask user — Is code correct or is it a bug?

REFACTORING

divergence

Structure changed but behavior equivalent (tests pass)Resolution: Auto — Update technical specs only

BUG_OR_DEFECT

divergence

Code contradicts spec AND tests fail or missingResolution: Ask user — Fix code or update spec?

AMBIGUOUS

divergence

Cannot determine type with confidenceResolution: Ask user — Classify manually

Execution phases

Phase 1

phase

Context loadingLoads all SDD artifacts, verifies source code exists, builds spec artifact index

Phase 2

phase

Code scanAnalyzes current code: endpoints, entities, business logic, integrations, configuration. Builds code feature index. Maps code features to spec artifacts via Refs: comments and naming conventions. Enriches with SDD MCP server data if available.

Phase 3

phase

Spec-code comparisonCompares: API contracts (method, path, params, schemas), business rules (validations, thresholds), state machines (states, transitions), domain model (fields, types, relationships). Detects spec without code, code without spec, behavioral differences.

Phase 4

phase

Divergence classificationClassifies each divergence using deterministic rules. Assigns confidence: HIGH, MEDIUM, LOW.

Phase 5

phase

Reconciliation planGroups divergences by type, prepares spec changes for auto-resolvable, prepares questions for user-decision types, calculates pipeline cascade impact.

Phase 6

phase

User reviewPresents summary, for each user-decision item presents options with recommendation. In --code-wins mode: skip this phase.

Phase 7

phase

Apply changesFor NEW_FUNCTIONALITY: adds specs marked [RECONCILED]. For REMOVED_FEATURE: marks specs [DEPRECATED]. For REFACTORING: updates technical references. For user-decided: applies chosen resolution.

Phase 8

phase

Pipeline state updateRecalculates hashes, marks affected stages as stale, updates pipeline-state.json, generates reconciliation report.

Output artifacts

reconciliation/RECONCILIATION-REPORT.md

file

Drift detection reportSections:

Executive summary (divergence counts by type)
Detailed divergence listing with classification evidence
Actions taken (auto-resolved and user-decided)
Pending items (deferred decisions, defect tasks)
Pipeline cascade impact
Traceability chain changes

requirements/REQUIREMENTS.md

file

Updated with new requirements or deprecations

spec/

directory

Updated specifications reflecting code reality

import

Converts external documentation to SDD format.

Invocation

/sdd:import path/to/file.yaml                         # Auto-detect format
/sdd:import path/to/export.csv --format=jira          # Explicit format
/sdd:import path/to/api.yaml --target=specs           # Target artifact type
/sdd:import path/to/requirements.csv --merge          # Merge with existing

Supported formats

Jira

format

Extensions: .json, .csvMaps to: Epics → requirement groups, Stories → use cases, Bugs → defect tracking, Tasks → implementation notes

OpenAPI/Swagger

format

Extensions: .yaml, .jsonMaps to: Paths → API contracts, Schemas → domain model, Security → NFRs, Descriptions → requirements

Markdown

format

Extensions: .mdMaps to: Headings → requirement sections, Lists → individual requirements, Code blocks → technical specs

Notion

format

Extensions: .md (with metadata), .csvMaps to: Database rows → requirements, Pages → specifications, Properties → requirement attributes

CSV

format

Extensions: .csvMaps to: Columns → requirement fields, Rows → individual requirements

Excel

format

Extensions: .xlsxMaps to: Sheets → artifact types, Rows → individual items, Named columns → requirement fields

Execution phases

Phase 1

phase

Format detectionIdentifies format via extension and content markers, validates format compatibility

Phase 2

phase

Parse inputParses files into normalized intermediate representation with: items, metadata, parse errors, skipped items

Phase 3

phase

Mapping previewApplies format-specific rules, converts descriptions to EARS, detects duplicates (if --merge), generates preview for confirmation

Phase 4

phase

User confirmationPresents mapping preview, handles duplicates (Skip/Merge/Replace), resolves ambiguities, confirms skipped items

Phase 5

phase

Generate SDD artifactsGenerates requirements and/or specifications marked [IMPORTED]. Applies merge logic if --merge.

Phase 6

phase

Quality checkVerifies completeness, consistency, traceability readiness. Generates quality metrics.

Phase 7

phase

Pipeline state updateUpdates pipeline-state.json, generates import report

Output artifacts

import/IMPORT-REPORT.md

file

Import summarySections:

Source files and formats
Import statistics (parsed, mapped, skipped, errors)
Mapping summary (original → SDD)
Quality assessment
Items needing manual review
Pipeline state impact

requirements/REQUIREMENTS.md

file

(if --target=requirements or --target=both) Generated or merged requirements with [IMPORTED] markers

spec/

directory

(if --target=specs or --target=both) Generated or merged specifications

Skills API

MCP Tools

Artifact Schemas

Brownfield skills reference

Brownfield skills reference

onboarding

Invocation

Detection phases

8 scenarios

Health score dimensions

Output artifacts

reverse-engineer

Invocation

Execution phases

Findings markers

Output artifacts

reconcile

Invocation

Divergence types

Execution phases

Output artifacts

import

Invocation

Supported formats

Execution phases

Output artifacts

Build docs developers (and LLMs) love

Skills API

MCP Tools

Artifact Schemas

​Brownfield skills reference

​onboarding

​Invocation

​Detection phases

​8 scenarios

​Health score dimensions

​Output artifacts

​reverse-engineer

​Invocation

​Execution phases

​Findings markers

​Output artifacts

​reconcile

​Invocation

​Divergence types

​Execution phases

​Output artifacts

​import

​Invocation

​Supported formats

​Execution phases

​Output artifacts

Build docs developers (and LLMs) love

Brownfield skills reference

onboarding

Invocation

Detection phases

8 scenarios

Health score dimensions

Output artifacts

reverse-engineer

Invocation

Execution phases

Findings markers

Output artifacts

reconcile

Invocation

Divergence types

Execution phases

Output artifacts

import

Invocation

Supported formats

Execution phases

Output artifacts