Skip to content

Cross-Repo Spec Tracking

Problem

A developer wants to track work that lives in repository B from repository A's spec namespace, because A is where they do most of their workflow (planning, review, gates). They create a SPEC-NNN in A whose deliverable lives in B.

This sounds reasonable. It is not. It produces:

  • Duplicate specs: The same spec text, problem, goal, and user stories appear in both A and B. They drift independently.
  • Meaningless quality gates: A's /vt-c-4-review and /vt-c-5-finalize cannot inspect a deliverable in another repo. The gates either get bypassed silently or run against nothing.
  • Audit confusion: Was the work shipped under A-SPEC-NNN or B-SPEC-MMM? Both, neither, somewhere between?
  • Activation pingpong: Stale activations linger in A because A's workflow never sees the actual completion event in B.

Symptoms (how this is detectable)

  • A spec in your repo's specs/ references a target path under another repo (/Users/.../<other-repo>/).
  • The other repo has its own specs/ directory with a parallel spec ID and matching content.
  • The cross-referenced spec is status: in_progress for an unusually long time, with no commits on its feature branch.
  • git log in your repo shows zero work for the spec; git log in the other repo shows the work shipped under a different spec ID.

Pattern: One repo, one spec namespace

A spec MUST live in the repository that owns its deliverable. The target repository's filesystem and CI are the authority on what shipped and when.

Two specific rules

  1. No cross-repo spec creation. If you find yourself opening specs/NNN-thing/ in repo A whose target is repo B, stop. Open specs/NNN-thing/ in repo B instead.

  2. External references go in intake/projects.yaml, not specs/. If repo A's workflow needs to know about repo B's work (e.g., for cross-project status dashboards), register repo B in intake/projects.yaml as a consuming project. That gives A awareness of B without claiming to govern B.

Decision tree

Where does the deliverable live?
├─ In this repo                  → spec in specs/, normal workflow
├─ In a sibling repo I own       → spec in THAT repo's specs/, register
│                                  the sibling in intake/projects.yaml
│                                  if I need cross-project status
└─ In an external/upstream repo  → no spec at all; this is upstream work,
                                   track via intake/inbox/ or a feedback
                                   issue, not a SPEC-NNN

What to do when you discover a duplicate

When auditing reveals you already have a duplicate cross-repo spec (the case that triggered this pattern), close the local spec with full provenance:

  1. In the local spec's state.yaml, set status: completed with duplicate_of pointing at the canonical spec: 

    status: completed
activated_at: "<original date>"
completed_at: "<actual ship date in the canonical repo>"
duplicate_of:
  repo: <org/repo>
  spec: SPEC-NNN
  spec_path: specs/N-slug/
  ship_commit: <abbrev sha>
  ship_date: YYYY-MM-DD
gate_bypass:
  date: "<closure date>"
  reason: |
    Cross-repo duplicate. Quality gates ran in the canonical repo;
    running them again here would be meaningless.
  skipped_gates: [plan_gate, build_gate, review_gate, finalize_gate]

  2. Mirror the dates: completed_at should be the actual ship date in the canonical repo, not the date you discovered the duplicate. This keeps the registry's progress trends honest.

  3. Don't delete the spec file. Leave it as a tombstone — it's a permanent pointer for anyone who later wonders "what was V025-SPEC-119 about?"

  4. If a worktree exists for the duplicate, tear it down. There is no work left to do.

Why bother registering the lesson at all?

The same mistake is easy to make again because:

  • A spec creation is a low-friction action (one /vt-c-activate --from-prd).
  • The "deliverable lives in repo B" detail is often missed during activation.
  • The downstream cost (duplicate tracking, gate bypass, audit confusion) only shows up months later.

Capturing the pattern means future activation flows can flag the issue at activation time: "This spec's target path is outside this repo. Did you mean to create the spec in the target repo instead?"

Where this came from

V025-SPEC-119 (Open Brain Documentation Site) was created on 2026-03-24 in V025-claude-toolkit, with target path /Users/rolf/01-repositories/01-VisiTrans/open-brain/. On the same day, the open-brain repo's local SPEC-001 (specs/1-docs-site/) was created with identical text and shipped to completion (commit d8ff56a in open-brain).

V025-SPEC-119 then sat as in_progress for ~6 weeks until a workflow audit caught the duplicate during a /vt-c-shape invocation. The shape skill was correctly stopped before generating gray-area questions because the premise (deliverable doesn't exist) was false.

  • intake/projects.yaml — proper place to register sibling/consumer repos
  • V025-SPEC-119 — origin (closed as duplicate)
  • open-brain SPEC-001 (specs/1-docs-site/ in Visitrans/open-brain) — canonical