| name | c-03-repo-bootstrap |
| description | Bootstrap onboarding for undocumented repos or existing memory slices. Builds root overviews, route-local overview pillars, evidence packs, file cards, onboarding waves, deleted-slice cleanup, curator reviews, and handoff while keeping the orchestrator thin. |
Repo Bootstrap
Bootstrap durable onboarding for a repository that has little or no memory coverage, or for an already-ledgered memory repo whose source slices need targeted creation, refresh, move handling, or cleanup.
The minimum successful bootstrap is one root repo overview under the c-08-ar-coordination-context-resolver skill resolved onboarding_root:
overview.md
For larger repositories, the scalable path is route-local and wave-based:
root overview.md
-> area research
-> coverage plan
-> governing route map
-> route-local overview.md construction pillars
-> evidence packs where needed
-> file cards
-> file-level onboarding waves
-> curator review
-> handoff
Core constraint: LLM context is a rolling window. A full repository cannot be understood safely in one unbounded pass. This skill breaks bootstrap into bounded phases where agents write durable artifacts to disk and the orchestrator reads only distilled artifacts, not raw repo dumps.
Design Philosophy
Locality-first memory
Durable memory must live where agents naturally look while traversing the codebase.
A root overview.md explains the repository as a whole. A route-local overview.md explains a source subtree as if that subtree were a small repository of its own. A file-level onboarding document explains one concrete source file and links back to the nearest governing overview.
Preferred durable placement, with every path relative to the resolved onboarding_root:
overview.md
overview.index.json
<mirrored-source-folder>/overview.md
<mirrored-source-folder>/overview.index.json
<mirrored-source-file>.md
Detached bootstrap/areas/* artifacts are allowed as temporary research and promotion artifacts. Durable agent-facing overviews exist to be discoverable through source-path traversal.
overview.index.json files are generated route indexes. They do not replace
overview prose or file-level onboarding. They let future c-04-retrieval-strategy-router skill reads infer child
routes, covered file sidecars, sparse coverage, and governing-overview fallback
without repeatedly probing for missing sidecars. They also carry a compact
hotPath block derived from each overview's ## Hot Path Summary plus
generated candidate and source-anchor hints.
Overview as construction pillar
Route-local overview.md files are intermediate durable memory artifacts created after area research has identified:
- where an area begins in the source tree
- what the area governs
- which files are load-bearing
- which concepts repeat across files
- which docs or cross-repo boundaries affect the area
- which files should later receive file-level onboarding
Later file-level onboarding workers use the nearest governing overview.md as a construction pillar. The overview supplies the local area model; the file-level onboarding preserves concrete file-specific knowledge.
Progressive discovery read order
When working on a source file, read onboarding from broadest to narrowest:
overview.md
overview.index.json
<ancestor-folder>/overview.md
<ancestor-folder>/overview.index.json
<nearest-folder>/overview.md
<nearest-folder>/overview.index.json
<source-file>.md
For example:
source:
src/helpdesk/mappers/PlatformMapper.php
onboarding read path:
overview.md
overview.index.json
src/overview.md
src/overview.index.json
src/helpdesk/overview.md
src/helpdesk/overview.index.json
src/helpdesk/mappers/overview.md
src/helpdesk/mappers/overview.index.json
src/helpdesk/mappers/PlatformMapper.php.md
This lets an agent reconstruct context whether it starts at the repo root or gets dropped directly onto a source file.
File-level self-sufficiency
File-level onboarding stays first-class. It must not collapse into “see overview.md”.
A file onboarding document must carry the file-specific facts that protect that file:
- purpose
- logic
- conventions
- invariants and boundaries
- repo-internal relationships
- docs references that affect this file
- cross-repo behavior that affects this file
- update history
It must also backlink to the nearest governing overview so future agents discover the local area model.
Knowledge promotion pipeline
Do not promote raw findings directly into durable memory. Use intermediate artifacts:
raw repo observation
-> scout finding
-> area report
-> coverage plan
-> governing route map
-> overview card
-> route-local overview.md
-> evidence pack
-> file card
-> file-level onboarding
-> curator review
Exploration artifacts help agents understand. Promotion artifacts help agents and humans decide what becomes memory. Durable memory artifacts are the reviewed layer future agents will trust.
Behavior To Preserve
This skill intentionally keeps the strongest current bootstrap behavior.
- Thin orchestrator — the orchestrator coordinates, reads distilled artifacts, updates state, and enforces gates. It does not ingest raw code, directory trees, grep dumps, or full repo search output.
- Bounded specialization — scout, structure, interface, pattern, concern, docs, boundary, overview, file, and curator workers operate on narrow scopes.
- Confidence tags — all factual findings in research and promotion artifacts use
[HIGH], [MEDIUM], or [LOW].
- Durable checkpoints — every phase produces artifacts that allow the bootstrap to stop and resume.
- Topology awareness — bootstrap resolves the active memory root, path rules, storage rules, source registry, and cross-repo rules through
c-08-ar-coordination-context-resolver before writing artifacts.
- Cross-repo read-only semantics — adjacent repos may be read only when allowed; only the target repo's memory is updated.
- Developer consultation where it matters — gated mode pauses at review gates; automated mode still parks uncertain claims and writes review artifacts.
c-05-create-or-update-onboarding-files skill ownership of file-level onboarding — the c-03-repo-bootstrap skill prepares file cards and waves, but the c-05-create-or-update-onboarding-files skill owns the canonical file-level content model.
Inputs
| Input | Required | Description |
|---|
repo | yes | Target repository name. |
topology | no | Optional override passed through the c-08-ar-coordination-context-resolver skill. Normal bootstrap passes only repo and lets the c-08-ar-coordination-context-resolver skill resolve topology. |
coordination-root | no | Optional coordination-root hint for explicit external-memory operations or repair. |
control-mode | no | gated or automated. If omitted, ask during Phase 0A. |
bootstrap-mode | no | quick-orientation, safe-starter-memory, cross-repo-focused, domain-doc-focused, existing-memory-slice-maintenance, or full-bootstrap. Defaults to safe-starter-memory when the user is unsure. |
seed-context | no | Optional paths to known onboarding or documentation that should seed the run. |
priority-areas | no | Optional area names or source routes to prioritize. If omitted, scout identifies them. |
Do not build compatibility behavior for older bootstrap depth labels. This repo is alpha; prefer clear current behavior over old aliases.
Control Modes
Bootstrap supports two control modes.
Gated workflow
The orchestrator pauses after major phases for developer review:
- source inventory review
- scout / area map
- root overview
- governing route map
- first route-local overview wave
- first file onboarding wave
- final handoff
Use gated mode when the repo is business-critical, unfamiliar, or likely to contain hidden company intent.
Automated workflow
The orchestrator may continue through the full bootstrap after setup without phase-by-phase developer approval, as long as hard stop conditions are not hit.
Automated mode removes human approval gates after setup. It does not remove evidence gates, review artifacts, curator reviews, state updates, or final handoff.
Automated execution starts only after the Phase 0 source inventory has been presented, corrected or accepted by the user, and recorded in bootstrap/input-ledger.md.
| Phase | Gated mode | Automated mode |
|---|
| Source inventory | pre-automation intake gate | pre-automation intake gate |
| Scout | pause for area-map review | continue, record assumptions |
| Root overview | pause for review | continue after self-check |
| Governing route map | pause for review | continue unless placement confidence is LOW |
| Route-local overview wave | pause after first wave | continue after curator pass |
| Docs evidence pack | ask when sources are missing | continue using approved sources; park missing evidence |
| Cross-repo boundary pack | ask on LOW confidence | continue only with HIGH/MEDIUM evidence; park LOW |
| File onboarding wave | pause after wave | continue after curator pass |
| Handoff | present final | present final and ask whether separate closeout should run |
Automated uncertainty handling
[HIGH] -> may enter durable memory with evidence
[MEDIUM] -> may enter durable memory with careful wording and evidence
[LOW] -> goes to Parking Lot / Open Questions / Handoff, not durable fact
Hard stops in both modes
Stop and ask the developer when:
- memory root cannot be resolved
- multiple memory roots are plausible
- target repo is ambiguous
- source inventory cannot be reviewed before automation begins
- required source access is missing for a load-bearing evidence pass
- cross-repo settings are ambiguous for a required boundary
- adjacent repo branch mismatches for a required boundary
- docs and code contradict each other on a load-bearing behavior
- output would require updating a non-target repo
- a
[LOW] claim would otherwise become durable fact
Source Inventory Review Rule
Before asking the user for additional sources, the bootstrap orchestrator must present a reviewable source inventory.
The inventory must show:
- sources discovered from the
c-08-ar-coordination-context-resolver skill resolved system/sources.md
- source categories
- source locations
- whether each source is readable or unavailable
- what the orchestrator intends to use each source for
- which sources will be ignored or treated as unavailable
- which source categories appear missing or weak
Ask only after showing the inventory:
Here is what I found and plan to treat as sources. Is this correct, and is anything missing?
Do not ask “do you have additional sources?” before showing what was found.
Write the reviewed result to:
bootstrap/input-ledger.md
Use templates/bootstrap-input-ledger-template.md.
Topology And Eligibility
Invoke c-08-ar-coordination-context-resolver before selecting bootstrap candidates or writing artifacts.
Use the resolved context to determine:
- active memory root
- onboarding storage mode
- source path eligibility rules
- file-type eligibility rules
system/settings.mdsystem/settings.json when presentsystem/sources.md- cross-repo allow rules
- branch safeguards
Apply resolved onboarding.pathRules before selecting source paths. In shared settings, scoped rules such as path: <repo-name> define eligible source paths and file types for that repository. Storage is resolved separately from onboarding.storage.
In mixed workspaces, resolving one repo must not move neighboring repos onto a different memory root.
Bootstrap candidate selection is governed by the resolved onboarding.pathRules from system/settings.json. Starter settings should include a standard exclusion baseline so broad repo rules do not select generated, vendored, build-output, cache, IDE, local-machine, or downloaded metadata files unless the developer explicitly includes them for the run.
Recommended settings.json path-rule excludes:
node_modules/**
vendor/**
dist/**
build/**
coverage/**
.cache/**
.pytest_cache/**
.venv/**
.idea/**
.vscode/**
.env
.env.*
**/generated/**
**/*.generated.*
**/*.Zone.Identifier
**/*:Zone.Identifier
Use the same settings baseline for fresh bootstrap and existing-memory-slice-maintenance. If a repository's resolved path rules are missing these common excludes, record that during source inventory review and prefer updating settings.json rather than relying on an agent-local filter.
Artifact Paths
All paths below are relative to the c-08-ar-coordination-context-resolver skill resolved onboarding_root.
overview.md
entities.md
bootstrap/
STATE.md
input-ledger.md
scout-report.md
coverage-plan.md
governing-route-map.md
areas/
<area>.md
<area>.brief.md
<area>/
structure.md
interfaces.md
patterns.md
concerns.md
overview-cards/
<mirrored-source-route>.overview-card.md
evidence/
docs/
<area-or-route>.docs-pack.md
cross-repo/
<area-or-route>.boundary-pack.md
file-cards/
<mirrored-source-path>.card.md
waves/
overview-wave-001.md
onboarding-wave-001.md
reviews/
overview-wave-001.curator.md
onboarding-wave-001.curator.md
handoff.md
<mirrored-source-folder>/overview.md
<mirrored-source-file>.md
Templates
Use explicit templates instead of inferring artifact shape from prior examples:
| Artifact | Template |
|---|
| Root repo overview | templates/repo-overview-template.md |
| Bootstrap input ledger | templates/bootstrap-input-ledger-template.md |
| Bootstrap state | templates/bootstrap-state-template.md |
| Coverage plan | templates/coverage-plan-template.md |
| Governing route map | templates/governing-route-map-template.md |
| Route-local overview card | templates/route-local-overview-card-template.md |
| Route-local overview | templates/route-local-overview-template.md |
| Docs evidence pack | templates/docs-evidence-pack-template.md |
| Cross-repo boundary pack | templates/cross-repo-boundary-pack-template.md |
| File card | templates/file-card-template.md |
| Onboarding wave | templates/onboarding-wave-template.md |
| Curator review | templates/curator-review-template.md |
| Bootstrap handoff | templates/bootstrap-handoff-template.md |
Citation And Reference Rules
Docs References, Repo-Internal References, and Cross-Repo References are explanation-first sections backed by citation tables when they carry behavioral or boundary context.
Required table columns:
| Finding | Citations | Source Path |
| ------- | --------- | ----------- |
Rules:
Finding is a concise summary of what the cited lines establish.Citations records exact line ranges, for example L10-L18 or L10-L18; L42-L47.Docs References uses canonical documentation links, even when a local mirror was read for line access.Repo-Internal References uses same-repo source, test, config, generated artifact, or onboarding evidence.Cross-Repo References uses workspace-relative links to adjacent repo code/onboarding or external boundary proof.- Never emit absolute filesystem paths in onboarding output.
- Treat
system/sources.md, search registries, embedding hits, and source lists as routing inputs only. Never cite them as proof.
- If no relevant source exists, keep the section and record what was checked plus that no relevant evidence was found.
Confidence Levels
All factual claims in scout reports, area reports, briefs, coverage plans, route maps, evidence packs, cards, waves, and curator reviews carry a confidence tag when they are not directly self-evident.
[HIGH] — confirmed by developer, authoritative docs, or matched producer/consumer evidence across a boundary.[MEDIUM] — clear from code reading or repeated local patterns, but not externally confirmed.[LOW] — inferred, speculative, naming-based, config-only, partial, or uncertain.
Promotion rules:
| Confidence | Durable memory handling |
|---|
[HIGH] | may be stated as fact with evidence |
[MEDIUM] | may be stated carefully with source evidence |
[LOW] | must be parked as unresolved; do not state as fact |
Bootstrap State File
Every bootstrap produces and maintains:
bootstrap/STATE.md
The state file is the first file read at the start of every bootstrap session and the last file updated at the end.
Use templates/bootstrap-state-template.md.
The state file tracks:
- current control mode
- current bootstrap mode
- topology and memory root
- source inventory status
- phase status
- areas
- governing routes
- route-local overview waves
- file onboarding waves
- decisions
- blockers
- parking lot
- deferred files
- next recommended action
Phase 0 — Setup, Topology, Control Mode, And Source Intake
0.1 Resolve topology
Invoke c-08-ar-coordination-context-resolver with the target repo and optional topology/coordination-root hints.
Done when:
- memory root is known
- repo-relative source path eligibility is known
- onboarding storage is known
system/settings.md and system/settings.json are resolved if presentsystem/sources.md is resolved or its absence is recorded- cross-repo rules and branch safeguards are known
0.2 Ask or record control mode
If control-mode was not supplied, present the two control modes and ask the user to choose gated or automated.
If bootstrap-mode was not supplied, ask for a mode or default to safe-starter-memory when the user is unsure.
Bootstrap modes:
| Mode | Use when | Output target |
|---|
quick-orientation | user wants repo understanding only | source inventory + scout + root overview |
safe-starter-memory | default for most repos | root overview + first route-local overview wave + first high-risk file wave |
cross-repo-focused | repo participates in multi-repo flows | root overview + boundary packs + boundary route/file coverage |
domain-doc-focused | behavior depends on domain docs | root overview + docs packs + docs-sensitive coverage |
existing-memory-slice-maintenance | already-ledgered memory needs coverage or cleanup for an added, moved, deleted, or newly important route | source inventory delta + route overview/card or cleanup plan + evidence packs as needed + targeted file wave or removal list + curator review + handoff |
full-bootstrap | mature/critical repo needs broad coverage | full pass model in waves |
Existing-memory slice maintenance
Use existing-memory-slice-maintenance when the repository already has a usable memory layer and the work is structural rather than a single-file update.
Use it for:
- a new package, module, feature area, or source route
- a moved package or module route
- a deleted package, module, feature area, or source route
- a newly important source area that lacks a governing route-local overview
- a stale route-local overview whose governed source slice changed meaning
- many files appearing or disappearing together
- targeted onboarding expansion where file-by-file maintenance would lose the structural context
This mode does not pretend the repository is blank. It starts from the existing root overview.md, entities.md when present, route-local overviews, verified file-level onboarding, bootstrap artifacts, and the source delta that triggered the maintenance.
For moved or deleted routes, preservation is the default question before removal. Inspect whether the old route's documented behavior moved into a new source route, split across multiple targets, merged into another route, or actually disappeared. Move or reuse accurate onboarding before retiring or removing stale artifacts; removal is only correct when no safe current target remains for the preserved knowledge.
Expansion outputs may include:
- source inventory delta
- route-local overview card
- route-local overview
- docs or cross-repo evidence packs where needed
- file cards for load-bearing files
- targeted onboarding wave
- curator review
- handoff
Cleanup outputs may include:
- stale route assessment
- cleanup, move, preservation, or removal plan
- affected route-local overview list
- affected child file-level onboarding list
- related bootstrap artifact list
- preserved-history decision
- curator review
- handoff
The c-05-create-or-update-onboarding-files skill remains the user-facing entry point for create/update onboarding requests. When the c-05-create-or-update-onboarding-files skill detects that the change is route-level create, refresh, move, or delete work, it should route to this c-03-repo-bootstrap skill mode instead of flattening the work into independent file-level onboarding edits.
0.3 Present source inventory before asking for additions
Read the resolved system/sources.md and present a source inventory:
## Source Inventory Review
### Sources I Plan To Use
| Source | Category | Location | Status | Planned Use |
| -------- | -------------------- | ------------------ | -------- | -------------------------------- |
| `<name>` | Domain Documentation | `<path/url label>` | readable | docs evidence packs for `<area>` |
### Sources I Will Not Use
| Source | Category | Reason |
| -------- | ------------ | ---------------------------------------------- |
| `<name>` | `<category>` | unavailable / stale / unrelated / wrong branch |
### Missing Or Weak Source Categories
| Category | Why It May Matter |
| -------------------- | ------------------------------------------------------------- |
| Domain Documentation | area reports suggest business rules not fully visible in code |
Then ask:
- Are these sources correct?
- Should any source be excluded?
- Are any important docs missing?
- Are there Confluence pages, internal docs, vendor docs, schemas, protocol specs, or adjacent repos I should add?
0.4 Write input ledger and state
Write:
bootstrap/input-ledger.md
bootstrap/STATE.md
Done when:
- source inventory has been presented and accepted or corrected by the user
- approved/excluded/user-added sources are recorded
- cross-repo context from settings is recorded
- control mode is recorded
- bootstrap mode is recorded
- hard stops for the run are recorded
Phase 1 — Scout
Goal
Map repository structure broadly without deep implementation analysis.
The scout is broad but shallow. It may read top-level structure, package manifests, build files, entrypoint hints, routing/config files, existing onboarding, approved source inventory, and allowed adjacent onboarding/code signals.
It must not read every file deeply.
Procedure
- Gather structural signals.
- Build a tech profile.
- Discover cross-repo signals allowed by topology.
- Identify functional areas.
- Assign every eligible top-level source path to one area or mark it excluded.
- Prioritize areas.
- Write
bootstrap/scout-report.md.
- In gated mode, ask the developer to confirm the area map.
Scout report required sections
# Scout Report — <repo>
## Tech Profile
## Functional Areas
## Cross-Repo Interface Map
## Out Of Scope
## Unresolved
## Developer Review Questions
Functional areas should include boundaries, priority, reason for priority, seed context, initial observations, and suggested deep-dive mode.
Done when:
- every top-level eligible source path is assigned to an area or excluded
- every area has boundaries and priority
- cross-repo hints are recorded, even if empty
STATE.md is updated
Phase 2 — Area Deep-Dives
Goal
Produce confidence-tagged area knowledge that explains structure, interfaces, patterns, and concerns.
Execution model
For each high-priority area, use up to four focused agents:
| Agent | Focus | Output |
|---|
| Structure agent | architecture, modules, data flow, state | bootstrap/areas/<area>/structure.md |
| Interface agent | APIs, events, protocols, cross-repo hints | bootstrap/areas/<area>/interfaces.md |
| Pattern agent | conventions, errors, tests, domain terms | bootstrap/areas/<area>/patterns.md |
| Concerns agent | invariants, traps, fragility, security | bootstrap/areas/<area>/concerns.md |
For small areas, use one combined area agent instead.
Sizing rules
| Area size | Recommended model |
|---|
< 10 files | inline or single area agent |
10–25 files | single area agent or two lenses |
25–75 files | specialized agents |
75+ files | split area first or process subareas |
Merge step
A merge agent reads only the section reports for one area and writes:
bootstrap/areas/<area>.md
bootstrap/areas/<area>.brief.md
The merge preserves confidence tags, resolves duplicates, records contradictions, identifies key files, and suggests route-local overview candidates.
Done when:
- prioritized areas have area reports and briefs
[LOW] claims remain unresolved or parked- key files and possible governing routes are identified
STATE.md is updated
Phase 3 — Root Repo Overview Synthesis
Goal
Create or refresh the root repo overview from the scout report and area briefs.
Output:
overview.md
Use templates/repo-overview-template.md.
Root overview verification is route-based. Record sourceRoute as <repo-root> and fill both lastVerifiedCommitHash and lastVerifiedCommitDate from the source commit that the overview was checked against. The c-02-memory-quality-control skill later compares that recorded commit to HEAD across the whole repository route and also checks for local staged or unstaged changes.
The synthesis agent reads:
bootstrap/STATE.mdbootstrap/input-ledger.mdbootstrap/scout-report.md- area briefs
- existing
overview.md if present
- specific full area reports only on demand
It does not load all raw source code or all full area reports upfront.
Required root overview sections:
## What This Repo Is
## Hot Path Summary
## Architecture At A Glance
## Code Structure
## Functional Areas
## Cross-Repo References
## Build & Dev
## Key Invariants
## Glossary Terms
## Docs References
## What To Explore Next
Done when:
- root overview exists
STATE.md records synthesis status- gated mode review is complete or automated mode self-check passed
Phase 4 — Bottom-Up Memory Build
Goal
Convert approved area findings into durable route-local overviews and file-level onboarding through small, evidence-backed, reviewable waves.
Core rule:
Build the next safe memory wave, not the whole memory layer at once.
4A — Coverage Planning
Write:
bootstrap/coverage-plan.md
Use templates/coverage-plan-template.md.
Inputs:
- root
overview.md
STATE.mdscout-report.md- area reports and briefs
- concerns reports
- interface reports
- input ledger
- developer review notes
Classify files and routes:
| Classification | Meaning | Default action |
|---|
landmine | hidden invariant / fragile logic | early file card + wave |
cross-repo-boundary | can break another repo/system | boundary pack + file card |
core-logic | central behavior | route overview and/or file card |
entrypoint | user/system entry into area | route overview and/or file card |
domain-mapper | transforms domain state | route overview and file card if non-obvious |
state-machine | state transitions | route overview + early file card |
security-sensitive | auth, validation, permissions | early file card |
routine-support | helper with limited risk | defer unless touched |
simple-dto-config | passive data/config | defer unless touched |
deleted-route | source route disappeared | cleanup plan + affected memory list |
moved-route | source route moved or was renamed | move plan + overview/link update list |
stale-onboarding-route | route-local memory no longer matches code | refresh or retire plan |
generated-vendor-build | generated/vendor/build output | exclude |
unknown | not enough evidence | investigate or ask |
Done when:
- priority routes and files are classified
- evidence needs are known
- deferred files have reasons and revisit triggers
- first overview wave candidates are known
4B — Governing Route Map
Write:
bootstrap/governing-route-map.md
Use templates/governing-route-map-template.md.
This artifact decides where durable route-local overview.md files should live in the mirrored onboarding hierarchy.
Placement principles:
- Place
overview.md at the source route where the area begins.
- Prefer locality over detached architecture folders.
- Do not create an overview merely because a folder exists.
- Create an overview when a subtree has shared models, workflows, repeated invariants, cross-repo boundaries, docs dependencies, multiple hotspots, or routing burden.
- For cross-cutting workflows, choose the most natural local anchor and add local mentions in participating route overviews.
Done when:
- proposed governing routes are listed
- considered-but-deferred routes are recorded
- stale, moved, or deleted routes are recorded when running existing-memory slice maintenance
- cross-cutting concepts have primary local anchors
- gated mode review is complete or automated mode can proceed with non-LOW placements
4C — Route-Local Overview Cards
For each selected governing route, write:
bootstrap/overview-cards/<mirrored-source-route>.overview-card.md
Use templates/route-local-overview-card-template.md.
Overview cards are work orders for route-local overview workers. They specify:
- why this overview exists
- what source subtree it governs
- what structures it must explain
- what files are load-bearing
- what docs or cross-repo packs apply
- what backlinks/downlinks are required
- what open questions remain
Done when:
- every first-wave route overview has a card
- cards list parent overview, child overview candidates, and governed files
- cards constrain workers enough to avoid broad repo re-discovery
4D — Route-Local Overview Waves
Create wave manifests under:
bootstrap/waves/overview-wave-001.md
A wave should include a small number of overview cards.
Default wave sizing:
| Route type | Max scope |
|---|
| high-risk boundary route | 1 route |
| workflow-owning route | 1 route |
| module route with multiple hotspots | 1–3 routes |
| routine directory | defer |
Overview workers write durable route-local overviews:
<mirrored-source-folder>/overview.md
Use templates/route-local-overview-template.md.
Route-local overview verification is also route-based. Record the governed repo-relative source route, then fill lastVerifiedCommitHash and lastVerifiedCommitDate from the source commit that the overview was checked against. A later change anywhere under that route is allowed to trigger c-02-memory-quality-control skill drift even if the prose still turns out to be correct after review.
A route-local overview must include:
- parent overview backlink
- hot path summary for fast route discovery
- what belongs here / what does not
- structures found here
- operating model
- main flows
- load-bearing files
- local invariants and traps
- repo-internal references
- cross-repo references
- docs references
- file-level onboarding map
- child overviews
- how to use this area
- update history
Done when:
- all overview wave targets exist or have blockers
- generated route indexes have been refreshed for created or changed route
overviews, including
hotPath fields
- the wave has a curator review
STATE.md is updated
4E — Domain Documentation Evidence Pass
For each priority area or route where domain behavior, external protocol behavior, vendor/library behavior, or business rules matter, write:
bootstrap/evidence/docs/<area-or-route>.docs-pack.md
Use templates/docs-evidence-pack-template.md.
Rules:
- Use
system/sources.md as a routing index only.
- Use its
Domain Documentation category as the required discovery path.
- Cite actual documentation or local mirror evidence, not
system/sources.md.
- If no relevant documentation exists, record what was checked.
- Embedding hits are pointers only; open and cite the source document.
Done when:
- each docs-dependent priority route has a docs pack or explicit no-evidence record
- every docs finding points to direct evidence
4F — Cross-Repo Boundary Pass
For each priority route with inbound or outbound cross-repo signals, write:
bootstrap/evidence/cross-repo/<area-or-route>.boundary-pack.md
Use templates/cross-repo-boundary-pack-template.md.
Rules:
- Read adjacent repos only when topology and branch safeguards allow it.
- Treat adjacent repos as read-only context.
- Record real system-boundary evidence only.
- Same-repo implementation facts belong in repo-internal references, not boundary packs.
- Naming-only ties are
[LOW] and must not become durable fact.
Done when:
- confirmed boundaries are listed with confidence
- branch/topology notes are recorded
- LOW-confidence ties are queued for review or handoff
4G — File Card Generation
For each priority source file, write:
bootstrap/file-cards/<mirrored-source-path>.card.md
Use templates/file-card-template.md.
A file card must include:
- classification and priority
- why the file matters
- governing overview path
- ancestor overviews
- evidence packs to read
- files the worker may read
- files the worker must not read without escalation
- required file onboarding sections
- known traps
- open questions
Do not assign file-level onboarding work without a file card unless the repo is tiny.
4H — File-Level Onboarding Waves
Create wave manifests under:
bootstrap/waves/onboarding-wave-001.md
Use templates/onboarding-wave-template.md.
Each file worker receives one file card and follows c-05-create-or-update-onboarding-files.
Default wave sizing:
| File type | Max scope |
|---|
| landmine file | 1–2 files |
| cross-repo boundary file | 1–2 files |
| core logic cluster | 2–3 files |
| mapper cluster | 3–5 files |
| DTO/config/simple utility | defer unless touched |
File onboarding workers must:
- read the file card first
- read the nearest governing overview and listed ancestor overviews
- read only listed source/evidence files unless escalating
- keep file-level onboarding self-sufficient
- add or update
governingOverview
- keep planning notes out of durable onboarding
- preserve strict 1-to-1 source mapping
After a file onboarding wave creates, updates, moves, or deletes sidecars,
refresh generated route indexes so the c-04-retrieval-strategy-router skill can use coveredFiles and route scope
instead of probing for sidecar presence.
4I — Curator Review
After each overview or onboarding wave, write:
bootstrap/reviews/<wave-name>.curator.md
Use templates/curator-review-template.md.
The curator checks:
- strict 1-to-1 mapping for file onboarding
- generated route indexes exist next to changed route overviews
- generated route indexes reflect changed file-level sidecar coverage
- route-local overview placement is mirrored and local
- file onboarding backlinks to nearest governing overview
- overview downlinks list governed files
- no task-local planning in durable memory
- docs references cite actual evidence
- repo-internal and cross-repo references use correct buckets
- no source registry or embedding hit is cited as proof
- no absolute filesystem paths
- update history is append-only
- LOW-confidence claims are not stated as facts
- deferred files are recorded
STATE.md is updated
4J — Developer Review And Next-Wave Decision
In gated mode, present each curator result and changed durable files to the developer.
Ask only high-value questions:
- Do these overviews/onboarding files match your understanding?
- Are any invariants missing?
- Are any compatibility notes actually obsolete code or stale docs?
- Are any
[LOW] claims confirmable or false?
- Should the next wave continue with the current priority order?
In automated mode, record the same questions in STATE.md and bootstrap/handoff.md unless they are hard blockers.
Phase 5 — Handoff
When pausing or completing bootstrap, write:
bootstrap/handoff.md
Use templates/bootstrap-handoff-template.md.
The handoff lists:
- control mode and bootstrap mode
- trusted coverage
- route-local overviews created
- file onboarding created
- route-local overviews and file onboarding removed, moved, or retired
- evidence packs created
- deferred coverage
- open questions
- known risks
- completed waves and curator results
- recommended next waves
- how future agents should use the bootstrap artifacts
Automated bootstrap stops at this handoff/review boundary. After presenting the handoff, ask whether a separate closeout should run.
Guided Mode Defaults
If the developer does not know how to choose areas or depth, use safe-starter-memory:
- Resolve topology.
- Present source inventory and write input ledger.
- Run scout.
- Pick the top 3 high-risk areas by cross-repo coupling, entrypoints, command/control paths, state-machine logic, hidden invariants, and concerns reports.
- Run area deep-dives for those areas.
- Build or refresh root overview.
- Create coverage plan.
- Create governing route map.
- Create route-local overview cards for the highest-value routes.
- Build overview wave 1.
- Run docs evidence only where domain docs matter.
- Run cross-repo boundary pass only where signals exist.
- Create file cards only for high and medium priority files.
- Build onboarding wave 1 with no more than 5 file cards.
- Run curator review.
- Handoff or ask before wave 2 depending on control mode.
If the selected mode is existing-memory-slice-maintenance:
- Resolve topology and read existing root, entity, route-local, and file-level onboarding for the affected slice.
- Present the source inventory delta and write input ledger after the user accepts or corrects it.
- Confirm the resolved
settings.json path rules include the standard excludes before selecting added, moved, deleted, or refreshed paths.
- Classify the route as expansion, move, cleanup, refresh, or defer.
- Create or update the coverage plan and governing route map for that slice only.
- For expansion or refresh, produce route-local overview cards, route-local overviews, evidence packs, file cards, targeted onboarding waves, curator review, and handoff as needed.
- For move or deletion, produce a cleanup plan, affected onboarding list, preserved-history decision, curator review, and handoff.
- Ask whether separate closeout should run after handoff.
Progress display for non-expert users:
## Bootstrap Progress
| Step | Status | What It Means |
| ---------------------- | ----------- | ---------------------------------------------------- |
| Resolve setup | done | The system knows where memory lives |
| Review sources | done | The source universe is explicit |
| Map repo | done | The system knows the main parts of the repo |
| Research risky areas | in progress | Agents are checking places most likely to break |
| Build root overview | pending | A repo guide will be created |
| Place local overviews | pending | Local construction pillars will be created |
| Create first file wave | pending | High-risk files get direct onboarding |
| Review | pending | Curator checks prevent bad memory from being trusted |
Implementation Guards
Only guard against likely or proven bad behavior.
- Do not create detached durable area overviews by default. Use route-local
overview.md files in the mirrored onboarding hierarchy.
- Do not let overview files replace file onboarding. File docs remain self-sufficient and backlink to governing overviews.
- Do not generate markdown for every file. Full coverage means every file is covered, deferred, or excluded — not that every file has a file doc.
- Do not create an overview for every folder. Create one only when the subtree has shared model, workflow, invariants, boundaries, docs dependencies, hotspots, or routing burden.
- Do not cite
system/sources.md, search registries, or embedding hits as evidence. They are routing inputs only.
- Do not update adjacent repo memory during target repo bootstrap. Cross-repo context is read-only unless a separate task targets that repo.
- Do not preserve stale code or stale docs under vague compatibility language. Compatibility requires evidence of an active consumer, migration requirement, external contract, supported version boundary, or developer-confirmed constraint.
- Do not let automated mode skip review artifacts. Automated mode changes pause behavior, not artifact quality.
- Do not ask for additional sources before showing found sources. Source intake must be reviewable.
- Do not promote
[LOW] claims to durable fact. Park them in state, handoff, or open questions.
- Do not add an extra repo-name folder under the resolved
onboarding_root. The resolver already returns the target repo's onboarding root.
- Do not run closeout as part of automated bootstrap. Handoff is the automation boundary; closeout requires a separate approval.
- Do not flatten route-level maintenance into unrelated file-level edits. Use
existing-memory-slice-maintenance when a slice is added, moved, deleted, or structurally refreshed.
Multi-Agent Execution Model
Orchestrator
-> resolves topology and control mode
-> presents source inventory
-> maintains STATE.md
-> dispatches scoped workers
-> reads only distilled artifacts
Scout agent
-> reads broad repo structure and approved source inventory
-> writes scout-report.md
Area lens agents
-> read one area only
-> write structure/interfaces/patterns/concerns reports
Area merge agent
-> reads area section reports
-> writes area report and brief
Synthesis agent
-> reads scout + area briefs + state
-> writes root overview.md
Coverage planner
-> reads overview + area artifacts
-> writes coverage-plan.md
Route mapper
-> writes governing-route-map.md
Overview card/worker agents
-> write route-local overview cards and route-local overview.md files
Docs librarian
-> writes docs evidence packs from approved documentation sources
Boundary mapper
-> writes cross-repo boundary packs from allowed adjacent context
File card/file worker agents
-> write file cards and invoke/follow the `c-05-create-or-update-onboarding-files` skill for file onboarding
Curator
-> validates each wave and writes curator review
The orchestrator remains thin throughout.
When To Use This Skill
| Situation | Use this skill? |
|---|
| New repo added to workspace, zero onboarding | yes |
| Repo has placeholder overview and needs real content | yes |
| Task will touch an un-bootstrapped area | yes, existing-memory-slice-maintenance when repo memory already exists |
| Repo root overview exists but agents still get lost in a subtree | yes, route-local overview wave |
| New package/module/source route appears in an already-ledgered repo | yes, existing-memory-slice-maintenance |
| Package/module/source route disappears or moves | yes, existing-memory-slice-maintenance cleanup or move handling |
| Cross-repo boundary is poorly understood | yes, cross-repo-focused mode |
| Domain docs influence code behavior | yes, domain-doc-focused mode |
| Repo is already well bootstrapped and one file changed | no, use the c-05-create-or-update-onboarding-files skill directly |
| Small script repo with a few files | probably not; write root overview directly |
Relationship To Other Skills
| Skill | Relationship |
|---|
c-08-ar-coordination-context-resolver | Required first step. Resolves memory root, settings, sources, path rules, storage, and cross-repo policy. |
c-05-create-or-update-onboarding-files | Owns final file-level onboarding semantics and routes structural slice maintenance back to the c-03-repo-bootstrap skill. The c-03-repo-bootstrap skill creates cards/waves and delegates file output rules to the c-05-create-or-update-onboarding-files skill. |
c-04-retrieval-strategy-router | Consumes bootstrapped overviews and file maps as the Intent substrate and can route to semantic/relationship providers first. |
c-02-memory-quality-control | Becomes relevant after bootstrap; touched files can be promoted from deferred to covered. |
l-01-agent-lifecycles | May trigger targeted bootstrap when an active job enters an uncovered area. |
confluence-search / documentation search skills | Feed the docs evidence pass through approved sources from the input ledger. |
Acceptance Criteria
This skill implementation is successful when:
- the minimum bootstrap still produces a useful root
overview.md
- source inventory is presented before asking for additions
- gated and automated control modes are explicit
- automated mode still writes review artifacts and curator reviews
- broad Phase 4 deepening is replaced with bottom-up passes
- route-local overviews are created in the mirrored onboarding hierarchy
- file-level onboarding remains self-sufficient and backlinks to governing overview
- docs evidence and cross-repo boundary evidence are separate passes
- file cards constrain file workers before the
c-05-create-or-update-onboarding-files skill is invoked
- curator review validates both overview waves and file onboarding waves
- current thin-orchestrator, confidence-tag, checkpoint, topology, and cross-repo read-only behavior is preserved
- guards prevent the likely bad behaviors without adding compatibility scaffolding for alpha-era labels
- existing-memory slice maintenance can create, refresh, move, or clean up route-local memory without treating the repo as blank
- automated bootstrap ends at handoff and asks whether separate closeout should run
