maestro-flow 0.3.37 → 0.3.39

package/.claude/commands/manage-harvest.md

@@ -1,94 +1,94 @@
----
-name: manage-harvest
-description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
-
-Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
-
-**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
-- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected):**
-- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
-- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
-- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
-
-Flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
-
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction and classification happen in-memory.
-2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
-3. **Never modify source artifacts** — harvest is purely extractive.
-
-Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
-
-**Next-step routing on completion:**
-- Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
-- Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category learning`
-- Full retrospective → `/quality-retrospective`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
-| E003 | error | Invalid `--source` type | Display valid source types from registry |
-| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
-| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
-| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
-| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
-| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
-| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly resolved (scan / session / path)
-- [ ] Source artifacts discovered and listed with metadata
-- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
-- [ ] All files in selected artifacts loaded and parsed
-- [ ] Knowledge fragments extracted with category, confidence, tags
-- [ ] Fragments filtered by `--min-confidence`
-- [ ] Routing classification applied (auto or forced by `--to`)
-- [ ] Dedup check passed against harvest-log.jsonl and existing stores
-- [ ] If `--dry-run`: preview displayed, no files written
-- [ ] If not dry-run: all routed items written to target stores
-- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
-- [ ] Spec entries added via `spec-add` mechanism
-- [ ] Issue entries appended to `issues.jsonl` with canonical schema
-- [ ] `harvest-log.jsonl` updated with provenance for each routed item
-- [ ] `harvest-report-{date}.md` written with full summary
-- [ ] No source artifacts modified
-- [ ] Summary displayed with counts and next-step routing
-</success_criteria>
+---
+name: manage-harvest
+description: Extract knowledge from artifacts into wiki/spec/issues
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
+
+Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
+
+**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected):**
+- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
+- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
+- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
+
+Flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
+
+**Key invariants:**
+1. **Read-only until Stage 6** — extraction and classification happen in-memory.
+2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
+3. **Never modify source artifacts** — harvest is purely extractive.
+
+Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
+
+**Next-step routing on completion:**
+- Review wiki entries → `maestro wiki list --type note`
+- Connect wiki graph → `/wiki-connect --fix`
+- Triage issues → `/manage-issue list --source harvest`
+- View specs → `/spec-load --category learning`
+- Full retrospective → `/quality-retrospective`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
+| E003 | error | Invalid `--source` type | Display valid source types from registry |
+| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
+| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
+| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
+| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
+| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
+| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / session / path)
+- [ ] Source artifacts discovered and listed with metadata
+- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
+- [ ] All files in selected artifacts loaded and parsed
+- [ ] Knowledge fragments extracted with category, confidence, tags
+- [ ] Fragments filtered by `--min-confidence`
+- [ ] Routing classification applied (auto or forced by `--to`)
+- [ ] Dedup check passed against harvest-log.jsonl and existing stores
+- [ ] If `--dry-run`: preview displayed, no files written
+- [ ] If not dry-run: all routed items written to target stores
+- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
+- [ ] Spec entries added via `spec-add` mechanism
+- [ ] Issue entries appended to `issues.jsonl` with canonical schema
+- [ ] `harvest-log.jsonl` updated with provenance for each routed item
+- [ ] `harvest-report-{date}.md` written with full summary
+- [ ] No source artifacts modified
+- [ ] Summary displayed with counts and next-step routing
+</success_criteria>

package/.claude/commands/manage-issue-discover.md

@@ -1,77 +1,77 @@
----
-name: manage-issue-discover
-description: Automated issue discovery -- multi-perspective analysis or prompt-driven exploration
-argument-hint: "[multi-perspective | by-prompt \"what to look for\"] [-y|--yes] [--scope=src/**] [--depth=standard|deep]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Automated issue discovery via multi-perspective codebase analysis (8 perspectives) or prompt-driven exploration. Discovers issues, deduplicates findings, and records them in `.workflow/issues/issues.jsonl`.
-
-- **Default (no args)**: Interactive mode selection — choose multi-perspective or prompt-driven.
-- **`multi-perspective`**: 8-perspective parallel agent scan — security, performance, reliability, maintainability, scalability, UX, accessibility, compliance.
-- **`by-prompt "..."`**: Prompt-driven — CLI delegate plans exploration strategy, agents explore iteratively with cross-dimension analysis.
-
-For CRUD operations (create, list, update, close, link), use `/manage-issue`.
-
-After discovery, use `/maestro-analyze --gaps <ISS-ID>` to perform root cause analysis on individual findings.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue-discover.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) — read when creating issue records from findings (Step 6/11)
-- [search-tools](~/.maestro/templates/search-tools.md) — search tool priority, passed to agents via workflow
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- optional. Parse first token to determine mode.
-
-**Modes:**
-- _(empty)_ -- interactive mode selection (AskUserQuestion)
-- `multi-perspective` -- 8-perspective parallel agent scan
-- `by-prompt "..."` -- prompt-driven iterative agent exploration (CLI-planned)
-
-**Flags:**
-- `-y` / `--yes` -- auto mode, skip confirmations
-- `--scope=<pattern>` -- file scope (default: `**/*`)
-- `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- issues appended here
-- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
-</context>
-
-<execution>
-Determine mode from $ARGUMENTS:
-- No arguments or empty → interactive selection via AskUserQuestion
-- First token is `multi-perspective` → multi-perspective mode
-- First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
-
-Follow '~/.maestro/workflows/issue-discover.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_PROJECT | error | `.workflow/` does not exist | Prompt user to run `/maestro-init` first |
-| E_DISCOVERY_FAILED | error | CLI analysis returned no results | Retry with different tool or report partial findings |
-| E_EMPTY_PROMPT | warning | `by-prompt` used without prompt text | Interactive prompt with suggested options |
-</error_codes>
-
-<success_criteria>
-- [ ] Discovery mode correctly determined from arguments
-- [ ] All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt)
-- [ ] Findings deduplicated before issue creation
-- [ ] Issues appended to issues.jsonl with correct schema
-- [ ] Discovery session fully traceable via session directory
-- [ ] Next step routing: `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
-</success_criteria>
+---
+name: manage-issue-discover
+description: Discover issues via multi-perspective analysis
+argument-hint: "[multi-perspective | by-prompt \"what to look for\"] [-y|--yes] [--scope=src/**] [--depth=standard|deep]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Automated issue discovery via multi-perspective codebase analysis (8 perspectives) or prompt-driven exploration. Discovers issues, deduplicates findings, and records them in `.workflow/issues/issues.jsonl`.
+
+- **Default (no args)**: Interactive mode selection — choose multi-perspective or prompt-driven.
+- **`multi-perspective`**: 8-perspective parallel agent scan — security, performance, reliability, maintainability, scalability, UX, accessibility, compliance.
+- **`by-prompt "..."`**: Prompt-driven — CLI delegate plans exploration strategy, agents explore iteratively with cross-dimension analysis.
+
+For CRUD operations (create, list, update, close, link), use `/manage-issue`.
+
+After discovery, use `/maestro-analyze --gaps <ISS-ID>` to perform root cause analysis on individual findings.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue-discover.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating issue records from findings (Step 6/11)
+- [search-tools](~/.maestro/templates/search-tools.md) — search tool priority, passed to agents via workflow
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- optional. Parse first token to determine mode.
+
+**Modes:**
+- _(empty)_ -- interactive mode selection (AskUserQuestion)
+- `multi-perspective` -- 8-perspective parallel agent scan
+- `by-prompt "..."` -- prompt-driven iterative agent exploration (CLI-planned)
+
+**Flags:**
+- `-y` / `--yes` -- auto mode, skip confirmations
+- `--scope=<pattern>` -- file scope (default: `**/*`)
+- `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- issues appended here
+- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+</context>
+
+<execution>
+Determine mode from $ARGUMENTS:
+- No arguments or empty → interactive selection via AskUserQuestion
+- First token is `multi-perspective` → multi-perspective mode
+- First token is `by-prompt` → prompt-driven mode, remaining tokens are the user prompt
+
+Follow '~/.maestro/workflows/issue-discover.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_PROJECT | error | `.workflow/` does not exist | Prompt user to run `/maestro-init` first |
+| E_DISCOVERY_FAILED | error | CLI analysis returned no results | Retry with different tool or report partial findings |
+| E_EMPTY_PROMPT | warning | `by-prompt` used without prompt text | Interactive prompt with suggested options |
+</error_codes>
+
+<success_criteria>
+- [ ] Discovery mode correctly determined from arguments
+- [ ] All perspectives analyzed (multi-perspective) or dimensions explored (by-prompt)
+- [ ] Findings deduplicated before issue creation
+- [ ] Issues appended to issues.jsonl with correct schema
+- [ ] Discovery session fully traceable via session directory
+- [ ] Next step routing: `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
+</success_criteria>

package/.claude/commands/manage-issue.md

@@ -1,73 +1,73 @@
----
-name: manage-issue
-description: Issue CRUD operations -- create, query, update, close, and link issues to tasks
-argument-hint: "<create|list|status|update|close|link> [options]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Issue lifecycle management for the project issue tracker. Supports create, list, status, update, close, and link (bidirectional issue-task cross-reference). All issues stored in `.workflow/issues/issues.jsonl` using the issue.json schema.
-
-For automated issue discovery, use `/manage-issue-discover`.
-
-**Closed-loop workflow**: After creating an issue, use `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, `/maestro-plan --gaps` for solution planning, and `/maestro-execute` for execution.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/issue.md
-</required_reading>
-
-<deferred_reading>
-- [issue.json template](~/.maestro/templates/issue.json) — read when creating or updating issue records (create, update, close)
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- subcommand + options. Parse first token as subcommand.
-
-**Valid subcommands:**
-- `create` -- create a new issue (--title, --severity, --source, --phase, --description)
-- `list` -- list issues with optional filters (--status, --phase, --severity, --source)
-- `status` -- show full detail for a specific issue (ISS-XXXXXXXX-NNN)
-- `update` -- update issue fields (ISS-XXXXXXXX-NNN --status, --priority, --severity, --tags, ...)
-- `close` -- close an issue with resolution (ISS-XXXXXXXX-NNN --resolution)
-- `link` -- link issue to a task (ISS-XXXXXXXX-NNN --task TASK-NNN)
-
-**State files:**
-- `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
-- `.workflow/issues/issue-history.jsonl` -- archived/closed issues
-</context>
-
-<execution>
-Parse subcommand from first token of $ARGUMENTS.
-Follow '~/.maestro/workflows/issue.md' completely.
-
-**Next-step routing on completion:**
-- create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
-- list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
-- close → `/manage-status`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E_NO_SUBCOMMAND | error | No subcommand provided in $ARGUMENTS | Display valid subcommands, prompt user to select |
-| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand | Display valid subcommands with usage hints |
-| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` directory does not exist | Auto-create directory and empty issues.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Subcommand parsed and routed to correct handler
-- [ ] Issue data read/written to correct JSONL file
-- [ ] Output displayed in appropriate format (table for list, detail for status)
-- [ ] Cross-references maintained (link creates bidirectional references)
-- [ ] Next step routing by subcommand:
-  - create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
-  - list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
-  - close → `/manage-status`
-</success_criteria>
+---
+name: manage-issue
+description: Create, query, update, close, and link issues
+argument-hint: "<create|list|status|update|close|link> [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Issue lifecycle management for the project issue tracker. Supports create, list, status, update, close, and link (bidirectional issue-task cross-reference). All issues stored in `.workflow/issues/issues.jsonl` using the issue.json schema.
+
+For automated issue discovery, use `/manage-issue-discover`.
+
+**Closed-loop workflow**: After creating an issue, use `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, `/maestro-plan --gaps` for solution planning, and `/maestro-execute` for execution.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/issue.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.maestro/templates/issue.json) — read when creating or updating issue records (create, update, close)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- subcommand + options. Parse first token as subcommand.
+
+**Valid subcommands:**
+- `create` -- create a new issue (--title, --severity, --source, --phase, --description)
+- `list` -- list issues with optional filters (--status, --phase, --severity, --source)
+- `status` -- show full detail for a specific issue (ISS-XXXXXXXX-NNN)
+- `update` -- update issue fields (ISS-XXXXXXXX-NNN --status, --priority, --severity, --tags, ...)
+- `close` -- close an issue with resolution (ISS-XXXXXXXX-NNN --resolution)
+- `link` -- link issue to a task (ISS-XXXXXXXX-NNN --task TASK-NNN)
+
+**State files:**
+- `.workflow/issues/issues.jsonl` -- active issues (one JSON per line)
+- `.workflow/issues/issue-history.jsonl` -- archived/closed issues
+</context>
+
+<execution>
+Parse subcommand from first token of $ARGUMENTS.
+Follow '~/.maestro/workflows/issue.md' completely.
+
+**Next-step routing on completion:**
+- create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+- list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
+- close → `/manage-status`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E_NO_SUBCOMMAND | error | No subcommand provided in $ARGUMENTS | Display valid subcommands, prompt user to select |
+| E_INVALID_SUBCOMMAND | error | Unrecognized subcommand | Display valid subcommands with usage hints |
+| E_ISSUES_DIR_MISSING | warning | `.workflow/issues/` directory does not exist | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed and routed to correct handler
+- [ ] Issue data read/written to correct JSONL file
+- [ ] Output displayed in appropriate format (table for list, detail for status)
+- [ ] Cross-references maintained (link creates bidirectional references)
+- [ ] Next step routing by subcommand:
+  - create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+  - list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
+  - close → `/manage-status`
+</success_criteria>