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
- Create symlink -
ln -s AGENTS.md CLAUDE.md (backup if exists)
- 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
1---2name: init3description: Initialize AGENTS.md with hierarchical structure and .agents.yml config4---56# Initialize AGENTS.md78Set up AI agent documentation and machine-readable config for this project.910**Architecture:** AGENTS.md (human guidance) + .agents.yml (machine config) + CLAUDE.md (symlink)1112## Step 1: Generate AGENTS.md1314Check existing state first: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/check-existing.sh`1516**If AGENTS.md exists**, ask: Regenerate | Enhance | Skip1718Then invoke the hierarchical agents skill:1920```21Skill(skill: "hierarchical-agents")22```2324Complete all 4 phases: Repository Analysis → Root AGENTS.md → Sub-folder files → Special Considerations2526For AGENTS.md best practices, see `resources/agents-md-template.md` in the init-agents-config skill.2728## Step 2: Gather Configuration2930Use `AskUserQuestion` to gather config. Ask in batches of max 4 questions.3132### Core Questions (All Users)3334| Question | Options |35|----------|---------|36| Tech Stack | Rails, Python, Node, Generic |37| App Status | Development, Production |38| Task Management | GitHub Issues, Linear, Beads, File-based |39| Workflow | Worktrees, Branches |40| Experience Level | Expert (Recommended), Senior, Intermediate, Beginner |4142**Experience level definitions:**43- **Beginner**: New to the technology, needs detailed explanations44- **Intermediate**: Comfortable with basics, learning advanced patterns45- **Senior**: Deep knowledge, focus on edge cases and best practices46- **Expert**: Authoritative, skip explanations, just show the code4748**Multi-stack projects** (e.g., Rails + React detected): Ask per-stack experience level instead of single level.4950### Stack-Specific Questions5152**Rails** (auto-detect ruby/rails versions first):5354| Question | Options |55|----------|---------|56| Database | SQLite, PostgreSQL, MySQL |57| Frontend | Hotwire, Inertia, API-only |58| CSS | Tailwind, Bootstrap, None |59| JavaScript | Importmap, esbuild, Vite |60| Deployment (multi) | Kamal, Fly.io, Heroku, Render |61| Solid Gems (multi) | Solid Cache, Solid Queue, Solid Cable |6263**Python** (auto-detect python version, framework):6465| Question | Options |66|----------|---------|67| Framework | FastAPI, Django, Flask, None |68| Package Manager | uv, Poetry, pip |69| Database | PostgreSQL, SQLite, None |7071**Node** (auto-detect node version, typescript, framework):7273| Question | Options |74|----------|---------|75| Framework | Next.js, React, Vue/Nuxt, Express/Fastify |76| Package Manager | pnpm, npm, yarn, bun |77| TypeScript | Yes, No |78| Styling | Tailwind, CSS Modules, Styled Components, Sass |79| Testing | Vitest, Jest, Playwright, Cypress |80| Deployment | Vercel, Cloudflare, Netlify, Railway |8182### Final Questions (All Users)8384| Question | Options |85|----------|---------|86| Branch Naming | feature/desc, issue-desc, type/issue-desc, user/desc |87| Track in Git | Yes (shared), No (local-only) |88| Local Overrides | Yes (if tracked), No |89| Browser | Chrome, Brave, Edge, Skip |9091## Step 3: Auto-Detect Values9293**Run these operations in parallel:**9495- Default branch: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/detect-branch.sh`96- Tech stack: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/detect-tech-stack.sh stack`97- Design system: `Glob: "**/design-system.md"`9899If design system found, record path in toolbox config.100101## Step 4: Write .agents.yml102103Load the init-agents-config skill:104105```106Skill(skill: "init-agents-config")107```108109Select template by tech_stack from `resources/`:110- `rails.yaml` | `python.yaml` | `node.yaml` | `generic.yaml`111112Replace placeholders with collected values. Handle conditionals:113- Only include `extras` if user selected Solid gems114- Only include `toolbox.build_task.design_system_path` if detected115- Only uncomment `browser.type` if Brave or Edge selected116117### Gitignore + Local Config118119If not tracking in git: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/gitignore-add.sh .agents.yml`120121If local overrides requested: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/gitignore-add.sh .agents.local.yml`122123If local overrides requested, write `.agents.local.yml` using template from `resources/local-config-template.yaml`.124125## Step 5: Finalize Setup1261271. **Create symlink** - `ln -s AGENTS.md CLAUDE.md` (backup if exists)1282. **Verify** - Run verification: !`${CLAUDE_PLUGIN_ROOT}/skills/init/scripts/verify-setup.sh`129130## Output Summary131132Report what was created:133- AGENTS.md structure (line count, sub-folders)134- .agents.yml (key settings)135- Design system status (detected path or suggest Skill("ux-brief"))136- Symlink and local config status
majesticlabs-dev