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

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

Failure cases

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.