OpenParable
Skip to content
← Back to skills

Maestro Quick

Productivity
maestro-quick

Maestro Quick is an Agent Skill for productivity published in the catlog22/maestro-flow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Quick task execution, skip optional agents

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/catlog22/maestro-flow/blob/HEAD/.codex/skills/maestro-quick/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/maestro-quick, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/workflows/codex-run-mode.md </required_reading>

Pipeline: [discuss] → analyze-q → plan → execute → [verify]

Quick tasks default to minimal interaction. --discuss adds a decision extraction step. --full adds plan-checking and post-execution verification.

$maestro-quick "add rate limiting to /api/auth endpoints"
$maestro-quick "refactor user service to use repository pattern" --discuss
$maestro-quick "fix memory leak in WebSocket handler" --full
$maestro-quick "add dark mode toggle to settings page" --discuss --full

Flags:

  • --discuss: Decision extraction before planning (Locked/Free/Deferred classification)
  • --full: Enable plan-checking (max 2 iterations) and post-execution verification
  • --commit: Commit the changes at the end of the task
  • -y: Auto mode: skip confirmation and commit automatically when --commit is used

Output: {run_dir}/outputs/{slug}/ with plan.json, execution results, optional verification

Output boundary: ALL metadata writes MUST target {run_dir}/outputs/{slug}/. Source code modifications are scoped to files identified in the plan. NEVER modify unrelated source files or .workflow/state.json structure beyond Run tasks entries.

Phase Gates (MANDATORY, BLOCKING)

GATE 1: Parse → Context

  • REQUIRED: Task description provided (non-empty).
  • BLOCKED if: empty description (E001).

GATE 2: Analysis → Plan

  • REQUIRED: Quick analysis completed with related files identified.
  • REQUIRED: Existing patterns found (≥1 similar implementation).
  • BLOCKED if: Run output directory creation failed (E002).

GATE 3: Execute → Report

  • REQUIRED: All plan tasks attempted and statuses recorded.
  • REQUIRED: plan.json updated with task outcomes.
  • BLOCKED if: plan.json missing or no task statuses.

Step 1: Parse Arguments

Extract from arguments:

  • --discuss flag
  • --full flag
  • Remaining text as task description (required — E001 if empty)

Step 2: Load Project Context

Read .workflow/state.json and .workflow/project.md if they exist. If .workflow/ does not exist, create minimal scratch structure anyway (quick works without full init).

Load coding specs + tools if available: maestro load --type spec --category coding. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run maestro load --type spec --category ui. Browse wiki: maestro search --category coding, load relevant entries via maestro load --type knowhow --id <id>. All optional — proceed without if unavailable.

Step 3: Create Run output directory

Generate slug from task description (lowercase, hyphens, max 40 chars). Create {run_dir}/outputs/{slug}/. Write config.json with: task, flags (discuss, full), created_at (ISO), status ("active").

Step 4: Discussion Phase (if --discuss)

Only when --discuss is set.

Analyze the task for gray areas and ambiguities:

  1. Identify decision points in the task
  2. Classify each as: Locked (clear from context), Free (implementation choice), Deferred (need user input)
  3. For Deferred items: ask user for decisions
  4. Write context.md to Run output directory with all decisions

Step 5: Quick Analysis

Rapid codebase exploration focused on the task:

  1. Search for related files using maestro explore (preferred, fallback Grep/Glob)
  2. Identify existing patterns to follow
  3. Map dependencies and integration points
  4. Write analysis findings to context.md (append if --discuss created it)

Step 6: Generate Plan

Create plan.json in Run output directory:

  • Decompose task into subtasks (typically 1-5 for quick tasks)
  • Each task has: id, title, description, scope, convergence_criteria, files
  • Assign single wave (sequential execution)

If --full: Present plan for review, allow up to 2 revision iterations.

Step 7: Execute Tasks

For each task in plan.json (sequential):

  1. Read task definition
  2. Implement changes following existing patterns
  3. Run any specified verification commands
  4. Write task summary with files_modified, status

Update plan.json task statuses as completed.

Step 8: Verification (if --full)

Only when --full is set. Run convergence criteria checks for each task via grep/test commands. If gaps found (W001): attempt single fix iteration, then report remaining gaps.

Step 9: Commit and Report

Stage only files modified during this skill execution (tracked via task summaries). Display the file list for user confirmation before committing (skip confirmation if -y). Commit: git add <file1> <file2> ... && git commit -m "quick: {slug} - {short description}". NEVER use git add -A — it may stage unrelated changes. Update .workflow/state.json Run tasks entry (if state.json exists).

Display report: task description, scratch path, status (completed/completed-with-gaps), tasks completed/total, files modified count. If --full: include verification result (PASS/GAPS).

Artifact Verification

Before reporting completion, verify: {scratchDir}/plan.json exists AND {scratchDir}/plan.json contains task statuses marked completed. Task status entries MUST include concrete evidence of completion (files_modified, verification results). If missing: DO NOT report completion.

<error_codes>

CodeSeverityDescriptionRecovery
E001errorTask description requiredAsk user for description
E002errorRun output directory creation failedCheck permissions
W001warningVerification found minor gapsReport gaps, continue

</error_codes>

<success_criteria>

  • Run output directory created with config.json
  • Analysis completed and context.md written
  • Plan generated with subtasks
  • All tasks executed and statuses updated
  • Changes committed (only if --commit is set): confirm with ask_user showing staged files and proposed commit message — unless -y is active, in which case auto-commit
  • Completion report displayed </success_criteria>