Init Project

---
name: init-project
description: Scan a new or unfamiliar repo and generate AGENTS.md with stack, commands, structure, and agent context.
allowed-tools: Glob Read Grep Write
effort: medium
---

# init-project

Scan the current project and detect its full tech stack, then generate an `AGENTS.md` file with structured context so future Claude agents have everything they need to work effectively in this codebase.

## Steps

### 1. Scan for stack indicators

Search the project root and subdirectories for the following files and patterns. Use Glob and Read tools — do not guess.

**Languages & runtimes**
- `package.json` → JavaScript / TypeScript packages; infer Node.js only from runtime markers (`engines.node`, `.nvmrc`, `.node-version`) or server/tooling entry points.
- `tsconfig.json` → TypeScript
- `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`, `.python-version`, `uv.lock`, `poetry.lock`, `Pipfile.lock` → Python
- `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml` → Rust
- `go.mod` → Go
- `pom.xml`, `build.gradle`, `build.gradle.kts` → Java / Kotlin
- `*.csproj`, `*.sln` → C# / .NET
- `Gemfile` → Ruby
- `composer.json`, `composer.lock`, `phpunit.xml`, `phpunit.xml.dist` → PHP
- `pubspec.yaml` → Dart / Flutter

**Frameworks**
- In `package.json` dependencies/devDependencies: look for `next`, `react`, `vite`, `@angular/core`, `vue`, `svelte`, `express`, `fastify`, `hono`, `remix`, `astro`, `nuxt`, `gatsby`
- In `composer.json` dependencies: look for `laravel/framework` and other declared PHP frameworks.
- In Python files: look for `django`, `flask`, `fastapi`, `sqlalchemy`
- In `Cargo.toml`: look for `axum`, `actix-web`, `rocket`
- In `go.mod`: look for `gin`, `echo`, `fiber`

**Databases & ORMs**
- In dependency files: look for `prisma`, `drizzle-orm`, `typeorm`, `sequelize`, `mongoose`, `pg`, `mysql2`, `sqlite3`, `redis`, `supabase`, `@planetscale`, `@neon`
- Config files: `prisma/schema.prisma`, `drizzle.config.*`

**Styling**
- `tailwind.config.*` → Tailwind CSS
- In `package.json`: `styled-components`, `@emotion`, `sass`, `less`, `@mui`, `@chakra-ui`, `@radix-ui`, `shadcn`

**Build tools & bundlers**
- `vite.config.*` → Vite
- `webpack.config.*` → Webpack
- `turbo.json` → Turborepo
- `nx.json` → Nx
- `rollup.config.*` → Rollup
- `.swcrc` → SWC

**Testing**
- In `package.json`: `jest`, `vitest`, `@testing-library`, `playwright`, `cypress`, `mocha`
- `pytest.ini`, `conftest.py` → pytest
- `jest.config.*`, `vitest.config.*`

**Infrastructure & deployment**
- `Dockerfile`, `docker-compose.*` → Docker
- `.github/workflows/` → GitHub Actions
- `vercel.json`, `.vercel/` → Vercel
- `netlify.toml` → Netlify
- `fly.toml` → Fly.io
- `terraform/`, `*.tf` → Terraform
- `kubernetes/`, `k8s/`, `*.yaml` with `kind: Deployment` → Kubernetes

**Monorepo**
- `pnpm-workspace.yaml` → pnpm workspaces
- `turbo.json` → Turborepo
- `nx.json` → Nx
- `lerna.json` → Lerna
- `packages/`, `apps/` directories → likely monorepo

**Package manager**
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → Yarn
- `bun.lock`, `bun.lockb` → Bun
- `package-lock.json` → npm
- `poetry.lock`, `uv.lock`, `Pipfile.lock` → Python dependency manager/lock
- `composer.lock` → Composer exact PHP package versions
- `Cargo.lock` → Cargo exact Rust dependency versions

**Environment & config**
- `.env`, `.env.example`, `.env.local` → environment variables (list keys only, never values)
- `*.config.ts`, `*.config.js` at root

### 2. Read key files in full

After identifying which files exist, read:
- `package.json` (full)
- `tsconfig.json` (full)
- `prisma/schema.prisma` or `drizzle.config.*` if present
- `README.md` if present (first 80 lines)
- `.env.example` if present (keys only)

For detected ecosystems, inspect relevant lockfile entries to report resolved dependency versions; do not print or read huge lockfiles wholesale when targeted search will do. Runtime versions may instead come from toolchain files, `engines`, CI, or deployment config.

### 3. Infer project type

Based on findings, classify the project as one or more of:
- `web-app` (frontend UI)
- `api` (backend/REST/GraphQL)
- `fullstack` (frontend + backend in same repo)
- `cli` (command-line tool)
- `library` (npm/pip/cargo package)
- `mobile` (React Native, Flutter, Expo)
- `monorepo` (multiple apps/packages)
- `infrastructure` (IaC, DevOps-only)

### 4. Generate AGENTS.md

Create `AGENTS.md` at the project root with the following structure. Be specific — list actual package versions from dependency files, not guesses. If something is uncertain, omit it rather than guess.

```markdown
# Project Context

## Project Type
<!-- e.g., fullstack web-app, monorepo -->

## Stack

### Language & Runtime
<!-- e.g., TypeScript 5.4, Node.js 20 -->

### Framework
<!-- e.g., Next.js 14 (App Router) -->

### Styling
<!-- e.g., Tailwind CSS 3.4, shadcn/ui -->

### Database & ORM
<!-- e.g., PostgreSQL via Prisma 5.x -->

### Testing
<!-- e.g., Vitest, Playwright for E2E -->

### Build & Tooling
<!-- e.g., Vite, Turborepo, pnpm workspaces -->

### Deployment
<!-- e.g., Vercel (frontend), Docker (API) -->

## Project Structure
<!-- Brief description of top-level directories and their purpose -->

## Environment Variables
<!-- List .env keys (no values) and what they're for if inferable -->

## Versioned Documentation
- For API-dependent changes, resolve package versions from lockfiles and consult matching local/Context documentation or official versioned docs.
- Context MCP is optional; install/configure it only when the user opts in. Do not edit host configuration or fetch documentation packages automatically.

## Development Commands
<!-- Extract from package.json scripts or README -->
```

### 5. Confirm to the user

- What stack and exact dependency versions were detected, clearly distinguishing lockfile resolutions from manifest ranges.
- Where `AGENTS.md` was written and which matching optional technology packs the user can review; do not imply packs were installed/copied or impose their commands.
- For API-dependent work, how `live-docs` will use the resolved version. Report Context as available only if observed, unavailable only if verified, otherwise unverified; offer setup as opt-in and never edit host configuration or trigger docs downloads without authorization.
- Any ambiguities or evidence gaps that could not be determined automatically.