Framework guidance

# Adopting Specification-First Delivery

Adoption begins by making one type of change easier to understand and control. Choose the path that best matches the work in front of you, then use it to build a Specification System that keeps intent, decisions, implementation, and evidence connected.

## Keep the Specification System close to the change.

Our reference implementation checks documentation into the codebase. A repository gives each specification a versioned, reviewable home that stays portable across delivery tools and close to the change it guides.

This is a tool-agnostic choice, not a restriction. If a product or knowledge platform can be reliably connected to your AI coding agents and managed through the same ownership, review, and change controls, use it. Tools such as Spec Kit can help teams structure specification-led work; they do not replace accountable decisions or acceptance evidence.

Four practical starting paths

## Begin with the software you actually need to change.

Use these flows to establish a trustworthy first delivery path. They describe a minimum sequence, not a fixed process. Add depth to each artifact when consequence, novelty, ambiguity, or dependencies warrant it.

Scenario 1

### Greenfield development

A new product or service is the clearest opportunity to establish shared language and working agreements before accidental conventions accumulate. Start with a small, valuable increment, but design the foundations so later contributors can understand the decisions that shaped it. Use the first increment to test both the product idea and the conventions that will guide later change.

#### Establish the system before the first trusted increment.

Greenfield delivery flow

- **Set outcome and authority:** State the intended outcome, users, scope, non-goals, material risks, and decision owners before choosing architecture or generating implementation work.
- **Create a shared language:** Build a concise glossary, identify actors and use cases, and describe normal paths, exceptions, rules, and acceptance conditions. Mark assumptions awaiting owner decisions.
- **Shape constraints and interfaces:** Capture system context, major components, data meaning, external contracts, security and operational needs, and quality attributes. Keep architectural alternatives and their rationale visible.
- **Put working knowledge with code:** Create repository structure, governing instructions, templates, test conventions, and documentation ownership. Check the material in with code so one change path preserves its history.
- **Deliver and learn one increment:** Turn the first slice into clearly scoped jobs, implement and verify it against the specification, then record acceptance evidence, deviations, and lessons for the next increment.

Scenario 2

### Brownfield development

For an existing codebase, the first task is not to describe everything. It is to establish enough reliable context for a safe next change and make uncertainty visible. Treat current code as evidence alongside tests, operations, documentation, and experienced people. The initial pilot should leave the codebase safer to change than it found it.

#### Create a safer path for the next change, then improve it incrementally.

Brownfield delivery flow

- **Establish a workable baseline:** Recover or confirm build, test, deployment, and rollback paths. Identify owners, critical dependencies, operational constraints, and the change most suitable for a first pilot.
- **Map the available evidence:** Compare code, tests, schemas, interfaces, runbooks, tickets, and stakeholder knowledge. Record contradictions and gaps instead of treating a single source as automatically authoritative.
- **Reconstruct the change scope:** Describe the behavior to change, the behavior to preserve, affected data and contracts, failure modes, and acceptance conditions. Escalate unresolved meaning to the right owner.
- **Install proportionate working rules:** Add repository guidance, decision records, specification templates, and evidence locations only where they support the change. Do not codify every existing habit or debt.
- **Deliver a traceable pilot:** Execute a clearly scoped increment, link implementation and verification to its specification, and use the review to refine the knowledge base before selecting the next improvement.

Scenario 3

### Rewrite an existing system

A rewrite is not an instruction to reproduce old code in a new technology. It is a decision to establish what behavior, data meaning, controls, and operating expectations should survive. Specification distillation gives the new system a reviewable starting point. Do not ask the build team to settle business contradictions through implementation choices.

#### Distill what matters before rebuilding any part of the system.

Rewrite delivery flow

- **Define the replacement decision:** State the business outcome, target scope, constraints, cutover expectations, and reasons a rewrite is preferable to incremental replacement, replatforming, or retirement.
- **Collect and distill evidence:** Examine requirements, code, tests, data, interfaces, production behavior, incidents, and practitioner knowledge. Produce a reviewable set of claims with associated confidence levels and supporting evidence.
- **Classify existing behavior:** Ask accountable owners to decide what to preserve, correct, replace, retire, defer, or leave unresolved. Existing implementation is evidence, not automatically the target specification.
- **Specify the target and migration:** Create the target behavior, architecture, data, contract, operational, security, compatibility, and migration specifications. Define equivalence evidence, rollback limits, and staged cutover conditions.
- **Rebuild by accepted slices:** Deliver replacement increments through normal specification-led work, compare them with the approved target and legacy obligations, then retain evidence before expanding or decommissioning.

Scenario 4

### Customize vendor or open-source software

Customizations often become invisible until the next upgrade breaks them. A specification set makes the organization’s additions, dependencies, and accepted trade-offs explicit, so the team can deliberately rebuild, replace, or retire them when the vendor baseline changes. The aim is not to preserve every modification, but to make each retained decision reproducible.

#### Make custom behavior reproducible across upgrades.

Customization delivery flow

- **Frame the upgrade and scope:** Identify the vendor release, supported extension points, required business outcome, customization owners, compatibility obligations, and the operational window available for the upgrade.
- **Inventory custom behavior:** Trace configuration, code extensions, data changes, integrations, reports, access controls, and workarounds. Link each item to the user need, owner, and evidence of current behavior.
- **Decide what should survive:** Classify each customization as preserve, adapt, replace with vendor capability, retire, or defer. Capture conflicts between the new baseline and existing business or technical constraints.
- **Specify the rebuild path:** Document extension points, adapters, migration steps, test cases, data conversion, fallback, and acceptance criteria. Keep custom code separate from the vendor baseline where practical.
- **Upgrade with evidence:** Apply the upgrade in a controlled environment, verify vendor and custom behavior together, accept the result with evidence, and update the specification set for the next release.

## Use the smallest path that produces trustworthy learning.

The same discipline applies in every scenario: make judgment explicit, assign each decision an owner, define execution scope and authority, and accept only with evidence. Once one path works, improve the next based on what the organization has learned.

[Review the Specification-First Delivery overview](https://specfirstdelivery.org/en-us/overview)