maestro-flow 0.3.43 → 0.3.45

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

@@ -1,151 +1,151 @@
----
-name: quality-refactor
-description: Reduce tech debt with reflection-driven iteration
-argument-hint: "<phase|--dir path> [--max-iterations N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
----
-
-<purpose>
-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.
-</purpose>
-
-<context>
-$ARGUMENTS -- module path, feature area, or "all", plus optional flags.
-
-**Usage**:
-
-```bash
-$quality-refactor "src/auth"                    # module path scope
-$quality-refactor "authentication"              # feature area scope
-$quality-refactor "all"                         # full codebase scan
-$quality-refactor "src/api --max-iterations 5"  # limit iteration rounds
-$quality-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/
-</context>
-
-<invariants>
-1. **Test after every change** -- zero regressions tolerated
-2. **Revert on failure** -- never leave broken state
-3. **Max 2 retries per task** with strategy adjustment
-4. **Reflection-driven** -- every round records strategy, outcome, adjustment
-5. **User approval required** before execution (Step 4)
-6. **Quick wins first** -- order by risk (low first) and dependency
-7. **Agent calls use `run_in_background: false`** for synchronous execution
-8. **Incremental safety** -- each task is independently safe to apply or revert
-</invariants>
-
-<execution>
-
-### 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
-
-Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries/` subdirectories. 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 coding`).
-
-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 to implement the refactoring — read `read_first` files, apply changes to targets, follow convergence criteria exactly.
-
-**5b. Run test suite** (npm test / pytest / go test as appropriate).
-
-**5c. Record in reflection-log.md:** Round number, task title, strategy, result (pass/fail), test outcome, adjustment for next round, files changed.
-
-**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: test result, tasks completed/total, tasks blocked, key learnings.
-
-### Step 7: Complete and Report
-
-Update `index.json`: status -> "completed", final execution/reflection counts.
-
-Display report: scope, tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings from reflection-log.md, artifact paths (`{REFACTOR_DIR}/reflection-log.md`, `{REFACTOR_DIR}/.summaries/`).
-
-**Next-step routing:**
-
-| Result | Next Step |
-|--------|-----------|
-| All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
-| Test failures remain after refactor | `$quality-debug "{scope}"` |
-| No test suite available for scope | `$quality-auto-test "{phase}"` |
-| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
-</execution>
-
-<error_codes>
-| 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 |
-</error_codes>
-
-<success_criteria>
-- [ ] Scope resolved and scratch directory created
-- [ ] Tech debt analysis completed with categorized findings
-- [ ] Refactoring plan approved by user
-- [ ] Each task executed with test verification
-- [ ] Failed changes reverted, retried with adjusted strategy
-- [ ] Reflection log records every round's strategy and outcome
-- [ ] Final test suite passes with zero regressions
-- [ ] Completion report with key learnings displayed
-</success_criteria>
+---
+name: quality-refactor
+description: Reduce tech debt with reflection-driven iteration
+argument-hint: "<phase|--dir path> [--max-iterations N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+---
+
+<purpose>
+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.
+</purpose>
+
+<context>
+$ARGUMENTS -- module path, feature area, or "all", plus optional flags.
+
+**Usage**:
+
+```bash
+$quality-refactor "src/auth"                    # module path scope
+$quality-refactor "authentication"              # feature area scope
+$quality-refactor "all"                         # full codebase scan
+$quality-refactor "src/api --max-iterations 5"  # limit iteration rounds
+$quality-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/
+</context>
+
+<invariants>
+1. **Test after every change** -- zero regressions tolerated
+2. **Revert on failure** -- never leave broken state
+3. **Max 2 retries per task** with strategy adjustment
+4. **Reflection-driven** -- every round records strategy, outcome, adjustment
+5. **User approval required** before execution (Step 4)
+6. **Quick wins first** -- order by risk (low first) and dependency
+7. **Agent calls use `run_in_background: false`** for synchronous execution
+8. **Incremental safety** -- each task is independently safe to apply or revert
+</invariants>
+
+<execution>
+
+### 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
+
+Create `.workflow/scratch/refactor-{slug}-{date}/` with `.task/` and `.summaries/` subdirectories. 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 coding`).
+
+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 to implement the refactoring — read `read_first` files, apply changes to targets, follow convergence criteria exactly.
+
+**5b. Run test suite** (npm test / pytest / go test as appropriate).
+
+**5c. Record in reflection-log.md:** Round number, task title, strategy, result (pass/fail), test outcome, adjustment for next round, files changed.
+
+**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: test result, tasks completed/total, tasks blocked, key learnings.
+
+### Step 7: Complete and Report
+
+Update `index.json`: status -> "completed", final execution/reflection counts.
+
+Display report: scope, tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings from reflection-log.md, artifact paths (`{REFACTOR_DIR}/reflection-log.md`, `{REFACTOR_DIR}/.summaries/`).
+
+**Next-step routing:**
+
+| Result | Next Step |
+|--------|-----------|
+| All tests pass, refactoring complete | `$quality-sync` (update codebase docs) |
+| Test failures remain after refactor | `$quality-debug "{scope}"` |
+| No test suite available for scope | `$quality-auto-test "{phase}"` |
+| Partial completion (some blocked) | `$quality-debug "{scope}"` for blocked tasks |
+</execution>
+
+<error_codes>
+| 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 |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope resolved and scratch directory created
+- [ ] Tech debt analysis completed with categorized findings
+- [ ] Refactoring plan approved by user
+- [ ] Each task executed with test verification
+- [ ] Failed changes reverted, retried with adjusted strategy
+- [ ] Reflection log records every round's strategy and outcome
+- [ ] Final test suite passes with zero regressions
+- [ ] Completion report with key learnings displayed
+</success_criteria>

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

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 <purpose>
 Multi-lens retrospective for completed phases. Context-Agent Fork loads phase artifacts once;
 four parallel lens agents (technical, process, quality, decision) analyze independently;
-synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and lessons.jsonl.
+synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and specs/learnings.md.
 
 ```
 +------------------------------------------------------------------+
@@ -71,8 +71,8 @@ When `-y`: Accept all routing recommendations without prompting. Route all insig
 - `.workflow/specs/{category-file}.md` -- `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` -- appended issue rows (`source: "retrospective"`)
 - `.workflow/knowhow/TIP-*.md` -- knowhow tips (via `manage-knowhow-capture` skill)
-- `.workflow/learning/lessons.jsonl` -- append-only insight log
-- `.workflow/learning/learning-index.json` -- updated searchable index
+- `.workflow/specs/learnings.md` -- append-only insight log
+- Index auto-maintained by WikiIndexer
 
 **Storage read (never modified)** — all resolved via `state.json.artifacts[]`:
 ```
@@ -125,7 +125,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
 9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
-10. **Lessons always written**: Append to `lessons.jsonl` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
+10. **Lessons always written**: Append to `specs/learnings.md` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
 
 <execution>
@@ -250,7 +250,7 @@ Write two files to `{target_dir}/`:
 - **retrospective.json**: phase, slug, timestamp, lenses_run, metrics, findings_by_lens, distilled_insights, routing_summary
 - **retrospective.md**: Header with phase/slug/timestamp, metrics table (tasks completed, test pass rate, review issues, UAT scenarios), findings by lens, distilled insights, routing summary
 
-Append each insight to `.workflow/learning/lessons.jsonl` and update `learning-index.json`.
+Append each insight to `.workflow/specs/learnings.md`.
 
 If `.workflow/specs/learnings.md` already exists, append each insight as `<spec-entry>` (category=`learning`, auto-extract keywords, date=today, source=`retrospective`). Never create the file -- only append if it exists.
 
@@ -287,6 +287,6 @@ Next steps: `$manage-status`, `$manage-issue "list --source retrospective"`, `$m
 - [ ] Synthesizer produces deduplicated insights with stable INS-ids
 - [ ] Routing applied per insight (spec/issue/knowhow/none) with confirmation
 - [ ] retrospective.{md,json} written to phase directory
-- [ ] Lessons appended to lessons.jsonl regardless of --no-route flag
+- [ ] Lessons appended to specs/learnings.md regardless of --no-route flag
 - [ ] Existing retrospective archived before overwrite
 </success_criteria>

package/.codex/skills/spec-add/SKILL.md

@@ -1,101 +1,104 @@
----
-name: spec-add
-description: Add spec entry by category
-argument-hint: "<category> <content>"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-<purpose>
-Add a spec entry using `<spec-entry>` closed-tag format. Each category maps 1:1 to a single target file.
-
-```bash
-$spec-add "coding Always use named exports for utility functions"
-$spec-add "learning Off-by-one in pagination when page=0"
-$spec-add "arch Use Zod for runtime validation over io-ts"
-$spec-add "quality All API endpoints must return structured error objects"
-```
-
-**Valid categories**: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation.
-
-**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
-</purpose>
-
-<context>
-$ARGUMENTS — `<category> <content>` where category selects the target file.
-
-**Category-to-file mapping (1:1, same as spec-load):**
-| Category | Target file |
-|----------|------------|
-| `coding` | `coding-conventions.md` |
-| `arch` | `architecture-constraints.md` |
-| `quality` | `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `learning` | `learnings.md` |
-| `bug` | `learnings.md` |
-| `pattern` | `coding-conventions.md` |
-| `decision` | `architecture-constraints.md` |
-| `rule` | `quality-rules.md` |
-| `validation` | `quality-rules.md` |
-
-Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
-</context>
-
-<execution>
-
-### Step 1: Parse Input
-
-Extract category (first token) and content (remainder) from arguments.
-- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
-- Validate content is non-empty (E001 if missing)
-
-### Step 2: Validate Specs Directory
-
-Verify `.workflow/specs/` exists (E002).
-
-### Step 3: Route to File
-
-Resolve target file from category-to-file mapping table. If the target file does not exist, create it with a basic header.
-
-### Step 4: Extract Keywords
-
-Auto-extract 3-5 relevant keywords from the content. Keywords should be:
-- Lowercase, no spaces (use hyphens for multi-word)
-- Domain-specific terms that would help future lookup
-- Avoid generic words (code, file, function, etc.)
-
-### Step 5: Write Entry
-
-Append `<spec-entry>` closed-tag block to target file:
-
-```markdown
-<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
-
-### {title extracted from content}
-
-{content}
-
-</spec-entry>
-```
-
-### Step 6: Confirm
-
-Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | fatal | Category and content are both required |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
-| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
-</error_codes>
-
-<success_criteria>
-- [ ] Category and content parsed and validated
-- [ ] Keywords auto-extracted from content (3-5 terms)
-- [ ] Entry written in `<spec-entry>` closed-tag format with keywords attribute
-- [ ] Entry appended to correct target file
-- [ ] Confirmation displayed with keywords and verify command
-</success_criteria>
+---
+name: spec-add
+description: Add spec entry by category with role tagging
+argument-hint: "<category> <content>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+Add a spec entry using `<spec-entry>` closed-tag format. Each category maps 1:1 to a single target file.
+
+```bash
+$spec-add "coding Always use named exports for utility functions"
+$spec-add "learning Off-by-one in pagination when page=0"
+$spec-add "arch Use Zod for runtime validation over io-ts"
+$spec-add "quality All API endpoints must return structured error objects"
+```
+
+**Valid categories**: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation.
+
+**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
+</purpose>
+
+<context>
+$ARGUMENTS — `<category> <content>` where category selects the target file.
+
+**Category-to-file mapping (1:1, same as spec-load):**
+| Category | Target file |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `tools` | `tools.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
+
+Category is determined by the first positional argument.
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract category (first token) and content (remainder) from arguments.
+- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
+- Validate content is non-empty (E001 if missing)
+
+### Step 2: Validate Specs Directory
+
+Verify `.workflow/specs/` exists (E002).
+
+### Step 3: Route to File
+
+Resolve target file from category-to-file mapping table. If the target file does not exist, create it with a basic header.
+
+### Step 4: Extract Keywords
+
+Auto-extract 3-5 relevant keywords from the content. Keywords should be:
+- Lowercase, no spaces (use hyphens for multi-word)
+- Domain-specific terms that would help future lookup
+- Avoid generic words (code, file, function, etc.)
+
+### Step 5: Write Entry
+
+Append `<spec-entry>` closed-tag block to target file:
+
+```markdown
+<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
+
+### {title extracted from content}
+
+{content}
+
+</spec-entry>
+```
+
+### Step 6: Confirm
+
+Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Category and content are both required |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "spec-setup" })` first |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and content parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format with keywords attribute
+- [ ] Entry appended to correct target file
+- [ ] Confirmation displayed with keywords and verify command
+</success_criteria>