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.