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:

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.
Delete the skill-created context files (preserve maestro:setup files).
Delete AGENTS.md and CLAUDE.md if they exist.
Report what was deleted.
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:

Project identity: Read README.md, package.json / pyproject.toml / Cargo.toml / go.mod / build.gradle / pom.xml / Gemfile / composer.json (whichever exists).
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.
Existing CLAUDE.md: Read CLAUDE.md if it exists -- extract any rules worth preserving.
Existing AGENTS.md: Read AGENTS.md if it exists -- note what it covers before overwriting.
Tooling: Detect non-obvious tool choices (bun vs npm, uv vs pip, pnpm vs yarn, custom wrappers).
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).
Architecture signals: Monorepo structure (packages/, apps/, crates/, services/), database configs, API patterns.
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

Create .maestro/context/ if it does not exist:
```
mkdir -p .maestro/context
```
Write AGENTS.md (overwrite if exists).
Write CLAUDE.md with the same content as AGENTS.md (overwrite if exists).
Write each progressive disclosure file to .maestro/context/.

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.

init