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 bymaestro:setup). The skill-created files use snake_case names likebuilding_the_project.md,running_tests.md,code_conventions.md,service_architecture.md,database_schema.md, etc. Themaestro:setupfiles 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:setupfiles). - Delete
AGENTS.mdandCLAUDE.mdif 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.mdif it exists -- extract any rules worth preserving. - Existing AGENTS.md: Read
AGENTS.mdif 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 -- notebr(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.mdwith the same content asAGENTS.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.