Repository Inspector

Safely maps an unfamiliar repository. Discovers the project structure, language, package manager, entry points, and test commands without modifying files.

1. Purpose

Provide a quick, accurate map of a repository so subsequent development skills know where to locate source code, configurations, and test runners.

2. When to Use

Use this skill when:

• Arriving in a new or unfamiliar codebase.
• User asks "What does this repo do?" or "How do I run this project?".
• Pre-flight step before diagnosing bugs or applying code changes.

3. When Not to Use

• Do not use to run deep code review or diff analysis; use diff-reviewer.
• Do not use to plan multi-step feature implementations; use task-brief.
• Do not use to diagnose a specific broken command; use command-failure-diagnoser.

4. Required Inputs

• workspace_root: The file path to the repository root directory (default: current working directory).

5. Missing-Input Behavior

1. If no workspace root is specified, use the current working directory.
2. If the directory does not exist or is empty, stop and report: "Error: Directory <path> is empty or does not exist."
3. Do not run commands in parent directories outside the workspace root.

6. Procedure

Follow these numbered actions:

1. Action 1: List Root Files and Directories
   • Check directory listing at top level. Look for manifest files: package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, Makefile.
2. Action 2: Identify Languages and Package Manager
   • Read the manifest file to identify runtime version, dependencies, scripts, and build tools.
   • Do not execute package installation or build scripts during inspection.
3. Action 3: Discover Key Entry Points
   • Search for main.*, index.*, src/index.*, cmd/, app/, or CLI binaries declared in manifest.
4. Action 4: Discover Test Setup
   • Check test script in manifest (npm test, pytest, cargo test, go test ./...).
   • Identify test directory (tests/, __tests__/, spec/, *_test.go).
5. Action 5: Safety and Secret Boundary Check
   • Verify that .env files, .git/, and secret credentials are NOT read into public output.
6. Action 6: Emit Repository Map
   • Format the findings using Section 8.

7. Decision Rules

• If multiple manifests exist (e.g. monorepo with root package.json and nested packages): record repository type as Monorepo and list top-level workspaces.
• If no manifest is found: inspect file extensions (.py, .sh, .c, .rs) to determine language.
• If documentation files exist (README.md, CONTRIBUTING.md): check quickstart command lines; do not read entire large files into context.

8. Output Format

Emit the repository overview using this structured template:

### Repository Map: [Project Name or Folder]

- **Primary Language / Stack**: [e.g., TypeScript / Node.js 22]
- **Package Manager / Build Tool**: [e.g., pnpm, npm, cargo, pip]
- **Architecture Style**: [Single package | Monorepo | CLI | Library | Web App]

#### Key Directories & Files
- `src/` - [Core source files]
- `tests/` - [Test suites]
- `config/` - [Configuration files]
- Entry point: `[path to entry file]`

#### Standard Commands
- **Install**: `[e.g., npm install]`
- **Build**: `[e.g., npm run build]`
- **Test**: `[e.g., npm test]`
- **Lint / Check**: `[e.g., npm run lint]`

#### Observations & Warnings
- [Notable findings, missing test configs, or special setup requirements]

9. Verification Checklist

• Root manifest was inspected without executing unverified code.
• Primary language, test command, and build command are verified from files.
• Entry point exists and was confirmed on disk.
• No secrets or personal data were captured in the output.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• The workspace contains no recognisable source code or build configuration.
• The directory contains encrypted files or requires proprietary credentials to inspect.

12. Examples

Example 1: Successful Execution

Input:

Inspect workspace: /workspace/sample-service
Files found: package.json, tsconfig.json, src/server.ts, src/routes.ts, tests/server.test.ts, README.md
package.json scripts: { "build": "tsc", "test": "vitest run", "start": "node dist/server.js" }

Expected Observable Actions:

1. Inspected package.json scripts and dependencies.
2. Verified entry point at src/server.ts.
3. Verified test runner is vitest run.

Output:

### Repository Map: sample-service

- **Primary Language / Stack**: TypeScript / Node.js
- **Package Manager / Build Tool**: npm / tsc
- **Architecture Style**: Web Service (Backend API)

#### Key Directories & Files
- `src/` - Application source code
- `src/server.ts` - Main HTTP server entry point
- `tests/` - Automated test suites
- `tsconfig.json` - TypeScript compiler configuration

#### Standard Commands
- **Install**: `npm install`
- **Build**: `npm run build`
- **Test**: `npm test`
- **Start**: `npm start`

#### Observations & Warnings
- Test command uses Vitest (`vitest run`).
- Output builds into `dist/`.

Example 2: Ambiguous or Failure Case

Input:

Inspect workspace: /workspace/empty-project (0 files present)

Output:

### Repository Map: Error - Empty Repository

- **Primary Language / Stack**: Unknown
- **Status**: Halted

The directory `/workspace/empty-project` is completely empty. No source files, manifests, or build scripts were found. Please clone the project repository or specify a populated workspace folder.

Example 3: Expected Final Output

Output:

### Repository Map: auth-gateway

- **Primary Language / Stack**: Python 3.11 / FastAPI
- **Package Manager / Build Tool**: Poetry (`pyproject.toml`)
- **Architecture Style**: REST Microservice

#### Key Directories & Files
- `auth_gateway/` - Main Python package
- `auth_gateway/main.py` - FastAPI app initialization
- `tests/` - Unit and integration tests using pytest
- `pyproject.toml` - Dependencies and tool settings

#### Standard Commands
- **Install**: `poetry install`
- **Build**: `poetry build`
- **Test**: `poetry run pytest`
- **Lint / Check**: `poetry run ruff check .`

#### Observations & Warnings
- Dockerfile present for container deployment.
- No local `.env` required if environment variables are provided.