maestro-flow 0.3.14 → 0.3.16

package/workflows/knowhow.md

@@ -0,0 +1,374 @@
+# KnowHow Workflow
+
+Reusable knowledge capture, retrieval, and management for cross-session recovery and knowledge reuse.
+
+## Dual Store Architecture
+
+| Store | Path | Format | Index |
+|-------|------|--------|-------|
+| `workflow` | `.workflow/knowhow/` | `{PREFIX}-*.md` (6 prefixes) | `.workflow/wiki-index.json` (unified, WikiIndexer) |
+| `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
+
+**System memory path detection:**
+```bash
+# Derive from project root — replace path separators with '--', prefix drive letter
+# e.g., D:\maestro2 → ~/.claude/projects/D--maestro2/memory/
+```
+
+---
+
+## Content Type Matrix
+
+Six types of knowhow, each with dedicated structure:
+
+| Type | Prefix | Purpose | Trigger |
+|------|--------|---------|---------|
+| `session` | KNW- | Session state recovery | End of complex task, before context switch |
+| `template` | TPL- | Reusable code/config templates | Extracting a pattern, saving boilerplate |
+| `recipe` | RCP- | Step-by-step operational guide | Documenting a workflow, onboarding |
+| `reference` | REF- | External doc / API quick-reference | Importing docs, saving URL summaries |
+| `decision` | DCS- | Architecture Decision Record | Making non-trivial design choices |
+| `tip` | TIP- | Quick note, snippet, reminder | Fleeting insight, debugging trick |
+
+All types share `WikiNodeType = 'knowhow'`. The `category` field distinguishes subtypes in wiki queries.
+
+---
+
+## Part A: KnowHow Management (manage-knowhow)
+
+Operations: list, search, view, edit, delete, prune across both stores.
+
+### Step 1: Resolve Paths
+
+- **Workflow**: `.workflow/knowhow/` (index: `.workflow/wiki-index.json`)
+- **System**: `~/.claude/projects/{project-path}/memory/`
+
+Verify stores exist. Neither → E001.
+
+### Step 2: Parse Input
+
+| Input | Route |
+|-------|-------|
+| No arguments, `list`, `列表`, `ls` | List mode |
+| `search <query>`, `搜索`, `find` | Search mode |
+| `view <id\|file>`, `查看`, `show` | View mode |
+| `edit <file>`, `编辑` | Edit mode (system store only) |
+| `delete <id\|file>`, `删除`, `rm` | Delete mode |
+| `prune`, `清理`, `cleanup` | Prune mode |
+
+**Store auto-detection:** Arguments matching `KNW-*`, `TIP-*`, `TPL-*`, `RCP-*`, `REF-*`, `DCS-*` → workflow store. Other filenames → system store.
+
+### Step 3: List
+
+Workflow: `maestro wiki list --type knowhow --json`, filter by `--tag`, `--type`, `--category`.
+System: Glob `*.md` files, extract titles.
+
+Display: ID/File, Type, Category, Date, Tags, Summary with navigation hints.
+
+### Step 4: Search
+
+Full-text search across both stores. Rank: exact match > heading > content.
+
+### Step 5-9: View, Edit, Delete, Prune, Integrity Check
+
+Same logic as before. Workflow entries managed via WikiWriter; system entries via direct file ops.
+
+---
+
+## Part B: KnowHow Capture (manage-knowhow-capture)
+
+Capture reusable knowledge into `.workflow/knowhow/`.
+
+### Step 1: Detect Type
+
+| Token | Type |
+|-------|------|
+| `compact`, `session`, `压缩` | session |
+| `template`, `tpl`, `模板` | template |
+| `recipe`, `rcp`, `配方`, `步骤` | recipe |
+| `reference`, `ref`, `参考` | reference |
+| `decision`, `dcs`, `决策`, `adr` | decision |
+| `tip`, `note`, `记录` | tip |
+| No arguments | AskUserQuestion (6 options) |
+
+### Step 2: Generate Content by Type
+
+#### session (KNW-{YYYYMMDD}-{HHMM}.md)
+
+Extract from current conversation. Sections:
+
+1. **Session ID** — WFS-* or `manual-{date}`
+2. **Project Root** — Absolute path
+3. **Objective** — High-level goal
+4. **Execution Plan** — Source type + complete verbatim content
+5. **Working Files** — 3-8 modified files with roles, absolute paths
+6. **Reference Files** — Key context files (CLAUDE.md, types, configs)
+7. **Last Action** — Final action + result
+8. **Decisions** — `| Decision | Reasoning |` table
+9. **Constraints** — User-specified limitations
+10. **Dependencies** — Added/changed packages
+11. **Known Issues** — Deferred bugs
+12. **Changes Made** — Completed modifications
+13. **Pending** — Next steps
+14. **Notes** — Unstructured
+
+Plan detection priority: IMPL_PLAN.md > TodoWrite > user-stated > inferred.
+Rules: VERBATIM plan, ABSOLUTE paths, decisions include reasoning.
+
+#### template (TPL-{YYYYMMDD}-{HHMM}.md)
+
+Reusable code or configuration pattern. Sections:
+
+```markdown
+---
+title: {descriptive name}
+type: template
+category: template
+lang: {typescript|python|bash|yaml|...}
+tags: [{comma-separated}]
+created: {ISO timestamp}
+---
+
+# {title}
+
+## Usage
+When and how to use this template.
+
+## Parameters
+| Placeholder | Description | Default |
+|-------------|-------------|---------|
+| `{{name}}` | ... | ... |
+
+## Dependencies
+- package-list
+
+## Code
+```{lang}
+{copy-paste ready code}
+```
+
+## Notes
+Additional context.
+```
+
+**Field guide:**
+- `lang` — Programming language or config format (required)
+- `Usage` — 1-2 sentences describing when to apply
+- `Parameters` — Placeholder table (optional)
+- `Code` — The actual template, ready to copy
+- `Dependencies` — What's needed before using
+
+#### recipe (RCP-{YYYYMMDD}-{HHMM}.md)
+
+Step-by-step operational guide. Sections:
+
+```markdown
+---
+title: {goal summary}
+type: recipe
+category: recipe
+tags: [{comma-separated}]
+created: {ISO timestamp}
+---
+
+# {title}
+
+## Goal
+What this recipe accomplishes.
+
+## Prerequisites
+- Tool/access/config requirements
+
+## Steps
+1. First step
+2. Second step
+...
+
+## Expected Outcome
+What success looks like.
+
+## Common Pitfalls
+- Gotcha 1
+- Gotcha 2
+
+## Related
+- [[recipe-xxx]] — Related recipes
+- [[template-xxx]] — Templates used
+```
+
+**Field guide:**
+- `Goal` — One sentence, actionable
+- `Prerequisites` — Everything needed before starting
+- `Steps` — Numbered, each step verifiable independently
+- `Expected Outcome` — Measurable result
+- `Common Pitfalls` — Known gotchas from experience
+
+#### reference (REF-{YYYYMMDD}-{HHMM}.md)
+
+External documentation digest. Sections:
+
+```markdown
+---
+title: {reference title}
+type: reference
+category: reference
+source: {original URL}
+tags: [{comma-separated}]
+created: {ISO timestamp}
+last_verified: {ISO date}
+---
+
+# {title}
+
+## Source
+{URL or document reference}
+
+## Key Points
+- Essential info point 1
+- Essential info point 2
+
+## Applicable Scenarios
+- When to consult this reference
+
+## Quick Examples
+```lang
+{copy-paste examples}
+```
+
+## Notes
+Additional context.
+```
+
+**Field guide:**
+- `source` — Original URL or document ID (required)
+- `Key Points` — Distilled essentials, not raw dump
+- `Applicable Scenarios` — "Use this when..."
+- `Quick Examples` — Most-used snippets first
+- `last_verified` — When the source was last checked
+
+#### decision (DCS-{YYYYMMDD}-{HHMM}.md)
+
+Architecture Decision Record. Sections:
+
+```markdown
+---
+title: {decision summary}
+type: decision
+category: decision
+status: {proposed|accepted|superseded}
+tags: [{comma-separated}]
+created: {ISO timestamp}
+---
+
+# {title}
+
+## Context
+Background and problem statement.
+
+## Decision
+What was decided.
+
+## Alternatives Considered
+| Alternative | Pros | Cons | Rejected Because |
+|-------------|------|------|------------------|
+| Option A | ... | ... | ... |
+| Option B | ... | ... | ... |
+
+## Rationale
+Why this choice over alternatives.
+
+## Consequences
+### Positive
+- Benefit 1
+
+### Negative
+- Trade-off 1
+
+## Related
+- [[spec-xxx]] — Affected spec
+- [[recipe-xxx]] — Implementation recipe
+```
+
+**Field guide:**
+- `status` — proposed → accepted → superseded lifecycle
+- `Context` — Enough background for future reader (no assumed knowledge)
+- `Alternatives` — Must list at least 2 rejected options with reasons
+- `Rationale` — The "why" matters more than the "what"
+- `Consequences` — Both positive and negative; be honest about trade-offs
+
+#### tip (TIP-{YYYYMMDD}-{HHMM}.md)
+
+Quick note. Minimal structure:
+
+```markdown
+---
+title: {tip summary}
+type: tip
+category: tip
+tags: [{comma-separated}]
+created: {ISO timestamp}
+---
+
+# {title}
+
+{content}
+
+## Context
+{Auto-detected files/modules}
+```
+
+### Step 3: Write File
+
+Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md`.
+
+Frontmatter keys by type:
+
+| Field | session | template | recipe | reference | decision | tip |
+|-------|:-------:|:--------:|:------:|:---------:|:--------:|:---:|
+| title | Y | Y | Y | Y | Y | Y |
+| type | Y | Y | Y | Y | Y | Y |
+| category | Y | Y | Y | Y | Y | Y |
+| tags | Y | Y | Y | Y | Y | Y |
+| created | Y | Y | Y | Y | Y | Y |
+| lang | | Y | | | | |
+| source | | | | Y | | |
+| status | | | | | Y | |
+| last_verified | | | | Y | | |
+
+### Step 4: Report
+
+Display confirmation with ID, type, file path, and type-specific summary line.
+
+---
+
+## Part C: Retrieval
+
+### CLI
+
+```bash
+maestro knowhow list                    # all entries
+maestro knowhow list --type template    # by type
+maestro knowhow search "deploy auth"    # full-text
+maestro knowhow get knowhow-{slug}      # view one
+
+maestro wiki list --type knowhow --json # programmatic
+maestro wiki list --type knowhow --category decision  # decisions only
+```
+
+### MCP
+
+```
+store_knowhow { operation: "search", query: "deploy" }
+store_knowhow { operation: "add", type: "template", title: "...", body: "..." }
+```
+
+### Type Label Reference
+
+| Wiki type | Category | Prefix | Label |
+|-----------|----------|--------|-------|
+| knowhow | session | KNW- | Session |
+| knowhow | tip | TIP- | Tip |
+| knowhow | template | TPL- | Template |
+| knowhow | recipe | RCP- | Recipe |
+| knowhow | reference | REF- | Reference |
+| knowhow | decision | DCS- | Decision |

package/workflows/learn.md

@@ -4,7 +4,9 @@ Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka
 
 Storage:
 - `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with retrospective output)
-- `.workflow/learning/learning-index.json` — searchable index (searchable index)
+- `.workflow/learning/learning-index.json` — searchable index
+
+**Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 
 This workflow does NOT spawn agents or call CLI tools. It is a thin file operation: parse → infer → append → confirm.
 
@@ -30,25 +32,23 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 
 | Flag | Effect |
 |------|--------|
-| `--category <name>` | One of: pattern, antipattern, decision, tool, gotcha, technique. Default: inferred. |
-| `--tag t1,t2` | Comma-separated tags. Always implicitly adds `manual` for capture mode. |
+| `--category <name>` | One of: pattern, antipattern, decision, tool, gotcha, technique, tip. Default: inferred (tip mode defaults to `tip`). |
+| `--tag t1,t2` | Comma-separated tags. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`. |
 | `--phase <N>` | Override auto-detected phase link. Use `--phase 0` to force "no phase". |
-| `--confidence <level>` | high / medium / low. Default: medium. |
+| `--confidence <level>` | high / medium / low. Default: medium (insight), low (tip). |
+| `--lens <name>` | Filter by retrospective lens: technical, process, quality, decision, git (list/search only). |
+| `--limit <N>` | List mode row limit (default 20). |
 
 ---
 
 ## Stage 1: parse_input
 
 ```
-1. Verify .workflow/ exists; else error E001.
-2. Tokenize $ARGUMENTS:
-   - First token determines mode:
-       "list"   → list mode
-       "search" → search mode (next token = query)
-       "show"   → show mode (next token = INS-id)
-       anything else → capture mode (entire quoted text = insight body)
-3. If empty arguments → AskUserQuestion: prompt for insight text.
-4. Validate --category against allowed set; unknown → error E002.
+Verify .workflow/ exists (else E001). Route by first token:
+  "list" → list | "search" → search (next token = query) | "show" → show (next token = INS-id)
+  "tip"  → tip capture (source="tip", category="tip", confidence="low", implicit tag "tip")
+  else   → capture mode (full quoted text = insight body)
+Empty args → AskUserQuestion. Invalid --category → E002.
 ```
 
 ---
@@ -78,26 +78,11 @@ fi
 
 Unless `--phase` is set:
 ```
-phase = null
-phase_slug = null
-
-IF .workflow/state.json exists:
-  state = read JSON
-  artifacts = state.artifacts ?? []
-
-  # Derive current phase from artifacts (first phase with in_progress, or first without completed execute)
-  phase = null
-  inProgressArt = artifacts.find(a => a.type === 'execute' && a.status === 'in_progress')
-  IF inProgressArt:
-    phase = inProgressArt.phase
-  ELSE:
-    phaseNums = [...new Set(artifacts.map(a => a.phase).filter(Boolean))].sort()
-    phase = phaseNums.find(p => !artifacts.some(a => a.phase === p && a.type === 'execute' && a.status === 'completed'))
-
-  IF phase is not null:
-    # Resolve slug from artifact registry
-    art = artifacts.find(a => a.phase === phase)
-    phase_slug = art?.slug ?? "phase-" + phase
+From .workflow/state.json artifacts, detect current phase:
+  1. Find first artifact with type=execute, status=in_progress
+  2. Else find first phase without a completed execute artifact
+  3. Resolve phase_slug from matching artifact (fallback: "phase-{N}")
+If no state.json → phase=null, phase_slug=null
 ```
 
 If `--phase 0` is passed, force `phase = null, phase_slug = null` regardless.
@@ -138,53 +123,15 @@ row = {
 }
 ```
 
-### Step 2.6: Append to lessons.jsonl
-
-```
-Serialize row as single JSON line (no pretty print)
-Append to .workflow/learning/lessons.jsonl
-```
-
-### Step 2.7: Update learning-index.json
-
-```
-Read .workflow/learning/learning-index.json
-Append to entries[]:
-  {
-    id: row.id,
-    type: "insight",
-    timestamp: row.captured_at,
-    file: "lessons.jsonl",
-    summary: row.title,
-    tags: row.tags,
-    lens: null,
-    category: row.category,
-    phase: row.phase,
-    phase_slug: row.phase_slug,
-    confidence: row.confidence,
-    routed_to: "none",
-    routed_id: null
-  }
-Write .workflow/learning/learning-index.json
-```
-
-### Step 2.8: Confirmation banner
+### Step 2.6: Persist
 
-```
-=== INSIGHT CAPTURED ===
-ID:         {INS-id}
-Category:   {category}
-Confidence: {confidence}
-Tags:       {tags joined by ", "}
-Phase:      {phase or "none"}{IF phase_slug: " ({phase_slug})"}
+Append row as single JSON line to `.workflow/learning/lessons.jsonl`.
 
-  {title}
+Update `.workflow/learning/learning-index.json` — append an index entry mirroring key row fields: `id`, `type:"insight"`, `timestamp`, `file:"lessons.jsonl"`, `summary` (=title), `tags`, `lens`, `category`, `phase`, `phase_slug`, `confidence`, `routed_to:"none"`, `routed_id:null`.
 
-File: .workflow/learning/lessons.jsonl
+### Step 2.7: Confirmation banner
 
-To browse: Skill({ skill: "manage-learn", args: "list" })
-To search: Skill({ skill: "manage-learn", args: "search <query>" })
-```
+Display: ID, category, confidence, tags, phase (+slug if present), title, file path, and hints for `list` / `search` commands.
 
 ---
 
@@ -192,19 +139,7 @@ To search: Skill({ skill: "manage-learn", args: "search <query>" })
 
 ### Step 3.1: Read entries
 
-```
-Read .workflow/learning/learning-index.json
-entries = index.entries
-
-Apply filters from flags:
-  --tag t1,t2  → keep entries where any tag matches any filter tag
-  --category X → keep entries where category == X
-  --phase N    → keep entries where phase == N
-  --lens X     → keep entries where lens == X (retrospective insights only)
-
-Sort by timestamp DESCENDING
-Default limit: 20 (override with --limit N)
-```
+Read `.workflow/learning/learning-index.json`. Filter by `--tag`, `--category`, `--phase`, `--lens` flags. Sort by timestamp descending. Limit to 20 (or `--limit N`).
 
 ### Step 3.2: Display table
 
@@ -237,29 +172,11 @@ Capture your first: Skill({ skill: "manage-learn", args: "\"...\"" })
 
 ### Step 4.1: Validate query
 
-```
-query = next token after "search"
-If empty → AskUserQuestion: "What text to search for?"
-```
+Next token after "search". Empty → AskUserQuestion.
 
 ### Step 4.2: Scan lessons.jsonl
 
-```
-matches = []
-FOR each line in .workflow/learning/lessons.jsonl:
-  row = JSON.parse(line)
-  haystack = lower(row.title + " " + row.summary + " " + row.tags.join(" ") + " " + row.category + " " + (row.lens or ""))
-  needle = lower(query)
-  IF haystack contains needle:
-    # Compute simple match rank
-    rank = 0
-    IF row.title contains needle: rank += 3
-    IF row.tags contains needle:  rank += 2
-    IF row.summary contains needle: rank += 1
-    matches.push({ row, rank })
-
-Sort matches by rank DESCENDING, then by captured_at DESCENDING
-```
+Case-insensitive search across each row's `title`, `summary`, `tags`, `category`, `lens`. Rank matches: title match +3, tags +2, summary +1. Sort by rank desc, then captured_at desc.
 
 ### Step 4.3: Display results
 
@@ -289,52 +206,15 @@ List all: Skill({ skill: "manage-learn", args: "list" })
 
 ### Step 5.1: Locate row
 
-```
-target_id = next token after "show"
-If missing → error E003: "Provide an INS-id (e.g. INS-a1b2c3d4)"
-
-row = null
-FOR each line in .workflow/learning/lessons.jsonl:
-  parsed = JSON.parse(line)
-  IF parsed.id == target_id:
-    row = parsed
-    break
-
-IF row is null → error E004: "Insight {target_id} not found"
-```
+Find row matching target INS-id in `lessons.jsonl`. Missing arg → E003. Not found → E004.
 
 ### Step 5.2: Resolve linked phase context (if any)
 
-```
-phase_context = null
-IF row.phase_slug is not null:
-  // Resolve phase dir from artifact registry
-  Read .workflow/state.json → state
-  artifacts = state.artifacts ?? []
-  phase_dir = null
-  art = artifacts.find(a => a.phase === row.phase && a.path)
-  IF art: phase_dir = ".workflow/" + art.path
-
-  IF phase_dir AND directory exists:
-    phase_context = {
-      title: read index.json.title from phase_dir,
-      status: read index.json.status,
-      retrospective_exists: file exists at phase_dir + "/retrospective.md"
-    }
-```
+If `row.phase_slug` set: look up phase directory from `state.json` artifacts, read its `index.json` for title/status, check for `retrospective.md`.
 
 ### Step 5.3: Resolve routed artifact (if any)
 
-```
-routed_path = null
-IF row.routed_id is not null:
-  IF row.routed_to == "spec":
-    routed_path = ".workflow/specs/" + row.routed_id
-  ELIF row.routed_to == "issue":
-    routed_path = ".workflow/issues/issues.jsonl#" + row.routed_id
-  ELIF row.routed_to == "note":
-    routed_path = ".workflow/memory/" + row.routed_id + ".md"
-```
+Map `routed_to` → path: `spec` → `.workflow/specs/{id}`, `issue` → `.workflow/issues/issues.jsonl#{id}`, `note` → `.workflow/knowhow/{id}.md`.
 
 ### Step 5.4: Display
 
@@ -375,38 +255,11 @@ PHASE CONTEXT:
 
 ---
 
-## Error Codes
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first |
-| E002 | error | Unknown `--category` (allowed: pattern, antipattern, decision, tool, gotcha, technique) |
-| E003 | error | `show` mode requires an INS-id argument |
-| E004 | error | Insight id not found in lessons.jsonl |
-| W001 | warning | Auto-phase detection found no matching artifact in registry; phase set to null |
-| W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild |
-
----
-
-## Success Criteria
-
-- [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture mode: `lessons.jsonl` row appended, valid JSON, all required fields present
-- [ ] Capture mode: `learning-index.json` updated with matching entry
-- [ ] Capture mode: phase auto-link resolves correctly from artifact registry
-- [ ] Capture mode: category inference produces a sensible default when --category absent
-- [ ] List mode: filters apply; output sorted newest-first
-- [ ] Search mode: results ranked by title > tags > summary match
-- [ ] Show mode: full insight displayed with phase context and routed artifact link if any
-- [ ] No file modifications outside `.workflow/learning/`
-
----
-
 ## Relationship to other workflows
 
 | Workflow | Relationship |
 |----------|--------------|
 | `quality-retrospective` | Producer. Writes insights into the same `lessons.jsonl` with `source: "retrospective"` and a populated `lens` field. |
-| `manage-memory-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. They share the JSONL+index pattern but live in different directories so retrieval semantics stay clean. |
+| `manage-knowhow-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. They share the JSONL+index pattern but live in different directories so retrieval semantics stay clean. |
 | `phase-transition` | Reader (informally). Phase-transition's free-form `.workflow/specs/learnings.md` is a distinct file with a different audience; do not merge them. |
 | `maestro-plan` | Future consumer. Should query `lessons.jsonl` filtered by tag/lens/category to inform planning decisions. (Out of scope for this command.) |