From shadowrepo
Cold-start a ShadowRepo for a codebase. Scans the entire repo, builds a feature tree and spec graph, writes structured JSON to .shadowrepo/. Use when: "build shadowrepo", "scan this project", "create a shadow repo", or first-time setup.
How this skill is triggered — by the user, by Claude, or both
Slash command
/shadowrepo:buildThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Cold-start: scan the entire repo, build feature tree + spec graph, write to `.shadowrepo/`.
Cold-start: scan the entire repo, build feature tree + spec graph, write to .shadowrepo/.
stdlib/methodology.md — extraction rules and quality standardsstdlib/data-model.md — types (Spec, Feature, Anchor, Relation)stdlib/recursion-engine.md — the execution pattern you will followstdlib/file-discovery.md — what to include/excludestdlib/quality-gates.md — validation checks applied during Merge step.shadowrepo/ already exists in the target repo:
/shadowrepo check or /shadowrepo update insteadConstruct the initial scope covering the entire repo:
scope = {
scope_id: "root",
parent_scope_id: null,
depth: 0,
target_repo_path: <current working directory>,
files: <all source files after applying file-discovery rules>,
context: {
existing_features: [],
existing_specs: [],
parent_understanding: null
},
mode: "full"
}
Use Glob to find all files. Apply file-discovery.md to classify and filter.
Build manifest (ground truth for coverage):
all_source_files — the complete filtered file listtotal_source_count — len(all_source_files)Execute up to 3 rounds. Each round targets uncovered files. The coverage gate (see quality-gates.md) is enforced — if coverage < 80%, backfill automatically.
stdlib/recursion-engine.md with the root scope (all source files)contracts/merge-result.md)covered_files = merge-result.covered_filescoverage_percent = len(covered_files) / total_source_count * 100coverage_percent >= 80% → DONE, proceed to Step 3gap_files = all_source_files − covered_files"Round 1: {specs} specs, {coverage}% coverage, {gap} files remaining"scope = {
scope_id: "backfill-r2",
parent_scope_id: "root",
depth: 0,
files: gap_files,
context: {
existing_features: <features from round 1>,
existing_specs: [],
parent_understanding: "Backfill round: these files were missed in round 1. Extract specs and assign to existing features. Do NOT rebuild the feature tree — use existing_features. Skip the Understand step."
},
mode: "full"
}
stdlib/recursion-engine.md with the backfill scopecovered_files → union of round 1 + round 2uncovered_files → recalculate: all_source_files − covered_filescoverage_percentcoverage_percent >= 80% → DONE, proceed to Step 3gap_files"Round 2: +{new_specs} specs, {coverage}% coverage, {gap} files remaining"scope_id: "backfill-r3""Round 3: +{new_specs} specs, {coverage}% coverage (final)"coverage_percent >= 80% → build_status = "COMPLETE"coverage_percent < 80% → build_status = "PARTIAL"After the coverage loop completes, write the final JSON files:
.shadowrepo/features.json — the feature tree (per contracts/feature.md).shadowrepo/specs.json — all specs (per contracts/spec.md).shadowrepo/coverage.json — file coverage map:
{
"covered_files": ["string[] — files with at least one anchored spec"],
"uncovered_files": ["string[] — files with no specs after all rounds"],
"coverage_percent": "number"
}
.shadowrepo/meta.json — repo metadata:
{
"repo_name": "string",
"repo_path": "string",
"last_commit_hash": "string | null",
"built_at": "string — ISO8601",
"build_status": "'COMPLETE' | 'PARTIAL'",
"build_rounds": "number — how many rounds were executed (1-3)",
"stats": {
"total_files": "number",
"total_features": "number",
"total_specs": "number",
"coverage_percent": "number"
}
}
Copy the dashboard template into .shadowrepo/ with data inlined:
dashboard.html from this skill's directory (alongside this SKILL.md)/*__SHADOWREPO_META__*/ null → /*__SHADOWREPO_META__*/ <meta.json contents>/*__SHADOWREPO_FEATURES__*/ null → /*__SHADOWREPO_FEATURES__*/ <features.json contents>/*__SHADOWREPO_SPECS__*/ null → /*__SHADOWREPO_SPECS__*/ <specs.json contents>/*__SHADOWREPO_COVERAGE__*/ null → /*__SHADOWREPO_COVERAGE__*/ <coverage.json contents>.shadowrepo/index.htmlResult: one self-contained HTML file. Double-click to open — no server needed.
.shadowrepo/.tmp/ directory (temp agent results from all rounds)Output a summary to the user (use ascii-ui.md Build Completion template):
ShadowRepo built {COMPLETE|PARTIAL}.
Features: {count} ({root_count} root, {sub_count} sub-features)
Specs: {count} (density: {specs_per_100_files}/100 files)
Coverage: {percent}% ({covered}/{total} files)
Rounds: {rounds_used}/3
Types: {intent}i / {decision}d / {constraint}cn / {contract}ct / {convention}cv / {context}cx / {change}ch
{if PARTIAL}
⚠ Coverage below 80% target. {uncovered_count} files have no specs.
Largest uncovered areas: {top_3_directories}
{endif}
Written to .shadowrepo/
Dashboard: open .shadowrepo/index.html in a browser
Follow stdlib/error-handling.md. Key points:
error-handling.md Coverage Recovery)build_status: "PARTIAL", report honestly to usernpx claudepluginhub waynewangyuxuan/shadowrepo-extension-package --plugin shadowrepoFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.