← Install and setup guides

How to upgrade from an older SpecDD project layout

How-To Install and setup Intermediate 1011008HOWTO-1011008

HOWTO-1011008Install and setupIntermediate

This guide shows how to move an older SpecDD project to the current layout without losing useful project-specific rules.

The current layout uses .specdd/bootstrap.md for official framework behavior, .specdd/bootstrap.project.md for shared project rules, .specdd/bootstrap.local.md for local preferences, root-level agent entrypoints, and .sdd specs near the files or directories they govern.

Current target layout

The current minimal layout is:

project-name/
  AGENTS.md
  CLAUDE.md
  .specdd/
    bootstrap.md
    bootstrap.project.md
    bootstrap.local.md
    .gitignore
  project-name.sdd

Local specs remain source-adjacent:

src/trips/itinerary.js
src/trips/itinerary.sdd

Steps

1. Inspect the old layout

Start from a reviewable branch:

git status --short
find . -name '*.sdd' -print
find . -path './.specdd/*' -print

Identify:

2. Update the framework bootstrap when bootstrap.md already exists

If the project already has:

.specdd/bootstrap.md

run:

specdd check-update
specdd update

Review:

git diff -- .specdd/bootstrap.md

specdd update updates the framework bootstrap. It preserves existing non-bootstrap files and does not recreate missing non-bootstrap files.

3. Initialize current support files when bootstrap.md is missing

If the old layout does not have .specdd/bootstrap.md, run current initialization from the intended content root:

specdd init

If the repository already has files named AGENTS.md, CLAUDE.md, or .specdd/bootstrap.project.md, the init flow leaves those existing non-bootstrap files unchanged. Review them and add any missing SpecDD wiring manually.

4. Move shared rules into bootstrap.project.md

Put shared team and project conventions in:

.specdd/bootstrap.project.md

Move rules such as:

Do not keep these conventions in the root spec just because the old layout did. The root spec should describe project intent and constraints; project-wide setup conventions belong in .specdd/bootstrap.project.md.

5. Keep local preferences local

Put personal or machine-specific preferences in:

.specdd/bootstrap.local.md

The current .specdd/.gitignore should contain:

bootstrap.local.md

If that ignore file is missing, create it before committing the migration.

6. Check agent entrypoints

The current entrypoint pattern is:

AGENTS.md
CLAUDE.md

AGENTS.md should tell agents to read .specdd/bootstrap.md. CLAUDE.md should point Claude-style workflows to AGENTS.md.

If the old layout used a different agent instruction file, keep any still-useful project guidance, but make sure the current entrypoints exist for the agents your team actually uses.

7. Check root spec naming

The root spec must match the selected content root directory basename.

Example:

travel-planner/
  travel-planner.sdd

If the old root spec has a different filename, rename it only after checking references and links. The human-facing Spec: value may remain descriptive:

Spec: Travel Planner

8. Review local spec placement

Keep useful existing .sdd files. Move or rename specs only when the old placement prevents reliable resolution.

Prefer same-basename local specs for implementation targets:

src/trips/itinerary.js
src/trips/itinerary.sdd

Use directory specs for inherited area context:

src/trips/trips.sdd

Use explicit References when a spec needs sibling context. Do not assume sibling specs are inherited automatically.

9. Verify the migration

Run:

specdd inspect .

For one important target, run:

specdd resolve path/to/target-file

Then check:

Common mistakes

← Install and setup guides