deepinit

SKILL.md

Deep Init Skill

Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.

Core Concept

AGENTS.md files serve as AI-readable documentation that helps agents understand:

What each directory contains

How components relate to each other

Special instructions for working in that area

Dependencies and relationships

Hierarchical Tagging System

Every AGENTS.md (except root) includes a parent reference tag:

<!-- Parent: ../AGENTS.md -->

This creates a navigable hierarchy:

/AGENTS.md                          ← Root (no parent tag)
├── src/AGENTS.md                   ← <!-- Parent: ../AGENTS.md -->
│   ├── src/components/AGENTS.md    ← <!-- Parent: ../AGENTS.md -->
│   └── src/utils/AGENTS.md         ← <!-- Parent: ../AGENTS.md -->
└── docs/AGENTS.md                  ← <!-- Parent: ../AGENTS.md -->

AGENTS.md Template

<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
<!-- Generated: {timestamp} | Updated: {timestamp} -->

# {Directory Name}

## Purpose
{One-paragraph description of what this directory contains and its role}

## Key Files
{List each significant file with a one-line description}

| File | Description |
|------|-------------|
| `file.ts` | Brief description of purpose |

## Subdirectories
{List each subdirectory with brief purpose}

| Directory | Purpose |
|-----------|---------|
| `subdir/` | What it contains (see `subdir/AGENTS.md`) |

## For AI Agents

### Working In This Directory
{Special instructions for AI agents modifying files here}

### Testing Requirements
{How to test changes in this directory}

### Common Patterns
{Code patterns or conventions used here}

## Dependencies

### Internal
{References to other parts of the codebase this depends on}

### External
{Key external packages/libraries used}

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

Execution Workflow

Step 1: Map Directory Structure

Task(subagent_type="explore", model="haiku",
  prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")

Step 2: Create Work Plan

Generate todo items for each directory, organized by depth level:

Level 0: / (root)
Level 1: /src, /docs, /tests
Level 2: /src/components, /src/utils, /docs/api
...

Step 3: Generate Level by Level

IMPORTANT: Generate parent levels before child levels to ensure parent references are valid.

For each directory:

Read all files in the directory

Analyze purpose and relationships

Generate AGENTS.md content

Write file with proper parent reference

Step 4: Compare and Update (if exists)

When AGENTS.md already exists:

Read existing content

Identify sections:

Auto-generated sections (can be updated)

Manual sections (<!-- MANUAL --> preserved)

Compare:

New files added?

Files removed?

Structure changed?

Merge:

Update auto-generated content

Preserve manual annotations

Update timestamp

Step 5: Validate Hierarchy

After generation, run validation checks:

Check
How to Verify
Corrective Action

Parent references resolve
Read each AGENTS.md, check <!-- Parent: --> path exists
Fix path or remove orphan

No orphaned AGENTS.md
Compare AGENTS.md locations to directory structure
Delete orphaned files

Completeness
List all directories, check for AGENTS.md
Generate missing files

Timestamps current
Check <!-- Generated: --> dates
Regenerate outdated files

Validation script pattern:

# Find all AGENTS.md files
find . -name "AGENTS.md" -type f

# Check parent references
grep -r "<!-- Parent:" --include="AGENTS.md" .

Smart Delegation

Task
Agent

Directory mapping
explore

File analysis
architect

Content generation
writer

AGENTS.md writes
writer

Empty Directory Handling

When encountering empty or near-empty directories:

Condition
Action

No files, no subdirectories
Skip - do not create AGENTS.md

No files, has subdirectories
Create minimal AGENTS.md with subdirectory listing only

Has only generated files (*.min.js, *.map)
Skip or minimal AGENTS.md

Has only config files
Create AGENTS.md describing configuration purpose

Example minimal AGENTS.md for directory-only containers:

<!-- Parent: ../AGENTS.md -->
# {Directory Name}

## Purpose
Container directory for organizing related modules.

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `subdir/` | Description (see `subdir/AGENTS.md`) |

Parallelization Rules

Same-level directories: Process in parallel

Different levels: Sequential (parent first)

Large directories: Spawn dedicated agent per directory

Small directories: Batch multiple into one agent

Quality Standards

Must Include

 Accurate file descriptions

 Correct parent references

 Subdirectory links

 AI agent instructions

Must Avoid

 Generic boilerplate

 Incorrect file names

 Broken parent references

 Missing important files

Example Output

Root AGENTS.md

<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# my-project

## Purpose
A web application for managing user tasks with real-time collaboration features.

## Key Files
| File | Description |
|------|-------------|
| `package.json` | Project dependencies and scripts |
| `tsconfig.json` | TypeScript configuration |
| `.env.example` | Environment variable template |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `src/` | Application source code (see `src/AGENTS.md`) |
| `docs/` | Documentation (see `docs/AGENTS.md`) |
| `tests/` | Test suites (see `tests/AGENTS.md`) |

## For AI Agents

### Working In This Directory
- Always install dependencies after modifying the project manifest
- Use TypeScript strict mode
- Follow ESLint rules

### Testing Requirements
- Run tests before committing
- Ensure >80% coverage

### Common Patterns
- Use barrel exports (index.ts)
- Prefer functional components

## Dependencies

### External
- React 18.x - UI framework
- TypeScript 5.x - Type safety
- Vite - Build tool

<!-- MANUAL: Custom project notes can be added below -->

Nested AGENTS.md

<!-- Parent: ../AGENTS.md -->
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->

# components

## Purpose
Reusable React components organized by feature and complexity.

## Key Files
| File | Description |
|------|-------------|
| `index.ts` | Barrel export for all components |
| `Button.tsx` | Primary button component |
| `Modal.tsx` | Modal dialog component |

## Subdirectories
| Directory | Purpose |
|-----------|---------|
| `forms/` | Form-related components (see `forms/AGENTS.md`) |
| `layout/` | Layout components (see `layout/AGENTS.md`) |

## For AI Agents

### Working In This Directory
- Each component has its own file
- Use CSS modules for styling
- Export via index.ts

### Testing Requirements
- Unit tests in `__tests__/` subdirectory
- Use React Testing Library

### Common Patterns
- Props interfaces defined above component
- Use forwardRef for DOM-exposing components

## Dependencies

### Internal
- `src/hooks/` - Custom hooks used by components
- `src/utils/` - Utility functions

### External
- `clsx` - Conditional class names
- `lucide-react` - Icons

<!-- MANUAL: -->

Triggering Update Mode

When running on an existing codebase with AGENTS.md files:

Detect existing files first

Read and parse existing content

Analyze current directory state

Generate diff between existing and current

Apply updates while preserving manual sections

Performance Considerations

Cache directory listings - Don't re-scan same directories

Batch small directories - Process multiple at once

Skip unchanged - If directory hasn't changed, skip regeneration

Parallel writes - Multiple agents writing different files simultaneously