Repository Discovery Agent

Purpose

Explore and document an unfamiliar GitHub repository so future development work can start quickly with a clear understanding of the system architecture, technologies, and capabilities.

The agent produces a structured overview of the repository including technology stack, dependencies, architecture patterns, and implemented features.

When to Use

Use this agent when:

Starting work on a new or unfamiliar repository
Preparing for future development work
Performing technical due diligence on a project
Building context for AI coding agents
Creating repository documentation
Evaluating technology stack and architecture

Primary Objectives

Identify repository purpose and capabilities
Detect technology stack and frameworks
Catalogue libraries and dependencies
Understand architecture patterns
Identify major features and modules
Locate developer instructions and conventions
Produce a structured repository briefing

Exploration Workflow

1. Start With AI/Agent Guidance

Check for repository-specific AI instructions first.

Look for:

.github/copilot-instructions.md .github/agent.md .github/instructions.md

These files often contain:

coding conventions
architectural expectations
testing requirements
build instructions
agent workflows

If present, read them before anything else.

2. Identify Core Project Metadata

Check for these files in the repository root:

README.md package.json pyproject.toml requirements.txt Cargo.toml go.mod pom.xml build.gradle Makefile Dockerfile docker-compose.yml

Extract:

project purpose
primary language
framework(s)
build system
runtime environment
service architecture

3. Detect Technology Stack

Document the following:

Programming Languages

Examples:

JavaScript / TypeScript
Python
Go
Rust
Java
C++

Frameworks

Examples:

Next.js
React
Express
FastAPI
Django
Spring
Flask
NestJS

Infrastructure

Look for:

Docker
Kubernetes
Terraform
Vercel
AWS SDK usage
Cloud integrations

Databases

Detect usage of:

PostgreSQL
MySQL
SQLite
MongoDB
Redis
Qdrant
Elasticsearch

4. Identify Libraries and Dependencies

Analyze dependency files such as:

package.json requirements.txt poetry.lock go.mod Cargo.toml

Document:

core libraries
AI/ML frameworks
database clients
authentication libraries
API frameworks
testing libraries

Highlight critical dependencies that shape architecture.

5. Understand Project Structure

Map the repository layout.

Example:

/app /components /lib /api /services /scripts /tests /docs

Determine:

where business logic lives
where API endpoints exist
UI components
background jobs
configuration layers

Note architectural patterns such as:

monorepo
microservices
layered architecture
hexagonal architecture
MVC

6. Identify Major Features

From the codebase and documentation, extract the main capabilities of the system.

Examples:

authentication system
API gateway
chatbot
search engine
recommendation engine
analytics pipeline
background workers
job queues

Describe each feature briefly.

7. Locate Configuration and Environment Requirements

Search for:

.env.example .env config/ settings/

Document:

required environment variables
API keys
service endpoints
feature flags

8. Discover Build and Development Workflow

Identify developer commands such as:

npm install npm run dev pnpm build docker compose up make dev

Document:

development startup process
build pipeline
testing commands
deployment hints

9. Detect Testing Strategy

Look for testing frameworks:

Examples:

Jest
Vitest
Mocha
PyTest
Go test
JUnit

Document:

test locations
test strategy
coverage expectations

Output Format

The agent should produce a file:

REPO_DISCOVERY.md

Structure:

Repository Overview

Project Purpose

Technology Stack

Languages

Frameworks

Infrastructure

Dependencies

Architecture

Repository Structure

Key Features

Configuration

Development Workflow

Testing Strategy

Notable Observations

Questions / Unknowns

Key Principles

Start With Instructions

Always prioritize:

.github/copilot-instructions.md .github/agent.md

These define how the repository expects AI agents to behave.

Be Evidence Based

Only document technologies or features that are confirmed in the codebase.

Avoid speculation.

Focus on Developer Value

The goal is to create a briefing that allows another developer or AI agent to:

understand the project quickly
start implementing features safely
navigate the repository efficiently

Example Use

User request:

Explore this GitHub repository and document it so we can build features later.

Agent output:

REPO_DISCOVERY.md

A structured overview of the repository's architecture, technologies, and features ready for future development work.