maestro-flow 0.5.2 → 0.5.31

package/.agents/skills/maestro-update/SKILL.md

@@ -13,109 +13,112 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<purpose>
-Version router — detect current version, run schema migration to latest, then follow the version-specific smart upgrade workflow.
-
-Migration scripts live in two layers:
-- **Schema** (`src/migrations/`): code-level state.json transforms, auto-chained by registry
-- **Workflow** (`~/.maestro/workflows/updates/`): version-specific upgrade guides with environment setup
-
-Schema migrations handle the mechanical version bump. Workflow docs handle the smart part — what the user needs to know, configure, or verify for that version. The router runs schema first, then loads the matching workflow doc.
-</purpose>
-
-<context>
-$ARGUMENTS — optional flags.
-
-**Flags:**
-- `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts
-- `--setup-only` -- Skip schema migration, run only the setup for current version
-
-**Version source:** `.workflow/state.json` → `version` field
-
-**Workflow docs:** `~/.maestro/workflows/updates/`
-- `update-v{TO}-setup.md` — post-migration setup for version {TO}
-
-**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
-</context>
-
-<execution>
-
-### Step 1: Detect Version
-
-```
-1. Read .workflow/state.json → extract version (default "1.0" if missing)
-2. Display:
-   === Maestro Update ===
-   Current version: v{version}
-```
-
-IF `--setup-only`:
-  → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
-  → IF exists: follow that document completely, then EXIT
-  → IF not exists: display "No setup script for v{version}" → EXIT
-
-### Step 2: Check for Updates
-
-```
-1. Run: npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
-2. Parse JSON output
-3. IF status = "up-to-date":
-     Display "Already up to date (v{version})"
-     → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
-     → IF exists: ask_user "Run setup for v{version}?" → load and follow
-     → EXIT
-
-4. Display target:
-   Update available: v{current} → v{target}
-   Schema migrations: {N} step(s) (handled automatically)
-```
-
-IF `--dry-run` → display info and EXIT.
-
-### Step 3: Execute
-
-```
-1. Confirm (unless --force):
-   ask_user: "Upgrade v{current} → v{target}?"
-   Options: [执行 / 取消]
-
-2. Create backup:
-   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
-
-3. Run schema migration (handles all intermediate steps automatically):
-   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
-   Parse result, display changes.
-
-4. IF failed → display backup restore command → EXIT
-
-5. Load version-specific setup:
-   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
-   IF exists → follow completely (hooks, deps, knowledge system config)
-
-6. Display: "v{current} → v{target}: done"
-```
-
-### Step 4: Summary
-
-```
-=== Update Complete ===
-Version: v{current} → v{target}
-Backup:  .workflow/state.json.backup-v{current}-{timestamp}
-
-Next steps:
-  /manage-status  -- Verify project state
-  /maestro        -- Continue workflow
-```
-
-</execution>
-
-<success_criteria>
-- [ ] Current version detected from state.json
-- [ ] Schema migrations run automatically (no manual intermediate steps)
-- [ ] Backup created before migration
-- [ ] Version-specific setup doc loaded and followed (if exists)
-- [ ] --setup-only runs only setup for current version
-- [ ] --dry-run previews without executing
-- [ ] Summary shows version change and backup path
-</success_criteria>
+<purpose>
+Detect current version, run schema migration to latest, then follow the version-specific upgrade workflow.
+Schema (`src/migrations/`) handles transforms; workflow docs (`~/.maestro/workflows/updates/`) handle setup.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts
+- `--setup-only` -- Skip schema migration, run only the setup for current version
+
+**Version source:** `.workflow/state.json` → `version` field
+
+**Workflow docs:** `~/.maestro/workflows/updates/`
+- `update-v{TO}-setup.md` — post-migration setup for version {TO}
+
+**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
+</context>
+
+<execution>
+
+### Step 1: Detect Version
+
+```
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display:
+   === Maestro Update ===
+   Current version: v{version}
+```
+
+IF `--setup-only`:
+  → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+  → IF exists: follow that document completely, then EXIT
+  → IF not exists: display "No setup script for v{version}" → EXIT
+
+### Step 2: Check for Updates
+
+```
+1. Run: npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+2. Parse JSON output
+3. IF status = "up-to-date":
+     Display "Already up to date (v{version})"
+     → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+     → IF exists: ask_user "Run setup for v{version}?" → load and follow
+     → EXIT
+
+4. Display target:
+   Update available: v{current} → v{target}
+   Schema migrations: {N} step(s) (handled automatically)
+```
+
+IF `--dry-run` → display info and EXIT.
+
+### Step 3: Execute
+
+```
+1. Confirm (unless --force):
+   ask_user: "Upgrade v{current} → v{target}?"
+   Options: [执行 / 取消]
+
+2. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
+
+3. Run schema migration (handles all intermediate steps automatically):
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   Parse result, display changes.
+
+4. IF failed → display backup restore command → EXIT
+
+5. Load version-specific setup:
+   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
+   IF exists → follow completely (hooks, deps, knowledge system config)
+
+6. Display: "v{current} → v{target}: done"
+```
+
+### Step 4: Summary
+
+```
+=== Update Complete ===
+Version: v{current} → v{target}
+Backup:  .workflow/state.json.backup-v{current}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] Schema migrations run automatically (no manual intermediate steps)
+- [ ] Backup created before migration
+- [ ] Version-specific setup doc loaded and followed (if exists)
+- [ ] --setup-only runs only setup for current version
+- [ ] --dry-run previews without executing
+- [ ] Summary shows version change and backup path
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Update complete | `/manage-status` to verify project state |
+| Want to continue workflow | `/maestro` |
+</completion>

package/.agents/skills/manage-codebase-rebuild/SKILL.md

@@ -14,74 +14,76 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-
-<purpose>
-Perform a full rebuild of the .workflow/codebase/ documentation system from scratch. Scans the entire project source to identify components, features, requirements, and ADRs, then spawns parallel workflow-codebase-mapper agents to generate all documentation artifacts. This is a destructive operation that overwrites existing codebase docs.
-
-Can run before or after `/maestro-init` -- works on any codebase with source files. Also serves the previous `spec-map` use case via `--focus <area>` for scoped dimension analysis.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-rebuild.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
-- `--force` -- Skip confirmation prompt and proceed directly
-- `--skip-commit` -- Do not auto-commit after rebuild
-
-**Mapper agent assignments (when `--focus` omitted):**
-| Agent | Focus | Output file |
-|-------|-------|-------------|
-| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
-| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
-| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
-| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
-
-**State files:**
-- `.workflow/` -- must be initialized (project.md, state.json exist)
-- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
-- `.workflow/codebase/doc-index.json` -- generated documentation index
-- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
-
-**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
-
-**Next-step routing on completion:**
-- View updated project state → `/manage-status`
-- Incremental updates later → `/quality-sync`
-- Verify KG stats → `maestro kg stats`
-- Verify wiki integration → `maestro search "kg" --type knowhow`
-- Future change impact → `maestro kg diff-wiki`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
-| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
-| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
-| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
-| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
-</error_codes>
-
-<success_criteria>
-- [ ] User confirmed rebuild (or --force used)
-- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
-- [ ] All 4 mapper agents spawned (failures logged as W001)
-- [ ] doc-index.json generated and valid
-- [ ] All documentation files regenerated
-- [ ] state.json updated with rebuild timestamp
-- [ ] project.md Tech Stack section updated if changes detected
-- [ ] KG pipeline executed (`maestro kg index`)
-- [ ] knowledge-graph.json generated in .workflow/codebase/
-- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
-- [ ] Next step routing: `/manage-status` or `/quality-sync` for incremental updates later
-- [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
-</success_criteria>
+
+<purpose>
+Full rebuild of `.workflow/codebase/` docs: 4 parallel mapper agents → tech-stack, architecture, features, concerns. Destructive — overwrites existing docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/codebase-rebuild.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
+- `--force` -- Skip confirmation prompt and proceed directly
+- `--skip-commit` -- Do not auto-commit after rebuild
+
+**Mapper agent assignments (when `--focus` omitted):**
+| Agent | Focus | Output file |
+|-------|-------|-------------|
+| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
+| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
+| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
+
+**State files:**
+- `.workflow/` -- must be initialized (project.md, state.json exist)
+- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
+- `.workflow/codebase/doc-index.json` -- generated documentation index
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
+
+**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| View updated state | `/manage-status` |
+| Incremental updates later | `/quality-sync` |
+| Verify KG stats | `maestro kg stats` |
+| Future change impact | `maestro kg diff-wiki` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
+| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
+| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
+| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
+</error_codes>
+
+<success_criteria>
+- [ ] User confirmed rebuild (or --force used)
+- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
+- [ ] All 4 mapper agents spawned (failures logged as W001)
+- [ ] doc-index.json generated and valid
+- [ ] All documentation files regenerated
+- [ ] state.json updated with rebuild timestamp
+- [ ] project.md Tech Stack section updated if changes detected
+- [ ] KG pipeline executed (`maestro kg index`)
+- [ ] knowledge-graph.json generated in .workflow/codebase/
+- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
+- [ ] Next step routed
+</success_criteria>

package/.agents/skills/manage-harvest/SKILL.md

@@ -14,84 +14,86 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<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>
+<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>