maestro-flow 0.5.0 → 0.5.2

package/.agents/skills/codify-to-knowhow/phases/03-generate-specs.md

@@ -68,7 +68,8 @@ ${spec.body}
 
   // 追加到目标文件
   // 优先使用 maestro spec add CLI
-  const cliResult = shell(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+  const descFlag = spec.description ? ` --description "${spec.description}"` : '';
+  const cliResult = shell(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
     // 回退：直接追加到文件

package/.agents/skills/manage-knowhow-capture/SKILL.md

@@ -25,7 +25,7 @@ Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --typ
 <context>
 $ARGUMENTS — type token + description + optional flags.
 
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+**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):
 
@@ -44,12 +44,14 @@ $ARGUMENTS — type token + description + optional flags.
 | Short text + `--tag` | tip | TIP- | — |
 | No args | — | — | ask_user (10 options) |
 
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
+**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**:

package/.agy/skills/codify-to-knowhow/phases/03-generate-specs.md

@@ -68,7 +68,8 @@ ${spec.body}
 
   // 追加到目标文件
   // 优先使用 maestro spec add CLI
-  const cliResult = run_command(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+  const descFlag = spec.description ? ` --description "${spec.description}"` : '';
+  const cliResult = run_command(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
     // 回退：直接追加到文件

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

@@ -22,7 +22,7 @@ Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --typ
 <context>
 $ARGUMENTS — type token + description + optional flags.
 
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+**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):
 
@@ -41,12 +41,14 @@ $ARGUMENTS — type token + description + optional flags.
 | Short text + `--tag` | tip | TIP- | — |
 | No args | — | — | ask_question (10 options) |
 
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
+**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**:

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

@@ -23,7 +23,7 @@ Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --typ
 <context>
 $ARGUMENTS — type token + description + optional flags.
 
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+**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):
 
@@ -42,12 +42,14 @@ $ARGUMENTS — type token + description + optional flags.
 | Short text + `--tag` | tip | TIP- | — |
 | No args | — | — | AskUserQuestion (10 options) |
 
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
+**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**:

package/.claude/skills/codify-to-knowhow/phases/03-generate-specs.md

@@ -68,7 +68,8 @@ ${spec.body}
 
   // 追加到目标文件
   // 优先使用 maestro spec add CLI
-  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}" 2>/dev/null`);
+  const descFlag = spec.description ? ` --description "${spec.description}"` : '';
+  const cliResult = Bash(`maestro spec add ${spec.category} "${spec.title}" "${spec.body}" --keywords "${spec.keywords}"${descFlag} 2>/dev/null`);
 
   if (cliResult.exitCode !== 0) {
     // 回退：直接追加到文件

package/.codex/skills/codify-to-knowhow/SKILL.md

@@ -246,7 +246,7 @@ type: ${asset.category}`;
     for (let i = 0; i < asset.entries.length; i++) {
       const entry = asset.entries[i];
       const entryId = `${asset.prefix}-${manifest.slug}-${String(i + 1).padStart(3, '0')}`;
-      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
+      body += `\n\n<knowhow-entry keywords="${entry.category},${entry.keywords}" date="${today}" title="${entry.title}" description="${entry.description || ''}" id="${entryId}" roles="${manifest.roles.join(',')}" source="codify-to-knowhow">
 
 ### ${entry.title}
 

package/.codex/skills/learn-decompose/SKILL.md

@@ -1,144 +1,144 @@
----
-name: learn-decompose
-description: Extract design patterns from code into specs and wiki
-argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
-scan a module, then a cross-reference agent deduplicates against existing patterns and
-produces a catalog. Discovered patterns persist to `.workflow/specs/learnings.md` and optionally to
-specs (via `spec-add`) and wiki.
-
-```
-Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
-```
-</purpose>
-
-<context>
-$ARGUMENTS — target path/module and optional flags.
-
-**Target resolution:**
-- File path → analyze that file
-- Directory path → all source files in it
-- Module name → Glob `src/**/{module}*`
-
-**Flags:**
-- `-y, --yes`: Skip confirmations
-- `-c, --concurrency N`: Max concurrent agents (default: 4)
-- `--continue`: Resume existing session
-- `--patterns <list>`: Comma-separated pattern names to focus on
-- `--save-spec`: Invoke `spec-add` for each new pattern
-- `--save-wiki`: Create wiki note entries per dimension group
-
-**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
-</context>
-
-<invariants>
-1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
-2. **Evidence required**: Every finding must have file:line anchors
-3. **Dedup before persist**: Cross-reference against existing specs + lessons
-4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
-5. **No files modified outside** `.workflow/knowhow/` (and optionally specs/wiki)
-</invariants>
-
-<execution>
-
-### Phase 1: Session Init + Target Resolution
-
-Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
-Extract remaining text as target path/module.
-
-Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro search --category coding`, load relevant entries.
-
-### Phase 2: Wave 1 — Parallel Dimension Scans
-
-Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
-
-| id | dimension | focus |
-|----|-----------|-------|
-| 1 | structural | Class hierarchy, composition, DI, factories, exports |
-| 2 | behavioral | Events, middleware, observer, command, state machines |
-| 3 | data | Repository, DTO, caching, serialization, validation |
-| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
-| 5 | cross-ref | Dedup + catalog from wave 1 findings |
-
-**output_schema** (both waves):
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "id":            { "type": "string" },
-    "result_status": { "type": "string", "enum": ["completed", "failed"] },
-    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
-    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
-    "findings":      { "type": "string", "maxLength": 500 },
-    "error":         { "type": "string" }
-  },
-  "required": ["id", "result_status", "findings"]
-}
-```
-
-Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
-
-**Shared termination contract** (embed in every instruction):
-```
-You MUST call report_agent_job_result EXACTLY ONCE before exiting.
-- Success → result_status=completed (patterns may be empty array if nothing found)
-- Failure → result_status=failed with error message
-- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
-- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
-- Every finding MUST include file:line anchors. No speculation.
-- Read-only analysis. Do NOT modify source.
-Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
-```
-
-Each dimension agent populates `patterns` as a JSON array string of:
-```json
-[{
-  "name": "pattern name",
-  "dimension": "structural|behavioral|data|error",
-  "confidence": "high|medium|low",
-  "anchors": ["file:line"],
-  "description": "what it does",
-  "rationale": "why this approach",
-  "tradeoffs": "what was given up"
-}]
-```
-
-### Phase 3: Wave 2 — Cross-Reference + Catalog
-
-Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
-- Match against dedup set → mark as `documented`, `known`, or `new`
-- Merge duplicates across dimensions (same pattern found by multiple agents)
-- Flag contradictions with documented conventions
-- Build pattern catalog grouped by dimension
-
-### Phase 4: Persist
-
-1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
-2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
-3. If `--save-spec`: invoke `spec-add` per new pattern
-4. If `--save-wiki`: create wiki note per dimension group
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target path not found | Check path or use module name |
-| E002 | error | No source files in target | Check target has .ts/.js files |
-| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
-| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete file list
-- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
-- [ ] Each finding has: name, dimension, confidence, anchors, description
-- [ ] Cross-reference performed (documented / known / new)
-- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
-- [ ] If --save-spec / --save-wiki: entries created
-</success_criteria>
+---
+name: learn-decompose
+description: Extract design patterns from code into specs and wiki
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `.workflow/specs/learnings.md` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/knowhow/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
+Extract remaining text as target path/module.
+
+Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro search --category coding`, load relevant entries.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
+    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (patterns may be empty array if nothing found)
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Every finding MUST include file:line anchors. No speculation.
+- Read-only analysis. Do NOT modify source.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+Each dimension agent populates `patterns` as a JSON array string of:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
+- Match against dedup set → mark as `documented`, `known`, or `new`
+- Merge duplicates across dimensions (same pattern found by multiple agents)
+- Flag contradictions with documented conventions
+- Build pattern catalog grouped by dimension
+
+### Phase 4: Persist
+
+1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target path not found | Check path or use module name |
+| E002 | error | No source files in target | Check target has .ts/.js files |
+| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
+- [ ] Each finding has: name, dimension, confidence, anchors, description
+- [ ] Cross-reference performed (documented / known / new)
+- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -1,83 +1,83 @@
----
-name: learn-follow
-description: Guided reading of code or wiki to extract patterns
-argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Guided reading experience for code files, wiki entries, or topics. Walks through content
-section by section using 4 forcing questions to extract patterns, identify assumptions,
-and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
-
-Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
-deep reading that builds understanding incrementally.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional flags.
-
-**Target resolution (auto-detected):**
-- File path → Read source file
-- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
-- Topic string → Search via `maestro search`, use top result
-
-**Flags:**
-- `--depth shallow` — Key patterns and structure only (default)
-- `--depth deep` — Every function, branch, assumption
-- `--save-wiki` — Create wiki note with reading notes
-
-**Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
-</context>
-
-<execution>
-
-### Stage 1: Resolve Target + Load Context Web
-- File: verify exists, parse imports for dependency files
-- Wiki ID: fetch + load forward/backlinks
-- Topic: search wiki, take top result
-- Build 1-hop context neighborhood (imports/exports or wiki links)
-
-### Stage 2: Build Reading Order
-- Single file: split into logical sections (function/class boundaries)
-- Directory: entry point → core modules → utilities → tests
-- `--depth shallow`: top-level structure only
-- `--depth deep`: every function body, every branch
-
-### Stage 3: Guided Reading (4 Forcing Questions per Section)
-1. **"What pattern is being used here?"** — design patterns, idioms, conventions
-2. **"Why this approach instead of alternatives?"** — trade-offs made
-3. **"What assumption does this depend on?"** — external state, input shape, ordering
-4. **"What would break if this changed?"** — fragility, downstream effects
-
-### Stage 4: Extract Patterns + Produce Understanding Map
-From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
-
-Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
-
-### Stage 5: Persist
-1. Write `KNW-follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
-3. If `--save-wiki`: create wiki note entry
-
-**Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
-| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
-| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
-| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved to concrete content
-- [ ] Context web loaded (imports/exports or wiki links)
-- [ ] All 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors
-- [ ] Understanding map produced with concepts, patterns, assumptions, questions
-- [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
-</success_criteria>
+---
+name: learn-follow
+description: Guided reading of code or wiki to extract patterns
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Walks through content
+section by section using 4 forcing questions to extract patterns, identify assumptions,
+and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
+
+Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
+deep reading that builds understanding incrementally.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → Read source file
+- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
+- Topic string → Search via `maestro search`, use top result
+
+**Flags:**
+- `--depth shallow` — Key patterns and structure only (default)
+- `--depth deep` — Every function, branch, assumption
+- `--save-wiki` — Create wiki note with reading notes
+
+**Output**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target + Load Context Web
+- File: verify exists, parse imports for dependency files
+- Wiki ID: fetch + load forward/backlinks
+- Topic: search wiki, take top result
+- Build 1-hop context neighborhood (imports/exports or wiki links)
+
+### Stage 2: Build Reading Order
+- Single file: split into logical sections (function/class boundaries)
+- Directory: entry point → core modules → utilities → tests
+- `--depth shallow`: top-level structure only
+- `--depth deep`: every function body, every branch
+
+### Stage 3: Guided Reading (4 Forcing Questions per Section)
+1. **"What pattern is being used here?"** — design patterns, idioms, conventions
+2. **"Why this approach instead of alternatives?"** — trade-offs made
+3. **"What assumption does this depend on?"** — external state, input shape, ordering
+4. **"What would break if this changed?"** — fragility, downstream effects
+
+### Stage 4: Extract Patterns + Produce Understanding Map
+From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+
+Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
+
+### Stage 5: Persist
+1. Write `KNW-follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
+3. If `--save-wiki`: create wiki note entry
+
+**Next steps:** `$learn-decompose <path>`, `$spec-add coding ...`, `$learn-second-opinion <file>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
+| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
+| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
+| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content
+- [ ] Context web loaded (imports/exports or wiki links)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Understanding map produced with concepts, patterns, assumptions, questions
+- [ ] `KNW-follow-{slug}-{date}.md` written
+- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
+</success_criteria>