Agent-Skills.md

Agent Skills: Maestro Setup

Scaffolds project context (product, tech stack, coding guidelines, product guidelines, workflow) and initializes track registry. Use for first-time project onboarding.

UncategorizedID: ReinaMacCredy/my-workflow/maestro-setup

Repository

ReinaMacCredy/my-workflow
ReinaMacCredyLicense: MIT
233

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ReinaMacCredy/maestro/tree/HEAD/skills/bundled/maestro-setup

Skill Files

Browse the full folder contents for maestro-setup.

Download Skill

Loading file tree…

skills/bundled/maestro-setup/SKILL.md

Skill Metadata

Name
maestro-setup
Description
Set up a repository for Maestro-guided, human-in-the-loop agent work. Use when a project needs Maestro-owned context docs, evidence-first onboarding, root AGENTS.md guidance, language style guides, or a setup report before implementation work begins.

Maestro Setup

Use this skill to create or refresh Maestro-owned project context. This is the canonical v1 setup behavior. Future maestro setup CLI commands must match this skill's behavior rather than inventing a separate setup model.

Core Contract

  • Skill-first, CLI-second. Do not add or assume a maestro setup CLI command.
  • Non-interactive by default. Do not ask questions during ordinary setup.
  • Evidence-first. Infer from repo files and mark uncertain facts as TODO.
  • Keep substantial setup content under .maestro/context/.
  • Root AGENTS.md is generated by Step 4 (init-deep workflow): a hierarchical PROJECT KNOWLEDGE BASE with the Maestro pointer absorbed inside, still wrapped by <!-- maestro-setup:start --> / <!-- maestro-setup:end --> markers.
  • Preserve user content outside managed markers.
  • Overwrite .maestro/setup-report.md on each run.
  • Do not fetch from the web. Use frozen snapshots in reference/styleguides/.

Managed Markers

Use these exact markers.

Root AGENTS.md block:

<!-- maestro-setup:start -->
...
<!-- maestro-setup:end -->

Generated context section:

<!-- maestro-setup:generated:start -->
...
<!-- maestro-setup:generated:end -->

If a managed block exists, replace only the block body. If it does not exist, append a new block. Never rewrite the whole file unless the file is new.

Setup Flow

1. Inspect Current State

Read:

  • root AGENTS.md, CLAUDE.md, README*, and package manifests when present
  • manifests such as package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Makefile, CMakeLists.txt, Package.swift
  • config files that reveal lint, format, test, build, and deployment behavior
  • top-level source/test directories and representative file extensions
  • existing .maestro/context/ docs when present

Record every evidence source used for .maestro/setup-report.md.

2. Detect Languages

Detect languages from manifests first, then file extensions. Copy only matched frozen snapshots from reference/styleguides/ to .maestro/context/code_styleguides/.

Use this map:

| Guide | Signals | |---|---| | angularjs.md | AngularJS dependency, angular.module, Angular 1 style files | | common-lisp.md | .lisp, .lsp, .asd | | cpp.md | .cc, .cpp, .cxx, .hh, .hpp, CMakeLists.txt | | csharp.md | .cs, .csproj, .sln | | go.md | go.mod, .go | | html-css.md | .html, .css, .scss, .sass, .less | | javascript.md | .js, .jsx, JavaScript package metadata | | java.md | .java, pom.xml, build.gradle | | json.md | .json, JSON schema files | | markdown.md | .md, .mdx | | objective-c.md | .m, .mm, .h with Objective-C patterns | | python.md | .py, pyproject.toml, requirements.txt, setup.py | | r.md | .R, .r, DESCRIPTION | | shell.md | .sh, .bash, .zsh, shell shebangs | | swift.md | .swift, Package.swift, Xcode Swift targets | | typescript.md | .ts, .tsx, tsconfig.json | | vimscript.md | .vim, .vimrc, Vim plugin metadata | | xml.md | .xml, .xsd, XML schemas |

If Dart or Kotlin is detected, do not copy external guides in v1. Mention that external Dart/Kotlin references were detected but intentionally excluded.

3. Create Or Refresh Context Docs

Ensure .maestro/context/ exists. Create or update these files using the templates in reference/context-templates/:

  • index.md
  • architecture.md
  • product-sense.md
  • quality-gates.md
  • security.md
  • workflow.md
  • planning.md

Each new file must contain:

  1. a generated block using the context managed markers
  2. a ## User Notes section outside the managed block

For existing files, update only the generated block. Preserve all user-written content outside it.

4. Generate Hierarchical AGENTS.md (init-deep)

Run the workflow defined verbatim in reference/init-deep.md. This step owns the root AGENTS.md end-to-end and produces:

  • a root PROJECT KNOWLEDGE BASE AGENTS.md
  • complexity-scored child AGENTS.md files in qualifying subdirectories
  • the <!-- AGENTS-HIERARCHY:START --> block per file linking parent and children

Absorbed Maestro pointer block. The root AGENTS.md body must include the maestro-setup pointer placed immediately after the ## OVERVIEW section, wrapped in the start/end markers (text identical to the prior standalone pointer):

<!-- maestro-setup:start -->
## Maestro Context

Before non-trivial work:
- Load `.maestro/context/index.md` first.
- Open only the specific context docs relevant to the task.
- Follow detected language guides under `.maestro/context/code_styleguides/`.
- Preserve user content outside managed setup sections.
- If context docs conflict with closer repo instructions, follow the closer
  instruction file and report the conflict.
<!-- maestro-setup:end -->

The block content is identical to the prior standalone pointer; only its home moves. Preserve handwritten content elsewhere in the file.

Failure handling. Each background explore agent retries once on failure. Remaining failures degrade to bash + manifest-only scoring. Failed agents and the resulting fallback are listed in .maestro/setup-report.md.

Non-interactive. This step never prompts. Ambiguity becomes a warning in the setup report, not a question to the user.

--create-new is not exposed at the maestro-setup level. Default behavior is non-destructive update: edit AGENTS.md files in place and preserve handwritten content. The destructive mode described in reference/init-deep.md stays internal and is not advertised by this skill.

5. Write Setup Report

Overwrite .maestro/setup-report.md from reference/setup-report-template.md.

The report must include:

  • timestamp
  • files created, updated, and skipped
  • languages detected and guides copied
  • evidence sources used
  • TODOs left in generated docs
  • warnings
  • recommended next action

6. Final Response

Report:

  • what was created or updated
  • detected languages
  • copied guide files
  • notable TODOs or warnings
  • the next command or action the user should take

Do not claim setup is complete unless root AGENTS.md, context docs, language guides, and .maestro/setup-report.md have all been checked.

Context Doc Intent

  • architecture.md: current repo shape, owned modules, boundaries, known pressure points.
  • product-sense.md: audience, product goals, UX/product guardrails.
  • quality-gates.md: build/test/lint/typecheck commands and review bar.
  • security.md: trust boundaries, sensitive files, approval gates.
  • workflow.md: human/agent delivery loop, review expectations, completion bar.
  • planning.md: thin policy bridge to maestro-brainstorm, maestro-plan, .maestro/plans/, maestro-task, and handoff.
  • index.md: map of all context docs and copied style guides.

Future CLI Contract

The later CLI should mirror this skill exactly:

  • maestro setup --dry-run --json
  • maestro setup --json
  • maestro setup check --json
  • maestro setup languages --json

Do not design extra CLI behavior while running this skill.