codebase-context

Extract and summarize codebase context for planning purposes. This skill provides quick analysis approaches for different project types and standardized output formats.

Quick Analysis Approach

1. Detect Tech Stack

JavaScript/TypeScript Projects:

cat package.json 2>/dev/null | head -60

Identify from output:

• dependencies / devDependencies for frameworks
• scripts for build/test commands
• type: "module" for ESM

Python Projects:

cat pyproject.toml 2>/dev/null || cat requirements.txt 2>/dev/null | head -30

Go Projects:

cat go.mod 2>/dev/null | head -15

Rust Projects:

cat Cargo.toml 2>/dev/null | head -30

2. Map Project Structure

# Get directory tree (excluding noise)
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' -not -path '*/target/*' | sort | head -40

# Count files by type
find . -type f -name "*.ts" -o -name "*.tsx" | wc -l
find . -type f -name "*.py" | wc -l
find . -type f -name "*.go" | wc -l

3. Find Key Documentation

# Project docs
ls -la README* CLAUDE* AGENTS* CONTRIBUTING* 2>/dev/null

# Config files
ls -la *.json *.yaml *.toml .env* 2>/dev/null

4. Identify Patterns

API Structure:

# REST endpoints
grep -r "app\.\(get\|post\|put\|delete\)" --include="*.ts" --include="*.js" | head -10

Component Patterns:

# React components
find . -path '*/components/*' -name "*.tsx" | head -10

Database Models:

# Schema definitions
find . -name "schema*" -o -name "*model*" | grep -v node_modules | head -10

Output Format

Structure codebase context summaries as:

## Technology Stack

**Language:** [e.g., TypeScript 5.x]
**Runtime:** [e.g., Node.js 20, Bun 1.x]
**Framework:** [e.g., Next.js 14 (App Router), FastAPI]
**Database:** [e.g., PostgreSQL with Drizzle ORM]
**Styling:** [e.g., Tailwind CSS]
**Testing:** [e.g., Vitest, Playwright]

## Project Structure

- `src/` - Main source code
  - `components/` - React components
  - `lib/` - Utility functions
  - `app/` - Next.js app router pages
- `tests/` - Test files

## Key Patterns

- [Pattern 1: e.g., "Server components by default, client components marked explicitly"]
- [Pattern 2: e.g., "API routes use zod for validation"]
- [Pattern 3: e.g., "Error handling uses Result types"]

## Conventions

- Package manager: [pnpm/npm/yarn/bun]
- Code style: [ESLint + Prettier config]
- Commit style: [Conventional commits]
- Branch strategy: [main + feature branches]

## Existing Documentation

- README.md: [brief summary]
- CLAUDE.md: [if exists, key points]
- AGENTS.md: [if exists, key points]

Integration Notes

This context should be:

1. Saved to .shipspec/planning/<feature>/context.md temporarily during planning
2. Used by PRD and design document generation
3. Referenced when creating implementation tasks

Note: The context file is automatically cleaned up after task generation completes. The relevant context is incorporated into the PRD, SDD, and TASKS.md files.

Common Tech Stack Indicators

| Indicator | Technology | |-----------|------------| | next.config.js | Next.js | | vite.config.ts | Vite | | tailwind.config.js | Tailwind CSS | | drizzle.config.ts | Drizzle ORM | | prisma/schema.prisma | Prisma ORM | | pyproject.toml | Modern Python | | go.mod | Go modules | | Cargo.toml | Rust |

Quality Checklist

Before finalizing context extraction:

• [ ] Tech stack versions identified
• [ ] Project structure mapped
• [ ] Key patterns documented
• [ ] Existing documentation referenced
• [ ] Conventions noted