← Spec-driven workflows guides

How to configure personal preferences in bootstrap.local.md

How-To Spec-driven workflows Beginner 1081006HOWTO-1081006

HOWTO-1081006Spec-driven workflowsBeginner

This guide shows you how to use .specdd/bootstrap.local.md for personal or machine-specific spec-driven development preferences without changing the shared project contract.

The local bootstrap file is useful because not every working preference belongs in Git. It is also risky if it starts overriding team rules, product behavior, or write authority. Keep it local, narrow, and non-authoritative over shared contracts.

Short answer

Put personal and machine-specific preferences in .specdd/bootstrap.local.md. Use it for local workflow notes, local tool paths, or personal reporting preferences. Do not use it for team conventions, durable product behavior, security exceptions, or broader edit authority. Keep it out of shared commits.

When to use this guide

Use this guide when:

Background

The bootstrap load order is:

.specdd/bootstrap.md
-> .specdd/bootstrap.project.md
-> .specdd/bootstrap.local.md

Later files may add local context or narrow behavior, but they must not silently weaken project contracts, inherited constraints, or write authority. That rule matters most for bootstrap.local.md because it is personal to one operator or environment.

Steps

1. Check that bootstrap.local.md is local

The file path is:

.specdd/bootstrap.local.md

SpecDD setups normally ignore this file so local preferences stay local. Confirm your repository ignores it:

.specdd/.gitignore

should include:

bootstrap.local.md

If the file is already tracked, remove it from the shared commit process before adding personal preferences.

2. Add only personal preferences

Good local entries are about your machine or your interaction style:

# Local Preferences

## Reporting

- When reporting completed work, include changed files and checks run.
- If a check is skipped, explain the local reason.

## Local Environment

- Prefer local test output paths under `/tmp/specdd-checks`.
- My local preview command uses port 1314 when 1313 is occupied.

These preferences affect how work is reported or run locally. They do not redefine product behavior.

3. Avoid weakening project rules

Do not write local overrides like:

- Ignore failing tests when the change looks correct.
- You may edit files outside `Can modify` if needed.
- Skip security review for local changes.

Those weaken shared contracts and should not be in a local bootstrap file. If a shared rule is wrong, change the shared rule through project review. If a spec boundary is wrong, update the owning .sdd spec through the normal spec-driven workflow.

4. Keep shared conventions elsewhere

Team conventions belong in:

.specdd/bootstrap.project.md

Durable behavior belongs in local .sdd specs:

src/trips/itinerary.sdd

Use bootstrap.local.md only for local preferences. If another contributor should follow the rule too, it is probably not local.

5. Verify the file is not committed

Before committing, check status:

git status --short

You should not see .specdd/bootstrap.local.md staged for commit. If your team intentionally tracks a local bootstrap template, keep personal machine details out of it and use a separate ignored file for actual local preferences.

Example

Good:

# SpecDD user-local overrides

## Local shell

- Use `pnpm test -- --runInBand` when local parallel tests are unstable on this machine.

## Reporting

- Include the exact command used for local verification.

Bad:

# SpecDD user-local overrides

- Ignore the billing spec during local work.
- Agents may modify sibling modules when convenient.
- Treat destination search references as writable.

The bad example changes authority and weakens shared constraints. That is not a personal preference.

Common mistakes

How to verify the result

Your local bootstrap is configured correctly when:

← Spec-driven workflows guides