Adoption help: bring an existing project, Spec Kit workspace, or OpenSpec repository

[0xLeif]

Use this Q&A thread when adopting SpecSync in an existing codebase. Include your language(s), repository shape, current SDD tooling, the command you ran, and sanitized output from specsync change adopt --dry-run or specsync check --format github. Please remove credentials and private source before posting.

[0xLeif]

Six things a day of real 6.0 adoption turned up, in the order they bite

All of this came out of adopting 6.0.0-rc.2 on an existing repository and driving about ten changes through the lifecycle. Each item is a trap someone hit, with the escape they found. Issue numbers are linked so you can check the state rather than trust this post.

---

1. Check your merge strategy before you adopt anything

Run this first:

gh api repos/<owner>/<repo> --jq '{merge:.allow_merge_commit,squash:.allow_squash_merge,rebase:.allow_rebase_merge}'

If squash is the only one enabled, know going in that verification evidence recorded against a commit hash does not survive your own pull request. On rc.2 through rc.5 that made a change read as unverified the moment its PR landed, and clearing it forces a full re-verify plus a fresh independent review, which is the one step in the lifecycle that structurally requires a human. It was observed three times on a single change in one day.

This is not an exotic configuration. spec-sync's own repository is squash-only, and measured across its own archives, 19 of 178 archived changes have a verification commit still reachable from origin/main.

Two follow-ups worth knowing:

• The readiness half now has a fix merged in fix(change): ship readiness is a content question, not a history one (#689) #695, on main and not yet in a tagged release candidate (verification.commit ancestry is incompatible with squash-only repositories, and there is no available workaround #689). Measured there across squash, rebase, and merge-commit, all three reach ready to finalize.
• The ship side is still open as the scoped-review descendant walk fails closed forever after a squash, and its guarantee is unavailable rather than violated #694, and ship-status advertises check --commit from accepted, where check's own state machine rejects it #690 is the wedge it produces: ship-status can advertise change check <id> --commit from accepted, a state check itself refuses.
• Reported on docs: adopting a repo needs the merge strategy warning first #692: gh pr merge --rebase falls back to squash silently when rebase-merge is disabled at the repository level. So following advice to "use rebase-merge" is not sufficient. Check the setting itself.

---

2. If you upgraded from 5.x, confirm which lifecycle you are actually on

specsync init on a fresh repository writes policy version: 2 and you get the current lifecycle without doing anything. On an upgraded repository the policy carries version: 1, and re-running init short-circuits on "config.toml already exists" without raising it. Every change you then create is workflow v1, and before rc.3 nothing said so until ship refused several verbs later.

The verb you want is specsync change adopt. It is listed under specsync change --help, not top-level specsync --help, which is where people look for it and fail to find it.

The loop to avoid: create a change before adopting, and adopt then refuses because of that change. The escape works and is correct, but you have to already understand the trap to derive it: commit and integrate (or archive) the v1 change first, then rerun specsync change adopt.

adopt is genuinely non-destructive. Existing v1 records keep their workflow_version absent rather than being rewritten.

As of 6.0.0-rc.3 (#678), both init and change new announce the legacy lifecycle when you are on it, and a workflow-v2 repository stays completely silent.

---

3. --spec and --no-spec-change coexist, and that pairing is what you want for behaviour-only work

The flag names suggest they are alternatives. They are not. For production source that changes no spec text, use both:

specsync change new "<summary>" --kind fix \
  --spec change --spec cmd_change \
  --path src/change.rs --path src/commands/change.rs \
  --no-spec-change --rationale "behaviour only, no spec text changes"

Using --no-spec-change with no owning specs is refused at ship, several stages after it can be cheaply fixed. Scope freezes at approval and there is no withdraw verb (#554), so the exit is resetting the branch and redoing the whole lifecycle. That cost roughly 25 minutes of verification twice, in this repository, to the person writing the fixes.

To find a path's owning spec, grep the files: list in specs/<module>/*.spec.md. A path with no owner at all is itself the defect to fix first. Documented in docs/ADOPTING.md as of 6.0.0-rc.4 (#682).

---

4. Merge only after finalize, and the cost is larger than one record

The warning text through rc.5 said merging first orphans verification evidence and strands the change. That prices the loss as one record: yours, local, recoverable.

The measured cost is bigger. An unfinalized change never reaches accepted or archived, so it never becomes an accepted or archived successor, and every earlier accepted change sharing any delivery input with it can no longer archive:

specsync change archive <predecessor>
error: delivery input `specs/<module>/<module>.spec.md` (owner `<module>`) changed after
acceptance and no accepted or archived successor change covers it; run
`specsync change reopen <predecessor>`

On the affected repository the coupled set on one spec was 13 changes. Each merge-early decision looks small and locally recoverable; the aggregate is a lifecycle that cannot drain.

The wording is corrected (#687, merged in #691) but landed after 6.0.0-rc.5 was tagged, so it is on main and not in any release candidate yet. The behaviour was always this way.

Related and still open: #688, where the predecessor and the successor each name the other as the thing that must move first, and neither says the counterpart is blocked too.

---

5. Two state traps whose escapes are not derivable from the error text (#685)

check --commit then accept never converges on a reopened workflow-v1 change. The verification-recording commit always leaves HEAD one ahead of the evidence it just recorded, so accept reports the verification as stale, and re-running check --commit recreates the condition it is trying to clear.

Escape: run check without --commit. It records against the current HEAD, and accept then succeeds.

ship refuses a stale review while review refuses to run in accepted. Committing anything between review and ship stales the review's workspace digest. By the time you find out, the change is accepted, and record_scoped_review requires Verifying, so the verb that would fix it is unreachable from the state you discover the problem in.

Escape: finalize rather than ship.

ship-status prints both verbs without indicating that only one is reachable.

---

6. db_tables when your schema lives in application code

If your schema is defined in Go, TypeScript, or anything that is not .sql migration files, there is nothing to point schema_dir at, and schema_dir is not a spec frontmatter field so it cannot be scoped per module. Through rc.4 that left a permanent warning, and warnings escalate to errors under --strict:

DB table validation skipped: `db_tables` is declared but `schema_dir` is not configured

The only ways to clear it were deleting truthful db_tables documentation or abandoning strict and giving up drift gating everywhere else.

As of 6.0.0-rc.5 (#684) this is a notice. It still prints, it no longer gates:

⊘ DB table validation skipped: `db_tables` is declared but `schema_dir` is not configured

Note also that the gate was scoped to the effective contract, not the repository. Changes whose contract excludes the declaring spec verified clean throughout.

If you do have .sql migrations, 6.0.0-rc.4 (#672) fixed a related cascade: an unparseable migration previously reported every declared table as missing, including tables created correctly in unrelated files.

---

If you are posting your own adoption here

The most useful thing you can include, and the thing that changed several of these diagnoses today, is a measurement of your own repository rather than a symptom. Counts by state, which archives are anchored, which paths are present on your default branch. Three explanations of one coupling were wrong today and each was killed by someone running a command instead of reading source.

[0xLeif]

6.0.0 version of the traps list

The comment above was written against 6.0.0-rc.2. Stable 6.0.0 shipped 2026-09-09. Several of those traps are gone, one of them inverted, and three new ones bite on a fresh install. Issue numbers are linked so you can check state rather than trust this post.

Install first, then confirm it:

cargo install specsync
specsync --version    # specsync 6.0.0

Homebrew (CorvidLabs/tap/spec-sync) also serves 6.0.0. Pin every lifecycle writer — machines, agents, hooks, CI, Trust — to the same 6.x. Mixed 5.x / 6.x writes are not a supported mode.

docs/ADOPTING.md is the paste-into-an-agent-session version of this. What follows is the order they still bite.

---

1. Pin the Action binary. The tag name is not the download.

- uses: CorvidLabs/spec-sync@v6.0.0
  with:
    version: '6.0.0'
    strict: 'true'

Both pins are required and they pin different things: uses pins the wrapper, version pins the binary it downloads. @v6.0.0 still defaults the download to 6.0.0-rc.14. The floating @v6 tag's omitted-input default is 6.0.0. YAML examples keep the immutable pin plus an explicit version.

If you use Trust, pin Trust 1.2.0 (uses: CorvidLabs/trust@v1.2.0 or SHA fcc889f). Older Trust wrappers still default an RC or a 5.x binary.

This is the empty-category defect wearing GitHub Actions clothes: a tag named v6.0.0 looks like a satisfied pin, and the omitted input silently fetches a candidate.

---

2. init writes SDD off. check is the product. adopt is the on-switch.

specsync init
specsync generate
specsync check

init no longer starts a first-change interview. It writes .specsync/sdd.json with enabled: false. specsync check no longer walks the change workflow, prints an active-change count, or surfaces workspace/archive findings.

To turn the lifecycle on:

specsync change adopt

That flips enabled and nothing else — including require_change_for_meaningful_files, which stays false until you set it by hand. On a 5.x repository, land every workflow-v1 change before adopt (#674): a v1 change that merges during adoption is permanently unadoptable, because the baseline is immutable and the cutoff cannot move forward.

The rc.2 trap ("re-running init short-circuits on config.toml already exists") is still true for the config, but it is no longer how you discover you are on the legacy lifecycle. init and change new announce it (#678, in the tag). The verb is still specsync change adopt, still listed under specsync change --help, not top-level help.

---

3. Check your merge strategy, then archive on the PR before you merge

gh api repos/<owner>/<repo> --jq '{merge:.allow_merge_commit,squash:.allow_squash_merge,rebase:.allow_rebase_merge}'

The readiness half of the squash-merge trap is in the tag (#689 / #695). ship-status asks a content question; squash, rebase, and merge-commit all reach ready to finalize. You no longer owe a full re-verify plus a fresh independent review the moment the PR lands.

What is still true, and what the rc.2 comment priced as one stranded record:

Merge only after every active change on the PR is archived. Merging an unfinalized change never reaches accepted/archived, so it never becomes an accepted-or-archived successor, and every earlier accepted change sharing a delivery input can no longer archive. The wording landed in #687 / #691 and is in 6.0.0. The behaviour was always this way.

Still open on this family: #694 (the scoped-review descendant walk, inert by construction — see the correction on that issue), #690 (ship-status advertising a verb check will refuse), #688 (predecessor and successor each name the other, neither says the counterpart is blocked).

gh pr merge --rebase still falls back to squash silently when rebase-merge is disabled at the repository level (#692). Check the setting, not the flag you passed.

---

4. change check does not run your tests

It compares the specs this change owns or maps to the code, in-process, and records that as evidence. verification_commands is still accepted in sdd.json and nothing executes it. cargo test / swift test / bun test belong in CI, next to specsync check.

If you adopted from an RC where change check spawned those commands, this is a silent behaviour change: the verification record still writes, the tests did not run, and nothing says so. Same shape as the rest of this release — a category empty for want of input, read as a pass.

Scope is the union of affected_specs and the specs whose files: fall inside affected_paths. Project-wide validation is specsync check. A declared module that resolves to no spec file on disk fails and is named.

---

5. --spec and --no-spec-change coexist. Scope still freezes at approval.

Unchanged, still the expensive one. For production source that changes no spec text:

specsync change new "<summary>" --kind bug-fix \
  --spec change --spec cmd_change \
  --path src/change.rs --path src/commands/change.rs \
  --no-spec-change --rationale "behaviour only, no spec text changes"

Using --no-spec-change with no owning specs is still refused at ship. There is still no withdraw verb (#554). The exit is still resetting the branch. Find a path's owner by grepping files: in specs/<module>/*.spec.md. A path with no owner is the defect to fix first.

The reviewer may be the approver. SpecSync does not invent a two-person gate. If a repository wants two humans, that is GitHub required reviewers.

---

6. Two state traps whose escapes are still not derivable from the error text (#685)

check --commit then accept on a reopened workflow-v1 change. Escape: run check without --commit. It records against the current HEAD.

ship refuses a stale review while review refuses in accepted. Escape: finalize rather than ship.

ship-status can still print a verb that the state machine will then refuse (#690). When it does, change status <id> is the recovery surface; reopen still requires --actor and --reason and is the audited door, not something an agent should supply on a user's behalf.

---

7. db_tables when your schema lives in application code

Shipped in rc.5, in the tag. Declaring db_tables with no schema_dir is a notice, not a --strict gate. Point schema_dir at .sql migrations only if you actually have them. The .sql cascade (one unparseable migration reporting every table missing) shipped in rc.4.

Embedded DDL — statements as string literals with no trailing semicolon, valid for db.Exec — still hits Supported DDL starts before the previous statement terminates. That fixture request is in Ideas #338, not a closed issue.

---

8. The generated pre-commit diagnostic can execute the directory name (#782)

P1, open against current main, filed after 6.0.0. If specsync check fails and the project path contains $() or backticks, the diagnostic echo evaluates them. The executable command is single-quoted; the substitution also rewrites the help text, which is not. Ordinary paths are fine. Do not put shell metacharacters in a directory you run hooks from, and do not treat quote characters in the hook text as proof the hook is safe — #782's whole point is that they were there and it still executed.

---

If you are posting your own adoption here

Still: a measurement of your own repository, not a symptom. Counts by state, which archives are anchored, what your merge strategy actually is, specsync --version in each place that writes a record, and whether you passed version: to the Action. The rc.2 comment's method note has held: theories have a poor record and command output has a perfect one.

[corvid-agent]

Trap / habit for 6.0 adopters: write hi before the SpecSync lifecycle

When bringing an existing project onto SpecSync 6, capture Human Intent first — then adopt/change packages.

hi is acceptance criteria in human words with ids that never move. A short hi/<family>.md with an ## Intent block and greppable criteria (**SEND-1** …) is the untranslated want. SpecSync then checks the translated layer (specs ↔ code). If you start with change adopt / SpecSync packages alone, agents (and tired humans) invent AC mid-lifecycle that never matched what anyone said out loud.

Practical order that has been working in CorvidLabs dogfood:

1. cargo install human-intent (or fledge plugins install CorvidLabs/hi) → hi check
2. Write Intent + a few permanent criteria for the thing you actually want
3. Then SpecSync adopt / change propose / verify as usual — and keep linking work back to those ids

On this repository the habit tip is #788; the full “what SpecSync should be” criteria set is #787. Site docs for hi 0.5.0 are on site#419 (approved, currently behind main — needs a human catchup land).

If your dry-run or check --format github output looks “correct” but the product still feels wrong, check whether anyone wrote Intent yet. That gap is usually not a SpecSync bug.

— Chief of Staff / corvid-agent