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
Refresh the root and per-member CLAUDE.md files so each workspace member has accurate, self-contained local guidance and the root stays thin and project-wide.
Step 0: Resolve workspace scope and detect monorepo shape
Determine:
- 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
Load references/workspace-discovery.md for:
- workspace detection order
- member inventory expectations
- discovery rules for exported surface, wiring, and dependency mapping
Stop early if:
- the workspace shape cannot be identified
- the target member set is too ambiguous to update safely
Success criteria: The workspace shape and refresh scope are explicit before discovery starts.
Step 1: Discover members, public surface, and wiring
For every in-scope member, inventory:
- 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
Also inventory workspace-wide capabilities (these belong in the root file, not per-member):
- project-committed skills (
.claude/skills/) and enabled MCP servers (.mcp.json /
.claude/settings*.json)
Rules:
- 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
Load references/workspace-discovery.md and complete the relevant discovery steps for the detected monorepo shape.
Load references/skills-and-mcp.md for skill/MCP discovery sources and redaction rules.
Success criteria: You have enough concrete inventory to write self-contained member docs without placeholders or false surface claims.
Step 2: Refresh per-member CLAUDE.md files
For each in-scope member, update or create a focused local CLAUDE.md that covers:
- purpose
- public or exported surface
- key files
- dependencies
- wiring and entry points
- usage pattern
- architecture notes
- testing guidance
Load:
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
Writing rules:
- 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
Success criteria: Every targeted member has an accurate, self-contained CLAUDE.md.
Step 3: Simplify the root CLAUDE.md
Treat the root file as the project-wide router:
- 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
- include a compact, INLINE "Available Skills & MCP — prefer these" section in the ROOT
CLAUDE.md,
plus a one-line pointer at the very top, so future agents use the repo's skills/MCP instead of
forgetting them (always-loaded text only — never a lazy reference, never per-member)
Rules:
- 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
Load references/output-contract.md for the root-file expectations and budget rules.
Load references/skills-and-mcp.md for the "Available Skills & MCP" section format and discovery sources.
Success criteria: Root stays thin and project-wide while member detail lives where Claude will lazy-load it.
Step 4: Verify coverage, self-containment, and budget
Validate the refresh before declaring completion:
- 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
Load references/output-contract.md for verification gates and budget targets.
If verification fails:
- improve coverage
- restore missing sections
- tighten duplicated content
- correct stale reachability or wiring claims
Success criteria: The workspace memory is compact, member-local, and actually useful to future agents.
Step 5: Report what changed
Summarize:
- detected workspace shape
- members refreshed
- files created or updated
- coverage or inventory highlights
- budget status
- intentionally deferred or out-of-scope members
Do not claim a perfect refresh if the workspace is only partially covered or if the requested scope excluded some members.
Success criteria: The user gets a clear summary of what workspace memory was refreshed and how complete it is.
Guardrails
- Do not use this skill PROACTIVELY (it mutates durable project memory) — run it only on explicit user
intent or when an explicit user-invoked workflow composes it (e.g.
/ship-playbook). It is no longer
disable-model-invocation, so workflows can call it; that is not license to run it unprompted.
- 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.
references/skills-and-mcp.md
Use to discover the repo's project skills and MCP servers and render the inline "Available Skills &
MCP — prefer these" section into the root CLAUDE.md.
Output Contract
Report:
- detected workspace shape and scope
- members refreshed
- files created or updated
- coverage and self-containment summary
- budget and verification result
- deferred or intentionally skipped members
1---
2name: map-project-monorepo
3version: 3.1.0
4description: |
5 Refresh a Cargo WORKSPACE or package monorepo's durable AI context — a self-contained `CLAUDE.md` per
6 member that Claude lazy-loads, plus a thin project-wide root, so a change in any member has local guidance
7 without bloating the root. Discovers each member's real reachable surface, key files, wiring, and
8 inter-member dependencies, then keeps the root project-wide. User-only maintenance workflow that mutates
9 durable memory across many members: it documents the ACTUAL exported/reachable surface (not raw
10 `pub`/`export` counts), grounds every claim in code, and preserves locked root decisions. Use to refresh
11 workspace-local context after refactors, member additions, or export changes.
12allowed-tools:
13 - Read
14 - Edit
15 - Write
16 - Glob
17 - Grep
18 - Bash
19user-invocable: true
20argument-hint: "[workspace scope or refresh target]"
21arguments:
22 - request
23when_to_use: |
24 Use when the user explicitly asks to refresh workspace or monorepo docs, regenerate per-member `CLAUDE.md`
25 files, or sync the root and member memory with the real repo shape — "/map-project-monorepo", "refresh all
26 crate docs", "update the monorepo CLAUDE files after the refactor". Do NOT use on a single-app repo (use
27 map-project), and do NOT run proactively after routine edits — it mutates durable project memory across
28 members, so it is user-only. It documents what each member IS; it does not author coding rules.
29metadata:
30 source: https://skillmd.com/skills/ulpi-io/map-project-monorepo
31---
32
33<EXTREMELY-IMPORTANT>
34This skill mutates durable project memory across multiple workspace members. Non-negotiable rules:
351. Discover the real workspace shape before writing any member `CLAUDE.md`.
362. Document the actual exported or reachable surface, not raw visibility markers alone.
373. Keep each member file self-contained enough for Claude's lazy-loading model.
384. Preserve root-level project rules and locked architectural decisions unless discovery proves them stale.
395. Do not run this skill PROACTIVELY on your own initiative (it mutates durable project memory) — only
40 on explicit user intent, OR when an explicit user-invoked workflow composes it (e.g. `/ship-playbook`
41 refreshing the maps after a build).
42</EXTREMELY-IMPORTANT>
43
44# Map Project Monorepo
45
46## Inputs
47
48- `$request`: Optional scope or refresh note such as `all crates`, `only packages/api-*`, or `refresh workspace docs after adding the sql crate`.
49
50## Goal
51
52Refresh the root and per-member `CLAUDE.md` files so each workspace member has accurate, self-contained local guidance and the root stays thin and project-wide.
53
54## Step 0: Resolve workspace scope and detect monorepo shape
55
56Determine:
57
58- whether the repo is a Cargo workspace or a package monorepo
59- whether the user wants a full refresh or a scoped member refresh
60- which members exist and which already have `CLAUDE.md` files
61- which root-level memory files and architectural rules already exist and should be preserved
62
63Load `references/workspace-discovery.md` for:
64
65- workspace detection order
66- member inventory expectations
67- discovery rules for exported surface, wiring, and dependency mapping
68
69Stop early if:
70
71- the workspace shape cannot be identified
72- the target member set is too ambiguous to update safely
73
74**Success criteria**: The workspace shape and refresh scope are explicit before discovery starts.
75
76## Step 1: Discover members, public surface, and wiring
77
78For every in-scope member, inventory:
79
80- actual exported or reachable surface
81- key source files
82- wiring files such as crate roots, package entry points, manifests, barrels, startup hooks, registries, routers, or feature flags
83- inter-member dependencies
84- tests, benchmarks, or runtime entry points
85- real consumer usage patterns when available
86
87Also inventory workspace-wide capabilities (these belong in the root file, not per-member):
88
89- project-committed skills (`.claude/skills/`) and enabled MCP servers (`.mcp.json` /
90 `.claude/settings*.json`)
91
92Rules:
93
94- do not equate raw `pub` or raw `export` counts with the real public surface
95- verify what consumers can actually reach first
96- prefer actual imports, re-exports, and runtime registration points over guesses
97- preserve existing member docs when they are still correct; extend or tighten them instead of regenerating blindly
98
99Load `references/workspace-discovery.md` and complete the relevant discovery steps for the detected monorepo shape.
100Load `references/skills-and-mcp.md` for skill/MCP discovery sources and redaction rules.
101
102**Success criteria**: You have enough concrete inventory to write self-contained member docs without placeholders or false surface claims.
103
104## Step 2: Refresh per-member `CLAUDE.md` files
105
106For each in-scope member, update or create a focused local `CLAUDE.md` that covers:
107
108- purpose
109- public or exported surface
110- key files
111- dependencies
112- wiring and entry points
113- usage pattern
114- architecture notes
115- testing guidance
116
117Load:
118
119- `references/output-contract.md` for required sections, size targets, and verification rules
120- `references/package-template.md` for library or package members
121- `references/app-template.md` for apps, binaries, or entrypoint-heavy members
122
123Writing rules:
124
125- use real workspace examples, not placeholders
126- keep tables and bullets preferred over repetitive prose
127- make each member file self-contained for Claude's lazy-loading behavior
128- document hidden wiring points if a future change would need them to make behavior reachable
129
130**Success criteria**: Every targeted member has an accurate, self-contained `CLAUDE.md`.
131
132## Step 3: Simplify the root `CLAUDE.md`
133
134Treat the root file as the project-wide router:
135
136- keep project-wide rules, locked decisions, testing policy, and workspace layout
137- remove member-specific API tables or file listings from root
138- ensure the root points clearly to member-local docs rather than duplicating them
139- include a compact, INLINE "Available Skills & MCP — prefer these" section in the ROOT `CLAUDE.md`,
140 plus a one-line pointer at the very top, so future agents use the repo's skills/MCP instead of
141 forgetting them (always-loaded text only — never a lazy reference, never per-member)
142
143Rules:
144
145- preserve root-level architectural constraints and steering decisions
146- do not erase useful human-authored global rules
147- move member detail down instead of letting the root become a second copy of every member file
148
149Load `references/output-contract.md` for the root-file expectations and budget rules.
150Load `references/skills-and-mcp.md` for the "Available Skills & MCP" section format and discovery sources.
151
152**Success criteria**: Root stays thin and project-wide while member detail lives where Claude will lazy-load it.
153
154## Step 4: Verify coverage, self-containment, and budget
155
156Validate the refresh before declaring completion:
157
158- every in-scope member has a `CLAUDE.md`
159- member docs describe the real reachable surface, not just raw visibility markers
160- wiring and entry points are documented where relevant
161- root no longer duplicates member-local details heavily
162- line budgets remain sane
163- the refreshed docs would let an implementation agent work in a touched member without searching blindly
164
165Load `references/output-contract.md` for verification gates and budget targets.
166
167If verification fails:
168
169- improve coverage
170- restore missing sections
171- tighten duplicated content
172- correct stale reachability or wiring claims
173
174**Success criteria**: The workspace memory is compact, member-local, and actually useful to future agents.
175
176## Step 5: Report what changed
177
178Summarize:
179
180- detected workspace shape
181- members refreshed
182- files created or updated
183- coverage or inventory highlights
184- budget status
185- intentionally deferred or out-of-scope members
186
187Do not claim a perfect refresh if the workspace is only partially covered or if the requested scope excluded some members.
188
189**Success criteria**: The user gets a clear summary of what workspace memory was refreshed and how complete it is.
190
191## Guardrails
192
193- Do not use this skill PROACTIVELY (it mutates durable project memory) — run it only on explicit user
194 intent or when an explicit user-invoked workflow composes it (e.g. `/ship-playbook`). It is no longer
195 `disable-model-invocation`, so workflows can call it; that is not license to run it unprompted.
196- Do not add `context: fork`; this workflow writes into the active repository.
197- Do not add `paths:`; this is a generic maintenance skill.
198- Do not overwrite useful root-level project rules without evidence they are stale.
199- Do not keep workspace discovery matrices, template encyclopedias, or quality scorecards inline in `SKILL.md`.
200- Do not bloat the root `CLAUDE.md`; push member detail down.
201- Do not mark the refresh complete without verifying self-containment and reachability.
202
203## When To Load References
204
205- `references/workspace-discovery.md`
206 Use for workspace detection order, member discovery rules, and exported-surface versus raw-visibility guidance.
207
208- `references/output-contract.md`
209 Use for required member/root sections, budget rules, and verification gates.
210
211- `references/package-template.md`
212 Use when refreshing library-style members.
213
214- `references/app-template.md`
215 Use when refreshing binaries, apps, servers, or entrypoint-heavy members.
216
217- `references/skills-and-mcp.md`
218 Use to discover the repo's project skills and MCP servers and render the inline "Available Skills &
219 MCP — prefer these" section into the root `CLAUDE.md`.
220
221## Output Contract
222
223Report:
224
2251. detected workspace shape and scope
2262. members refreshed
2273. files created or updated
2284. coverage and self-containment summary
2295. budget and verification result
2306. deferred or intentionally skipped members