repo-onboarding-context-map

星标6

分支0

更新时间2026年7月7日 23:44

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.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

fusebase-dev

fusebase-dev/fusebase-flow

打开 GitHub 仓库查看创作者相关仓库

下载

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

List repo root files (top level only). Identify project type (Node/Python/Go/Rust/etc.) and frontend/backend split if visible.
Read root README.md if present. Read up to 3 most-referenced docs in docs/.
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.
Detect build/test/lint commands from manifest files. Capture exact commands.
Identify protected-path candidates: long-lived worker code, generated files, migration files, deployment configs.
Identify risky system boundaries: external APIs, database migrations, auth surfaces, file system writes outside repo.
Run git log --oneline -30 to read commit cadence + recent areas of activity.
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.
Propose updates to AGENTS.md "project-specific values" section. Show the diff in chat. Do NOT apply unless operator says "apply".
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.

同仓库更多 Skills

同仓库

find-wasted-code

fusebase-dev/fusebase-flow

Use ONLY when the operator runs "/find-wasted-code" (or explicitly asks to "scan the repo for dead-end tool calls / broken links / missing helpers / footgun configs / silent push-through"). Statically scans THIS repo for friction footguns and writes a tracked report to docs/wasted-code/report.md. Manual-trigger ONLY — do NOT auto-invoke; the skill carries disable-model-invocation and no hook wires it. Read-only except the one report write. Findings are review candidates, never auto-fixes. Do NOT use for token/transcript economy (/token-waste-audit), for process ceremony (/find-wasted-effort), or for CLI/Flow drift health (/fusebase-health).

2026-07-156

lightweight-lane

fusebase-dev/fusebase-flow

Use at Specify to classify a ticket Full vs Lightweight, and whenever a change looks small / reversible / low-risk ("small fix", "tweak", "hotfix", "drop pretty-printing", "bump a constant"). Operationalizes FR-21 — ceremony proportional to change size. Defines the eligibility gate, the change-note artifact, the one-pass build→verify→deploy procedure, and mid-flight promotion. Do NOT use for risky/uncertain work, schema/data migrations, security/permission changes, new public contracts needing a decision, unknown-root-cause diagnostics, or large features — those take the Full lane.

2026-07-146

role-discipline

fusebase-dev/fusebase-flow

ALWAYS load at session start. After self-attesting, Read references/<role>.md for your role (Product Owner / AI Developer / Architect / Deploy phase) — role-specific don't-list, exact refusal phrasing for FR violations, and recovery pointers; shared cross-role protocols live in this file. Mandatory; not on-demand.

2026-07-146

product-owner

fusebase-dev/fusebase-flow

Use when the operator types /product-owner, asks to activate Product Owner, start a Product Owner or PO session, or searches /product in Codex for Fusebase Flow project management. Do NOT use for implementing code; route implementation to the AI Developer role.

2026-07-116

module-size-discipline

fusebase-dev/fusebase-flow

Use when planning tasks that touch big source files, when an edit would push a file past the module-size ceiling, when the pre-commit module-size ratchet warns or blocks, or when generating policies/module-size-baseline.txt. Operationalizes FR-25 — module-size ratchet (ceiling default 800; over-ceiling files may shrink, never grow; extraction along a responsibility seam is in-scope, not scope creep). Do NOT use for docs/markdown size (FR-23 owns docs), to force decomposition of an existing monolith (that is its own explicit ticket), or to judge split quality by regex (seam-vs-mechanical is semantic — code-review owns it).

2026-07-106

release-deploy-reporting

fusebase-dev/fusebase-flow

Use ONLY when verification passed AND operator explicitly says "prepare deploy" / "draft deploy" / "ship it"; drafts deploy handoff, captures deploy hash + probes + smoke, advises spec DRAFT→DONE flip. Do NOT auto-invoke; operator triggers explicitly.

2026-07-106

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

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

List repo root files (top level only). Identify project type (Node/Python/Go/Rust/etc.) and frontend/backend split if visible.
Read root README.md if present. Read up to 3 most-referenced docs in docs/.
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.
Detect build/test/lint commands from manifest files. Capture exact commands.
Identify protected-path candidates: long-lived worker code, generated files, migration files, deployment configs.
Identify risky system boundaries: external APIs, database migrations, auth surfaces, file system writes outside repo.
Run git log --oneline -30 to read commit cadence + recent areas of activity.
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.
Propose updates to AGENTS.md "project-specific values" section. Show the diff in chat. Do NOT apply unless operator says "apply".
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.