---
name: init
description: Initialize AGENTS.md with hierarchical structure and .agents.yml config
allowed-tools: Bash Write Read Grep Glob AskUserQuestion Skill
---

# Initialize AGENTS.md

Set up AI agent documentation and machine-readable config for this project.

**Architecture:** AGENTS.md (human guidance) + .agents.yml (machine config) + CLAUDE.md (symlink)

## Step 1: Generate AGENTS.md

Check existing state first: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/check-existing.sh`

**If AGENTS.md exists**, ask: Regenerate | Enhance | Skip

Then invoke the hierarchical agents skill:

```
Skill(skill: "hierarchical-agents")
```

Complete all 4 phases: Repository Analysis → Root AGENTS.md → Sub-folder files → Special Considerations

For AGENTS.md best practices, see `resources/agents-md-template.md` in the init-agents-config skill.

## Step 2: Gather Configuration

Use `AskUserQuestion` to gather config. Ask in batches of max 4 questions.

### Core Questions (All Users)

| Question | Options |
|----------|---------|
| Tech Stack | Rails, Python, Node, Generic |
| App Status | Development, Production |
| Task Management | GitHub Issues, Linear, Beads, File-based |
| Workflow | Worktrees, Branches |
| Experience Level | Expert (Recommended), Senior, Intermediate, Beginner |

**Experience level definitions:**
- **Beginner**: New to the technology, needs detailed explanations
- **Intermediate**: Comfortable with basics, learning advanced patterns
- **Senior**: Deep knowledge, focus on edge cases and best practices
- **Expert**: Authoritative, skip explanations, just show the code

**Multi-stack projects** (e.g., Rails + React detected): Ask per-stack experience level instead of single level.

### Stack-Specific Questions

**Rails** (auto-detect ruby/rails versions first):

| Question | Options |
|----------|---------|
| Database | SQLite, PostgreSQL, MySQL |
| Frontend | Hotwire, Inertia, API-only |
| CSS | Tailwind, Bootstrap, None |
| JavaScript | Importmap, esbuild, Vite |
| Deployment (multi) | Kamal, Fly.io, Heroku, Render |
| Solid Gems (multi) | Solid Cache, Solid Queue, Solid Cable |

**Python** (auto-detect python version, framework):

| Question | Options |
|----------|---------|
| Framework | FastAPI, Django, Flask, None |
| Package Manager | uv, Poetry, pip |
| Database | PostgreSQL, SQLite, None |

**Node** (auto-detect node version, typescript, framework):

| Question | Options |
|----------|---------|
| Framework | Next.js, React, Vue/Nuxt, Express/Fastify |
| Package Manager | pnpm, npm, yarn, bun |
| TypeScript | Yes, No |
| Styling | Tailwind, CSS Modules, Styled Components, Sass |
| Testing | Vitest, Jest, Playwright, Cypress |
| Deployment | Vercel, Cloudflare, Netlify, Railway |

### Final Questions (All Users)

| Question | Options |
|----------|---------|
| Branch Naming | feature/desc, issue-desc, type/issue-desc, user/desc |
| Track in Git | Yes (shared), No (local-only) |
| Local Overrides | Yes (if tracked), No |
| Browser | Chrome, Brave, Edge, Skip |

## Step 3: Auto-Detect Values

**Run these operations in parallel:**

- Default branch: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/detect-branch.sh`
- Tech stack: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/detect-tech-stack.sh stack`
- Design system: `Glob: "**/design-system.md"`

If design system found, record path in toolbox config.

## Step 4: Write .agents.yml

Load the init-agents-config skill:

```
Skill(skill: "init-agents-config")
```

Select template by tech_stack from `resources/`:
- `rails.yaml` | `python.yaml` | `node.yaml` | `generic.yaml`

Replace placeholders with collected values. Handle conditionals:
- Only include `extras` if user selected Solid gems
- Only include `toolbox.build_task.design_system_path` if detected
- Only uncomment `browser.type` if Brave or Edge selected

### Gitignore + Local Config

If not tracking in git: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/gitignore-add.sh .agents.yml`

If local overrides requested: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/gitignore-add.sh .agents.local.yml`

If local overrides requested, write `.agents.local.yml` using template from `resources/local-config-template.yaml`.

## Step 5: Finalize Setup

1. **Create symlink** - `ln -s AGENTS.md CLAUDE.md` (backup if exists)
2. **Verify** - Run verification: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/verify-setup.sh`

## Output Summary

Report what was created:
- AGENTS.md structure (line count, sub-folders)
- .agents.yml (key settings)
- Design system status (detected path or suggest Skill("ux-brief"))
- Symlink and local config status