orient

Files (1)

• SKILL.md

SKILL.md (first lines)

# Orient

Systematically explore a codebase and produce a structured orientation that
tells a developer everything they need to start working productively. Depth
scales with project size — small projects get a tight summary, large projects
get a layered map.

## Phase 1 — Project Identity

Establish what the project *is* before reading any source code.

### Read top-level files (in order of priority)

1. `README.md` / `README` — stated purpose, setup instructions, feature list
2. `AGENTS.md` — architecture boundaries, "always do / never do" rules
3. `.cursor/rules/` — workspace conventions for this project
4. Manifest file — `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
   `pom.xml`, `Gemfile`, `composer.json`, or equivalent
5. `CONTRIBUTING.md`, `ARCHITECTURE.md`, `docs/` index — if present

### Extract

- **One-sentence purpose**: What does this project do, for whom?
- **Domain**: What problem space does it operate in?
- **Stage**: Early build, growth, or mature/stable?
- **Key dependencies**: Frameworks, databases, external services

If the README is absent or unhelpful, infer purpose from the manifest
description field, directory names, and import patterns.

## Phase 2 — Shape

Map the physical layout without reading file contents yet.

```bash
# Get directory tree (depth 2–3 depending on project size)
find . -type f | head -200
# or
tree -L 3 -I 'node_modules|.git|dist|build|__pycache__|venv|.venv|target'
```

### Categorize top-level directories

| Role | Common names | What to look for |
|------|-------------|------------------|
| Source | `src/`, `lib/`, `app/`, `pkg/`, `internal/` | Production code |
| Tests | `test/`, `tests/`, `spec/`, `__tests__/` | Test suites |
| Config | Root dotfiles, `config/`, `.github/` | Build/CI/lint config |
| Docs | `docs/`, `doc/`, `wiki/` | Documentation |
| Infra | `infra/`, `deploy/`, `terraform/`, `k8s/`, `docker/` | Deployment |
| Scripts | `scripts/`, `bin/`, `tools/` | Automation helpers |
| Generated | `dist/`, `build/`, `out/`, `target/` | Build artifacts (skip) |

### Identify the tech stack

From manifest files and directory structure, determine:
- Language(s) and version constraints
- Framework(s) — web, CLI, library, monorepo tooling
- Database / storage layer
- Build system and package manager
- CI/CD platform (from `.github/workflows/`, `.gitlab-ci.yml`, etc.)

## Phase 3 — Architecture

Now read code — but strategically. The goal is to understand the skeleton, not
every function.

### Scaling strategy

| Project size | Approach |
|--------------|----------|
| **Small** (≤20 files) | Read every source file. Full picture is cheap. |
| **Medium** (21–100 files) | Read entry points + 3–5 core modules. Skim the rest by name/export. |
| **Large** (>100 files) | Read entry points, trace one request/command end-to-end, read the 5 highest-import-count modules. |

### Find entry points

Look for:
- `main.ts`, `index.ts`, `app.ts`, `server.ts` — web/API entry
- `main.py`, `app.py`, `__main__.py`, `manage.py` — Python entry
- `main.go`, `cmd/` — Go entry
- `src/main.rs`, `src/lib.rs` — Rust entry
- `bin/` scripts, CLI definitions
- `package.json` `"main"`, `"bin"`, `"exports"` fields
- Framework-specific: `pages/`, `app/` (Next.js), `routes/` (Express/Rails)

### Trace the skeleton

From entry points, follow the import graph to identify:
- **Core modules** — where the main logic lives
- **Data layer** — models, schemas, database access
- **API surface** — routes, handlers, controllers, exported functions
- **Shared utilities** — helpers used across modules
- **Configuration** — how settings flow into the system

Read 3–5 pivotal files fully to understand the primary abstraction patterns.

### Identify boundaries

- Monorepo packages / workspaces
- Service boundaries (if microservices)
- Plugin / extension points
- Public API vs internal implementation

## Phase 4 — Features and Functionality

Shift from code structure to user/consumer perspective.

### For applications (web, CLI, desktop)

Enumerate:
- User-facing features (routes, pages, commands)
- Authentication / authorization model
- Data inputs and outputs
- Background jobs, workers, scheduled tasks
- External integrations (APIs, webhooks, third-party services)

### For libraries / SDKs

From jcottam/agent-resources, MIT.

More from jcottam/agent-resources