원클릭으로 Manus에서 모든 스킬 실행

c-03-repo-bootstrap

스타27

포크4

업데이트2026년 7월 4일 23:30

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.

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

Foxfire1st

Foxfire1st/agents-remember

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

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.md
system/settings.json when present
system/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 present
system/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.md
bootstrap/input-ledger.md
bootstrap/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.md
scout-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

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

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

Design Philosophy

Locality-first memory

Durable memory must live where agents naturally look while traversing the codebase.

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 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

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.md
system/settings.json when present
system/sources.md
cross-repo allow rules
branch safeguards

In mixed workspaces, resolving one repo must not move neighboring repos onto a different memory root.

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

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

[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 present
system/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

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

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.

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.

The synthesis agent reads:

bootstrap/STATE.md
bootstrap/input-ledger.md
bootstrap/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.md
scout-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.

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

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

c-03-repo-bootstrap

이 저장소의 다른 Skills

이 저장소의 다른 Skills

Repo Bootstrap

Design Philosophy

Locality-first memory

Overview as construction pillar

Progressive discovery read order

File-level self-sufficiency

Knowledge promotion pipeline

Behavior To Preserve

Inputs

Control Modes

Gated workflow

Automated workflow

Automated uncertainty handling

Hard stops in both modes

Source Inventory Review Rule

Topology And Eligibility

Artifact Paths

Templates

Citation And Reference Rules

Confidence Levels

Bootstrap State File

Phase 0 — Setup, Topology, Control Mode, And Source Intake

0.1 Resolve topology

0.2 Ask or record control mode

Existing-memory slice maintenance

0.3 Present source inventory before asking for additions

0.4 Write input ledger and state

Phase 1 — Scout

Goal

Procedure

Scout report required sections

Phase 2 — Area Deep-Dives

Goal

Execution model

Sizing rules

Merge step

Phase 3 — Root Repo Overview Synthesis

Goal

Phase 4 — Bottom-Up Memory Build

Goal

4A — Coverage Planning

4B — Governing Route Map

4C — Route-Local Overview Cards

4D — Route-Local Overview Waves

4E — Domain Documentation Evidence Pass

4F — Cross-Repo Boundary Pass

4G — File Card Generation

4H — File-Level Onboarding Waves

4I — Curator Review

4J — Developer Review And Next-Wave Decision

Phase 5 — Handoff

Guided Mode Defaults

Implementation Guards

Multi-Agent Execution Model

When To Use This Skill

Relationship To Other Skills

Acceptance Criteria

Repo Bootstrap

Design Philosophy

Locality-first memory

Overview as construction pillar

Progressive discovery read order

File-level self-sufficiency

Knowledge promotion pipeline

Behavior To Preserve

Inputs

Control Modes

Gated workflow

Automated workflow

Automated uncertainty handling

Hard stops in both modes

Source Inventory Review Rule

Topology And Eligibility

Artifact Paths

Templates

Citation And Reference Rules

Confidence Levels