maestro-quick

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

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