Codebase Recon
Map dependencies, layers, and circular-deps risk before you refactor, onboard, or review an unfamiliar repo.
Overview
Codebase recon is an agent skill most often used in Build (also Ship review and Idea research) that structures dependency mapping, layer detection, and circular-dependency analysis before you change an unfamiliar system.
Install
npx skills add https://github.com/outfitter-dev/agents --skill codebase-reconWhat is this skill?
- Forward and reverse dependency mapping (imports, interfaces, runtime, and data deps)
- Circular dependency detection with resolution strategies (extract module, invert deps, split components)
- Layer identification for three-tier and hexagonal/clean-style boundaries
- Explicit red flags for implicit cycles through shared state and event subscribers
Adoption & trust: 1 installs on skills.sh; 26 GitHub stars; 2/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You are about to refactor or ship a fix but do not know what imports what, which layers exist, or where hidden cycles will break the build.
Who is it for?
Onboarding to a legacy or forked repo, planning extractions, or pre-review orientation when git history alone is not enough structure.
Skip if: Greenfield projects with a handful of files where informal reading is faster than a formal recon pass.
When should I use this skill?
You need structured architecture and dependency analysis on an existing codebase before implementing, refactoring, or reviewing changes.
What do I get? / Deliverables
You get a dependency and layer map with circular-dep red flags and resolution options so the next implementation or review step targets the right seams.
- Dependency and layer narrative for the scoped codebase
- Circular dependency red flags and suggested resolution approaches
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
First appears in Build when you need a structured mental model of the system before meaningful implementation or refactor work. Architecture recon is project understanding and scope navigation—PM-style orientation inside the codebase, not shipping a UI feature.
Where it fits
Before sprint planning, map which services own billing versus auth so tasks do not collide.
Trace reverse dependents on a repository module before changing its public interface.
Assess whether a PR introduces a new import cycle between UI and data layers.
Evaluate an acquired repo’s layering to estimate integration cost.
How it compares
Use as a structured recon playbook for your agent—not a substitute for dedicated static-analysis CLIs or architecture-as-code diagrams.
Common Questions / FAQ
Who is codebase-recon for?
Solo and indie developers using coding agents to understand SaaS, API, or CLI repos they did not originally author.
When should I use codebase-recon?
In Build before large refactors, in Ship during review when assessing blast radius, and in Idea/competitors-style research when evaluating a forked or acquired codebase’s structure.
Is codebase-recon safe to install?
It is documentation-style analysis guidance; review the Security Audits panel on this page and limit agent filesystem/git scope to repos you own.
SKILL.md
READMESKILL.md - Codebase Recon
# Architecture Analysis Techniques for analyzing system structure, dependencies, and component relationships. ## Dependency Mapping ### Forward Dependencies What a component relies on: 1. **Direct imports** — explicit dependencies in code 2. **Indirect references** — called through interfaces 3. **Runtime dependencies** — configuration, environment 4. **Data dependencies** — shared state, databases ### Reverse Dependencies What relies on this component: 1. **Direct dependents** — explicit imports from other modules 2. **Interface consumers** — components using this API 3. **Side effect consumers** — code relying on mutations 4. **Event subscribers** — listeners for this component's events ### Circular Dependencies Red flags: - A imports B, B imports A - Longer cycles: A → B → C → A - Implicit cycles through shared state Resolution strategies: - Extract shared code to separate module - Introduce interface/abstraction layer - Invert dependency direction - Break into smaller components ## Layer Identification ### Detecting Layers Look for: - **Directional flow** — data/control flows one way - **Abstraction levels** — concrete → abstract as you ascend - **Responsibility clustering** — similar concerns grouped - **Interface boundaries** — clear contracts between groups ### Common Layer Patterns **Three-tier**: - Presentation (UI, API endpoints) - Business logic (domain, workflows) - Data access (repositories, queries) **Hexagonal/Clean**: - Core domain (entities, business rules) - Application layer (use cases, orchestration) - Infrastructure (frameworks, external services) - Interfaces (controllers, adapters) **Microservices**: - Service boundary (API gateway) - Service logic (domain per service) - Data layer (per-service database) - Cross-cutting (auth, logging, monitoring) ### Layer Violations Violations indicate architectural drift: - Lower layer imports higher layer - Business logic in presentation layer - Data access code in domain entities - Infrastructure concerns leaking into core ## Interface Analysis ### Contract Definition Examine: - **Input types** — what does it accept? - **Output types** — what does it return? - **Error modes** — what can fail, how? - **Side effects** — mutations, I/O, state changes - **Invariants** — what must always be true? ### API Quality Strong interfaces show: - **Cohesion** — methods belong together - **Minimal surface** — small, focused API - **Clear contracts** — types tell the story - **Stability** — changes don't cascade - **Composability** — works well with others Weak interfaces show: - **Kitchen sink** — unrelated methods bundled - **Leaky abstractions** — implementation details exposed - **Unstable** — frequent breaking changes - **Rigid** — hard to extend or compose ## Component Relationships ### Relationship Types **Composition**: - Component owns sub-components - Lifecycles coupled - Strong cohesion - Example: `Page` owns `Header`, `Footer` **Aggregation**: - Component references others - Independent lifecycles - Loose coupling - Example: `ShoppingCart` references `Product` **Dependency**: - Uses another component's interface - No ownership - Can be swapped - Example: `AuthService` uses `Database` **Association**: - Knows about but doesn't own - Weak relationship - Often bidirectional - Example: `User` ↔ `Post` (many-to-many) ### Coupling Analysis **Low coupling** (good): - Communicate through interfaces - Few shared assumptions - Changes localized - Easy to test in isolation **High coupling** (risky): - Direct field access - Shared mutable state - Knowledge of implementation - Changes ripple widely ## Architectural Pattern Recognition ### Layered Architecture Indicators: - Unidirectional dependencies (top → bottom) - Each layer uses only layer below - Clear separation of concerns Trade-offs: - ✓ Simple, well-understood - ✓ Easy to enforce rules - ✗ Can become rigid - ✗ Performance overhead ### Event-Driven Architecture Indicators: - Pub/sub or