maestro-flow 0.5.3 → 0.5.31

package/.agy/skills/manage-issue/SKILL.md

@@ -10,63 +10,62 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<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>
+<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>

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

@@ -13,71 +13,73 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<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 (ask_question)
-- `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 ask_question
-- 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>
+<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 (ask_question)
+- `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 ask_question
+- 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/.agy/skills/manage-kg-extractors/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: manage-kg-extractors
+description: Analyze codebase patterns and generate .workflow/kg/extractors.yaml for custom symbol extraction
+argument-hint: [--scan-only] [--append] [--language <lang>]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+
+<purpose>
+Analyze current repository's code patterns to auto-generate `.workflow/kg/extractors.yaml` — a declarative config that teaches MaestroGraph's codegraph extractor to recognize project-specific symbols beyond standard function/class/method declarations.
+
+Detects: builder/factory API registrations, domain constant patterns, custom decorator conventions, framework-specific patterns, module-level constants.
+</purpose>
+
+<context>
+$ARGUMENTS -- optional flags.
+
+**Flags:**
+- `--scan-only` — Only report detected patterns, don't write extractors.yaml
+- `--append` — Append new rules to existing extractors.yaml (default: overwrite)
+- `--language <lang>` — Limit analysis to specific language (python, typescript, java, etc.)
+
+**Analysis targets (per language):**
+
+| Language | Pattern Types |
+|----------|--------------|
+| Python | `define_*()` builder APIs, ALL_CAPS constants, `Final[...]` annotations, dataclass/pydantic fields |
+| TypeScript | const enum, namespace exports, decorator factories, config objects |
+| Java | static final constants, @Bean/@Component annotations, builder patterns |
+| Go | exported constants (const blocks), interface registrations |
+| All | Custom factory/builder call patterns with string-literal first args |
+
+**Output:** `.workflow/kg/extractors.yaml` — declarative rules for PluginEngine.
+
+**Rule format:**
+```yaml
+version: 1
+defaults:
+  onError: warn
+  conflictPolicy: merge-metadata
+plugins:
+  - id: <project>.<pattern>
+    languages: [<lang>]
+    mode: declarative
+    declarative:
+      rules:
+        - id: <rule-id>
+          match:
+            type: call | assignment | regex
+            pattern: "<pattern>"
+            nameRegex: "<optional filter>"
+            scope: module | class | any
+          extract:
+            kind: constant | variable | property | field
+            decorators: ["<semantic_tag>"]
+            metadata:
+              semanticKind: "<domain_kind>"
+```
+</context>
+
+<execution>
+
+### Phase 1: Discover patterns
+
+Spawn **3 parallel agents** to scan the codebase:
+
+| Agent | Focus | Method |
+|-------|-------|--------|
+| Agent 1 | **Builder/factory calls** | Grep for patterns like `define_*("`, `register_*("`, `add_*("` where first arg is a string literal |
+| Agent 2 | **Constants & annotations** | Grep for ALL_CAPS assignments, Final[], static final, const enum, exported const |
+| Agent 3 | **Framework patterns** | Detect framework (from package.json/setup.py/go.mod) → grep framework-specific registration patterns |
+
+Each agent returns: `[{pattern_type, regex_evidence, file_count, sample_matches: [{file, line, code}]}]`
+
+### Phase 2: Generate rules
+
+For each discovered pattern with ≥3 occurrences:
+1. Determine match type (call/assignment/regex)
+2. Build pattern string and optional nameRegex
+3. Assign appropriate kind and semanticKind
+4. Generate rule entry
+
+### Phase 3: Validate & write
+
+1. Show discovered patterns summary to user
+2. ask_question: confirm/edit/skip each pattern group
+3. Write `.workflow/kg/extractors.yaml`
+4. Run `maestro kg index` to verify new symbols are extracted
+
+If `--scan-only`: stop after Phase 2 summary.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verify new symbols | `maestro kg search "<pattern_name>"` |
+| Re-index after changes | `maestro kg index` |
+| View KG stats | `maestro kg stats` |
+| Edit rules manually | Edit `.workflow/kg/extractors.yaml` |
+| Add script plugin | Create `.workflow/kg/extractors/<name>.mjs` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Run maestro-init first |
+| W001 | warning | No patterns detected for language | Try broader scan or different language |
+| W002 | warning | Pattern has < 3 occurrences | Skipped by default, include with --min-count 1 |
+| W003 | warning | Existing extractors.yaml will be overwritten | Use --append to preserve |
+</error_codes>
+
+<success_criteria>
+- [ ] At least 1 pattern detected in the codebase
+- [ ] extractors.yaml generated with valid rules
+- [ ] Each rule has match.type, match.pattern, extract.kind
+- [ ] Re-index succeeds with new extractors.yaml active
+- [ ] New symbols searchable via `maestro kg search`
+</success_criteria>

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

@@ -10,69 +10,73 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Unified memory management across two stores:
-1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts, tips, insights, and all reusable knowledge, created by `manage-knowhow-capture`
-2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
-
-Also scans `.workflow/specs/learnings.md` for legacy insight entries (backward compat with former `manage-learn`).
-
-Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/knowhow.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
-
-**Subcommands:**
-- `list` — List entries from both stores (default if no arguments)
-- `search <query>` — Full-text search across both stores
-- `view <id|file>` — Display a workflow entry by ID or system file by name
-- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
-- `delete <id|file>` — Remove an entry/file (with confirmation)
-- `prune` — Bulk cleanup by criteria
-
-**Flags:**
-- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
-- `--tag <tag>` — Filter by tag (workflow store)
-- `--type <compact|tip>` — Filter by entry type (workflow store)
-- `--before <YYYY-MM-DD>` — Entries before date
-- `--after <YYYY-MM-DD>` — Entries after date
-- `--dry-run` — Preview destructive ops without executing
-- `--confirm` — Skip confirmation prompt
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
-| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
-| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
-| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
-| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
-| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
-| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
-</error_codes>
-
-<success_criteria>
-- [ ] Both store paths correctly resolved
-- [ ] Subcommand correctly detected from arguments
-- [ ] Store auto-detected from argument format (KNW-*/TIP-* vs filename)
-- [ ] List: both stores displayed with appropriate formatting
-- [ ] Search: results from both stores, ranked by relevance
-- [ ] View: correct store selected, full content displayed
-- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
-- [ ] Delete: MEMORY.md protected, confirmation required, references checked
-- [ ] Prune: workflow-only, filters validated, index updated
-- [ ] Integrity check catches orphans and broken links
-- [ ] Next step: `/manage-knowhow-capture compact` to save new knowhow, or `/manage-status` to continue workflow
-</success_criteria>
+<purpose>
+Manage knowhow across two stores: workflow (`.workflow/knowhow/`) and system memory (`~/.claude/projects/*/memory/`). Operations: list, search, view, edit, delete, prune.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Dual store architecture (paths, formats, index) defined in workflow knowhow.md.
+
+**Subcommands:**
+- `list` — List entries from both stores (default if no arguments)
+- `search <query>` — Full-text search across both stores
+- `view <id|file>` — Display a workflow entry by ID or system file by name
+- `edit <file>` — Edit a system memory file (MEMORY.md or topic file)
+- `delete <id|file>` — Remove an entry/file (with confirmation)
+- `prune` — Bulk cleanup by criteria
+
+**Flags:**
+- `--store <workflow|system|all>` — Target store (default: `all` for list/search, inferred for other ops)
+- `--tag <tag>` — Filter by tag (workflow store)
+- `--type <compact|tip>` — Filter by entry type (workflow store)
+- `--before <YYYY-MM-DD>` — Entries before date
+- `--after <YYYY-MM-DD>` — Entries after date
+- `--dry-run` — Preview destructive ops without executing
+- `--confirm` — Skip confirmation prompt
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
+| E002 | error | Entry ID or filename not found | execute_view, execute_delete |
+| E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
+| E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
+| W001 | warning | Workflow index has orphaned files or dangling references | integrity_check |
+| W002 | warning | MEMORY.md references non-existent topic file | integrity_check |
+| W003 | warning | MEMORY.md exceeds 200 lines — content will be truncated at load | execute_edit |
+</error_codes>
+
+<success_criteria>
+- [ ] Both store paths correctly resolved
+- [ ] Subcommand correctly detected from arguments
+- [ ] Store auto-detected from argument format (KNW-*/TIP-* vs filename)
+- [ ] List: both stores displayed with appropriate formatting
+- [ ] Search: results from both stores, ranked by relevance
+- [ ] View: correct store selected, full content displayed
+- [ ] Edit: system memory files editable, MEMORY.md kept under 200 lines
+- [ ] Delete: MEMORY.md protected, confirmation required, references checked
+- [ ] Prune: workflow-only, filters validated, index updated
+- [ ] Integrity check catches orphans and broken links
+- [ ] Next step routed
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Want to capture new knowhow | `/manage-knowhow-capture` |
+| View project state | `/manage-status` |
+| Prune stale entries | `/manage-knowledge-audit --scope knowhow` |
+</completion>