← Getting started guides

How to link existing docs and content with SpecDD

How-To Getting started Beginner 1001009HOWTO-1001009

HOWTO-1001009Getting startedBeginner

Many projects already have useful docs: architecture notes, ADRs, product briefs, runbooks, API docs, support content, or a documentation tree. You do not need to copy all of that into .sdd files to use SpecDD.

This guide shows how to link existing docs and content into a SpecDD setup so humans and agents can find the right context before changing the project.

Short answer

Put project-wide documentation locations in .specdd/bootstrap.project.md. Use local .sdd specs for operational contracts: what the area owns, what must stay true, what is out of scope, and which existing docs can be read for context. Use explicit paths in Structure, Can read, or References when a local spec depends on nearby docs or content.

When to use this guide

Use this guide when:

Steps

1. Inventory the docs worth linking

Start with the docs that affect implementation or review.

Examples:

docs/architecture/
docs/adr/
docs/runbooks/
content/help/
api/openapi.yaml
README.md

Do not link every file just because it exists. Link the material that helps agents and reviewers make better local decisions.

2. Map shared doc locations in bootstrap.project.md

Add project-wide documentation guidance to:

.specdd/bootstrap.project.md

Example:

# Project documentation

Use these existing docs as shared project context when they are relevant to the task:

- `./docs/architecture/`: architecture notes and dependency direction
- `./docs/adr/`: accepted architecture decisions
- `./docs/runbooks/`: operational behavior and incident response notes
- `./api/openapi.yaml`: public HTTP API contract
- `./content/help/`: user-facing help content

Do not treat these docs as write authority. For implementation work, resolve the governing `.sdd` spec chain and use
the nearest local spec's `Can modify` or `Owns` section for edit authority.

This is the best first link because .specdd/bootstrap.project.md is shared setup context. It tells agents where to look without forcing every local spec to repeat the same documentation map.

3. Keep specs as operational contracts

Specs are not ordinary documentation. Existing docs may explain background, history, rationale, or user-facing details. Specs should define the contract that must guide work.

Good local spec content:

Avoid copying long docs into a spec. Link them instead, then summarize only the rule that must be operational during implementation.

4. Use Structure for local docs and content

Use Structure when docs or content belong to the current area or descendants.

Example:

Spec: Help Content

Purpose:
  Keep user-facing help pages accurate and task-focused.

Structure:
  ./billing/: Billing help pages
  ./account/: Account management help pages
  ./style-guide.md: Help content style rules

Must:
  Help pages describe current product behavior.
  Setup steps are written as concrete user actions.

Must not:
  Document unreleased behavior as available.

Structure helps humans and agents understand local organization without reading the whole tree.

5. Use Can read for context without edit permission

Use Can read when a spec may read existing docs or content for context, but should not modify those files under this spec.

Example:

Spec: Billing Settings

Purpose:
  Let account admins review and update billing settings.

Owns:
  ./billing-settings.ts
  ./billing-settings.test.ts

Can read:
  /docs/adr/billing-provider.md
  /content/help/billing/

Must:
  Billing settings reflect the current billing provider rules.

Must not:
  Edit help content from this implementation spec.

Can read is context. It does not grant write permission.

Use References when the relationship is explicit and important for understanding the local contract.

Example:

Spec: Password Reset

Purpose:
  Let users request a secure password reset email.

Owns:
  ./password-reset.ts
  ./password-reset.test.ts

References:
  /docs/adr/authentication-boundaries.md
  ../email/email-delivery.sdd

Must:
  Password reset emails are sent through the approved email delivery boundary.

Must not:
  Bypass authentication boundary decisions recorded in the ADR.

Use References for context outside the inherited spec chain. References do not create inherited authority or permission to edit the referenced area.

7. Ask an agent to use the linked context

Keep the prompt focused on one action:

Explain how the Billing Settings spec uses the billing docs.

For implementation:

Implement the open billing settings task.

The project bootstrap and local specs should tell the agent where existing docs live and which docs matter for the target.

Run:

specdd inspect .
specdd lint

For one target that should see linked context, run:

specdd resolve path/to/target-file

Check:

Common mistakes

← Getting started guides