/init

description: Initialize project with AGENTS.md and create symlinks for all AI assistants
category: claude-setup
allowed-tools: Write, Bash(ln:*), Bash(mkdir:*), Bash(test:*), Bash(echo:*), Read, Glob, Task

Initialize AGENTS.md for Your Project

Create a comprehensive AGENTS.md file following the universal standard, with symlinks for all AI assistants.

Current Status

!`test -f AGENTS.md && echo "⚠️ AGENTS.md already exists" || echo "✅ Ready to create AGENTS.md"`

Task

Please analyze this codebase and create an AGENTS.md file containing: 1. Build/lint/test commands - especially for running a single test 2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.

Usage notes:

• The file you create will be given to agentic coding agents (such as yourself) that operate in this repository
• If there's already an AGENTS.md, improve it
• If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include them
• Start the file with: "# AGENTS.md\nThis file provides guidance to AI coding assistants working in this repository."

1. Gather Repository Information

Use Task tool with description "Gather repository information" to run these Glob patterns in parallel:

• `package*.json` - Node.js project files
• `*.md` - Documentation files
• `.github/workflows/*.yml` - GitHub Actions workflows
• `.github/workflows/*.yaml` - GitHub Actions workflows (alternate extension)
• `.cursor/rules/**` - Cursor rules
• `.cursorrules` - Cursor rules (alternate location)
• `.github/copilot-instructions.md` - GitHub Copilot rules
• `.claude/agents/**/*.md` - Specialized AI subagents
• `requirements.txt`, `setup.py`, `pyproject.toml` - Python projects
• `go.mod` - Go projects
• `Cargo.toml` - Rust projects
• `Gemfile` - Ruby projects
• `pom.xml`, `build.gradle` - Java projects
• `*.csproj` - .NET projects
• `Makefile` - Build automation
• `.eslintrc*`, `.prettierrc*` - Code style configs
• `tsconfig.json` - TypeScript config
• `.env.example` - Environment configuration
• `**/*.test.*`, `**/*.spec.*` - Test files (limit to a few)
• `Dockerfile`, `docker-compose*.yml` - Docker configuration

Also examine:

• README.md for project overview and command documentation
• package.json scripts to document all available commands
• GitHub workflows to identify CI/CD commands
• A few source files to infer coding conventions
• Test files to understand testing patterns
• `.claude/agents/` directory to discover available subagents

**Script Consistency Check**: When documenting npm scripts from package.json, verify they match references in:

• GitHub Actions workflows (npm run, npm test, etc.)
• README.md installation and usage sections
• Docker configuration files
• Any setup or deployment scripts

2. Check for Existing Configs

• If AGENTS.md exists, improve it based on analysis
• If .cursorrules or .cursor/rules/* exist, incorporate them
• If .github/copilot-instructions.md exists, include its content
• If other AI configs exist (.clinerules, .windsurfrules), merge them
• If `.claude/agents/` directory exists, document available subagents with their descriptions and usage examples

3. Create AGENTS.md

Based on your analysis, create AGENTS.md with this structure:

# AGENTS.md
This file provides guidance to AI coding assistants working in this repository.

**Note:** [Document if CLAUDE.md or other AI config files are symlinks to AGENTS.md]

# [Project Name]

[Project Overview: Brief description of the project's purpose and architecture]

## Build & Commands

[Development, testing, and deployment commands with EXACT script names:]

**CRITICAL**: Document the EXACT script names from package.json, not generic placeholders.
For example:
- Build: `npm run build` (if package.json has "build": "webpack")
- Test: `npm test` (if package.json has "test": "jest")
- Type check: `npm run typecheck` (if package.json has "typecheck": "tsc --noEmit")
- Lint: `npm run lint` (if package.json has "lint": "eslint .")

If the project uses different names, document those:
- Type check: `npm run tsc` (if that's what's in package.json)
- Lint: `npm run eslint` (if that's what's in package.json)
- Format: `npm run prettier` (if that's what's in package.json)

[Include ALL commands from package.json scripts, even if they have non-standard names]

### Script Command Consistency
**Important**: When modifying npm scripts in package.json, ensure all references are updated:
- GitHub Actions workflows (.github/workflows/*.yml)
- README.md documentation
- Contributing guides
- Dockerfile/docker-compose.yml
- CI/CD configuration files
- Setup/installation scripts

Common places that reference npm scripts:
- Build commands → Check: workflows, README, Dockerfile
- Test commands → Check: workflows, contributing docs
- Lint commands → Check: pre-commit hooks, workflows
- Start commands → Check: README, deployment docs

**Note**: Always use the EXACT script names from package.json, not assumed names

## Code Style

[Formatting rules, naming conventions, and best practices:]
- Language/framework specifics
- Import conventions
- Formatting rules
- Naming conventions
- Type usage patterns
- Error handling patterns
[Be specific based on actual code analysis]

## Testing

[Testing frameworks, conventions, and execution guidelines:]
- Framework: [Jest/Vitest/Pytest/etc]
- Test file patterns: [*.test.ts, *.spec.js, etc]
- Testing conventions
- Coverage requirements
- How to run specific test suites

### Testing Philosophy
**When tests fail, fix the code, not the test.**

Key principles:
- **Tests should be meaningful** - Avoid tests that always pass regardless of behavior
- **Test actual functionality** - Call the functions being tested, don't just check side effects
- **Failing tests are valuable** - They reveal bugs or missing features
- **Fix the root cause** - When a test fails, fix the underlying issue, don't hide the te