maestro-flow 0.3.46 → 0.3.47

package/.claude/agents/ui-design-agent.md

@@ -41,6 +41,7 @@ STEP 1: Identify Task Pattern
 
 STEP 2: Load Context
 → Read input data specified in task prompt
+→ Load existing UI conventions: `maestro spec load --category ui` (if available, respect established design tokens and component patterns)
 → Validate BASE_PATH and output directory structure
 
 STEP 3: Execute Pattern-Specific Generation

package/.claude/agents/workflow-executor.md

@@ -58,6 +58,9 @@ You implement a single task from the execution plan. Each task is executed atomi
   - Quality rules (enforcement criteria)
   - All specs with `readMode: required` and `category: execution`
   - **Must comply**: All generated code must follow loaded spec constraints
+- **UI specs (conditional)** -- If task involves frontend/UI work (focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`, or description contains UI keywords), also load via `maestro spec load --category ui`:
+  - Design tokens, component conventions, visual system constraints
+  - PRODUCT.md/DESIGN.md references
 - Prior task summaries from `.summaries/` (for context on dependencies)
 - `context.md` -- Phase context with Locked/Free/Deferred decisions (read to understand constraints before implementing)
 - `analysis.md` -- Phase analysis with 6-dimension scores (reference for quality expectations)

package/.claude/commands/learn-decompose.md

@@ -12,160 +12,105 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Systematic pattern extraction from code. Analyzes a module or directory across 4 dimensions (structural, behavioral, data, error) using parallel agents, then catalogs findings with code anchors. Discovered patterns can be persisted to specs (via `spec-add`) and wiki (via `maestro wiki create`).
-
-Unlike `learn-follow` which reads code with forcing questions, this command is purpose-built for pattern identification and cataloging. It produces a reusable pattern catalog that feeds into the spec system.
+Systematic pattern extraction: analyze module across 4 dimensions using parallel agents, catalog findings with code anchors, persist to specs/wiki. Produces reusable pattern catalog.
 </purpose>
 
 <context>
-Arguments: $ARGUMENTS
-
-**Target resolution:**
-- File path → analyze that file
-- Directory path → analyze all source files in it
-- Module name → Glob for matching directory under `src/`
-
-**Flags:**
-- `--patterns <list>` — Comma-separated pattern names to look for (e.g., "observer,factory,middleware"). If omitted, detect all.
-- `--save-spec` — Invoke `Skill({ skill: "spec-add" })` for each newly discovered pattern
-- `--save-wiki` — Create wiki note entries per pattern group via `maestro wiki create --type note`
-
-**Storage written:**
-- `.workflow/knowhow/KNW-decompose-{slug}-{YYYY-MM-DD}.md` — Pattern decomposition report
-- `.workflow/specs/learnings.md` — One `<spec-entry>` per discovered pattern (source: "decompose")
-- If `--save-spec`: entries appended to `.workflow/specs/coding-conventions.md`
-- If `--save-wiki`: new wiki note entries
-
-**Storage read:**
-- Source files at target path
-- `.workflow/specs/coding-conventions.md` — Existing documented patterns (for dedup)
-- `.workflow/specs/learnings.md` — Previously identified patterns (for dedup)
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution**: file path → that file; directory → all source files; module name → Glob `src/**/{module}*`.
+
+**Flags**:
+- `--patterns <list>`: Comma-separated pattern names to look for (default: detect all)
+- `--save-spec`: `Skill("spec-add")` for each new pattern
+- `--save-wiki`: create wiki note per dimension group
+
+**Storage read**: target files + `coding-conventions.md` + `specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `specs/learnings.md`
 </context>
 
-<execution>
-
-### Stage 1: Resolve Target
-- If argument is a file: verify exists, use as single-file target
-- If argument is a directory: list all `.ts`, `.tsx`, `.js`, `.jsx` files (exclude `node_modules`, `dist`, `.test.`)
-- If argument is a module name: Glob `src/**/{module}*` to find matching directory
-- If target unresolvable, AskUserQuestion with suggestions
-
-### Stage 2: Load Existing Patterns
-- Read `.workflow/specs/coding-conventions.md` — extract documented patterns
-- Search `specs/learnings.md` for `<spec-entry>` blocks with `roles="implement"` — previously discovered
-- Build dedup set: pattern names already known
-
-### Stage 3: Parallel Agent Analysis (4 dimensions)
-Spawn 4 Agents in a single message, each analyzing the target from one dimension:
-
-**Agent 1 — Structural Patterns:**
-- Class hierarchy and composition relationships
-- Module boundaries and encapsulation
-- Dependency injection / inversion of control
-- Builder, Factory, Singleton patterns
-- Export structure (barrel files, re-exports)
-
-**Agent 2 — Behavioral Patterns:**
-- Event flow (EventEmitter, pub/sub, callbacks)
-- Middleware chains and interceptors
-- Observer/subscriber patterns
-- Command/strategy patterns
-- State machines
-
-**Agent 3 — Data Patterns:**
-- Repository / data access patterns
-- DTO / transformation pipelines
-- Caching strategies (memoization, LRU, TTL)
-- Serialization / deserialization
-- Schema validation approaches
-
-**Agent 4 — Error Patterns:**
-- Error boundary and propagation
-- Retry / backoff / circuit breaker
-- Fallback chains
-- Validation and guard clauses
-- Logging and observability patterns
-
-Each agent returns findings as structured list:
-```json
-[{
-  "name": "pattern name",
-  "dimension": "structural|behavioral|data|error",
-  "confidence": "high|medium|low",
-  "anchors": ["file:line", "file:line"],
-  "description": "what it does",
-  "rationale": "why this approach",
-  "tradeoffs": "what was given up"
-}]
-```
-
-If `--patterns` specified, instruct agents to focus only on named patterns.
-
-### Stage 4: Cross-Reference & Dedup
-- Match agent findings against existing pattern set from Stage 2
-- Mark each finding: `documented` (already in specs), `known` (in knowhow), or `new`
-- Flag contradictions: finding conflicts with documented convention
-- Merge duplicate findings across agents (same pattern found by multiple dimensions)
-
-### Stage 5: Produce Pattern Catalog
-Build the decomposition report grouped by dimension:
-
-```markdown
-# Pattern Decomposition: {target}
-
-## Summary
-- Patterns found: N (M new, K documented, J known)
-- Dimensions analyzed: structural, behavioral, data, error
-- Contradictions: N
-
-## Structural Patterns
-| Pattern | Confidence | Location | Status |
-|---------|-----------|----------|--------|
-| {name} | high | {file:line} | new / documented / known |
-
-### {Pattern Name}
-**Description:** ...
-**Code example:** (inline snippet from anchor)
-**Trade-offs:** ...
-
-## Behavioral Patterns
-...
-```
-
-### Stage 6: Persist
-1. Write `.workflow/knowhow/KNW-decompose-{slug}-{date}.md`
-2. Append each **new** pattern as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "decompose,pattern,{dimension},{target-slug}"`:
-   - Stable INS-id from `hash("decompose" + target + pattern_name)`
-4. If `--save-spec`: for each new pattern, invoke `Skill({ skill: "spec-add", args: "pattern {description}" })`
-5. If `--save-wiki`: create wiki note per dimension group via `maestro wiki create --type note --slug decompose-{dimension}-{slug}`
-6. Display summary with counts and next steps
-
-**Next-step routing:**
-- Follow-along on a specific pattern → `/learn-follow <anchor-file>`
-- Get second opinion on findings → `/learn-second-opinion <target>`
-- Add all new patterns to specs → `/spec-add coding ...` per pattern
-</execution>
+<state_machine>
+
+<states>
+S_RESOLVE    — 解析 target 为具体文件列表                PERSIST: —
+S_DEDUP      — 加载已有 patterns 用于去重                PERSIST: —
+S_ANALYZE    — 4 维度并行 Agent 分析                     PERSIST: —
+S_CROSSREF   — 交叉引用、去重、标记状态                   PERSIST: —
+S_CATALOG    — 生成 pattern catalog 报告                  PERSIST: outputs
+S_PERSIST    — 写文件 + 可选 spec-add/wiki create         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_DEDUP       WHEN: file list resolved
+  → S_RESOLVE     WHEN: unresolvable                     DO: AskUserQuestion
+
+S_DEDUP:
+  → S_ANALYZE     DO: read coding-conventions.md + specs/learnings.md → build known pattern set
+
+S_ANALYZE:
+  → S_CROSSREF    DO: A_PARALLEL_DIMENSION_ANALYSIS
+
+S_CROSSREF:
+  → S_CATALOG     DO: A_CROSSREF_DEDUP
+
+S_CATALOG:
+  → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
+
+S_PERSIST:
+  → END           DO: append specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_PARALLEL_DIMENSION_ANALYSIS
+
+Spawn 4 Agents in single message:
+
+| Agent | Dimension | Looks for |
+|-------|-----------|-----------|
+| 1 | Structural | Class hierarchy, composition, DI/IoC, Factory/Builder/Singleton, barrel exports |
+| 2 | Behavioral | Event flow, middleware chains, observer/pub-sub, command/strategy, state machines |
+| 3 | Data | Repository/DAO, DTO pipelines, caching (memo/LRU/TTL), serialization, schema validation |
+| 4 | Error | Error boundaries, retry/backoff/circuit-breaker, fallback chains, guard clauses, logging |
+
+If `--patterns` specified: agents focus only on named patterns.
+
+Each agent returns: `[{ name, dimension, confidence (high/medium/low), anchors [file:line], description, rationale, tradeoffs }]`
+
+### A_CROSSREF_DEDUP
+
+For each finding, match against known pattern set:
+| Status | Condition |
+|--------|-----------|
+| documented | Already in coding-conventions.md |
+| known | In specs/learnings.md |
+| new | Not seen before |
+
+Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
+
+</actions>
+
+</state_machine>
 
 <error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target path not found | Check path exists, or use a module name |
-| E002 | error | No source files found in target directory | Check target has .ts/.js files, exclude filters may be too aggressive |
-| W001 | warning | One or more dimension agents failed — partial results | Proceed with available dimensions, retry failed ones |
-| W002 | warning | coding-conventions.md not found — skipping dedup against specs | All patterns marked as "new" |
-| W003 | warning | Large target (>50 files) — analysis may be slow | Consider narrowing scope with --patterns filter |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | No source files in target | Check target has .ts/.js files |
+| W001 | One+ dimension agent failed | Proceed with available dimensions |
+| W003 | Large target (>50 files) | Consider --patterns filter |
 </error_codes>
 
 <success_criteria>
-- [ ] Target resolved to concrete file list
-- [ ] Existing patterns loaded for dedup
-- [ ] All 4 dimension agents spawned in parallel
-- [ ] Each finding has: name, dimension, confidence, anchors, description, tradeoffs
-- [ ] Cross-reference performed (documented / known / new status assigned)
-- [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `specs/learnings.md` as `<spec-entry>` blocks with stable INS-ids
-- [ ] If --save-spec: spec entries created for new patterns
-- [ ] If --save-wiki: wiki notes created per dimension group
-- [ ] No files modified outside `.workflow/knowhow/` (and optionally specs/wiki)
-- [ ] Summary displayed with pattern counts and next-step routing
+- [ ] 4 dimension agents spawned in parallel, findings with anchors
+- [ ] Cross-reference: documented/known/new status assigned
+- [ ] Pattern catalog written + specs/learnings.md appended
 </success_criteria>
+
+<next_step_routing>
+- Follow-along → `/learn-follow <anchor-file>`
+- Second opinion → `/learn-second-opinion <target>`
+- Add to specs → `/spec-add coding ...`
+</next_step_routing>

package/.claude/commands/learn-follow.md

@@ -12,151 +12,116 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Guided reading experience for code files, wiki entries, or topics. Instead of just reading code, this command walks through content section by section using forcing questions (inspired by gstack `/office-hours` brainstorming) to extract patterns, identify assumptions, and build a structured understanding map.
-
-Outputs reading notes with extracted patterns, open questions, and connection points. Insights persist to `specs/learnings.md` as `<spec-entry>` blocks and optionally become wiki note entries for the knowledge graph.
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
-Arguments: $ARGUMENTS
-
-**Target resolution (auto-detected from first argument):**
-- File path (e.g., `src/commands/wiki.ts`) → Read source file
-- Wiki ID (e.g., `spec-auth`, `phase-planning`) → Fetch via `maestro wiki get`
-- Topic string (e.g., `"authentication flow"`) → Search via `maestro wiki search`, use top result
-
-**Flags:**
-- `--depth shallow` — Quick pass: key patterns and structure only (default)
-- `--depth deep` — Thorough: every function, every branch, every assumption
-- `--save-wiki` — Create a wiki note entry with the reading notes via `maestro wiki create --type note`
-
-**Storage written:**
-- `.workflow/knowhow/KNW-follow-{slug}-{YYYY-MM-DD}.md` — Reading notes with understanding map
-- `.workflow/knowhow/specs/learnings.md` — Appended pattern/technique `<spec-entry>` blocks
-- If `--save-wiki`: new wiki note entry
-
-**Storage read:**
-- Target source file or wiki entry
-- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
-- `.workflow/specs/coding-conventions.md` — Convention reference for pattern matching
-- `.workflow/knowhow/specs/learnings.md` — Prior insights for dedup and cross-reference
+$ARGUMENTS — target and optional flags.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path (contains `/` or `\`) | Read source file |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| Topic string | `maestro wiki search "<topic>"` → top result; fallback: Grep src/ |
+
+**Flags**:
+- `--depth shallow` (default): key patterns and structure only
+- `--depth deep`: every function, every branch, every assumption
+- `--save-wiki`: create wiki note entry with reading notes
+
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `specs/learnings.md`
 </context>
 
-<execution>
-
-### Stage 1: Resolve Target
-- If argument looks like a file path (contains `/` or `\`, or matches a glob): verify file exists via Read
-- If argument matches wiki ID pattern (`<type>-<slug>`): fetch via `maestro wiki get <id>` (offline mode)
-- Otherwise: treat as topic string, run `maestro wiki search "<topic>"`, take the top result. If no result, fall back to Grep across `src/` for the topic.
-- If target cannot be resolved, AskUserQuestion with suggestions.
-
-### Stage 2: Load Context Web
-For the resolved target, build a 1-hop context neighborhood:
-
-**If wiki entry:**
-- `maestro wiki forward <id>` — What this entry references
-- `maestro wiki backlinks <id>` — What references this entry
-- Read the body of top 3 related entries for context
-
-**If code file:**
-- Parse imports/requires to identify dependency files
-- Grep for exports used by other files (reverse dependencies)
-- Read the first 50 lines of top 3 dependent files for context
-
-**If directory:**
-- List files, identify entry points (index.ts, main.ts, cli.ts)
-- Build reading order: entry point → core modules → utilities → tests
-
-### Stage 3: Build Reading Order
-- For a single file: split into logical sections (function boundaries, class boundaries, export groups)
-- For a wiki entry: split by markdown headings
-- For a directory: order files by dependency (entry points first, leaf modules last)
-- For `--depth shallow`: limit to top-level structure (function signatures, section headers)
-- For `--depth deep`: include every function body, every branch
-
-### Stage 4: Guided Reading with Forcing Questions
-Walk through each section in reading order. For each section, apply 4 forcing questions:
-
-1. **"What pattern is being used here?"** — Identify design patterns, idioms, conventions. Compare against `coding-conventions.md`.
-2. **"Why this approach instead of alternatives?"** — What trade-offs were made? What was the simpler approach not chosen?
-3. **"What assumption does this depend on?"** — What must be true for this code/content to be correct? External state? Input shape? Ordering?
-4. **"What would break if this changed?"** — Fragility analysis. What downstream effects would a change have?
-
-Record answers as structured annotations per section.
-
-### Stage 5: Extract Patterns
-From the forcing question answers, extract:
-- **Design patterns**: named patterns with code anchors (file:line)
-- **Naming conventions**: how things are named and why
-- **Error handling approach**: how errors flow through this code/content
-- **Data flow**: how data enters, transforms, and exits
-- **Assumptions**: explicit and implicit assumptions identified
-
-Cross-reference each pattern against existing `coding-conventions.md` entries:
-- Already documented → note as "confirmed convention"
-- Not documented → flag as "undocumented pattern" (candidate for `spec-add`)
-
-### Stage 6: Produce Understanding Map
-Build a structured summary document:
-
-```markdown
-# Follow-Along: {target name}
-
-## Key Concepts
-- {concept}: {one-line explanation}
-
-## Patterns Identified
-| Pattern | Location | Convention Status |
-|---------|----------|-------------------|
-| {name} | {file:line} | documented / undocumented |
-
-## Assumptions
-- {assumption}: {what depends on it}
-
-## Open Questions
-- {question}: {why it matters}
-
-## Connections
-- Links to: {forward link entries}
-- Referenced by: {backlink entries}
-- Related insights: {matching specs/learnings.md entries}
-```
-
-### Stage 7: Persist
-1. Write `.workflow/knowhow/KNW-follow-{slug}-{date}.md` with the understanding map
-2. Append each new pattern/technique as a `<spec-entry>` block to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "follow,{target-slug}"`:
-   - Stable INS-id from `hash("follow" + target + pattern_name)`
-3. If `--save-wiki`: run `maestro wiki create --type note --slug follow-{slug} --title "Follow-Along: {target}" --body-file .workflow/knowhow/KNW-follow-{slug}-{date}.md`
-5. Display summary with key findings and next steps
-
-**Next-step routing:**
-- Deep dive into a discovered pattern → `/learn-decompose <path>`
-- Add undocumented pattern to specs → `/spec-add coding <description>`
-- Get second opinion on a finding → `/learn-second-opinion <file>`
-- Browse related wiki entries → `/wiki-digest <topic>`
-</execution>
+<state_machine>
+
+<states>
+S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
+S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
+S_ORDER        — 确定阅读顺序                                PERSIST: —
+S_READ         — 逐节应用 forcing questions                   PERSIST: —
+S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
+S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved
+  → S_RESOLVE     WHEN: unresolvable                       DO: AskUserQuestion with suggestions
+
+S_CONTEXT:
+  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
+
+S_ORDER:
+  → S_READ        DO: A_BUILD_READING_ORDER
+
+S_READ:
+  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
+
+S_EXTRACT:
+  → S_PERSIST     DO: A_EXTRACT_PATTERNS
+
+S_PERSIST:
+  → END           DO: write KNW-follow + append specs/learnings.md [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_BUILD_CONTEXT_WEB
+
+| Target type | Context |
+|-------------|---------|
+| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
+| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
+| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
+
+### A_BUILD_READING_ORDER
+
+- Single file: split by function/class/export boundaries
+- Wiki entry: split by markdown headings
+- Directory: order by dependency (entry points first, leaf last)
+- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
+
+### A_GUIDED_READ
+
+For each section, apply 4 forcing questions:
+
+| # | Question | Extracts |
+|---|----------|----------|
+| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
+| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
+| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
+| 4 | "What would break if this changed?" | Fragility, downstream effects |
+
+### A_EXTRACT_PATTERNS
+
+Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
+
+Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
+
+</actions>
+
+</state_machine>
 
 <error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target not resolvable (file not found, wiki ID not found, search returned 0) | Check path/ID, or rephrase topic for search |
-| E002 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| W001 | warning | Wiki graph unavailable (no .workflow/ wiki entries) — skipping context web | Proceed with code-only context (imports/exports) |
-| W002 | warning | coding-conventions.md not found — skipping convention comparison | Patterns flagged as "unknown convention status" |
-| W003 | warning | Target is very large (>1000 lines) — auto-switching to shallow depth | Use --depth deep to override |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
+| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
 </error_codes>
 
 <success_criteria>
-- [ ] Target resolved to concrete content (file, wiki entry, or search result)
-- [ ] Context web loaded (forward/backlinks for wiki, imports/exports for code)
-- [ ] Reading order established (sections/files ordered logically)
-- [ ] All 4 forcing questions applied per section
-- [ ] Patterns extracted with file:line anchors
-- [ ] Convention comparison performed against coding-conventions.md
-- [ ] Understanding map produced with: concepts, patterns, assumptions, questions, connections
-- [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `specs/learnings.md` appended with discovered patterns as `<spec-entry>` blocks (stable INS-ids)
-- [ ] If --save-wiki: wiki note entry created
-- [ ] No files modified outside `.workflow/knowhow/` (and optionally wiki)
-- [ ] Summary displayed with next-step routing
+- [ ] 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors and convention cross-ref
+- [ ] Understanding map + spec-entry blocks written
 </success_criteria>
+
+<next_step_routing>
+- Deep pattern dive → `/learn-decompose <path>`
+- Add to specs → `/spec-add coding <description>`
+- Second opinion → `/learn-second-opinion <file>`
+</next_step_routing>