---
name: dual-init
description: Initialize project with both AGENTS.md (universal agent instructions) and CLAUDE.md (Claude-specific extensions). Use instead of /init when you want portable agent instructions that work across multiple AI coding tools.
---

# Dual Init: Generate AGENTS.md and CLAUDE.md

This command analyzes the codebase and generates two complementary files:
1. **AGENTS.md** - Universal instructions following the agents.md standard (https://agents.md)
2. **CLAUDE.md** - Claude Code specific extensions that reference AGENTS.md

## Process

### Step 1: Analyze the Codebase

Gather information about the project by examining:
- Package files (package.json, pyproject.toml, Cargo.toml, pom.xml, build.gradle, etc.)
- Existing documentation (README.md, CONTRIBUTING.md, docs/)
- Configuration files (.eslintrc, prettier.config, tsconfig.json, etc.)
- CI/CD configuration (.github/workflows/, .gitlab-ci.yml, Jenkinsfile)
- Existing agent/editor configs (.cursorrules, .cursor/rules/, .github/copilot-instructions.md)
- Test configuration and structure
- Source code structure and patterns
- Git configuration and hooks

### Step 2: Generate AGENTS.md

Create AGENTS.md at the repository root with ONLY universal, portable information that works across all AI coding agents. This file should be useful for Cursor, Codex, Jules, Aider, Windsurf, and other tools.

**AGENTS.md should include:**

```markdown
# AGENTS.md

## Project Overview
[One-line description of what this project does]

## Tech Stack
[Languages, frameworks, key dependencies]

## Development Commands
[Commands any agent needs to know - keep it minimal and essential]
- Build: `command`
- Test: `command`
- Lint: `command`
- Run dev server: `command`

## Project Structure
[High-level directory layout - only the important parts]
- `/src` - Main source code
- `/tests` - Test files
- etc.

## Code Style
[Universal style guidelines detected from config files or codebase patterns]
- Formatting preferences
- Naming conventions
- Import/export patterns

## Testing Instructions
[How to run tests, what framework is used, where fixtures live]

## Architecture Notes
[Key architectural decisions that affect how code should be written]

## Important Constraints
[Security considerations, performance requirements, compatibility notes]
```

**AGENTS.md should NOT include:**
- Claude-specific tool names (BatchTool, GlobTool, etc.)
- MCP server configurations
- Hooks or permission settings
- References to Claude Code commands
- Anything that only makes sense for Claude

### Step 3: Generate CLAUDE.md

Create CLAUDE.md at the repository root that references AGENTS.md and adds Claude Code specific enhancements.

**CLAUDE.md structure:**

```markdown
# CLAUDE.md

<!-- This file extends AGENTS.md with Claude Code specific instructions -->
<!-- See AGENTS.md for universal project context and commands -->

@AGENTS.md

## Claude Code Specific

### MCP Servers
[If .mcp.json exists or MCP servers would be useful, document them here]

### Useful Slash Commands
[Reference any custom commands in .claude/commands/ or .claude/skills/]

### Workflow Preferences
[Claude-specific workflow hints, like when to use /compact, how to handle large changes]

### Tool Usage Hints
[Guidance on when to use specific Claude tools like Bash, Read, Grep, etc.]

### Permission Notes
[Any permission patterns that are commonly needed in this project]
```

### Step 4: Present Results

After generating both files:
1. Show a brief summary of what was included in each file
2. Explain the relationship between the two files
3. Suggest next steps for customization

## Important Guidelines

1. **Keep AGENTS.md portable** - Never include Claude-specific terminology
2. **Keep both files concise** - Context window space is precious
3. **Avoid obvious instructions** - Don't include generic advice like "write clean code"
4. **Be specific** - Include actual commands, not placeholders
5. **Respect existing content** - If either file exists, suggest improvements rather than overwriting
6. **Use @-references** - CLAUDE.md should use `@AGENTS.md` to pull in the universal content

## Handling Existing Files

- If AGENTS.md exists: Review it and suggest improvements based on codebase analysis
- If CLAUDE.md exists: Review it and suggest adding the @AGENTS.md reference if missing
- If both exist: Analyze both and suggest how to better separate concerns between them
- If neither exists: Generate both from scratch

## Output Format

Generate the files with clear markdown formatting. After creating the files, provide:
1. A brief summary of what each file contains
2. Any recommendations for further customization
3. Note if any existing agent/editor configurations were incorporated