init（初始化）

AGENTS.md + CLAUDE.md -- Context File Generator

Generate minimal, high-impact AGENTS.md and CLAUDE.md context files for this repository using the WHAT/WHY/HOW framework. Both files share identical content -- CLAUDE.md is the standard file Claude Code reads automatically, while AGENTS.md is the cross-agent convention. See reference/AGENTS.md for the template, rules, and progressive disclosure specs.

Arguments

$ARGUMENTS

• --reset: Regenerate everything from scratch -- overwrite AGENTS.md, CLAUDE.md, and all context files created by this skill, then re-run the full exploration.
• Default (no args): Generate AGENTS.md, CLAUDE.md, and context files. If either file already exists, overwrite it directly.

Step 1: Handle --reset

If $ARGUMENTS contains --reset:

1. Check which .maestro/context/ files were created by this skill (not by maestro:setup). The skill-created files use snake_case names like building_the_project.md, running_tests.md, code_conventions.md, service_architecture.md, database_schema.md, etc. The maestro:setup files use kebab-case: product.md, tech-stack.md, guidelines.md, product-guidelines.md, workflow.md, index.md.
2. Delete the skill-created context files (preserve maestro:setup files).
3. Delete AGENTS.md and CLAUDE.md if they exist.
4. Report what was deleted.
5. Continue to Step 2 to regenerate everything from scratch.

Step 2: Explore the Codebase

Read-only exploration. Do NOT ask the user for permission to explore -- just do it.

2a: Check for Maestro Context (pre-fill)

Search for .maestro/context/product.md.

If it exists, maestro:setup has been run. Read these files for pre-fill data:

• .maestro/context/product.md -- purpose, users, features
• .maestro/context/tech-stack.md -- languages, frameworks, tools
• .maestro/context/guidelines.md -- coding conventions
• .maestro/context/workflow.md -- build/test methodology

Store findings as pre-fill. Do NOT ask questions the context already answers.

2b: Explore the Codebase

Regardless of whether maestro context exists, explore the codebase to discover or verify:

1. Project identity: Read README.md, package.json / pyproject.toml / Cargo.toml / go.mod / build.gradle / pom.xml / Gemfile / composer.json (whichever exists).
2. Build and test commands: Read the package manifest scripts section, Makefile, justfile, Taskfile.yml, CI config (.github/workflows/*.yml, .gitlab-ci.yml), docker-compose.yml.
3. Existing CLAUDE.md: Read CLAUDE.md if it exists -- extract any rules worth preserving.
4. Existing AGENTS.md: Read AGENTS.md if it exists -- note what it covers before overwriting.
5. Tooling: Detect non-obvious tool choices (bun vs npm, uv vs pip, pnpm vs yarn, custom wrappers).
6. Linter/formatter configs: Check for .eslintrc*, prettier*, biome.json, ruff.toml, .rubocop.yml, clippy.toml, .editorconfig. Note what they enforce (used by template rules to avoid duplication).
7. Architecture signals: Monorepo structure (packages/, apps/, crates/, services/), database configs, API patterns.
8. Issue tracking: Check for .beads/ directory first. If it exists, the project uses Beads -- note br (beads_rust) as the issue tracking tool and skip checking for other issue trackers (GitHub Issues, Jira, Linear, etc.). Only probe for alternative issue trackers if .beads/ is absent.

The agent decides what to read based on what it finds. This is exploration, not a rigid checklist -- adapt to the project.

2c: Synthesize Findings

Organize discoveries into these categories (internal notes, not output):

• WHAT: Project purpose, tech stack, key dependencies
• WHY: Why the project exists, who it's for
• HOW: Build commands, test commands, dev server, lint commands, non-obvious tooling
• RULES: Behavioral rules that apply to every session
• TASK-SPECIFIC: Details that belong in progressive disclosure files (test patterns, architecture details, database schema, etc.)

Step 3: Draft AGENTS.md

Use the template and rules from reference/AGENTS.md. The output file MUST be under 100 lines.

Step 4: Draft Progressive Disclosure Files

Use the progressive disclosure guidance from reference/AGENTS.md to create well-named files in .maestro/context/.

Step 5: Write Files

1. Create .maestro/context/ if it does not exist: mkdir -p.maestro/context
2. Write AGENTS.md (overwrite if exists).
3. Write CLAUDE.md with the same content as AGENTS.md (overwrite if exists).
4. Write each progressive disclosure file to .maestro/context/.
5. Display summary: AGENTS.md + CLAUDE.md generated. - AGENTS.md ({line_count} lines) - CLAUDE.md ({line_count} lines) -.maestro/context/building_the_project.md -.maestro/context/running_tests.md {additional files as created} Next steps: - Review AGENTS.md / CLAUDE.md and edit manually for accuracy - /maestro:AGENTS.md --reset -- regenerate from scratch

Relationship to Other Commands

Recommended workflow:

• /maestro:setup -- Scaffold project context (run first)
• /maestro:AGENTS.md -- You are here. Generate AGENTS.md context file
• /maestro:new-track -- Create a feature/bug track with spec and plan
• /maestro:implement -- Execute the implementation
• /maestro:review -- Verify implementation correctness
• /maestro:status -- Check progress across all tracks

AGENTS.md is an optional context enhancement that complements /maestro:setup. While setup creates project-level context files, this skill generates a codebase-oriented AGENTS.md with progressive disclosure. Run it after setup to give all agents richer context about the repository structure.