maestro-flow 0.3.14 → 0.3.16

package/workflows/quick.md

@@ -38,38 +38,14 @@ AskUserQuestion(
 Store response as `$DESCRIPTION`.
 If still empty, re-prompt: "Please provide a task description."
 
-Display banner based on active flags:
+Display banner: `WORKFLOW > QUICK TASK` with active flag suffix:
 
-If `$DISCUSS_MODE` and `$FULL_MODE`:
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK (DISCUSS + FULL)
-------------------------------------------------------------
-Discussion + plan checking + verification enabled
-```
-
-If `$DISCUSS_MODE` only:
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK (DISCUSS)
-------------------------------------------------------------
-Discussion phase enabled -- surfacing gray areas before planning
-```
-
-If `$FULL_MODE` only:
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK (FULL MODE)
-------------------------------------------------------------
-Plan checking + verification enabled
-```
-
-Default (no flags):
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK
-------------------------------------------------------------
-```
+| Flags | Banner Suffix | Subtitle |
+|-------|--------------|----------|
+| --discuss + --full | `(DISCUSS + FULL)` | Discussion + plan checking + verification enabled |
+| --discuss only | `(DISCUSS)` | Discussion phase enabled -- surfacing gray areas before planning |
+| --full only | `(FULL MODE)` | Plan checking + verification enabled |
+| none | _(no suffix)_ | _(no subtitle)_ |
 
 ---
 
@@ -239,43 +215,11 @@ Passed inline to planner agent in Step 5.
 
 **Spawn workflow-planner in quick mode:**
 
-```
-Task(
-  prompt="
-<planning_context>
-
-**Mode:** ${FULL_MODE ? 'quick-full' : 'quick'}
-**Directory:** ${QUICK_DIR}
-**Description:** ${DESCRIPTION}
-
-Read these files:
-- .workflow/state.json (Project state)
-- ./CLAUDE.md (Project instructions, if exists)
-
-Project specs (pre-loaded in Step 4.5):
-${specs_content || 'No specs found.'}
-${DISCUSS_MODE ? '- ' + QUICK_DIR + '/context.md (User decisions -- locked)' : ''}
-
-</planning_context>
-
-<constraints>
-- Create a SINGLE plan with 1-3 focused tasks
-- Quick tasks should be atomic and self-contained
-- No research phase
-${FULL_MODE ? '- Target ~40% context usage (structured for verification)' : '- Target ~30% context usage (simple, focused)'}
-${FULL_MODE ? '- Each task MUST have files, action, convergence.criteria, implementation fields' : ''}
-</constraints>
-
-<output>
-Write plan to: ${QUICK_DIR}/plan.json
-Write tasks to: ${QUICK_DIR}/.task/TASK-{NNN}.json
-Return: ## PLANNING COMPLETE with plan path
-</output>
-",
-  subagent_type="workflow-planner",
-  description="Quick plan: ${DESCRIPTION}"
-)
-```
+Spawn `workflow-planner` agent with:
+
+- **Context**: mode (`quick` or `quick-full`), directory, description, state.json, CLAUDE.md, specs, context.md (if discuss mode)
+- **Constraints**: single plan with 1-3 atomic tasks, no research phase. Full mode: ~40% context usage + require files/action/convergence.criteria/implementation per task. Default: ~30% context usage.
+- **Output**: `${QUICK_DIR}/plan.json`, `${QUICK_DIR}/.task/TASK-{NNN}.json`. Return `## PLANNING COMPLETE` with plan path.
 
 After planner returns:
 1. Verify plan.json exists at `${QUICK_DIR}/plan.json`
@@ -299,27 +243,10 @@ Skip entirely if NOT $FULL_MODE.
 Spawning plan checker...
 ```
 
-```
-Task(
-  prompt="
-Verify quick task plan.
-
-Read: ${QUICK_DIR}/plan.json and ${QUICK_DIR}/.task/TASK-*.json
-
-Check dimensions:
-- Requirement coverage: Does the plan address the task description?
-- Task completeness: Do tasks have files, action, convergence.criteria, implementation?
-- Scope sanity: Appropriately sized for quick task (1-3 tasks)?
-${DISCUSS_MODE ? '- Context compliance: Does plan honor decisions from context.md?' : ''}
-
-Return one of:
-- ## VERIFICATION PASSED
-- ## ISSUES FOUND -- structured issue list
-",
-  subagent_type="workflow-plan-checker",
-  description="Check quick plan: ${DESCRIPTION}"
-)
-```
+Spawn `workflow-plan-checker` agent to verify plan.json and TASK-*.json:
+
+- **Check dimensions**: requirement coverage, task completeness (files/action/convergence.criteria/implementation), scope sanity (1-3 tasks), context compliance (if discuss mode).
+- **Return**: `## VERIFICATION PASSED` or `## ISSUES FOUND` with structured issue list.
 
 **Handle checker return:**
 
@@ -344,26 +271,10 @@ If iteration_count >= 2:
 
 **Spawn workflow-executor:**
 
-```
-Task(
-  prompt="
-Execute quick task.
-
-Read:
-- ${QUICK_DIR}/plan.json (Plan)
-- ${QUICK_DIR}/.task/TASK-*.json (Tasks)
-- .workflow/state.json (Project state)
-- ./CLAUDE.md (Project instructions, if exists)
-
-Constraints:
-- Execute all tasks in the plan
-- Commit each task atomically
-- Create summary for each task at: ${QUICK_DIR}/.summaries/TASK-{NNN}-summary.md
-",
-  subagent_type="workflow-executor",
-  description="Execute: ${DESCRIPTION}"
-)
-```
+Spawn `workflow-executor` agent:
+
+- **Read**: plan.json, TASK-*.json, state.json, CLAUDE.md
+- **Constraints**: execute all tasks, atomic commits per task, write summaries to `${QUICK_DIR}/.summaries/TASK-{NNN}-summary.md`
 
 After executor returns:
 1. Verify summaries exist
@@ -385,22 +296,7 @@ Skip entirely if NOT $FULL_MODE.
 Spawning verifier...
 ```
 
-```
-Task(
-  prompt="
-Verify quick task goal achievement.
-Task directory: ${QUICK_DIR}
-Task goal: ${DESCRIPTION}
-
-Read: ${QUICK_DIR}/plan.json and ${QUICK_DIR}/.summaries/
-
-Check plan objectives against actual codebase.
-Write verification result to: ${QUICK_DIR}/verification.json
-",
-  subagent_type="workflow-verifier",
-  description="Verify: ${DESCRIPTION}"
-)
-```
+Spawn `workflow-verifier` agent: check plan objectives against actual codebase using plan.json and summaries. Write result to `${QUICK_DIR}/verification.json`.
 
 Read verification result:
 | Status | Action |
@@ -445,53 +341,8 @@ git commit -m "quick({slug}): ${DESCRIPTION}"
 
 Display completion:
 
-If $FULL_MODE:
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK COMPLETE (FULL MODE)
-------------------------------------------------------------
-
-Quick Task: {$DESCRIPTION}
-
-Summary: ${QUICK_DIR}/.summaries/
-Verification: ${QUICK_DIR}/verification.json ({status})
-Directory: ${QUICK_DIR}
-
-------------------------------------------------------------
-Ready for next task: /workflow:quick
-```
-
-If NOT $FULL_MODE:
-```
-------------------------------------------------------------
-  WORKFLOW > QUICK TASK COMPLETE
-------------------------------------------------------------
-
-Quick Task: {$DESCRIPTION}
-
-Summary: ${QUICK_DIR}/.summaries/
-Directory: ${QUICK_DIR}
-
-------------------------------------------------------------
-Ready for next task: /workflow:quick
-```
-
----
+Display completion banner `WORKFLOW > QUICK TASK COMPLETE` (with `(FULL MODE)` suffix if applicable):
+- Show: Quick Task name, Summary path (`${QUICK_DIR}/.summaries/`), Directory path
+- Full mode also shows: Verification path + status (`${QUICK_DIR}/verification.json`)
+- Footer: `Ready for next task: /workflow:quick`
 
-## Success Criteria
-
-- [ ] --full and --discuss flags parsed from arguments when present
-- [ ] Flags are composable (--discuss --full works)
-- [ ] User provides task description (prompted if missing)
-- [ ] Project validated (state.json exists)
-- [ ] Scratch directory created at .workflow/scratch/quick-{slug}-{date}/
-- [ ] index.json created in scratch dir
-- [ ] (--discuss) Gray areas identified, decisions captured in context.md
-- [ ] (--discuss) context.md honors "All clear" skip and "You decide" discretion
-- [ ] plan.json + .task/TASK-*.json created by planner
-- [ ] (--full) Plan checker validates plan, revision loop capped at 2
-- [ ] .summaries/TASK-*-summary.md created by executor
-- [ ] (--full) verification.json created by verifier
-- [ ] state.json updated with quick task record
-- [ ] Artifacts committed
-- [ ] index.json status set to "completed"

package/workflows/refactor.md

@@ -22,58 +22,17 @@ Output: scratch/refactor-{slug}-{date}/ with index.json + reflection-log.md + .t
 - "all" -> full codebase scan
 - Empty -> prompt user:
 
-```
-AskUserQuestion(
-  header: "Refactoring Scope",
-  question: "What scope should be refactored?",
-  options: [
-    { label: "Module path", description: "e.g., src/auth -- specific directory" },
-    { label: "Feature area", description: "e.g., authentication -- conceptual scope" },
-    { label: "Full codebase", description: "Scan everything for tech debt" }
-  ]
-)
-```
+Prompt user for scope type: module path, feature area, or full codebase.
 
-Generate slug from scope (lowercase, hyphens, max 40 chars).
-Set date to current date (YYYY-MM-DD).
+Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYY-MM-DD.
 
 ---
 
 ### Step 2: Create Scratch Directory
 
-**Create scratch directory and index.json:**
+Create `REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"` with `.task/` and `.summaries/` subdirs.
 
-```bash
-REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"
-mkdir -p "$REFACTOR_DIR/.task"
-mkdir -p "$REFACTOR_DIR/.summaries"
-```
-
-Write index.json:
-```json
-{
-  "id": "refactor-{slug}-{date}",
-  "type": "refactor",
-  "title": "Refactor: {scope description}",
-  "status": "active",
-  "created_at": "{ISO timestamp}",
-  "updated_at": "{ISO timestamp}",
-  "scope": "{original scope argument}",
-  "plan": {
-    "task_ids": [],
-    "task_count": 0
-  },
-  "execution": {
-    "method": "agent",
-    "tasks_completed": 0,
-    "tasks_total": 0
-  },
-  "reflection": {
-    "rounds": 0,
-    "strategy_adjustments": []
-  }
-}
-```
+Write index.json: id, type="refactor", title, status="active", scope, plan (empty task_ids), execution (method=agent, counts=0), reflection (rounds=0).
 
 ---
 
@@ -91,81 +50,28 @@ Used in Step 3 to detect pattern violations against project conventions.
 
 **Analyze scope for tech debt:**
 
-Read all files in scope. Use specs_content (if loaded) to detect convention violations. Identify and categorize issues:
+Read all files in scope. Use specs_content to detect convention violations. Categorize issues:
 
-1. **Duplication** - Repeated code blocks, copy-paste patterns
-2. **Complexity hotspots** - Functions too long, deep nesting, high cyclomatic complexity
-3. **Naming issues** - Inconsistent naming, unclear variable/function names
-4. **Dependency tangles** - Circular deps, tight coupling, god objects
-5. **Dead code** - Unused functions, unreachable branches
-6. **Pattern violations** - Inconsistent with project conventions (from specs/)
+1. **Duplication** - copy-paste patterns
+2. **Complexity** - long functions, deep nesting, high cyclomatic complexity
+3. **Naming** - inconsistent or unclear names
+4. **Dependencies** - circular deps, tight coupling, god objects
+5. **Dead code** - unused functions, unreachable branches
+6. **Pattern violations** - inconsistent with specs/ conventions
 
-Present analysis summary:
-```
-## Scope Analysis: {scope}
-
-| Category | Count | Severity |
-|----------|-------|----------|
-| Duplication | 3 | medium |
-| Complexity | 5 | high |
-| Naming | 8 | low |
-| Dependencies | 2 | high |
-| Dead code | 4 | low |
-
-Total issues: 22
-Recommended priority: Complexity > Dependencies > Duplication > Naming > Dead code
-```
-
-Confirm with user before proceeding to planning.
+Present category/count/severity summary table. Confirm with user before planning.
 
 ---
 
 ### Step 4: Plan Refactoring
 
-**Generate refactoring plan:**
-
-Write plan.json:
-```json
-{
-  "scope": "{scope}",
-  "total_tasks": N,
-  "strategy": "incremental -- each task is independently safe",
-  "tasks": ["TASK-001", "TASK-002", ...]
-}
-```
-
-For each identified issue, create .task/TASK-{NNN}.json:
-```json
-{
-  "id": "TASK-{NNN}",
-  "title": "{specific refactoring}",
-  "status": "pending",
-  "type": "refactor",
-  "category": "duplication|complexity|naming|dependency|dead_code|pattern",
-  "description": "{what to change and why}",
-  "read_first": ["path/to/file.ts", "path/to/related.ts"],
-  "files": [
-    { "path": "path/to/file.ts", "action": "modify", "target": "{function_or_class}", "change": "{concrete_change}" }
-  ],
-  "action": "{detailed steps with concrete values}",
-  "convergence": {
-    "criteria": ["{grep-verifiable completion criterion}"],
-    "verification": "Run existing tests to confirm no regressions"
-  },
-  "implementation": ["{step 1 with concrete values}"],
-  "risk": "low|medium|high"
-}
-```
+Write plan.json (scope, total_tasks, strategy="incremental", task IDs).
 
-Order tasks by: high risk last, dependencies respected, quick wins first.
+For each issue, create `.task/TASK-{NNN}.json`: id, title, status=pending, type=refactor, category, description, read_first (files), files (path/action/target/change), convergence criteria, implementation steps, risk level.
 
-Update index.json plan fields.
+Order: quick wins first, high risk last, dependencies respected. Update index.json plan fields.
 
-**Present plan to user via AskUserQuestion:**
-- Show affected files with proposed changes
-- Highlight risk areas and dependency impacts
-- Ask for approval, modifications, or rejection
-- Capture any additional constraints or priorities
+Present plan to user: affected files, risk areas, dependency impacts. Ask approval/modifications/rejection.
 
 ---
 
@@ -173,128 +79,29 @@ Update index.json plan fields.
 
 **Execute each task with reflection tracking:**
 
-Initialize reflection-log.md:
-```markdown
-# Refactoring Reflection Log
-
-Scope: {scope}
-Started: {ISO timestamp}
-
----
-```
-
-For each task in order:
-
-**5a. Execute the refactoring:**
-Implement the change as described in the task.
+Initialize reflection-log.md (scope, timestamp).
 
-**5b. Run existing tests:**
-```bash
-# Detect and run test suite
-npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1 || echo "No test runner detected"
-```
-
-**5c. Record in reflection-log.md:**
-```markdown
-## Round {N}: {task title}
-
-- **Strategy:** {approach taken}
-- **Result:** {pass|fail} -- {brief outcome}
-- **Tests:** {all pass | N failures}
-- **Adjustment:** {what to change in approach for next round, or "none needed"}
-- **Files changed:** {list}
-
----
-```
-
-**5d. Handle test failures:**
-If tests fail after a refactoring:
-1. Revert the change
-2. Record failure in reflection-log.md with strategy adjustment
-3. Attempt with adjusted strategy (max 2 retries per task)
-4. If still failing, mark task as "blocked" and continue to next
-
-**5e. Update task status:**
-Update .task/TASK-{NNN}.json status to "completed" or "blocked".
-Write .summaries/TASK-{NNN}-summary.md.
-Update index.json execution fields.
-Update reflection.rounds and strategy_adjustments in index.json.
+For each task:
+- **5a.** Implement the refactoring change.
+- **5b.** Run test suite (npm test / pytest / go test).
+- **5c.** Record in reflection-log.md: strategy, result, test status, adjustment needed, files changed.
+- **5d.** On test failure: revert, record, retry with adjusted strategy (max 2 retries). If still failing: mark "blocked", continue.
+- **5e.** Update task status (completed/blocked), write summary, update index.json execution and reflection fields.
 
 ---
 
 ### Step 6: Final Verification
 
-**Run full test suite after all tasks:**
-
-```bash
-npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1
-```
-
-Record final state in reflection-log.md:
-```markdown
-## Final Verification
-
-- **Tests:** {all pass | N failures}
-- **Tasks completed:** {N}/{total}
-- **Tasks blocked:** {N}
-- **Key learnings:** {patterns discovered during refactoring}
-```
+Run full test suite. Record final state in reflection-log.md: test results, tasks completed/blocked, key learnings.
 
 ---
 
 ### Step 7: Complete
 
-**Update index.json and present summary:**
-
-Update index.json:
-```json
-{
-  "status": "completed",
-  "updated_at": "{ISO timestamp}",
-  "execution": {
-    "tasks_completed": N,
-    "tasks_total": M
-  },
-  "reflection": {
-    "rounds": N,
-    "strategy_adjustments": ["list of adjustments made"]
-  }
-}
-```
+Update index.json: status="completed", execution counts, reflection rounds + strategy_adjustments.
 
-Present completion summary:
-```
-## Refactoring Complete: {scope}
-
-| Metric | Value |
-|--------|-------|
-| Tasks completed | {N}/{total} |
-| Tasks blocked | {N} |
-| Reflection rounds | {N} |
-| Strategy adjustments | {N} |
-| Tests passing | {yes/no} |
-
-Key learnings:
-{from reflection-log.md}
-
-Artifacts:
-- Reflection log: {REFACTOR_DIR}/reflection-log.md
-- Task results: {REFACTOR_DIR}/.summaries/
-```
+Present summary: tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings.
+List artifacts: reflection-log.md, .summaries/.
 
-If regressions found: list affected tests and suggest Skill({ skill: "quality-debug" }).
-
----
+If regressions found: list affected tests and suggest quality-debug.
 
-## Success Criteria
-
-- [ ] Scope parsed and validated
-- [ ] Scratch directory created with index.json
-- [ ] Scope analysis identifies tech debt categories
-- [ ] plan.json + .task/TASK-*.json created for each refactoring
-- [ ] Each task executed with test verification (no regressions)
-- [ ] reflection-log.md tracks strategy per round with adjustments
-- [ ] Test failures trigger revert + retry with adjusted strategy
-- [ ] Full test suite passes at end
-- [ ] index.json updated with final status
-- [ ] .summaries/ written for completed tasks