Deepinit

Deep Init Skill

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

Read references/scope-and-preservation.md before running on a repository with existing AGENTS.md files or runtime directories. Validate results with scripts/validate_agents_hierarchy.py.

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 runtime/build/cache directories from references/scope-and-preservation.md.")

Default excludes:

• .git/, node_modules/, dist/, build/, coverage/, .next/, .nuxt/, __pycache__/, .venv/, venv/
• Root runtime state: .omc/, .omx/, .survey/, .codex/, .claude/, .gemini/, .agents/, .opencode/, .ouroboros/

Keep .agent-skills/ in scope because it is repository source, not runtime state.

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: 1. Read all files in the directory 2. Analyze purpose and relationships 3. Generate AGENTS.md content 4. Write file with proper parent reference

Step 4: Compare and Update (if exists)

When AGENTS.md already exists:

1. Read existing content 2. Identify sections:

• Auto-generated sections (can be updated)
• Manual sections (<!-- MANUAL --> preserved)

3. Compare:

• New files added?
• Files removed?
• Structure changed?

4. Merge:

• Update auto-generated content
• Preserve manual annotations
• Update timestamp
• Keep existing instructions that are still true; flag stale instructions instead of deleting them silently

Step 5: Validate Hierarchy

After generation, run validation checks:

Validation script pattern:

python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py .

Smart Delegation

Empty Directory Handling

When encountering empty or near-empty directories:

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

1. Same-level directories: Process in parallel 2. Different levels: Sequential (parent first) 3. Large directories: Spawn dedicated agent per directory 4. 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
• [ ] Documenting ignored runtime state as source architecture
• [ ] Replacing user-authored manual notes

Runtime-Specific Notes

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:

1. Detect existing files first 2. Read and parse existing content 3. Analyze current directory state 4. Generate diff between existing and current 5. 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

References

• Scope and preservation
• scripts/validate_agents_hierarchy.py

Deepinit Scope and Preservation

Use this reference before creating or refreshing AGENTS.md files.

Directory Scope

Deepinit documents source structure, not runtime debris.

Always exclude:

• .git/
• node_modules/
• dist/, build/, coverage/
• .next/, .nuxt/
• __pycache__/, .pytest_cache/, .mypy_cache/
• .venv/, venv/, env/
• root runtime state: .omc/, .omx/, .survey/, .codex/, .claude/, .gemini/, .opencode/, .ouroboros/

Conditional:

• Root .agents/ is source only when the project deliberately uses oh-my-agent / OMA as a checked-in portable harness. Otherwise treat it as generated/runtime state.
• .agent-skills/ is always source in this repository. Document its skill folders, references, scripts, evals, and catalog files.
• .agent-skills-wiki/ is source when already tracked or explicitly used as project knowledge.

Manual Preservation

Preserve everything after the marker:

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

When a file uses a shorter marker such as <!-- MANUAL: -->, treat the marker and all following content as manual. Do not rewrite, summarize, or delete it.

Parent Links

Every non-root AGENTS.md must start with a relative parent link:

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

Rules:

• The path must resolve from the AGENTS.md file's directory.
• Root AGENTS.md has no parent tag.
• If a directory's nearest documented parent is more than one level up because skipped directories are excluded, use the correct relative path.

Runtime Notes

Validation

Run:

python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py .
python3 .agent-skills/deepinit/scripts/validate_agents_hierarchy.py . --strict

Expected result:

• default mode passes with warnings for legacy AGENTS.md files that predate deepinit
• strict mode requires all non-root AGENTS.md parent links to resolve
• strict mode requires manual markers to be present and preserved