Summarize

Summarize Skill

Overview

Analyze an entire codebase and produce two artifacts targeted at new developers:

1. CODEBASE_ARCHITECTURE.md — a detailed, Obsidian-ready architecture document covering structure, dependencies, data flow, API layer, configuration, and testing strategy.
2. QUICK_REFERENCE.md — a concise cheat sheet of commands, key files, patterns, and gotchas for day-to-day navigation.

Both files are written to the repository root where the user invoked /summarize.

---

Instructions

Phase 1 — Parallel Codebase Analysis

Use the Workflow tool to fan out nine parallel analysis agents. Each agent focuses on a single concern. Launch all nine simultaneously; do not wait for one before starting the next.

Assign each agent the following scopes:

Agent 1 — File Structure & Entry Points

• Map the top-level directory tree (depth ≤ 4).
• Identify primary entry points: main.*, index.*, app.*, server.*, cmd/, src/.
• Note any monorepo layout (packages/, apps/, libs/, services/, workspace files).
• Record build output directories (dist/, build/, out/, .next/, target/).

Agent 2 — Packages & Dependencies

• Parse all dependency manifests present in the repo:
  • JavaScript/TypeScript: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
  • Python: requirements.txt, pyproject.toml, Pipfile, setup.py, setup.cfg
  • Rust: Cargo.toml, Cargo.lock
  • Go: go.mod, go.sum
  • Ruby: Gemfile, Gemfile.lock
  • Java/Kotlin: pom.xml, build.gradle, build.gradle.kts
  • .NET: *.csproj, *.fsproj, packages.config
• Separate production dependencies from dev/test dependencies.
• Flag major framework versions (React, Next.js, Django, FastAPI, Rails, Spring, etc.).
• Note any workspace or multi-package configurations.

Agent 3 — CI/CD & Automation Workflows

• Locate all CI/CD configuration files:
  • GitHub Actions: .github/workflows/*.yml
  • GitLab CI: .gitlab-ci.yml
  • CircleCI: .circleci/config.yml
  • Bitbucket Pipelines: bitbucket-pipelines.yml
  • Jenkins: Jenkinsfile
  • Azure Pipelines: azure-pipelines.yml
  • Makefile, Taskfile, scripts/ directory
• Summarize each pipeline: trigger conditions, stages, environment targets, deployment steps.
• Note any secrets, environment variable references, or deployment targets.

Agent 4 — Navigation & Routing Patterns

• Detect and document routing strategies:
  • React Router: <Route>, createBrowserRouter, useNavigate
  • Next.js: pages/, app/ directory conventions, dynamic segments
  • Vue Router: router/index.*, routes array
  • Angular: RouterModule, Routes
  • SvelteKit: routes/ directory
  • Backend routers: Express router, FastAPI @app.route, Rails routes.rb, Django urls.py, Go mux, Spring @RequestMapping
• List all route definitions with their paths and associated components/handlers.
• Identify protected/authenticated routes and middleware applied.

Agent 5 — Core Modules & Their Responsibilities

• Enumerate the main source directories and modules under src/, lib/, app/, pkg/, internal/, core/, domain/, features/, or equivalent.
• For each module/directory, describe its single responsibility in one sentence.
• Identify shared utilities, helpers, and cross-cutting concerns.
• Note any architectural patterns: MVC, hexagonal, feature-sliced design, clean architecture, domain-driven design.

Agent 6 — Data Flow & State Management

• Identify state management solutions:
  • Frontend: Redux, Zustand, Jotai, Recoil, MobX, Pinia, NgRx, context API
  • Backend: in-memory store, database sessions, message queues
• Trace the primary data flow: where data enters (API call, form, event), how it is transformed, where it is persisted or displayed.
• Document any event bus, pub/sub, or observable patterns.
• Note database schemas or ORM models if source files are present.

Agent 7 — API Layer & Endpoints

• List all API endpoints defined in the codebase with method, path, and handler name.
• Identify the API style: REST, GraphQL, tRPC, gRPC, WebSocket, or mixed.
• Document authentication/authorization mechanisms: JWT, session cookies, OAuth, API keys, middleware guards.
• Note any external services or third-party APIs called (look for fetch/axios/httpx/requests calls to external URLs, SDK imports for AWS/GCP/Stripe/etc.).
• Check for OpenAPI/Swagger specs (openapi.yaml, swagger.json).

Agent 8 — Configuration & Environment Setup

• Identify all configuration files: .env.example, .env.local, config/, settings.*, appsettings.json, application.yml, Dockerfile, docker-compose*.yml, kubernetes/, helm/, .nvmrc, .tool-versions, Makefile.
• List required environment variables (from .env.example or documented references).
• Document how to run the project locally: install steps, dev server commands, seed/migrate commands.
• Note containerization and infrastructure-as-code if present.

Agent 9 — Testing Strategy

• Locate all test files and directories: __tests__/, *.test.*, *.spec.*, tests/, test/, spec/.
• Identify testing frameworks and tools: Jest, Vitest, Pytest, RSpec, JUnit, Go test, Playwright, Cypress, Testing Library, Storybook.
• Categorize test types present: unit, integration, end-to-end, contract, snapshot.
• Note test coverage configuration and any CI quality gates.
• Identify test fixtures, factories, and mock strategies.

---

Phase 2 — Synthesize CODEBASE_ARCHITECTURE.md

After all nine agents complete, synthesize their findings into a single cohesive document.

1. Read references/full-report-template.md to obtain the exact section structure and Obsidian formatting conventions to follow.
2. Populate every section of the template with concrete findings from the agents. Do not leave placeholder text; if a section is not applicable (e.g., no frontend routing in a pure backend service), write a one-line note explaining why.
3. Use Obsidian-compatible Markdown:
   • Wikilinks for cross-references between sections: [[Section Name]]
   • Callout blocks for warnings, tips, and important notes: > [!NOTE], > [!WARNING], > [!TIP]
   • Mermaid diagrams where they add clarity (architecture overview, data flow, entity relationships). Wrap in ```mermaid fences.
   • Dataview-compatible frontmatter tags for indexing.
4. Open the document with a YAML frontmatter block:

   ---
   tags: [architecture, codebase, onboarding]
   created: <today's date ISO 8601>
   project: <repo name inferred from package.json name, go.mod module, or directory name>
   ---
   

5. Write the final file to <repo-root>/CODEBASE_ARCHITECTURE.md.

---

Phase 3 — Synthesize QUICK_REFERENCE.md

1. Read references/quick-reference-template.md to obtain the exact layout.
2. Distill the most actionable information from all agents into the cheat sheet:
   • The five most important commands to know (install, dev, test, build, lint/format).
   • The ten most important files/directories to know.
   • Key environment variables required to run the project.
   • The routing or navigation mental model in three bullet points or fewer.
   • Common gotchas or non-obvious setup steps discovered during analysis.
3. Keep the document scannable: use tables, code fences, and short bullet lists. Aim for a document a developer can read end-to-end in under five minutes.
4. Write the final file to <repo-root>/QUICK_REFERENCE.md.

---

Phase 4 — Confirm Output

After writing both files, report to the user:

• The absolute paths of the two files written.
• A three-sentence summary of what the codebase does, its primary tech stack, and the single most important architectural decision to be aware of.
• Any sections that could not be fully populated (e.g., no test files found, no routing layer detected) so the user can fill them in manually.

---

Tech Stack Handling Notes

Monorepo

When the repo uses a workspace tool (npm workspaces, pnpm workspaces, Turborepo, Nx, Lerna, Bazel), Agent 1 must document each package/app separately. In CODEBASE_ARCHITECTURE.md, dedicate a subsection per package under "Core Modules". The Mermaid diagram should show inter-package dependency edges.

Microservices

When the repo contains multiple services (distinct Dockerfile per subdirectory, multiple main.* entry points, or a services/ top-level directory), treat each service as a module in Agent 5. In CODEBASE_ARCHITECTURE.md, add a "Service Map" section with a Mermaid diagram showing service-to-service communication and shared infrastructure.

Frontend-Only (SPA / SSG)

Skip Agent 7's backend endpoint enumeration. Focus Agent 6 on client-side state and data fetching (React Query, SWR, Apollo Client). Note the BFF or external API base URL from environment configuration.

Backend-Only (API / CLI / Worker)

Skip Agent 4's frontend routing section. Focus Agent 7 on exhaustive endpoint listing. If a CLI tool, document the command tree (cobra, click, argparse) in place of routes.

Fullstack (Next.js, Nuxt, SvelteKit, Remix, Rails, Django)

Agent 4 and Agent 7 overlap for framework-native routing. Document file-based routes once under routing, and note which routes are API routes versus page routes.

Mobile (React Native, Flutter, Kotlin, Swift)

Replace Agent 4's web routing with navigation library patterns (React Navigation, Flutter Navigator 2.0, Android NavGraph, iOS UINavigationController). Agent 8 should cover platform-specific build steps (Xcode schemes, Gradle variants, eas.json).

---

File Reference

File	Purpose
references/full-report-template.md	Section structure for CODEBASE_ARCHITECTURE.md
references/quick-reference-template.md	Layout for QUICK_REFERENCE.md
CODEBASE_ARCHITECTURE.md	Generated — written to repo root
QUICK_REFERENCE.md	Generated — written to repo root

Templates in references/ define structure; this skill populates content. Do not modify the templates during skill execution.