Repo Context Builder

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.

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

2. Runtime and entrypoints:

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

3. Quality and test signals:

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

4. Architecture signals:

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

5. Operational signals when available:

• deployment workflows
• observability setup
• release or environment docs

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

REPO_CONTEXT

<!-- Fill this document from repository evidence. Replace every placeholder. If a section cannot be completed, write Not found in repo or Unknown. Use file paths as evidence anchors throughout. -->

1. Repository identity

• Repository:
• Primary purpose:
• Repository type: single app | service | library | monorepo | infra | mixed
• Primary languages:
• Primary frameworks / platforms:
• Primary deployment target:
• Default / main branch:
• Root path analyzed:
• Last analyzed:
• Analyzer:

2. One-paragraph summary

Write a tight paragraph explaining what the repository does, who or what it serves, and the main technical shape of the codebase.

3. Top-level layout

4. Main runtime surfaces and entrypoints

Examples of surfaces:

• web app
• API server
• worker
• CLI
• scheduler / cron job
• shared package with no runtime surface

5. Architecture summary

5.1 Main components

Summarize the important apps, services, packages, layers, or modules.

5.2 Request, job, and data flow

Describe the real flow through the system. Prefer simple prose over diagrams unless the repo already contains a canonical diagram.

5.3 Boundaries and coupling

Note important boundaries, shared libraries, internal APIs, and places where coupling is high.

5.4 External systems and integrations

6. Data, state, and contracts

Add or remove rows based on the repo.

7. Build, run, and verification workflow

7.1 Prerequisites

List the actual prerequisites discovered in the repo.

7.2 Install / sync

~~~bash

exact commands from repo, if found

~~~

7.3 Run locally

~~~bash

exact commands from repo, if found

~~~

7.4 Lint / format / typecheck / test

~~~bash

exact commands from repo, if found

~~~

7.5 Build / package

~~~bash

exact commands from repo, if found

~~~

7.6 Deploy / release

~~~bash

exact commands from repo, if found

~~~

8. Configuration and secrets

9. Testing and quality signals

Adapt rows to the repo.

10. Infrastructure, CI/CD, and operations

10.1 Infrastructure / platform summary

10.2 CI / automation summary

10.3 Observability, logging, and runtime support

10.4 Release / deployment risks

11. Important files to read first

Keep this list short and high-signal.

12. Current pain points, tech debt, and risks

- - -

13. Change guidance for future agents

List implementation constraints, preferred patterns, and important do-not-break expectations that future work should respect.

- - -

14. Open questions and unknowns

15. Evidence log

List the highest-value files that informed this document.

- - -

REVIEW_BRIEF

<!-- Fill this document from the current user request plus repository evidence. If the user did not specify a task, infer the highest-value next task and state that it was inferred. Replace every placeholder. -->

1. Task identity

• Task / feature / problem:
• Desired outcome:
• Status: new | in progress | refresh | inferred from repo
• Priority / urgency:
• Repo / package / area:
• Related issue / PR / branch:
• Prepared on:
• Prepared by:

2. User request or inferred brief

Paste or paraphrase the request concisely. If inferred, say so explicitly.

3. Scope definition

In scope

- -

Out of scope

- -

Assumptions

- -

Constraints

- -

Non-goals

- -

4. Relevant repository context

Key components and systems involved

- -

Relevant files and directories

Existing patterns to follow

Describe the implementation patterns, abstractions, conventions, or workflows already present in the repo that should be followed for this task.

5. Current-state findings

6. Gaps, risks, and unknowns

7. Recommended plan

7.1 Implementation or review sequence

1. 2. 3.

7.2 Design decisions

7.3 Files likely to change

8. Verification plan

Automated checks

~~~bash

exact commands from repo, if found

~~~

Manual / exploratory checks

- -

Rollback or safety checks

- -

9. Deliverables expected from the next working session

• code changes:
• tests:
• docs:
• infra / config:
• PR / handoff notes:

10. Ready-to-paste working prompt for the next session

~~~text Use the attached REPO_CONTEXT.md and REVIEW_BRIEF.md as the source of truth for this repository and task. Re-read the relevant files referenced in both documents before changing code. Then execute the plan in REVIEW_BRIEF.md, keep changes scoped, follow existing repo conventions, update docs/tests as needed, and verify the work with the exact commands listed in the brief before finishing. ~~~

11. Handoff notes

Capture anything a future agent or engineer should know before starting.

- -

Output checklist

Use this checklist before finalizing REPO_CONTEXT.md and REVIEW_BRIEF.md.

Required checks

• Every section in both templates is filled.
• No placeholder text remains.
• Unknowns are labeled explicitly as Unknown or Not found in repo.
• Commands are exact and executable-looking.
• Key claims cite concrete file paths.
• Risks are specific, not generic.
• Monorepo outputs distinguish root concerns from package concerns.
• The brief includes a ready-to-paste working prompt for the next session.

Quality bar for REPO_CONTEXT.md

REPO_CONTEXT.md should answer these questions quickly:

1. What is this repository for? 2. What are the main apps, services, packages, or modules? 3. How do I run, lint, typecheck, test, build, and deploy it? 4. What files should I read first? 5. What risks or unknowns matter right now?

Quality bar for REVIEW_BRIEF.md

REVIEW_BRIEF.md should answer these questions quickly:

1. What is the task? 2. What is in scope and out of scope? 3. Which files and systems matter? 4. What does the repo already do today? 5. What is the recommended next plan? 6. How do I verify the work safely? 7. What prompt should I use next?

Compression rule

Be concise, but not shallow.

Good:

• short tables
• one-paragraph summaries
• explicit file paths
• exact commands
• bullets with decisions and risks

Bad:

• generic narrative
• repeated wording across sections
• giant code excerpts
• giant file trees
• vague advice like "review the backend" or "run tests"

Repo analysis playbook

Use this playbook to gather evidence efficiently and avoid generic repo summaries.

1. Source priority

Trust signals in this order:

1. Executable configuration and code

• manifests
• lockfiles
• CI workflows
• deployment config
• container config
• infra definitions
• entrypoint code

2. Tests and test configuration 3. Repository docs such as README*, docs/, ADRs, specs, runbooks 4. Recent git history and change hotspots 5. Generated artifacts, vendored code, build output, coverage output

If prose and code disagree, prefer the executable source of truth and note the mismatch.

2. Fast scan order

Root-level must-read files

Read what exists:

• README*
• AGENTS.md
• .env.example, .env.sample, sample.env
• manifest files such as pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml
• lockfiles such as uv.lock, package-lock.json, pnpm-lock.yaml, bun.lock, poetry.lock, Cargo.lock
• CI and automation such as .github/workflows/*, Makefile, justfile, Taskfile.yml
• deployment and infra such as Dockerfile*, compose*.yml, vercel.json, fly.toml, render.yaml, serverless.yml, *.tf, template.yaml, cdk.json

Runtime and architecture files

Look for:

• API and web entrypoints
• CLI entrypoints
• job / worker / scheduler entrypoints
• config loaders
• dependency injection, app factory, or bootstrap code
• routing layers
• service boundaries
• domain models, schemas, migrations, queues, adapters

Quality signals

Look for:

• lint config
• typecheck config
• format config
• test config
• representative tests
• pre-commit hooks or similar enforcement

3. Repo type heuristics

Python repo

Prioritize:

• pyproject.toml
• uv.lock, poetry.lock, requirements*.txt
• src/, package dirs, app entrypoints
• pytest config and tests
• ASGI / WSGI / FastAPI / Django / Flask entrypoints

JavaScript / TypeScript repo

Prioritize:

• package.json
• workspace config such as pnpm-workspace.yaml, turbo.json, nx.json
• build config such as next.config.*, vite.config.*, tsconfig*.json
• apps/, packages/, src/
• scripts in package.json

Monorepo

Prioritize:

• root workspace config
• root CI and deployment config
• each deployable app or service
• shared packages used by more than one app
• package-specific run and test commands

4. What to extract for REPO_CONTEXT.md

Always extract these when available:

• repository purpose and product / service role
• main deployable surfaces
• important packages / apps / services
• architecture boundaries and data flows
• local setup and execution commands
• lint / typecheck / test / build commands
• deployment targets and release workflow
• environment and secrets conventions
• integrations and external systems
• operational signals such as logging, metrics, alerts
• important files and directories to read first
• current risks, debt, and unknowns

5. What to extract for REVIEW_BRIEF.md

Always extract these when available:

• the current ask or best inferred next task
• affected code areas and systems
• existing implementation pattern to follow
• current-state findings with evidence
• constraints, assumptions, and non-goals
• concrete plan and file touch list
• verification commands and manual checks
• unresolved questions that block safe implementation

6. Evidence anchor style

Use file paths inline. Good examples:

• pyproject.toml
• .github/workflows/ci.yml
• apps/web/package.json
• src/api/main.py
• infra/prod/template.yaml

Prefer path-based evidence over vague phrases like "the config" or "the backend".

7. Anti-patterns to avoid

Do not:

• dump the entire tree
• rewrite the README into a new README
• infer architecture from folder names alone
• claim test coverage or deployment health without evidence
• assume a repo is production-ready because deployment files exist
• silently omit missing sections
• invent environment variables, secrets, commands, or ownership

8. Good default when the user did not specify a task

When no specific task is given, choose the most valuable review brief by ranking these:

1. broken or missing verification pipeline 2. unclear or fragile deployment path 3. large architecture risk or cross-cutting debt 4. missing docs that block future work 5. highest-leverage next feature clearly implied by the repo

State that the brief is inferred from repository evidence.