repo-onboarding-context-map

name	repo-onboarding-context-map
description	Use on first Fusebase Flow install, opening an unfamiliar repo, or after major restructuring; produces durable context map (commands, structure, protected paths, risky boundaries). Do NOT use for routine ticket investigation.
source_inspiration	conceptual-only
license_status	clean-room-original
fusebase_flow_version	3.30.8
risk_level	low
invocation	manual
expected_outputs	["docs/specs/repo-context.md","AGENTS.md (project-specific section, recommended updates)"]
related_workflows	["setup.md","session-initiation.md"]
hook_dependencies	["none"]

Repo Onboarding & Context Map

Purpose

Inspect an unfamiliar repo and produce a durable context map so future sessions know the project's structure, commands, protected paths, and risky system boundaries without re-investigating each session.

Named reader: workflows/session-initiation.md step 5 — every new session reads docs/specs/repo-context.md when it exists and is <90 days old, instead of re-investigating. The map header MUST carry Generated: <YYYY-MM-DD> so readers can apply the freshness gate.

When to invoke

• First-time installation of Fusebase Flow into an existing repo
• Operator says "I'm picking up this repo" / "what's in this codebase?" / "set up flow here"
• After a major structural change (large rename, monorepo split, framework swap)
• When docs/specs/repo-context.md is missing or older than 90 days

Do not invoke when

• A current repo-context.md exists and the repo hasn't changed structurally
• Operator is asking a code-specific question — use code-review or normal investigation
• A spec is in flight — don't pivot to onboarding mid-ticket

Required inputs

Input	Where it lives	If missing
Repo root	git root	Stop; ask operator to confirm working directory
Package/project files	package.json, pyproject.toml, Cargo.toml, etc.	Note "no manifest detected"; describe based on file extensions only
Existing READMEs	README.md, docs/, etc.	Note absence; flag as Phase-4 onboarding gap
CLI edition map, for this edition	docs/fusebase-cli-edition.md	Continue with generic repo map, but mark CLI provider asset mapping unknown

Procedure

1. List repo root files (top level only). Identify project type (Node/Python/Go/Rust/etc.) and frontend/backend split if visible.
2. Read root README.md if present. Read up to 3 most-referenced docs in docs/.
3. If this is the Fusebase CLI edition or a downstream Fusebase Apps project, read docs/fusebase-cli-edition.md and record which CLI provider assets are present and relevant.
4. Detect build/test/lint commands from manifest files. Capture exact commands.
5. Identify protected-path candidates: long-lived worker code, generated files, migration files, deployment configs.
6. Identify risky system boundaries: external APIs, database migrations, auth surfaces, file system writes outside repo.
7. Run git log --oneline -30 to read commit cadence + recent areas of activity.
8. Save findings to docs/specs/repo-context.md using templates/spec.md adapted for context-mapping (see template). Stamp a Generated: <YYYY-MM-DD> line in the header — workflows/session-initiation.md step 5 uses it for the 90-day freshness gate.
9. Propose updates to AGENTS.md "project-specific values" section. Show the diff in chat. Do NOT apply unless operator says "apply".
10. Propose initial policies/protected-paths.yml candidates. Save as draft if operator approves; do NOT auto-write.

Output artifacts

Artifact	Path	Mode
Repo context map	docs/specs/repo-context.md	Mode B (full)
AGENTS.md project-specific updates (proposed)	chat diff	Mode A
Protected paths candidates	policies/protected-paths.yml (proposed; commit only on operator approval)	Mode B (full, YAML)

Failure cases

Failure mode	Detection	Response
Repo has no manifest, no README, no docs	Initial scan returns nothing identifying	Capture what's visible (file extensions, recent commits). Mark repo-context.md as partial and ask operator to fill the gaps.
Repo is a monorepo with conflicting conventions	Multiple package.json / pyproject.toml at different paths	Map each subdir separately. Flag in repo-context.md "monorepo: yes".
Repo uses git submodules	.gitmodules exists	Note submodules in repo-context.md but do not recurse into them; map a submodule only if the operator explicitly asks.

Escalation path

• Repo too large to scan in one pass (>10k files) → ask operator which subdirs to prioritize
• Build commands fail when run → file backlog ticket for build-environment-fix; do not propose flow installation until build is healthy

Anti-patterns

• Do not silently write AGENTS.md updates — propose, get operator approval, then write
• Do not commit policies/protected-paths.yml candidates without operator approval
• Do not save permanent memories about the repo without operator confirmation
• Do not invoke during an in-flight spec — context-mapping is a separate, longer-running task

Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.