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.