maestro-flow 0.1.0 → 0.1.2

package/.codex/skills/quality-refactor/SKILL.md

@@ -1,191 +1,191 @@
----
-name: maestro-refactor
-description: Tech debt reduction with reflection-driven iteration. Analyze scope, plan refactoring, execute with test verification, reflect on strategy per round.
-argument-hint: "<phase|--dir path> [--max-iterations N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
----
-
-# Refactor
-
-## Usage
-
-```bash
-$maestro-refactor "src/auth"                    # module path scope
-$maestro-refactor "authentication"              # feature area scope
-$maestro-refactor "all"                         # full codebase scan
-$maestro-refactor "src/api --max-iterations 5"  # limit iteration rounds
-$maestro-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume existing
-```
-
-**Flags**:
-- `<phase|scope>`: Module path, feature area, or "all"
-- `--dir path`: Resume existing refactor scratch directory
-- `--max-iterations N`: Max refactoring rounds (default: 3)
-
-**Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
-
----
-
-## Overview
-
-Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
-
----
-
-## Implementation
-
-### Step 1: Parse Scope
-
-1. Parse `$ARGUMENTS` for scope and flags
-2. If `--dir` provided: resume existing scratch directory (skip to Step 5)
-3. Scope types:
-   - Module path (e.g., "src/auth") -> scan that directory
-   - Feature area (e.g., "authentication") -> search for related files
-   - "all" -> full codebase scan
-4. If empty: prompt user via AskUserQuestion with options (Module path / Feature area / Full codebase)
-5. Detect `--max-iterations N` (default: 3)
-
-### Step 2: Create Scratch Directory
-
-```bash
-REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"
-mkdir -p "$REFACTOR_DIR/.task"
-mkdir -p "$REFACTOR_DIR/.summaries"
-```
-
-Write `index.json` with type "refactor", scope, status "active", plan/execution/reflection counters.
-
-### Step 3: Scope Analysis
-
-Load project specs if available (`maestro spec load --category execution`).
-
-Analyze scope for tech debt categories:
-
-| Category | What to Look For |
-|----------|-----------------|
-| Duplication | Repeated code blocks, copy-paste patterns |
-| Complexity | Long functions, deep nesting, high cyclomatic complexity |
-| Naming | Inconsistent naming, unclear identifiers |
-| Dependencies | Circular deps, tight coupling, god objects |
-| Dead code | Unused functions, unreachable branches |
-| Pattern violations | Inconsistent with project conventions |
-
-Present analysis summary table with category, count, severity.
-Confirm with user before proceeding.
-
-### Step 4: Plan Refactoring
-
-1. Write `plan.json` with scope, total_tasks, strategy ("incremental -- each task independently safe")
-2. For each identified issue, create `.task/TASK-{NNN}.json`:
-   - id, title, status (pending), type (refactor), category
-   - description, read_first files, files with action/target/change
-   - convergence.criteria (grep-verifiable), verification command
-   - implementation steps, risk level
-3. Order: high risk last, dependencies respected, quick wins first
-4. Update `index.json` plan fields
-5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
-
-### Step 5: Execute with Reflection
-
-Initialize `reflection-log.md` if not exists.
-
-For each task in order:
-
-**5a. Execute refactoring:**
-
-Spawn Agent for complex refactoring tasks:
-```
-Agent({
-  subagent_type: "general-purpose",
-  description: "Execute refactoring: {task title}",
-  prompt: "Implement refactoring as described. Read files in read_first, apply changes to target files. Follow convergence criteria exactly.",
-  run_in_background: false
-})
-```
-
-**5b. Run test suite:**
-```bash
-npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1
-```
-
-**5c. Record in reflection-log.md:**
-```markdown
-## Round {N}: {task title}
-
-- **Strategy:** {approach taken}
-- **Result:** {pass|fail}
-- **Tests:** {all pass | N failures}
-- **Adjustment:** {what to change next, or "none needed"}
-- **Files changed:** {list}
-```
-
-**5d. Handle test failures:**
-1. Revert the change
-2. Record failure + strategy adjustment in reflection-log.md
-3. Retry with adjusted strategy (max 2 retries per task)
-4. If still failing: mark task "blocked", continue to next
-
-**5e. Update state:**
-- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
-- `.summaries/TASK-{NNN}-summary.md` written
-- `index.json` execution and reflection fields updated
-
-### Step 6: Final Verification
-
-Run full test suite. Record final state in reflection-log.md:
-```markdown
-## Final Verification
-
-- **Tests:** {result}
-- **Tasks completed:** {N}/{total}
-- **Tasks blocked:** {N}
-- **Key learnings:** {patterns discovered}
-```
-
-### Step 7: Complete and Report
-
-Update `index.json`: status -> "completed", final execution/reflection counts.
-
-```
-## 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/
-```
-
-If regressions: suggest Skill({ skill: "quality-debug" }).
-
----
-
-## Error Handling
-
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Scope/description required | Prompt user for module path, feature area, or "all" |
-| E002 | error | Test suite not available | Suggest creating tests first, or proceed with manual verification |
-| W001 | warning | Partial test coverage | Note uncovered areas, proceed with extra caution |
-
----
-
-## Core Rules
-
-- **Test after every change** -- zero regressions tolerated
-- **Revert on failure** -- never leave broken state
-- **Max 2 retries per task** with strategy adjustment
-- **Reflection-driven** -- every round records strategy, outcome, adjustment
-- **User approval required** before execution (Step 4)
-- **Quick wins first** -- order by risk (low first) and dependency
-- **Agent calls use `run_in_background: false`** for synchronous execution
-- **Incremental safety** -- each task is independently safe to apply or revert
+---
+name: maestro-refactor
+description: Tech debt reduction with reflection-driven iteration. Analyze scope, plan refactoring, execute with test verification, reflect on strategy per round.
+argument-hint: "<phase|--dir path> [--max-iterations N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+# Refactor
+
+## Usage
+
+```bash
+$maestro-refactor "src/auth"                    # module path scope
+$maestro-refactor "authentication"              # feature area scope
+$maestro-refactor "all"                         # full codebase scan
+$maestro-refactor "src/api --max-iterations 5"  # limit iteration rounds
+$maestro-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume existing
+```
+
+**Flags**:
+- `<phase|scope>`: Module path, feature area, or "all"
+- `--dir path`: Resume existing refactor scratch directory
+- `--max-iterations N`: Max refactoring rounds (default: 3)
+
+**Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
+
+---
+
+## Overview
+
+Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
+
+---
+
+## Implementation
+
+### Step 1: Parse Scope
+
+1. Parse `$ARGUMENTS` for scope and flags
+2. If `--dir` provided: resume existing scratch directory (skip to Step 5)
+3. Scope types:
+   - Module path (e.g., "src/auth") -> scan that directory
+   - Feature area (e.g., "authentication") -> search for related files
+   - "all" -> full codebase scan
+4. If empty: prompt user via AskUserQuestion with options (Module path / Feature area / Full codebase)
+5. Detect `--max-iterations N` (default: 3)
+
+### Step 2: Create Scratch Directory
+
+```bash
+REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"
+mkdir -p "$REFACTOR_DIR/.task"
+mkdir -p "$REFACTOR_DIR/.summaries"
+```
+
+Write `index.json` with type "refactor", scope, status "active", plan/execution/reflection counters.
+
+### Step 3: Scope Analysis
+
+Load project specs if available (`maestro spec load --category execution`).
+
+Analyze scope for tech debt categories:
+
+| Category | What to Look For |
+|----------|-----------------|
+| Duplication | Repeated code blocks, copy-paste patterns |
+| Complexity | Long functions, deep nesting, high cyclomatic complexity |
+| Naming | Inconsistent naming, unclear identifiers |
+| Dependencies | Circular deps, tight coupling, god objects |
+| Dead code | Unused functions, unreachable branches |
+| Pattern violations | Inconsistent with project conventions |
+
+Present analysis summary table with category, count, severity.
+Confirm with user before proceeding.
+
+### Step 4: Plan Refactoring
+
+1. Write `plan.json` with scope, total_tasks, strategy ("incremental -- each task independently safe")
+2. For each identified issue, create `.task/TASK-{NNN}.json`:
+   - id, title, status (pending), type (refactor), category
+   - description, read_first files, files with action/target/change
+   - convergence.criteria (grep-verifiable), verification command
+   - implementation steps, risk level
+3. Order: high risk last, dependencies respected, quick wins first
+4. Update `index.json` plan fields
+5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
+
+### Step 5: Execute with Reflection
+
+Initialize `reflection-log.md` if not exists.
+
+For each task in order:
+
+**5a. Execute refactoring:**
+
+Spawn Agent for complex refactoring tasks:
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "Execute refactoring: {task title}",
+  prompt: "Implement refactoring as described. Read files in read_first, apply changes to target files. Follow convergence criteria exactly.",
+  run_in_background: false
+})
+```
+
+**5b. Run test suite:**
+```bash
+npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1
+```
+
+**5c. Record in reflection-log.md:**
+```markdown
+## Round {N}: {task title}
+
+- **Strategy:** {approach taken}
+- **Result:** {pass|fail}
+- **Tests:** {all pass | N failures}
+- **Adjustment:** {what to change next, or "none needed"}
+- **Files changed:** {list}
+```
+
+**5d. Handle test failures:**
+1. Revert the change
+2. Record failure + strategy adjustment in reflection-log.md
+3. Retry with adjusted strategy (max 2 retries per task)
+4. If still failing: mark task "blocked", continue to next
+
+**5e. Update state:**
+- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
+- `.summaries/TASK-{NNN}-summary.md` written
+- `index.json` execution and reflection fields updated
+
+### Step 6: Final Verification
+
+Run full test suite. Record final state in reflection-log.md:
+```markdown
+## Final Verification
+
+- **Tests:** {result}
+- **Tasks completed:** {N}/{total}
+- **Tasks blocked:** {N}
+- **Key learnings:** {patterns discovered}
+```
+
+### Step 7: Complete and Report
+
+Update `index.json`: status -> "completed", final execution/reflection counts.
+
+```
+## 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/
+```
+
+If regressions: suggest Skill({ skill: "quality-debug" }).
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage | Note uncovered areas, proceed with extra caution |
+
+---
+
+## Core Rules
+
+- **Test after every change** -- zero regressions tolerated
+- **Revert on failure** -- never leave broken state
+- **Max 2 retries per task** with strategy adjustment
+- **Reflection-driven** -- every round records strategy, outcome, adjustment
+- **User approval required** before execution (Step 4)
+- **Quick wins first** -- order by risk (low first) and dependency
+- **Agent calls use `run_in_background: false`** for synchronous execution
+- **Incremental safety** -- each task is independently safe to apply or revert

package/.codex/skills/quality-sync/SKILL.md

@@ -1,89 +1,89 @@
----
-name: maestro-sync
-description: Sync codebase docs after code changes -- traces git diff through component/feature/requirement layers
-argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Sync
-
-## Usage
-
-```bash
-$maestro-sync
-$maestro-sync "--since HEAD~5"
-$maestro-sync "--full"
-$maestro-sync "--dry-run"
-$maestro-sync "--since abc123 --dry-run"
-```
-
-**Flags**:
-- `--full` -- Complete resync of all tracked files (ignores git diff)
-- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
-- `--dry-run` -- Show what would be updated without writing
-
----
-
-## Implementation
-
-### Step 1: Validate
-
-```bash
-test -d .workflow || exit 1  # E001: not initialized
-```
-
-### Step 2: Detect Changes
-
-If `--full`: skip diff, mark all tracked files as changed.
-
-Otherwise:
-1. Read last sync timestamp from `state.json` field `last_synced`
-2. If `--since` provided, use that as baseline
-3. Run `git diff --name-only {baseline} HEAD` to get changed files
-
-If no changes and not `--full`, report clean state (W001) and exit.
-
-### Step 3: Trace Impact Chain
-
-For each changed file, trace through `doc-index.json` impact layers:
-1. **File layer** -- Which doc entries reference this file directly
-2. **Component layer** -- Which components contain this file
-3. **Feature layer** -- Which features depend on affected components
-4. **Requirement layer** -- Which requirements trace to affected features
-
-Build the full set of affected documentation entries.
-
-### Step 4: Update Documentation
-
-If `--dry-run`: display affected entries and exit.
-
-For each affected entry:
-1. Re-read source files
-2. Regenerate the documentation section in `.workflow/codebase/`
-3. Update `doc-index.json` with new timestamp and content hash
-
-### Step 5: Update State
-
-Update `state.json`:
-- `last_synced: "{ISO timestamp}"`
-- `last_synced_commit: "{HEAD commit hash}"`
-
-Update affected `index.json` files in phase directories if task files were modified.
-
-Display summary:
-```
-=== SYNC COMPLETE ===
-Files changed: {N}
-Components affected: {C}
-Features affected: {F}
-Docs updated: {D}
-```
-
----
-
-## Error Handling
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
-| W001 | warning | No changes detected since last sync |
+---
+name: maestro-sync
+description: Sync codebase docs after code changes -- traces git diff through component/feature/requirement layers
+argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Sync
+
+## Usage
+
+```bash
+$maestro-sync
+$maestro-sync "--since HEAD~5"
+$maestro-sync "--full"
+$maestro-sync "--dry-run"
+$maestro-sync "--since abc123 --dry-run"
+```
+
+**Flags**:
+- `--full` -- Complete resync of all tracked files (ignores git diff)
+- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
+- `--dry-run` -- Show what would be updated without writing
+
+---
+
+## Implementation
+
+### Step 1: Validate
+
+```bash
+test -d .workflow || exit 1  # E001: not initialized
+```
+
+### Step 2: Detect Changes
+
+If `--full`: skip diff, mark all tracked files as changed.
+
+Otherwise:
+1. Read last sync timestamp from `state.json` field `last_synced`
+2. If `--since` provided, use that as baseline
+3. Run `git diff --name-only {baseline} HEAD` to get changed files
+
+If no changes and not `--full`, report clean state (W001) and exit.
+
+### Step 3: Trace Impact Chain
+
+For each changed file, trace through `doc-index.json` impact layers:
+1. **File layer** -- Which doc entries reference this file directly
+2. **Component layer** -- Which components contain this file
+3. **Feature layer** -- Which features depend on affected components
+4. **Requirement layer** -- Which requirements trace to affected features
+
+Build the full set of affected documentation entries.
+
+### Step 4: Update Documentation
+
+If `--dry-run`: display affected entries and exit.
+
+For each affected entry:
+1. Re-read source files
+2. Regenerate the documentation section in `.workflow/codebase/`
+3. Update `doc-index.json` with new timestamp and content hash
+
+### Step 5: Update State
+
+Update `state.json`:
+- `last_synced: "{ISO timestamp}"`
+- `last_synced_commit: "{HEAD commit hash}"`
+
+Update affected `index.json` files in phase directories if task files were modified.
+
+Display summary:
+```
+=== SYNC COMPLETE ===
+Files changed: {N}
+Components affected: {C}
+Features affected: {F}
+Docs updated: {D}
+```
+
+---
+
+## Error Handling
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | `.workflow/` not initialized -- run `Skill({ skill: "maestro-init" })` first |
+| W001 | warning | No changes detected since last sync |