maestro-flow 0.5.2 → 0.5.31

package/.claude/commands/manage-kg-extractors.md

@@ -0,0 +1,128 @@
+---
+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:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<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. AskUserQuestion: 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/.claude/commands/manage-knowhow-capture.md

@@ -1,82 +1,92 @@
----
-name: manage-knowhow-capture
-description: Capture reusable knowledge as templates, recipes, or tips
-argument-hint: "[<type>] [<description>] [--lang <lang>] [--source <url>] [--tag t1,t2]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<purpose>
-Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
-Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/knowhow.md
-</required_reading>
-
-<context>
-$ARGUMENTS — type token + description + optional flags.
-
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--description <desc>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
-
-**Type routing** (first token match):
-
-| Token | Type | Prefix | Key fields |
-|-------|------|--------|------------|
-| `compact`/`session`/`压缩`/`保存` | compact | KNW- | objective, files, decisions, plan, pending |
-| `template`/`tpl`/`模板` | template | TPL- | language, code block, usage, parameters |
-| `recipe`/`rcp`/`配方`/`步骤` | recipe | RCP- | prerequisites, steps, expected outcome, pitfalls |
-| `reference`/`ref`/`参考`/`引用` | reference | REF- | source URL, key points, scenarios, examples |
-| `decision`/`dcs`/`决策`/`adr` | decision | DCS- | context, alternatives table, rationale, consequences |
-| `tip`/`note`/`记录`/`快速` | tip | TIP- | content, tags |
-| `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
-| `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
-| `document`/`doc`/`文档` | document | DOC- | (general fallback) |
-| `insight`/`ins`/`洞察`/`经验` | insight | INS- | content, tags, phase (replaces former manage-learn) |
-| Short text + `--tag` | tip | TIP- | — |
-| No args | — | — | AskUserQuestion (10 options) |
-
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/knowhow.md' completely.
-
-**Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
-
-**Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
-
-**Type-specific content rules**:
-
-| Type | Content extraction |
-|------|-------------------|
-| compact | Extract from conversation: session ID, objective, execution plan (verbatim), working files (3-8), decisions, constraints, pending. Plan priority: workflow IMPL_PLAN.md > TodoWrite > user-stated > inferred. |
-| template | Ask for: language, code block, parameters (placeholders), usage context, dependencies |
-| recipe | Ask for: goal, prerequisites, numbered steps, expected outcome, common pitfalls |
-| reference | From --source URL or ask. Key points, applicable scenarios, quick examples. Offer WebFetch if URL provided. |
-| decision | Context, alternatives (table: alt/pros/cons/rejected-because), rationale, consequences. Status: proposed/accepted/superseded. |
-| tip | Content = everything after type token. Auto-detect context from recent files. |
-| asset | assetType (api-contract/data-model/prompt/config), codePaths, category for agent discovery |
-| blueprint | Architecture design with codePaths and category |
-</execution>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E002 | Template: no code provided after prompt | Ask again or cancel |
-| E003 | Recipe: no steps provided after prompt | Ask again or cancel |
-| W001 | No active workflow session (compact) | Captures conversation only |
-| W002 | Plan detection found no explicit plan (compact) | Uses inferred plan |
-</error_codes>
-
-<success_criteria>
-- [ ] Type detected or selected, all type-specific fields populated
-- [ ] File written to .workflow/knowhow/ with correct prefix and YAML frontmatter
-- [ ] Confirmation displayed with ID, type, path
-</success_criteria>
+---
+name: manage-knowhow-capture
+description: Capture reusable knowledge as templates, recipes, or tips
+argument-hint: "[<type>] [<description>] [--lang <lang>] [--source <url>] [--tag t1,t2]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
+Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowhow.md
+</required_reading>
+
+<context>
+$ARGUMENTS — type token + description + optional flags.
+
+**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--description <desc>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+
+**Type routing** (first token match):
+
+| Token | Type | Prefix | Key fields |
+|-------|------|--------|------------|
+| `compact`/`session`/`压缩`/`保存` | compact | KNW- | objective, files, decisions, plan, pending |
+| `template`/`tpl`/`模板` | template | TPL- | language, code block, usage, parameters |
+| `recipe`/`rcp`/`配方`/`步骤` | recipe | RCP- | prerequisites, steps, expected outcome, pitfalls |
+| `reference`/`ref`/`参考`/`引用` | reference | REF- | source URL, key points, scenarios, examples |
+| `decision`/`dcs`/`决策`/`adr` | decision | DCS- | context, alternatives table, rationale, consequences |
+| `tip`/`note`/`记录`/`快速` | tip | TIP- | content, tags |
+| `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
+| `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
+| `document`/`doc`/`文档` | document | DOC- | (general fallback) |
+| `insight`/`ins`/`洞察`/`经验` | insight | INS- | content, tags, phase (replaces former manage-learn) |
+| Short text + `--tag` | tip | TIP- | — |
+| No args | — | — | AskUserQuestion (10 options) |
+
+**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/knowhow.md' completely.
+
+**Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
+
+**Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
+
+**Type-specific content rules**:
+
+| Type | Content extraction |
+|------|-------------------|
+| compact | Extract from conversation: session ID, objective, execution plan (verbatim), working files (3-8), decisions, constraints, pending. Plan priority: workflow IMPL_PLAN.md > TodoWrite > user-stated > inferred. |
+| template | Ask for: language, code block, parameters (placeholders), usage context, dependencies |
+| recipe | Ask for: goal, prerequisites, numbered steps, expected outcome, common pitfalls |
+| reference | From --source URL or ask. Key points, applicable scenarios, quick examples. Offer WebFetch if URL provided. |
+| decision | Context, alternatives (table: alt/pros/cons/rejected-because), rationale, consequences. Status: proposed/accepted/superseded. |
+| tip | Content = everything after type token. Auto-detect context from recent files. |
+| asset | assetType (api-contract/data-model/prompt/config), codePaths, category for agent discovery |
+| blueprint | Architecture design with codePaths and category |
+</execution>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Template: no code provided after prompt | Ask again or cancel |
+| E003 | Recipe: no steps provided after prompt | Ask again or cancel |
+| W001 | No active workflow session (compact) | Captures conversation only |
+| W002 | Plan detection found no explicit plan (compact) | Uses inferred plan |
+</error_codes>
+
+<success_criteria>
+- [ ] Type detected or selected, all type-specific fields populated
+- [ ] File written to .workflow/knowhow/ with correct prefix and YAML frontmatter
+- [ ] Confirmation displayed with ID, type, path
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Entry captured | `/manage-knowhow list` to view library |
+| Want to connect entries | `/manage-wiki connect` |
+| Want to bridge to specs | `/spec-add <category>` with `--spec-category` |
+</completion>

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

@@ -1,79 +1,83 @@
----
-name: manage-knowhow
-description: Manage knowhow entries (workflow and system)
-argument-hint: "<subcommand: list|search|view|edit|delete|prune> [query|id] [--store workflow|system|all] [--tag <tag>] [--type compact|tip]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-<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>
+---
+name: manage-knowhow
+description: Manage knowhow entries (workflow and system)
+argument-hint: "<subcommand: list|search|view|edit|delete|prune> [query|id] [--store workflow|system|all] [--tag <tag>] [--type compact|tip]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<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>