repo-context-builder— agent skill

Create or refresh REPO_CONTEXT.md and REVIEW_BRIEF.md for the current repository.

Keep the workflow evidence-first, compact, and deterministic. The goal is to leave behind two high-signal documents that future agents and chats can use immediately without re-discovering the repository from scratch.

Use bundled resources

Read these files before writing output:

• assets/templates/REPO_CONTEXT.md
• assets/templates/REVIEW_BRIEF.md
• references/repo-analysis-playbook.md
• references/output-checklist.md

Optional helper:

• scripts/repo_inventory.py generates a fast inventory of the repository. Use it when helpful, but do not rely on it blindly. Verify important claims against the actual files.

Output contract

Produce exactly these files at the repository root unless the user explicitly asks for different paths:

• REPO_CONTEXT.md
• REVIEW_BRIEF.md

If files already exist, update them in place instead of creating duplicates.

Required workflow

1. Resolve the repository and scope

1. Identify the repository root.
2. Determine whether the repo is a single app, service, library, infra repo, or monorepo.
3. Determine whether the user asked for:

• a full initial intake,
• a refresh of stale repo docs,
• or a task-scoped brief for a specific feature, bug, migration, or review.

1. If the user did not specify a focused task, still create a useful generic REVIEW_BRIEF.md that captures the highest-value next work areas, risks, and recommended entry points.

2. Collect evidence before writing

Inspect the repo in this order:

1. Root signals:

• README*
• AGENTS.md
• manifests and lockfiles
• CI config
• container and deployment config
• infra directories

1. Runtime and entrypoints:

• server entry files
• CLI entry files
• app bootstrap files
• job and worker entry files

1. Quality and test signals:

• lint, typecheck, test config
• test directories and representative tests

1. Architecture signals:

• top-level app, package, service, or module folders
• shared libraries
• adapters, API routes, models, schemas, migrations, queues, jobs

1. Operational signals when available:

• deployment workflows
• observability setup
• release or environment docs

1. Git signals when available and useful:

• active branch
• recent commits
• recent changed areas

Use the optional inventory script if it helps accelerate discovery, but confirm important claims by reading the underlying files.

3. Fill REPO_CONTEXT.md

Use the bundled template and replace every placeholder.

Requirements:

• Summarize the repository’s purpose in one tight paragraph.
• Describe the actual architecture, not a guessed ideal architecture.
• Capture exact setup, run, lint, typecheck, test, build, and deploy commands when they are discoverable.
• For monorepos, include the root plus each materially important package or app.
• Include the most important files and why they matter.
• Record risks, tech debt, and open unknowns explicitly.
• Use file paths as evidence anchors throughout.

4. Fill REVIEW_BRIEF.md

Use the bundled template and replace every placeholder.

Requirements:

• Translate the current task into a concise engineering brief.
• Capture in-scope and out-of-scope boundaries.
• List the relevant files, packages, and systems.
• Explain the current state with evidence.
• Identify gaps, risks, and unknowns.
• Propose a concrete implementation or review plan.
• Include an exact verification plan with commands.
• End with a ready-to-paste working prompt for the next agent or chat.

If there is no specific task from the user, make the brief about one of these, in priority order:

1. the most valuable missing capability,
2. the highest-risk weakness,
3. or the highest-leverage cleanup / hardening opportunity.

5. Validate before finishing

Before you stop, verify all of the following:

• Both files exist in the repository root.
• No placeholder markers remain.
• No section is silently omitted. Use Not found in repo or Unknown when necessary.
• Commands are copied exactly from the repo when possible, not invented.
• Claims about architecture, deployment, tests, or integrations are backed by file evidence.
• The writing is concise and decision-useful, not bloated.

Evidence rules

• Prefer repository files over assumptions.
• Prefer executable config over prose docs when they disagree.
• Prefer current manifests and CI definitions over stale README instructions.
• Treat generated code, vendored files, and build output as low-trust signals.
• If something cannot be confirmed, label it explicitly as Unknown or Not found in repo.

Writing rules

• Write for future engineers and future agents.
• Be specific. Name files, directories, commands, workflows, services, and boundaries.
• Keep summaries dense and useful.
• Do not dump giant file trees.
• Do not copy large blocks from README files.
• Do not hallucinate commands, environments, services, secrets, or deployment targets.
• Do not mark something as production-ready unless the repo evidence supports that claim.

Monorepo rules

When the repo contains multiple apps or packages:

• Describe the repo root separately from each important package or app.
• Distinguish shared libraries from deployable services.
• Record package-specific commands when they differ from root commands.
• Call out cross-package dependencies and ownership boundaries when they are inferable.

Missing-information rules

When evidence is incomplete:

• State exactly what was missing.
• State where you looked.
• State the consequence of the missing information.
• Suggest the fastest way to resolve the unknown.

Completion standard

This skill is complete only when a future agent could open the repo with just these two files and quickly understand:

• what the repo is,
• how it is structured,
• how to run and verify it,
• what matters most,
• and how to start the next task safely.

Invocation examples

Explicit invocation is the most reliable way to use this skill.

Example prompts:

• $repo-context-builder Analyze this repository and create REPO_CONTEXT.md plus REVIEW_BRIEF.md using the bundled templates.
• $repo-context-builder Refresh the existing REPO_CONTEXT.md and REVIEW_BRIEF.md after recent changes. Re-check commands, architecture notes, and risks.
• $repo-context-builder Analyze this repo and create a task-scoped REVIEW_BRIEF.md for the current authentication bug, plus refresh REPO_CONTEXT.md where needed.