Scan blueprint docs and assign missing PRD/ADR/PRP/WO IDs. Use when assigning IDs to docs; --dry-run to preview, --link-issues to create GitHub issues for orphans.
Scan blueprint docs and assign missing PRD/ADR/PRP/WO IDs. Use when assigning IDs to docs; --dry-run to preview, --link-issues to create GitHub issues for orphans.
args
[--dry-run] [--link-issues]
argument-hint
--dry-run to preview changes, --link-issues to create GitHub issues for orphans
allowed-tools
Read, Write, Edit, Glob, Bash, AskUserQuestion
model
sonnet
name
blueprint-sync-ids
Scan all PRDs, ADRs, PRPs, and work-orders, assign IDs to documents missing them, and update the manifest registry.
When to Use This Skill
Use this skill when...
Use blueprint-sync instead when...
You're assigning PRD-NNN / ADR-NNNN / PRP-NNN / WO-NNN to docs missing them
You want to detect modified or stale generated content (not IDs)
You're previewing ID assignments with --dry-run
You're reconciling drift between .claude/rules/ and the manifest
You want to create GitHub issues for orphan docs via --link-issues
Use document-linking instead for runtime cross-doc traceability
Flags
Flag
Description
--dry-run
Preview changes without modifying files
--link-issues
Also create GitHub issues for orphan documents
Interaction Mode
Before any closing AskUserQuestion menu, resolve the automation config:
When EFFECTIVE_INTERACTION_MODE=quietand this invocation was
automation-initiated (autopilot, session bookend, drift-nudge follow-up — not
a slash command the user typed), skip closing navigation menus ("what next?" /
"create another?" style): apply the safe default and end with a one-line
receipt instead. Quiet mode never skips confirmation gates that guard writes —
only navigation menus. A direct user invocation always behaves fully
interactively (explicit intent overrides quiet; see ADR-0020).
Run the helper. It owns the read-only scan: frontmatter id: extraction across
PRDs/ADRs/PRPs/work-orders, deriving the expected ADR-NNNN / WO-NNN from each
filename, flagging NEEDS_ID (no id) and id_mismatch (frontmatter id disagrees
with the filename-derived expectation), and building the reverse github_issues
index from the manifest registry:
PRD_NEEDS_ID / ADR_NEEDS_ID / PRP_NEEDS_ID / WO_NEEDS_ID and the
needs_id issues are the documents to assign IDs to in Step 7 (each carries
DOC= and, for ADRs/WOs, the EXPECTED= filename-derived ID).
ADR_MISMATCH / WO_MISMATCH and the id_mismatch issues (HAS= vs
EXPECTED=) are documents whose frontmatter id disagrees with their filename
— reconcile these in Step 7, never silently. STATUS=ERROR indicates at least
one mismatch.
GH_ISSUE_MAPPINGS and MANIFEST_PRESENT summarise the reverse-index build
(Step 9 detail below).
The audit is read-only; it makes no edits. Surface its counts as the Step 6
report and proceed to the mutating steps.
Step 7: Assign IDs (unless --dry-run)
For each document needing an ID:
PRDs:
Get next PRD number: jq '.id_registry.last_prd' manifest.json + 1
Generate ID: PRD-NNN (zero-padded)
Insert into frontmatter after first ---:
id:PRD-001
Update manifest: increment last_prd, add to documents
ADRs:
Derive ID from filename: 0003-title.md → ADR-0003
Insert into frontmatter
Add to manifest documents
PRPs:
Get next PRP number: jq '.id_registry.last_prp' manifest.json + 1
Generate ID: PRP-NNN
Insert into frontmatter
Update manifest: increment last_prp, add to documents
Work-Orders:
Derive ID from filename: 003-task.md → WO-003
Insert into frontmatter
Add to manifest documents
Step 8: Extract Titles and Links
For each document, also extract:
Title: First # heading or frontmatter name/title field
Existing links: relates-to, implements, github-issues from frontmatter
The Step 2 audit already groups the manifest's per-document github_issues
arrays into the reverse index (GH_ISSUE_MAPPINGS= reports how many distinct
issue numbers map to documents). Write that reverse index into the manifest:
