monorepo-initialization

What this skill does

# Monorepo Initialization Skill

## Purpose

Systematically initialize AGENTS.md files throughout a monorepo, creating a hierarchical context system where:
- Root AGENTS.md coordinates all agents
- Each package/service has its own AGENTS.md with hierarchy metadata
- All files link back to root CLAUDE.md (philosophy) 
- AI agents can navigate context efficiently across packages

This enables large projects to maintain clear, navigable agent guidance without overwhelming token budgets.

## When to Use

- **New monorepo setup** - Initialize entire project structure
- **Adding new packages** - Run on new subdirectory
- **Improving agent context** - Refresh existing AGENTS.md files
- **Scaling team** - Ensure new members understand cross-package dependencies
- **Microservices** - Document each service's agent context independently

## The Problem

Without structured AGENTS.md hierarchy:
- Agents get confused about project structure
- Context is scattered or missing
- Cross-package dependencies aren't clear
- Scaling to 5+ packages becomes difficult
- New team members waste time understanding structure

With this skill:
- Agents understand full project structure
- Each package has focused, actionable guidance
- Dependencies and integration points are documented
- Scales to 20+ packages without confusion

## Process

### Phase 1: Discovery (5-10 minutes)

Script automatically scans for:
- **Project files**: package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml
- **Directories**: src/, lib/, components/, services/
- **Config files**: .cursorrules, .github/copilot-instructions.md
- **Documentation**: README.md, docs/

Scoring heuristic:
```
Project file present:     +10 points
src/lib/components dir:   +5 points
Config file present:      +3 points
>10 source files:         +3 points
README/docs present:      +2 points
Threshold: > 5 points = initialize
```

### Phase 2: Root Analysis

Create root AGENTS.md containing:
- Project overview
- All agents and their modes
- Available commands and skills
- Directory structure index (table of all packages)
- Hierarchy linking explanation

Example:
```markdown
# Project Agents

## Directory Structure

| Package | Level | Purpose | Key Files |
|---------|-------|---------|-----------|
| `packages/api` | API Services | REST backend | src/routes/, src/models/ |
| `packages/web` | Frontend | React UI | src/components/, src/pages/ |

## Hierarchy Linking

Each package maintains its own AGENTS.md with:
- **Hierarchy Level**: Role in system (e.g., "API Services")
- **Parent**: Link to this AGENTS.md
- **Philosophy**: Link to CLAUDE.md

See individual AGENTS.md files for package-specific guidance.
```

### Phase 3: Package Initialization

For each important subdirectory, create localized AGENTS.md (~20 lines):

**Metadata** (Required per Anthropic hierarchy docs):
```markdown
---
hierarchy:
  level: "API Services"
  parent: "../AGENTS.md"
  philosophy: "../../CLAUDE.md"
---

# API Service Agents
```

**Content**:
- Framework/tech stack used
- Build/lint/test commands with examples
- Code style guidelines (imports, formatting, naming)
- Common patterns specific to this package
- Integration points with other packages
- Key files and their purposes

**Example for API package**:
```markdown
# API Service Agents

**Hierarchy Level**: API Services (REST backend, database layer)  
**Parent**: [../AGENTS.md](../AGENTS.md)  
**Philosophy**: [CLAUDE.md](../../CLAUDE.md)

## Tech Stack

- Express.js (server framework)
- TypeScript (type safety)
- Prisma (ORM)
- PostgreSQL (database)

## Key Commands

```bash
# Development
npm run dev              # Start dev server on :3000
npm run build            # Compile TypeScript
npm run test             # Run Jest tests
npm run test:watch       # Watch mode

# Single test example
npm test -- routes.test.ts

# Linting & formatting
npm run lint             # ESLint check
npm run format           # Prettier format
```

## Code Style

**Imports**: Absolute paths from src/, relative for same package
```typescript
import { UserService } from '@api/services'  // Cross-package
import { helper } from '../utils'             // Local
```

**Naming**: camelCase functions, PascalCase classes, UPPER_SNAKE_CASE constants

**Types**: Explicit return types for all functions, use Zod for runtime validation

## Patterns

- **Services**: Business logic in `/services`, thin controllers
- **Models**: Prisma schemas in `/prisma/schema.prisma`
- **Error handling**: Use custom AppError class with status codes
- **Logging**: Use logger instance (shared/logger)

## Integration Points

- **Web package**: Uses `/api/*` routes via fetch
- **Shared package**: Uses types and utilities from shared
- **Database**: Migrations in `/prisma/migrations`

## AI Agent Guidance

For Claude/GPT working in this package:
1. Follow Express.js patterns (middleware, routing)
2. Always add types (no `any`)
3. Write tests alongside features
4. Update Prisma schema, run migrations
5. Reference `/shared` for shared types/utilities
```

### Phase 4: Root CLAUDE.md Update

Update (or create) root CLAUDE.md to document the hierarchy:

```markdown
# Project Philosophy

[Your guiding principles and vision...]

## Agent Coordination

See **[AGENTS.md](./AGENTS.md)** for:
- Agents and their modes (plan/build/review)
- Available commands and skills
- Directory context index

This CLAUDE.md defines **philosophy**. AGENTS.md documents **agents and tools**.

## Agent Contexts (Hierarchical)

Each package/service maintains specialized agent context:

| Directory | AGENTS.md | Level | Purpose |
|-----------|-----------|-------|---------|
| Root | [AGENTS.md](./AGENTS.md) | Coordination | Project overview, cross-package agents |
| `packages/api` | [packages/api/AGENTS.md](./packages/api/AGENTS.md) | API Services | REST backend, database layer |
| `packages/web` | [packages/web/AGENTS.md](./packages/web/AGENTS.md) | Frontend | React UI, styling, client logic |
| `packages/shared` | [packages/shared/AGENTS.md](./packages/shared/AGENTS.md) | Shared Utilities | Types, helpers, common code |

Each subdirectory's AGENTS.md includes hierarchy metadata:
- **Hierarchy Level**: Role in system architecture
- **Parent**: Link to parent AGENTS.md for coordination
- **Philosophy**: Link to this CLAUDE.md for guiding principles

This three-tier system (philosophy → coordination → specialization) allows AI agents to:
1. Understand project vision and values (CLAUDE.md)
2. Understand cross-package structure (root AGENTS.md)
3. Get specialized guidance for their specific package (package AGENTS.md)
```

### Phase 5: Verification & Cleanup

Verify all links work:
```bash
✓ Root AGENTS.md exists and links to all packages
✓ Root CLAUDE.md lists all AGENTS.md files
✓ Each package AGENTS.md has hierarchy metadata
✓ No broken relative paths
✓ Build commands are tested (where applicable)
```

Cleanup:
```bash
git add .
git commit -m "chore: initialize monorepo AGENTS.md hierarchy"
```

## Usage

### CLI (from root):
```bash
# Initialize entire project (interactive)
/monorepo-initialization

# Dry-run: preview without changes
/monorepo-initialization --dry-run

# Initialize with specific depth
/monorepo-initialization --depth=3

# Re-initialize (overwrite existing)
/monorepo-initialization --preserve=false

# Initialize specific directory
/monorepo-initialization packages/my-new-service
```

### OpenCode:
```python
use_skill("monorepo-initialization", {
    "depth": 2,
    "dry_run": False,
    "preserve": False
})
```

### Claude Code:
```
Use monorepo-initialization skill to set up AGENTS.md hierarchy for new packages
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--depth N` | Maximum recursion depth | 2 |
| `--dry-run` | Preview without making changes | false |
| `--preserve` | Keep existing AGENTS.md files | false |
| `--batch-size N` | Process N directories at a time | 3 |
| `--min-score N` | Minimum importance score to initialize | 5 |