maestro-flow 0.5.2 → 0.5.31

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

@@ -1,95 +1,97 @@
----
-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.
-4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
-
-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 → `/manage-wiki connect --fix`
-- Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --role implement`
-- 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 from workflow artifacts → route to wiki/spec/issue stores. Works on any artifact (vs retrospective which is phase-scoped).
+</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.
+4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
+
+Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Wiki entries created | `maestro wiki list --type note` |
+| Wiki graph needs linking | `/manage-wiki connect --fix` |
+| Issues created | `/manage-issue list --source harvest` |
+| Specs extracted | `/spec-load --role implement` |
+| Full phase retrospective | `/quality-retrospective` |
+</completion>
+
+<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,81 +1,83 @@
----
-name: manage-issue-discover
-description: Discover issues via multi-perspective analysis
-argument-hint: "[multi-perspective | by-prompt <prompt>] [-y] [--scope <glob>] [--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 (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
-- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
-
-### Pre-load specs
-1. **Debug specs**: Run `maestro spec load --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
-2. Optional — proceed without if unavailable.
-</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 <prompt>] [-y] [--scope <glob>] [--depth standard|deep]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Automated issue discovery: multi-perspective (8 perspectives) or prompt-driven. Deduplicates and records to `issues.jsonl`. For CRUD operations, use `/manage-issue`.
+</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 (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
+- `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+
+### Pre-load specs
+1. **Debug specs**: Run `maestro spec load --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
+2. Optional — proceed without if unavailable.
+</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 routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Issues discovered | `/manage-issue list` to review |
+| Need root cause analysis | `/maestro-analyze --gaps <ISS-ID>` |
+| Want to plan fixes | `/maestro-plan --gaps` |
+</completion>

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

@@ -1,73 +1,72 @@
----
-name: manage-issue
-description: Create, query, update, close, and link issues
-argument-hint: "<subcommand: create|list|status|update|close|link> [--title text] [--severity S] [--status S] [--resolution text]"
-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: "<subcommand: create|list|status|update|close|link> [--title text] [--severity S] [--status S] [--resolution text]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Issue lifecycle management: create, list, status, update, close, link. Stored in `.workflow/issues/issues.jsonl`. For automated discovery, use `/manage-issue-discover`.
+</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.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Subcommand | Suggestion |
+|-----------|-----------|
+| create | `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps` |
+| list | `/maestro-analyze --gaps <ISS-ID>` for open issues |
+| close | `/manage-status` |
+</completion>
+
+<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 routed by subcommand
+</success_criteria>