maestro-flow-one 0.2.34 → 0.2.35

package/maestro-flow/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/maestro-flow/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>

package/maestro-flow/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/maestro-flow/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>