Repository Discovery and Initial Scan Prompt Template

This prompt is for an AI coding agent or a developer-assisted workflow that has just been pointed at a new, unfamiliar repository. The job-to-be-done is to produce a structured, high-confidence inventory of the repository's top-level anatomy—directories, build manifests, configuration files, and primary entry points—before any code is modified or any deeper analysis is attempted. The ideal user is an AI engineer integrating a coding agent into a CI/CD pipeline, a developer onboarding tool, or an automated code review system. The reader needs the agent to build a reliable mental model of the project structure without hallucinating files, misclassifying generated code as source, or missing critical configuration that controls builds, deployments, or security posture.

Use this prompt when the agent has read access to the repository root but no prior context about the project's language, framework, build system, or monorepo layout. It is designed for the initial cold-start scan: the moment after git clone and before any task-specific reasoning. The prompt expects the agent to traverse the top-level directory tree, identify standard signals (e.g., package.json, Makefile, Dockerfile, .github/workflows/, src/, tests/), and report findings in a structured schema. Do not use this prompt for deep semantic analysis, dependency graph construction, or security vulnerability scanning—those are downstream tasks that depend on the inventory this prompt produces. Do not use it when the repository is already indexed by a language server or when a compile_commands.json or LSP workspace is available; in those cases, a symbol-indexing or build-system-specific prompt is more appropriate.

The prompt includes explicit constraints to prevent common failure modes: it instructs the agent to ignore .git/, node_modules/, vendor/, and other dependency directories; to flag when a critical file is missing rather than inventing one; and to report confidence levels for each finding. Before wiring this into an automated pipeline, you must pair it with a validation harness that cross-references the agent's output against a manual ls -la or tree listing of the repository root. If the agent misses a Dockerfile or misidentifies a src/ directory as application code when it contains only generated protobuf stubs, the harness should flag the output for human review. For repositories with compliance or security sensitivity, require a human to confirm the inventory before any subsequent edit or analysis prompt is executed.

This prompt template is the core instruction set for an AI coding agent to perform an initial, read-only discovery scan on an unfamiliar repository. It is designed to be dropped into an agent harness that has already mounted the repository filesystem and has access to standard discovery tools like ls, cat, grep, and git. The prompt forces the agent to produce a structured JSON output, which your application can then parse, validate, and use to populate a context map for subsequent agent tasks.

markdownCopy
You are a senior software engineer performing an initial discovery scan on an unfamiliar repository. Your goal is to produce a structured, high-confidence inventory of the codebase. You have access to the filesystem at the root path [REPO_PATH]. You may use standard Unix tools to explore, but you must not modify any files.

First, explore the top-level directory structure. Then, identify and read key configuration files. Finally, trace the build system and entry points.

Your final output must be a single JSON object conforming to this schema:
{
  "repository_name": "string",
  "primary_language": "string | null",
  "build_system": "string | null",
  "package_manager": "string | null",
  "top_level_dirs": [
    {
      "name": "string",
      "inferred_purpose": "string",
      "confidence": "high | medium | low"
    }
  ],
  "key_config_files": [
    {
      "path": "string",
      "purpose": "string"
    }
  ],
  "entry_points": [
    {
      "path": "string",
      "type": "main | server | cli | route_registration | other",
      "confidence": "high | medium | low"
    }
  ],
  "test_directories": ["string"],
  "ignored_paths": ["string"],
  "summary": "A dense, 3-5 sentence summary of the repository's purpose, tech stack, and architecture."
}

Constraints:
- [CONSTRAINTS]: Only use read-only commands. Do not run builds, install dependencies, or execute any code. If a directory is too large to fully scan, note it in `ignored_paths` with a reason. Prioritize accuracy over speed.
- If you cannot determine a field with high confidence, set its value to `null` or an empty array and lower the confidence rating.

To adapt this template, replace the [REPO_PATH] placeholder with the actual mounted path in your agent's execution environment. The [CONSTRAINTS] block is a hook for you to inject environment-specific rules, such as a list of directories to skip entirely, a maximum scan depth, or a token budget for the final summary. After the agent runs, your harness must validate the output JSON against the schema. A critical next step is to run a manual or automated evaluation: compare the agent's top_level_dirs and entry_points against a known-good listing to measure recall and precision. If the agent misses a critical path like a hidden .github directory or a non-standard build file, add that as a negative example to your evaluation set and consider refining the prompt's exploration instructions.

This prompt is designed as the first step in an agent's orientation sequence. Wire it as a synchronous preflight call before any file modification, test execution, or dependency installation is permitted. The agent should invoke this prompt immediately after confirming it has a valid working directory and read access. The output is a structured inventory that downstream prompts—entry-point detection, build system identification, test runner discovery—consume as their [CONTEXT] block. Treat the discovery output as a snapshot, not a live index; re-run it when the agent changes branches, pulls new commits, or after any scaffold or dependency generation step that alters the top-level repository shape.

Validation is mandatory before the agent acts on the discovery output. Implement a post-processing validator that checks: (1) every returned directory path exists on disk, (2) key config files like package.json, pyproject.toml, Cargo.toml, or Makefile are present in the output if they exist in the repository root, (3) the entry-points array is non-empty for application repositories, and (4) no generated or vendor directories (node_modules, pycache, .venv, vendor/, dist/) appear in the top-level directory listing unless explicitly requested. If validation fails, retry the prompt once with an explicit [CONSTRAINTS] amendment that lists the missing or invalid items. If the second attempt also fails, log the discrepancy, surface it to the operator, and block downstream agent actions until resolved. For high-risk repositories—those containing deployment configs, database migrations, or infrastructure-as-code—require human confirmation of the discovery output before the agent proceeds to any mutating operation.

Model choice matters here. Use a model with strong instruction-following and structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature to 0 or near-zero to maximize consistency across runs. The prompt expects a JSON output schema; enforce it with structured output mode or a JSON mode toggle if available. If your harness uses a model that does not support strict JSON mode, wrap the call in a retry loop with a schema validator and a repair prompt that feeds parse errors back to the model. Log the full prompt, raw response, parse errors, and validation results to your observability pipeline. This trace is invaluable when debugging why an agent misidentified a monorepo layout or missed a critical entry point. Do not cache discovery results across sessions unless you also cache the git commit SHA and re-validate on cache hit.