Skip to main content
The SDD Plugin provides a complete brownfield adoption strategy for integrating structured development into existing codebases. Whether you have a bare codebase with no documentation, comprehensive external docs, or partial SDD artifacts with drift, the plugin detects your project’s state and generates a tailored adoption plan.

​
Brownfield workflow

The brownfield adoption process follows four key steps:
1

Diagnose project state

Run /sdd:onboarding to scan your project and classify it into one of 8 scenarios. The skill generates a comprehensive diagnostic report with a step-by-step action plan.
2

Import existing documentation

Use /sdd:import to convert external documentation from Jira, OpenAPI, Markdown, Notion, CSV, or Excel into SDD format.
3

Reverse engineer from code

Run /sdd:reverse-engineer to analyze your codebase and generate complete SDD artifacts including requirements, specifications, test plans, and architecture documentation.
4

Reconcile drift

Use /sdd:reconcile to detect and resolve divergences between your SDD artifacts and the current codebase.

​
Eight project scenarios

The onboarding skill classifies projects into eight distinct scenarios, each with a specific adoption strategy:

Greenfield

No code, no docs. Start with the standard pipeline from /sdd:requirements-engineer.

Brownfield bare

Code exists with no documentation or tests. Run /sdd:reverse-engineer to bootstrap all SDD artifacts from the codebase.

SDD drift

SDD artifacts exist but have diverged from the code. Use /sdd:reconcile to detect and align differences.

Partial SDD

Some SDD artifacts exist but the pipeline is incomplete. Resume from the gap in the pipeline.

Brownfield with docs

Code and non-SDD documentation exist. Run /sdd:import to convert docs, then /sdd:reverse-engineer to fill gaps, then /sdd:reconcile to align.

Tests as spec

Good test coverage but poor or missing documentation. Run /sdd:reverse-engineer with a test-first strategy to extract behavior from tests.

Multi-team

Monorepo or microservices with mixed states across modules. Perform per-module assessment with phased adoption.

Fork/migration

Project forked from another codebase. Assess upstream artifacts, then run /sdd:import or /sdd:reverse-engineer for the delta.

​
Health scoring

The onboarding skill calculates a health score (0-100) representing SDD readiness across seven dimensions:
DimensionWeightCriteria
Requirements coverage20 pts0=none, 10=informal docs, 20=SDD format
Specification coverage20 pts0=none, 10=partial specs, 20=full spec/
Test coverage15 pts0=none, 8=some tests, 15=good coverage+plan
Architecture documentation15 pts0=none, 8=README/diagrams, 15=SDD plan/
Traceability15 pts0=none, 8=partial refs, 15=full chain
Code quality signals10 pts0=none, 5=linter, 10=types+linter+CI
Pipeline state5 pts0=none, 3=partial, 5=complete pipeline-state.json
Scores of 80-100 indicate SDD compliance with minor gaps only. Scores below 40 require systematic adoption.

​
Invocation modes

All brownfield skills support multiple invocation modes for different use cases: 
# Full diagnostic (default)
/sdd:onboarding

# Quick scan without deep analysis
/sdd:onboarding --quick

# Reassessment after partial adoption
/sdd:onboarding --reassess

# Import with automatic format detection
/sdd:import path/to/api.yaml

# Import with explicit format
/sdd:import path/to/export.csv --format=jira

# Reverse engineer full codebase
/sdd:reverse-engineer

# Reverse engineer specific modules
/sdd:reverse-engineer --scope=src/api,src/models

# Inventory only without artifact generation
/sdd:reverse-engineer --inventory-only

# Reconcile with dry run
/sdd:reconcile --dry-run

# Reconcile with code as source of truth
/sdd:reconcile --code-wins

​
Confidence and markers

Brownfield skills tag artifacts with markers to indicate their origin and confidence level:
MarkerMeaningRequires Review
[IMPORTED]Artifact imported from external documentationYes
[INFERRED]Artifact derived from code patternsYes
[IMPLICIT-RULE]Business rule embedded in code without docsYes
[RECONCILED]Artifact updated during reconciliationNo
[RETROACTIVE]Task documenting already-implemented featureNo
[DEAD-CODE]Unreachable or unused code detectedReview recommended
[TECH-DEBT]Suboptimal implementation requiring future workReview recommended
[WORKAROUND]Temporary fix or hackReview recommended
All artifacts tagged with [IMPORTED], [INFERRED], or [IMPLICIT-RULE] require user validation before proceeding with downstream pipeline stages.

​
Next steps

Onboarding skill

Learn how the onboarding skill diagnoses projects and generates adoption plans.

Import skill

Convert external documentation from Jira, OpenAPI, Notion, and more.

Reverse engineer skill

Extract complete SDD artifacts from existing codebases.

Reconcile skill

Detect and resolve drift between specs and code.

Build docs developers (and LLMs) love

Get started for freeTalk to us