Map Project Monorepo

Inputs

• $request

  : Optional scope or refresh note such as

  all crates

  ,

  only packages/api-*

  , or

  refresh workspace docs after adding the sql crate

  .

Goal

CLAUDE.md

Step 0: Resolve workspace scope and detect monorepo shape

• whether the repo is a Cargo workspace or a package monorepo
• whether the user wants a full refresh or a scoped member refresh
• which members exist and which already have

  CLAUDE.md

  files
• which root-level memory files and architectural rules already exist and should be preserved

references/workspace-discovery.md

• workspace detection order
• member inventory expectations
• discovery rules for exported surface, wiring, and dependency mapping

• the workspace shape cannot be identified
• the target member set is too ambiguous to update safely

Step 1: Discover members, public surface, and wiring

• actual exported or reachable surface
• key source files
• wiring files such as crate roots, package entry points, manifests, barrels, startup hooks, registries, routers, or feature flags
• inter-member dependencies
• tests, benchmarks, or runtime entry points
• real consumer usage patterns when available

• do not equate raw

  pub

  or raw

  export

  counts with the real public surface
• verify what consumers can actually reach first
• prefer actual imports, re-exports, and runtime registration points over guesses
• preserve existing member docs when they are still correct; extend or tighten them instead of regenerating blindly

references/workspace-discovery.md

Step 2: Refresh per-member

CLAUDE.md

files

CLAUDE.md

• purpose
• public or exported surface
• key files
• dependencies
• wiring and entry points
• usage pattern
• architecture notes
• testing guidance

• references/output-contract.md

  for required sections, size targets, and verification rules

• references/package-template.md

  for library or package members

• references/app-template.md

  for apps, binaries, or entrypoint-heavy members

• use real workspace examples, not placeholders
• keep tables and bullets preferred over repetitive prose
• make each member file self-contained for Claude's lazy-loading behavior
• document hidden wiring points if a future change would need them to make behavior reachable

CLAUDE.md

Step 3: Simplify the root

CLAUDE.md

• keep project-wide rules, locked decisions, testing policy, and workspace layout
• remove member-specific API tables or file listings from root
• ensure the root points clearly to member-local docs rather than duplicating them

• preserve root-level architectural constraints and steering decisions
• do not erase useful human-authored global rules
• move member detail down instead of letting the root become a second copy of every member file

references/output-contract.md

Step 4: Verify coverage, self-containment, and budget

• every in-scope member has a

  CLAUDE.md

• member docs describe the real reachable surface, not just raw visibility markers
• wiring and entry points are documented where relevant
• root no longer duplicates member-local details heavily
• line budgets remain sane
• the refreshed docs would let an implementation agent work in a touched member without searching blindly

references/output-contract.md

• improve coverage
• restore missing sections
• tighten duplicated content
• correct stale reachability or wiring claims

Step 5: Report what changed

• detected workspace shape
• members refreshed
• files created or updated
• coverage or inventory highlights
• budget status
• intentionally deferred or out-of-scope members

Guardrails

• Do not use this skill proactively; it is explicit-user-only because it mutates durable project memory.
• Do not add

  context: fork

  ; this workflow writes into the active repository.
• Do not add

  paths:

  ; this is a generic maintenance skill.
• Do not overwrite useful root-level project rules without evidence they are stale.
• Do not keep workspace discovery matrices, template encyclopedias, or quality scorecards inline in

  SKILL.md

  .
• Do not bloat the root

  CLAUDE.md

  ; push member detail down.
• Do not mark the refresh complete without verifying self-containment and reachability.

When To Load References

• references/workspace-discovery.md

  Use for workspace detection order, member discovery rules, and exported-surface versus raw-visibility guidance.

• references/output-contract.md

  Use for required member/root sections, budget rules, and verification gates.

• references/package-template.md

  Use when refreshing library-style members.

• references/app-template.md

  Use when refreshing binaries, apps, servers, or entrypoint-heavy members.

Output Contract

1. detected workspace shape and scope
2. members refreshed
3. files created or updated
4. coverage and self-containment summary
5. budget and verification result
6. deferred or intentionally skipped members