document-linking

Document Linking

Provides a unified ID system connecting PRDs, ADRs, PRPs, work-orders, GitHub issues, commits, and PRs. IDs are project-scoped, auto-generated on first access, and maintained bidirectionally.

When to Use This Skill

Use this skill when...	Use blueprint-sync-ids instead when...
You need bidirectional links between PRD/ADR/PRP/issue at runtime	You're doing a one-shot bulk ID assignment for docs missing IDs
You're auto-assigning an ID on first document access	You want a --dry-run preview of bulk ID changes
You want to validate broken cross-document references	Use blueprint-adr-validate instead for ADR-only relationship checks
You need to find orphan docs/issues across the project	Use document-detection instead when capturing a brand-new doc

ID Format

Document Type	Format	Example	Notes
PRD	PRD-NNN	PRD-001	3-digit, zero-padded
ADR	ADR-NNNN	ADR-0003	4-digit (matches existing convention)
PRP	PRP-NNN	PRP-007	3-digit, zero-padded
Work-Order	WO-NNN	WO-042	3-digit, matches work-order number

Frontmatter Schema

All blueprint documents should include these fields:

---
id: PRD-001                    # Unique identifier (auto-generated if missing)
relates-to:                    # Cross-document references (optional)
  - ADR-0003
  - PRP-002
github-issues:                 # Linked GitHub issues (optional)
  - 42
  - 87
implements:                    # For PRPs: source PRD (optional)
  - PRD-001
# ... existing fields (created, modified, status, etc.)
---

ID Registry (manifest.json)

IDs are tracked in docs/blueprint/manifest.json:

{
  "id_registry": {
    "last_prd": 3,
    "last_prp": 7,
    "documents": {
      "PRD-001": {
        "path": "docs/prds/user-authentication.md",
        "github_issues": [42, 87],
        "title": "User Authentication"
      },
      "ADR-0003": {
        "path": "docs/adrs/0003-database-choice.md",
        "github_issues": [],
        "title": "Database Choice"
      },
      "PRP-002": {
        "path": "docs/prps/oauth-integration.md",
        "github_issues": [45],
        "implements": ["PRD-001"],
        "title": "OAuth Integration"
      }
    },
    "github_issues": {
      "42": ["PRD-001", "PRP-002"],
      "45": ["PRP-002"],
      "87": ["PRD-001"]
    }
  }
}