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