Link code repos to a spec

Specs often live in a dedicated plans repo while the implementation happens in one or more sibling code repos. Linked repos give a spec its own review tabs for those local repos, so the Diff Explorer can show docs, code/main, lander/main, or whatever implementation branches belong to that spec.

Use linked repos when:

• The plan lives outside the codebase it describes.
• One spec touches multiple repos.
• You want reviewers to read the spec and inspect related code changes in the same SpecRider window.

1. Declare repo handles

In the plans repo, add or edit .specrider/workspace.json. The repos object maps stable handles to local folders:

{
  "schema_version": "1",
  "repos": {
    "code": "../specrider",
    "lander": "../specrider-lander",
    "integrations": "../specrider-integrations"
  }
}

Paths are resolved relative to the plans repo root unless they are absolute. Keep handles short and human-readable; they become the labels users see in the review tabs.

self is reserved for the plans repo itself. You do not need to declare it.

2. Link a spec to branches

In the spec’s YAML frontmatter, add a links: array. Each entry points at one configured repo handle and one review branch:

---
status: in-progress
owner: jake
iteration: 2
last_review: codex · 2026-05-18
tags: [connectors, sdk, typescript]
links:
  - repo: code
    branch: main
    base: main
  - repo: lander
    branch: docs/linked-repos
    base: main
  - repo: integrations
    branch: shopify-sync
    base: main
---

repo must match a handle from .specrider/workspace.json. branch is the branch SpecRider should review. base is the comparison base; it defaults to main when omitted.

The chip shown in the frontmatter keeps the visible label compact: repo handle, branch icon, branch name. The base stays available in the tooltip because it matters for the diff range, but it is not usually the thing you scan for.

3. Review from the commit rail

Open the Commits rail or Diff Explorer. Specs with valid links: entries show one tab for the plans repo plus one tab for each linked repo:

docs
code/main
lander/docs/linked-repos
integrations/shopify-sync

Select a tab to switch the commit graph and diff body to that repo. The plans repo tab is still where uncommitted spec changes live. Linked repo tabs are read-only in SpecRider; they are for review, not hidden writes.

Trust linked folders

SpecRider treats linked repos like other local folders: it will not read from them until you trust the workspace and linked folders. If a linked tab shows a trust callout, review the paths and approve them from the prompt.

For the full trust model, see Workspace trust .

Git actions and terminal behavior

The Fetch button can refresh linked repo refs. Pull and Push only become available when the linked branch is currently checked out in that linked repo folder; otherwise SpecRider keeps those write-side actions disabled so it does not mutate the wrong branch.

When you need to write code, commit, rebase, or switch branches, use the terminal. SpecRider can follow the active Diff Explorer repo for terminal cwd, which keeps agent work pointed at the implementation repo while the spec remains visible.

Troubleshooting

• Unknown repo handle — the repo: value in links: is not declared in .specrider/workspace.json.
• No linked tab appears — check that links: is a YAML array and each entry has both repo and branch.
• Trust callout appears — trust the linked folder before reviewing it.
• Pull or Push is disabled — checkout the linked branch in that repo folder, then refresh the rail.