Reference

Validate spec dependencies across repositories. Zero network cost by default; remote verification is opt-in.

Overview

Specs can declare dependencies on modules in other repositories using the owner/repo@module syntax in depends_on. This lets you verify that upstream APIs you depend on are still documented and available.

depends_on:
  - specs/database/database.spec.md          # local ref
  - corvid-labs/algochat@messaging           # cross-project ref

Local refs are validated by specsync check (file must exist). Cross-project refs require specsync resolve --remote which fetches the target repo's registry from GitHub.

How It Works

1. You declare a cross-project dependency in your spec's depends_on
2. specsync resolve --remote parses the owner/repo@module syntax
3. Fetches specsync-registry.toml from the root of the target repo's default branch on GitHub
4. Checks that the module exists in the registry

No authentication required for public repos. Private repos need a GITHUB_TOKEN environment variable.

Publishing Your Registry

For other projects to reference your modules, commit .specsync/registry.toml to your repo's default branch:

specsync init-registry                     # uses project folder name
specsync init-registry --name myapp        # custom name
git add .specsync/registry.toml
git commit -m "chore: add spec registry for cross-project refs"
git push

The registry lists all modules from your specs directory:

[registry]
name = "spec-sync"

[specs]
cli = "specs/cli/cli.spec.md"
parser = "specs/parser/parser.spec.md"

Verifying References

# Local refs only (no network, runs in check too)
specsync resolve

# Local + cross-project refs (fetches registries from GitHub)
specsync resolve --remote

Output:

Cross-project references:
  ✓ CorvidLabs/spec-sync@cli: resolved
  ✓ CorvidLabs/spec-sync@parser: resolved
  ✗ CorvidLabs/spec-sync@nonexistent: module not in registry

CI Usage

Add resolve --remote to your CI pipeline to catch broken cross-project refs:

- name: Verify cross-project refs
  run: specsync resolve --remote

specsync check validates local refs only and never hits the network. Use resolve --remote explicitly when you want cross-project verification. This keeps CI fast by default.

Error Cases