# 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

- Skill name: `maestro-quick`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/catlog22/maestro-flow/blob/HEAD/.codex/skills/maestro-quick/SKILL.md
- Repository: catlog22/maestro-flow (463 GitHub stars when collected)

## SKILL.md

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

<purpose>
Shortened pipeline for well-understood tasks. Creates a Run output directory, runs quick analysis, generates a plan, executes tasks, and optionally verifies results. Single agent, sequential flow — no CSV waves needed.

**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.
</purpose>

<context>

```bash
$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.
</context>

<invariants>
1. **Speed over ceremony** — minimal overhead, get to implementation fast
2. **Follow existing patterns** — grep for 3+ similar implementations before writing new code
3. **Optional commits** — commits are only created if the --commit flag is explicitly passed; otherwise, the task completes without staging or committing files
4. **Scratch isolation** — all metadata stays in {run_dir}/outputs/{slug}/
5. **Works without init** — quick tasks function even without full .workflow/ setup
</invariants>

<execution>

### 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).

</execution>

### 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>

| Code | Severity | Description | Recovery |
|------|----------|-------------|----------|
| E001 | error | Task description required | Ask user for description |
| E002 | error | Run output directory creation failed | Check permissions |
| W001 | warning | Verification found minor gaps | Report 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>

---

Source: https://www.openparable.com/skill/productivity/maestro-quick (OpenParable). Cite the canonical URL above.
