| name | blueprint-workspace-scan |
| description | Discover child blueprint workspaces and refresh the manifest. Use when adding/removing a child blueprint or when status shows stale portfolio data. |
| args | [--max-depth N] [--dry-run] |
| argument-hint | --dry-run to preview without writing; --max-depth sets search depth (default 4) |
| allowed-tools | Bash(bash *), Read, Glob |
| created | "2026-04-12T00:00:00.000Z" |
| modified | "2026-06-18T00:00:00.000Z" |
| reviewed | "2026-04-12T00:00:00.000Z" |
/blueprint:workspace-scan
Refresh the monorepo root blueprint's workspaces.children registry by walking
the filesystem for child docs/blueprint/manifest.json files, reading their
feature-tracker.json when present, and writing cached rollup stats back to the
root manifest.
When to Use This Skill
| Use this skill when... | Use /blueprint:status instead when... |
|---|
| Adding or removing a child blueprint | Just inspecting overall blueprint state |
Root workspaces.children looks stale | You do not run a monorepo |
Migrating to format_version 3.3.0 | You only want per-project details |
Context
- Root manifest: !
find . -path '*/docs/blueprint/*' -maxdepth 3 -name manifest.json
- Candidate child manifests: !
find . -maxdepth 6 -type d \( -name node_modules -o -name .git -o -name dist -o -name build \) -prune -o -type f -path '*/docs/blueprint/manifest.json' -print
- Current scan time: !
date -u +%Y-%m-%dT%H:%M:%SZ
Parameters
Parse these from $ARGUMENTS:
--dry-run: Preview discovered children and the JSON that would be written — make no changes.--max-depth N: Maximum directory depth to search (default 4). Increase for deeply nested monorepos.
Execution
Execute this workspace scan:
Step 1: Verify a root manifest exists
If docs/blueprint/manifest.json is missing, stop and report that the current
directory is not a blueprint root. Suggest /blueprint:init for new projects.
Step 2: Run the scan script
Invoke the bundled script; it walks the tree, writes the updated manifest, and
emits a structured summary:
bash "${CLAUDE_SKILL_DIR}/scripts/workspace-scan.sh" \
--project-dir "$(pwd)" \
--max-depth 4 $ARGUMENTS
The script:
- Refuses to run on a manifest whose
workspaces.role == "child".
- Skips
node_modules, .git, dist, build, target, .venv.
- Writes
workspaces.role=root, discovery_strategy=auto-cache,
last_scanned_at, and a refreshed children[] array with cached_stats.
- Leaves existing feature-tracker data untouched.
Step 3: Report findings
Summarize the script output for the user:
- Number of children discovered.
- Any children whose
manifest_format_version is below 3.3.0 (suggest running
/blueprint:upgrade inside them if the user wants a fully v3.3 portfolio).
- Any children without a
feature-tracker.json (cached stats will be null).
Step 4: Next steps
Recommend running /blueprint:feature-tracker-sync at the root afterwards to
recompute derived statuses for any portfolio FRs that use implemented_by.
Agentic Optimizations
| Context | Command |
|---|
| Preview changes | /blueprint:workspace-scan --dry-run |
| Deeper monorepo | /blueprint:workspace-scan --max-depth 6 |
| Refresh all | /blueprint:workspace-scan followed by /blueprint:feature-tracker-sync |
Quick Reference
| Key | Meaning |
|---|
workspaces.role | root on the top manifest, child on per-project manifests |
workspaces.children[].path | Path relative to the root (e.g., projects/esp32-lamp) |
workspaces.children[].cached_stats | Rolled-up {total, complete, completion_percentage, current_phase} from the child's feature-tracker |
Post-actions
- If any child was removed from the registry (e.g., deleted on disk), the
script replaces
children[] wholesale — verify expected workspaces still
appear.
- Commit the updated manifest with a conventional commit:
chore(blueprint-plugin): refresh workspaces registry.
