maestro-flow 0.5.1 → 0.5.3

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -55,7 +55,7 @@ Update `doc-index.json` timestamps and `state.json.codebase_last_refreshed`. Dis
 | Code | Severity | Description |
 |------|----------|-------------|
 | E001 | fatal | `.workflow/` not initialized |
-| E002 | fatal | No codebase docs exist -- use `Skill({ skill: "codebase-rebuild" })` instead |
+| E002 | fatal | No codebase docs exist -- use `$manage-codebase-rebuild` instead |
 | W001 | warning | No changes detected since last refresh |
 </error_codes>
 

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

@@ -1,99 +1,99 @@
----
-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] [--prune] [--age N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Knowledge extraction from workflow artifacts, routed into three stores: wiki entries,
-spec conventions, and trackable issues. Prevents knowledge loss from completed sessions.
-
-**Closed-loop**: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<context>
-$ARGUMENTS — session-id, path, or empty for scan mode.
-
-**Modes:**
-- No args → `scan`: discover all harvestable artifacts, interactive selection
-- `<session-id>` → `session`: harvest specific session
-- `<path>` → `path`: harvest from explicit directory
-
-**Flags:**
-- `--to <target>` — Force routing: wiki, spec, issue, auto (default: auto)
-- `--source <type>` — Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all
-- `--recent N` — Artifacts within last N days (default: 30)
-- `--dry-run` — Preview without writing
-- `-y` — Skip confirmations
-- `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
-- `--prune` — State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context
-- `--age N` — Graduation age threshold in days (default: 14). Used with `--prune`
-
-**Source registry:**
-| Source | Scan Path | Key Files |
-|--------|-----------|-----------|
-| analysis | `.workflow/.analysis/ANL-*/` | conclusions.json |
-| brainstorm | `.workflow/scratch/brainstorm-*/` | guidance-specification.md |
-| lite-plan | `.workflow/.lite-plan/*/` | plan.json |
-| lite-fix | `.workflow/.lite-fix/*/` | fix-plan.json |
-| debug | `.workflow/.debug/*/` | debug-log.md |
-| scratchpad | `.workflow/.scratchpad/` | *.md |
-| session | `.workflow/active/WFS-*/` | workflow-session.json |
-| learning | `.workflow/specs/` | learnings.md |
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9 (`--prune` mode).
-
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction/classification in-memory only
-2. **Dedup before write** — check harvest-log.jsonl + existing stores
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
-4. **Never modify source artifacts** — purely extractive
-5. **Confidence filtering** — below threshold logged but not routed
-6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `title`, `description`, `keywords`, `date`, `source="harvest"` attributes
-
-**Routing rules:**
-- Universal design patterns → `coding` or `arch` category
-- Component-level pitfalls → `learning` category
-- Quality enforcement rules → `quality` category
-- Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-- Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `Skill({ skill: "spec-add", args: "<category> <content>" })`
-- Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
-
-**Next steps:** `/manage-wiki health`, `maestro search --type note`, `/wiki-connect --fix`, `/wiki-digest`, `/manage-issue list --source harvest`
-
-**Prune mode** (`--prune`): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from `artifacts[]` → `artifact_archive[]`, prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Run $maestro-init |
-| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
-| E003 | error | Invalid --source type | Display valid types |
-| E004 | error | Session ID not found | Show available sessions |
-| W001 | warning | No harvestable artifacts in window | Widen --recent |
-| W003 | warning | Fragments below threshold | Lower --min-confidence |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode resolved (scan / session / path)
-- [ ] Artifacts discovered and parsed
-- [ ] Fragments extracted with category, confidence, tags
-- [ ] Dedup check passed against harvest-log.jsonl and stores
-- [ ] If not dry-run: routed items written to target stores
-- [ ] harvest-log.jsonl updated with provenance
-- [ ] harvest-report-{date}.md written
-- [ ] No source artifacts modified
-- [ ] If --prune: artifacts classified (active/graduated/stale/protected)
-- [ ] If --prune: graduated artifacts → knowhow + artifact_archive[]
-- [ ] If --prune: accumulated_context pruned (resolved deferred/blockers, deduplicated decisions)
-- [ ] If --prune: state.json backed up before modification
-</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] [--prune] [--age N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Knowledge extraction from workflow artifacts, routed into three stores: wiki entries,
+spec conventions, and trackable issues. Prevents knowledge loss from completed sessions.
+
+**Closed-loop**: harvest extracts → stores → downstream consumers (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<context>
+$ARGUMENTS — session-id, path, or empty for scan mode.
+
+**Modes:**
+- No args → `scan`: discover all harvestable artifacts, interactive selection
+- `<session-id>` → `session`: harvest specific session
+- `<path>` → `path`: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: wiki, spec, issue, auto (default: auto)
+- `--source <type>` — Filter: analysis, brainstorm, debug, lite-plan, lite-fix, scratchpad, session, learning, all
+- `--recent N` — Artifacts within last N days (default: 30)
+- `--dry-run` — Preview without writing
+- `-y` — Skip confirmations
+- `--min-confidence N` — Minimum 0.0-1.0 (default: 0.5)
+- `--prune` — State hygiene mode: classify artifacts, graduate harvested → knowhow, archive from state.json, prune accumulated_context
+- `--age N` — Graduation age threshold in days (default: 14). Used with `--prune`
+
+**Source registry:**
+| Source | Scan Path | Key Files |
+|--------|-----------|-----------|
+| analysis | `.workflow/.analysis/ANL-*/` | conclusions.json |
+| brainstorm | `.workflow/scratch/brainstorm-*/` | guidance-specification.md |
+| lite-plan | `.workflow/.lite-plan/*/` | plan.json |
+| lite-fix | `.workflow/.lite-fix/*/` | fix-plan.json |
+| debug | `.workflow/.debug/*/` | debug-log.md |
+| scratchpad | `.workflow/.scratchpad/` | *.md |
+| session | `.workflow/active/WFS-*/` | workflow-session.json |
+| learning | `.workflow/specs/` | learnings.md |
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9 (`--prune` mode).
+
+**Key invariants:**
+1. **Read-only until Stage 6** — extraction/classification in-memory only
+2. **Dedup before write** — check harvest-log.jsonl + existing stores
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)`
+4. **Never modify source artifacts** — purely extractive
+5. **Confidence filtering** — below threshold logged but not routed
+6. **Spec format enforcement** — all spec routing must use `<spec-entry>` closed-tag format with `title`, `description`, `keywords`, `date`, `source="harvest"` attributes
+
+**Routing rules:**
+- Universal design patterns → `coding` or `arch` category
+- Component-level pitfalls → `learning` category
+- Quality enforcement rules → `quality` category
+- Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+- Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `$spec-add "<category> <content>"`
+- Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
+
+**Next steps:** `$manage-wiki health`, `maestro search --type note`, `$wiki-connect --fix`, `$wiki-digest`, `$manage-issue list --source harvest`
+
+**Prune mode** (`--prune`): Classifies artifacts (active/graduated/stale/protected), graduates harvested artifacts to wiki knowhow, archives from `artifacts[]` → `artifact_archive[]`, prunes resolved entries from accumulated_context. Files on disk are never deleted. Always backs up state.json before writing.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run $maestro-init |
+| E002 | error | Invalid --to target | Valid: wiki, spec, issue, auto |
+| E003 | error | Invalid --source type | Display valid types |
+| E004 | error | Session ID not found | Show available sessions |
+| W001 | warning | No harvestable artifacts in window | Widen --recent |
+| W003 | warning | Fragments below threshold | Lower --min-confidence |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode resolved (scan / session / path)
+- [ ] Artifacts discovered and parsed
+- [ ] Fragments extracted with category, confidence, tags
+- [ ] Dedup check passed against harvest-log.jsonl and stores
+- [ ] If not dry-run: routed items written to target stores
+- [ ] harvest-log.jsonl updated with provenance
+- [ ] harvest-report-{date}.md written
+- [ ] No source artifacts modified
+- [ ] If --prune: artifacts classified (active/graduated/stale/protected)
+- [ ] If --prune: graduated artifacts → knowhow + artifact_archive[]
+- [ ] If --prune: accumulated_context pruned (resolved deferred/blockers, deduplicated decisions)
+- [ ] If --prune: state.json backed up before modification
+</success_criteria>

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -2,7 +2,7 @@
 name: manage-issue-discover
 description: Discover issues via multi-perspective analysis
 argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[by-prompt 'what to look for']\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>

package/.codex/skills/manage-knowhow/SKILL.md

@@ -1,95 +1,95 @@
----
-name: manage-knowhow
-description: Manage knowhow entries (workflow and system)
-argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type type]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Manage knowhow entries across workflow and system stores. Provides list, search, view, edit, delete, and prune operations over `.workflow/knowhow/` (workflow store) and `~/.claude/projects/{project}/memory/` (system store).
-</purpose>
-
-<context>
-$ARGUMENTS — subcommand followed by options. Defaults to `list` if no arguments.
-
-```bash
-$manage-knowhow
-$manage-knowhow "list --store workflow"
-$manage-knowhow "search authentication"
-$manage-knowhow "view KNW-20260318-001"
-$manage-knowhow "edit MEMORY.md"
-$manage-knowhow "delete TIP-20260318-001 --confirm"
-$manage-knowhow "prune --before 2026-01-01 --type tip --dry-run"
-```
-
-**Subcommands**: `list`, `search`, `view`, `edit`, `delete`, `prune`.
-
-**Flags**:
-- `--store workflow|system|all` — Target store (default: all)
-- `--tag <tag>` — Filter by tag
-- `--type <session|tip|template|recipe|reference|decision>` — Filter by knowhow type
-- `--confirm` — Skip delete confirmation prompt
-- `--before <date>` / `--after <date>` — Date filters for prune
-- `--dry-run` — Preview prune without deleting
-</context>
-
-<execution>
-
-### Step 1: Resolve Store Paths
-
-- **Workflow store**: `.workflow/knowhow/` (entries: `KNW-*.md`, `TIP-*.md`, `TPL-*.md`, `RCP-*.md`, `REF-*.md`, `DCS-*.md`, indexed in `.workflow/wiki-index.json`)
-- **System store**: `~/.claude/projects/{project}/memory/` (files: `MEMORY.md` + topic `.md` files)
-
-Derive system path from project root (replace path separators with `--`, prefix drive letter).
-
-### Step 2: Parse Subcommand
-
-Default to `list` if no arguments. Parse first token as subcommand.
-
-### Step 3: Execute Subcommand
-
-**list**: Show entries from both stores (or filtered by `--store`, `--tag`, `--type`).
-- Workflow: use `maestro search --type knowhow --json` or read `.workflow/wiki-index.json`, display ID, type, category, date, tags, title
-- System: list `.md` files in system memory directory
-
-**search `<query>`**: Full-text grep across both stores. Rank by match count.
-
-**view `<id|file>`**: Auto-detect store from format (`KNW-*/TIP-*/TPL-*/RCP-*/REF-*/DCS-*` = workflow, else system). Display full content.
-
-**edit `<file>`**: Edit a system memory file. Read current content, apply changes. Warn if MEMORY.md exceeds 200 lines (W003).
-
-**delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file (WikiIndexer auto-updates `.workflow/wiki-index.json` on next access).
-
-**prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. `--dry-run` previews without deleting.
-
-### Step 4: Integrity Check
-
-After write operations, verify:
-- No orphaned files without index entries (W001)
-- No dangling index references to missing files (W001)
-- System MEMORY.md references valid topic files (W002)
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | No stores found — for workflow store run `Skill({ skill: "manage-knowhow-capture" })`; for system store run `Skill({ skill: "manage-memory-capture" })` or create MEMORY.md |
-| E002 | error | Entry ID or filename not found |
-| E003 | error | Prune requires at least one filter flag |
-| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead |
-| W001 | warning | Index has orphaned files or dangling references |
-| W002 | warning | MEMORY.md references non-existent topic file |
-| W003 | warning | MEMORY.md exceeds 200 lines — content truncated at load |
-</error_codes>
-
-<success_criteria>
-- [ ] Store paths resolved correctly for both workflow and system stores
-- [ ] Subcommand parsed and validated (defaults to list)
-- [ ] list: displays entries from selected stores with filtering
-- [ ] search: full-text grep across stores, ranked by match count
-- [ ] view: auto-detects store, displays full content
-- [ ] edit: reads and applies changes to system memory files
-- [ ] delete: requires confirmation, prevents MEMORY.md deletion
-- [ ] prune: requires filter, supports --dry-run, workflow store only
-- [ ] Integrity check after write operations (orphans, dangling refs)
-</success_criteria>
+---
+name: manage-knowhow
+description: Manage knowhow entries (workflow and system)
+argument-hint: "[list|search|view|edit|delete|prune] [query|id|file] [--store workflow|system|all] [--tag tag] [--type type]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Manage knowhow entries across workflow and system stores. Provides list, search, view, edit, delete, and prune operations over `.workflow/knowhow/` (workflow store) and `~/.claude/projects/{project}/memory/` (system store).
+</purpose>
+
+<context>
+$ARGUMENTS — subcommand followed by options. Defaults to `list` if no arguments.
+
+```bash
+$manage-knowhow
+$manage-knowhow "list --store workflow"
+$manage-knowhow "search authentication"
+$manage-knowhow "view KNW-20260318-001"
+$manage-knowhow "edit MEMORY.md"
+$manage-knowhow "delete TIP-20260318-001 --confirm"
+$manage-knowhow "prune --before 2026-01-01 --type tip --dry-run"
+```
+
+**Subcommands**: `list`, `search`, `view`, `edit`, `delete`, `prune`.
+
+**Flags**:
+- `--store workflow|system|all` — Target store (default: all)
+- `--tag <tag>` — Filter by tag
+- `--type <session|tip|template|recipe|reference|decision>` — Filter by knowhow type
+- `--confirm` — Skip delete confirmation prompt
+- `--before <date>` / `--after <date>` — Date filters for prune
+- `--dry-run` — Preview prune without deleting
+</context>
+
+<execution>
+
+### Step 1: Resolve Store Paths
+
+- **Workflow store**: `.workflow/knowhow/` (entries: `KNW-*.md`, `TIP-*.md`, `TPL-*.md`, `RCP-*.md`, `REF-*.md`, `DCS-*.md`, indexed in `.workflow/wiki-index.json`)
+- **System store**: `~/.claude/projects/{project}/memory/` (files: `MEMORY.md` + topic `.md` files)
+
+Derive system path from project root (replace path separators with `--`, prefix drive letter).
+
+### Step 2: Parse Subcommand
+
+Default to `list` if no arguments. Parse first token as subcommand.
+
+### Step 3: Execute Subcommand
+
+**list**: Show entries from both stores (or filtered by `--store`, `--tag`, `--type`).
+- Workflow: use `maestro search --type knowhow --json` or read `.workflow/wiki-index.json`, display ID, type, category, date, tags, title
+- System: list `.md` files in system memory directory
+
+**search `<query>`**: Full-text grep across both stores. Rank by match count.
+
+**view `<id|file>`**: Auto-detect store from format (`KNW-*/TIP-*/TPL-*/RCP-*/REF-*/DCS-*` = workflow, else system). Display full content.
+
+**edit `<file>`**: Edit a system memory file. Read current content, apply changes. Warn if MEMORY.md exceeds 200 lines (W003).
+
+**delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file (WikiIndexer auto-updates `.workflow/wiki-index.json` on next access).
+
+**prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. `--dry-run` previews without deleting.
+
+### Step 4: Integrity Check
+
+After write operations, verify:
+- No orphaned files without index entries (W001)
+- No dangling index references to missing files (W001)
+- System MEMORY.md references valid topic files (W002)
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | No stores found — for workflow store run `$manage-knowhow-capture`; for system store run `$manage-memory-capture` or create MEMORY.md |
+| E002 | error | Entry ID or filename not found |
+| E003 | error | Prune requires at least one filter flag |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead |
+| W001 | warning | Index has orphaned files or dangling references |
+| W002 | warning | MEMORY.md references non-existent topic file |
+| W003 | warning | MEMORY.md exceeds 200 lines — content truncated at load |
+</error_codes>
+
+<success_criteria>
+- [ ] Store paths resolved correctly for both workflow and system stores
+- [ ] Subcommand parsed and validated (defaults to list)
+- [ ] list: displays entries from selected stores with filtering
+- [ ] search: full-text grep across stores, ranked by match count
+- [ ] view: auto-detects store, displays full content
+- [ ] edit: reads and applies changes to system memory files
+- [ ] delete: requires confirmation, prevents MEMORY.md deletion
+- [ ] prune: requires filter, supports --dry-run, workflow store only
+- [ ] Integrity check after write operations (orphans, dangling refs)
+</success_criteria>