# Openspec Brownfield Baseline

> Introduce OpenSpec into an existing codebase by deriving baseline specs from current behavior, then switch future work to change-driven development. Use when a project already has substantial implementation but no trustworthy spec baseline, when the user wants to bootstrap `openspec/specs/` from current behavior, or when a team needs to capture present-day contracts before making further changes.

- Skill: `tumf/openspec-brownfield-baseline` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tumf/openspec-brownfield-baseline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tumf/openspec-brownfield-baseline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tumf (https://skillmd.com/u/tumf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tumf/openspec-brownfield-baseline

---


# OpenSpec Brownfield Baseline

Use this when a user wants to adopt OpenSpec in the middle of an existing software project and needs to create trustworthy baseline specs from the current implementation.

## Goal

Create `openspec/specs/` as a current-state source of truth for the parts of the system that matter now, without blindly canonizing accidental behavior, bugs, or implementation details. After the baseline exists, all future work should flow through `openspec/changes/`.

## Core principles

- `openspec/specs/` is the current source of truth for system behavior.
- Focus on behavior contracts, not internal implementation details.
- Reverse-engineered specs are drafts until reviewed by a human.
- Start with high-change or high-risk domains first; do not try to spec the whole repository unless explicitly asked.
- Prefer domain boundaries based on user-visible capabilities, not folder layout.

## When to use this

- A project already has substantial implementation but no OpenSpec baseline.
- The team wants to move from code-first to spec-driven development.
- The user asks to generate or bootstrap specs from an existing repo.
- The repo has tests, APIs, or workflows whose current behavior should be captured before more changes are made.

## Expected outputs

1. A proposed domain map for `openspec/specs/`.
2. Draft `spec.md` files for selected domains.
3. A short review note listing:
   - intended behavior confirmed
   - inferred behavior needing review
   - likely bugs or accidental behavior not promoted to spec
4. A recommendation for how future changes should be done under `openspec/changes/`.

## Standard workflow

### 1. Initialize or normalize OpenSpec structure

If OpenSpec is not present:

- run `openspec init` if the CLI is available
- otherwise create the structure manually:
  - `openspec/specs/`
  - `openspec/changes/`

Do not start by writing change artifacts. First establish the current-state baseline in `openspec/specs/`.

### 2. Choose scope before drafting

Do not attempt full-repo coverage by default. Propose a first wave of domains such as:

- auth
- users
- billing
- public-api
- webhooks
- admin
- sync
- notifications

Choose domains by answering:

- what external contracts exist?
- what areas change often?
- what areas would be risky to modify without a baseline?
- what areas already have tests or stable workflows?

### 3. Gather evidence for each domain

For each domain, inspect the current implementation surface and collect evidence from:

- routes, controllers, handlers
- schemas, validation, serializers
- service-layer entry points
- tests, especially integration and end-to-end tests
- README/docs/API references
- DB constraints or state transitions when behaviorally relevant
- logs, telemetry, retry semantics, idempotency, and side effects if externally observable

Prefer existing tests as strong evidence of intended behavior.

### 4. Extract contracts, not code structure

Translate the evidence into behavior statements that answer:

- what inputs are accepted?
- what outputs or state changes occur?
- what are the success conditions?
- what failures are user-visible?
- what side effects occur?
- what authorization or timing constraints exist?
- what ordering, idempotency, or retry guarantees exist?

Do not copy implementation detail into the spec unless it is part of an external contract.

## What belongs in a baseline spec

Good candidates:

- API request/response behavior
- validation and authorization rules
- state transitions
- error behavior
- idempotency and retry rules
- notification or webhook behavior
- side effects visible to operators or users
- business constraints and invariants

Avoid unless explicitly required:

- helper methods and class decomposition
- ORM-specific details
- internal caching tricks
- exact module layout
- accidental or buggy behavior
- implementation plans or refactor strategy

### 5. Draft `spec.md` files in OpenSpec format

Each domain should usually live under:

- `openspec/specs/<domain>/spec.md`

Use a structure like:

```md
# <Domain Name>

## Purpose
<Short statement of what the domain is responsible for>

## Requirements

### Requirement: <Behavior name>
The system SHALL <observable behavior>.

#### Scenario: <Happy path>
- GIVEN <context>
- WHEN <action>
- THEN <expected outcome>

#### Scenario: <Failure or edge case>
- GIVEN <context>
- WHEN <action>
- THEN <expected outcome>
```

Use RFC 2119 language where appropriate: SHALL, MUST, SHOULD.

Prefer a few solid requirements with concrete scenarios over a giant dump of implementation trivia.

### 6. Keep draft confidence separate from final truth

While drafting, track whether each requirement is:

- confirmed by tests or docs
- inferred from code
- needs human review

This confidence labeling can live in review notes or draft comments, but should not pollute the final baseline spec unless the user explicitly wants that.

### 7. Review before promoting to source of truth

Before treating the generated specs as canonical, perform a review pass that distinguishes:

- intentional product behavior
- implementation leakage
- legacy quirks
- known bugs
- under-specified areas

If something looks like a bug or accidental behavior, call it out instead of silently turning it into a requirement.

### 8. Verify the baseline

Before finishing, verify that:

- selected high-value domains are covered
- each requirement is observable and testable
- scenarios include not only happy paths but also failure or edge conditions where relevant
- spec language matches current behavior closely enough to guide future changes
- the baseline is small enough to maintain

If asked, identify gaps between the specs and the code/tests.

#### Validate specs with the OpenSpec CLI

After drafting specs, run the OpenSpec validator to check structural and formatting correctness:

```bash
# If the CLI is installed globally
openspec validate --specs --json

# Or via npx without global install
npx @fission-ai/openspec@latest validate --specs --json
```

The `--specs` flag targets spec files under `openspec/specs/`. The `--json` flag produces machine-readable output, which is useful for CI pipelines and automated checks.

Fix any reported errors before promoting specs to source of truth. Common issues include:
- missing required sections (Purpose, Requirements)
- malformed scenario blocks (GIVEN/WHEN/THEN)
- invalid RFC 2119 language usage

If the CLI is not available, fall back to manual review of the spec structure against the format described in step 5.

### 9. Switch future work to changes

After the baseline is accepted, recommend that all new work go through:

- `openspec/changes/<change-id>/proposal.md`
- `openspec/changes/<change-id>/specs/...`
- `design.md`
- `tasks.md`

The baseline captures current truth; changes capture deltas.

## Recommended rollout strategy

Use phased adoption unless the user explicitly wants exhaustive coverage.

### Phase 1

Capture the most important domains first, usually:

- auth
- billing
- public-api
- webhooks

### Phase 2

Add internal but operationally important areas:

- admin
- sync
- batch jobs
- notifications

### Phase 3

Expand to lower-risk or edge-case-heavy areas as they are touched.

This keeps OpenSpec adoption practical and aligned with real development work.

## Agent operating guidance

When applying this skill:

1. Start by proposing a domain map and a narrow first-wave scope.
2. Inspect the repo and tests before drafting specs.
3. Draft specs domain by domain.
4. Call out ambiguities and likely accidental behavior explicitly.
5. Do not claim the whole repo is now spec-covered unless it actually is.
6. If the user wants execution, create files under `openspec/specs/` rather than only describing the approach.

## Good response shape

When responding to the user, prefer this structure:

- recommended first-wave domains
- proposed files to create under `openspec/specs/`
- sample requirement/scenario for one domain
- review risks or ambiguities
- next action: draft the baseline specs now, or start with one selected domain

## Pitfalls

- Trying to spec the entire system in one pass
- Treating current code as automatically correct
- Writing implementation details instead of contracts
- Omitting failure scenarios
- Mixing current-state baseline with future change design
- Generating specs without checking tests or externally visible behavior

## Completion criteria

This skill is successfully applied when:

- `openspec/specs/` exists with draft baseline specs for the chosen domains
- each baseline spec captures observable behavior in requirement/scenario form
- questionable behavior is called out for review instead of silently canonized
- the user can continue future work via `openspec/changes/`