maestro-flow 0.3.42 → 0.3.44

package/workflows/ui-codify-package.md

@@ -0,0 +1,161 @@
+# UI Codify: Phase 3 — Reference Package Generation
+
+将提取结果转换为可分享的参考包，包含交互式预览页面。
+
+## Prerequisites
+
+来自前序 Phase 的变量：
+- `temp_dir` — 临时工作区，包含提取结果
+- `package_dir` — 目标包目录
+- `package_name` — 包名
+
+## Step 3.1: Copy Token Files
+
+```bash
+echo "[Phase 3] Preparing component data from extraction"
+
+# 1. Copy layout templates (required)
+cp "${temp_dir}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
+
+if [ ! -f "${package_dir}/layout-templates.json" ]; then
+  echo "ERROR: Failed to copy layout templates"
+  exit 1
+fi
+
+component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0)
+echo "  Layout templates copied (${component_count} components)"
+
+# 2. Copy design tokens (required)
+cp "${temp_dir}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json"
+
+if [ ! -f "${package_dir}/design-tokens.json" ]; then
+  echo "ERROR: Failed to copy design tokens"
+  exit 1
+fi
+echo "  Design tokens copied"
+
+# 3. Copy animation tokens (optional)
+if [ -f "${temp_dir}/animation-extraction/animation-tokens.json" ]; then
+  cp "${temp_dir}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json"
+  echo "  Animation tokens copied"
+else
+  echo "  W001: Animation tokens not found (optional, continuing)"
+fi
+
+echo "[Phase 3] Token files prepared"
+```
+
+---
+
+## Step 3.2: Preview Generation (Agent)
+
+**Agent Task**:
+
+```javascript
+Agent(ui-design-agent): `
+  [PREVIEW_SHOWCASE_GENERATION]
+  Generate interactive multi-component showcase panel for reference package
+
+  PACKAGE_DIR: ${package_dir} | PACKAGE_NAME: ${package_name}
+
+  ## Input Files (MUST READ ALL)
+
+  1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
+  2. ${package_dir}/design-tokens.json (design tokens - REQUIRED)
+  3. ${package_dir}/animation-tokens.json (optional, if exists)
+
+  ## Generation Agent
+
+  Create interactive showcase with these sections:
+
+  ### Section 1: Colors
+  - Display all color categories as color swatches
+  - Show hex/rgb values
+  - Group by: brand, semantic, surface, text, border
+
+  ### Section 2: Typography
+  - Display typography scale (font sizes, weights)
+  - Show typography combinations if available
+  - Include font family examples
+  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
+    * Common sizes table (small_text, body_text, heading)
+    * Common combinations with use cases
+
+  ### Section 3: Components
+  - Render all components from layout-templates.json (use layout_templates field)
+  - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
+    * **Display usage_guide** (from layout-templates.json):
+      - Common sizes table with dimensions and use cases
+      - Variant recommendations (when to use primary/secondary/etc)
+      - Usage context list (typical scenarios)
+      - Accessibility tips checklist
+  - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
+  - Display all variants side-by-side
+  - Show DOM structure with proper styling
+  - Include usage code snippets in <details> tags
+  - Clearly label component types (universal vs specialized)
+
+  ### Section 4: Spacing & Layout
+  - Visual spacing scale
+  - Border radius examples
+  - Shadow depth examples
+  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
+    * Size guide table (tight/normal/loose categories)
+    * Common patterns with use cases and pixel values
+
+  ### Section 5: Animations (if available)
+  - Animation duration examples
+  - Easing function demonstrations
+
+  ## Output Requirements
+
+  Generate 2 files:
+  1. ${package_dir}/preview.html
+  2. ${package_dir}/preview.css
+
+  ### preview.html Structure:
+  - Complete standalone HTML file
+  - Responsive design with mobile-first approach
+  - Sticky navigation for sections
+  - Interactive component demonstrations
+  - Code snippets in collapsible <details> elements
+  - Footer with package metadata
+
+  ### preview.css Structure:
+  - CSS Custom Properties from design-tokens.json
+  - Typography combination classes
+  - Component classes from layout-templates.json
+  - Preview page layout styles
+  - Interactive demo styles
+
+  ## Critical Requirements
+  - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
+  - ✅ Generate complete, interactive showcase HTML
+  - ✅ All CSS uses var() references to design tokens
+  - ✅ Display ALL components from layout-templates.json
+  - ✅ **Separate universal components from specialized components** in the showcase
+  - ✅ Display component DOM structures with proper styling
+  - ✅ Include usage code snippets
+  - ✅ Label each component type clearly (Universal / Specialized)
+  - ✅ **Display usage recommendations** when available:
+    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
+    - Components: usage_guide for universal components (from layout-templates)
+    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
+  - ✅ Gracefully handle missing usage data (display sections only if data exists)
+  - ✅ Use Write() to save both files:
+    - ${package_dir}/preview.html
+    - ${package_dir}/preview.css
+  - ❌ NO external research or MCP calls
+`
+```
+
+## Output Structure
+
+```
+${package_dir}/
+├── layout-templates.json    # Layout templates (copied from extraction)
+├── design-tokens.json       # Design tokens (copied from extraction)
+├── animation-tokens.json    # Animation tokens (optional)
+├── preview.html             # Interactive showcase (NEW)
+└── preview.css              # Showcase styling (NEW)
+```

package/workflows/ui-codify.md

@@ -0,0 +1,225 @@
+# UI Codify: Main Workflow
+
+从源代码提取设计系统，生成参考包，固化为知识资产。
+
+## Architecture
+
+```
+Phase 1 (inline)     Phase 2 (deferred)       Phase 3 (deferred)       Phase 4 (deferred)
+  Validate &           3 Parallel Agents        Reference Package        Knowhow Assets
+  Setup                ┌─ Style Agent           Copy tokens +            Manifest +
+  ├─ Parse args        ├─ Animation Agent       Generate preview         codify-to-knowhow
+  ├─ Validate source   └─ Layout Agent          (preview.html/css)       + cleanup
+  ├─ Package name      ↓                        ↓                        ↓
+  └─ Workspace         design-tokens.json       preview.html             knowhow-manifest.json
+                       animation-tokens.json    preview.css              → knowhow files
+                       layout-templates.json                             → spec entries
+```
+
+## Data Flow
+
+```
+Input: source_path, package_name, output_dir, overwrite
+
+Phase 1 → source_path, package_name, output_dir, temp_dir, package_dir
+    ↓
+Phase 2 → design-tokens.json, animation-tokens.json, layout-templates.json
+    ↓      (written to temp_dir)
+Phase 3 → preview.html, preview.css, token files copied to package_dir
+    ↓
+Phase 4 → knowhow-manifest.json → codify-to-knowhow → knowhow + specs
+    ↓
+Completion report
+```
+
+## TodoWrite Pattern
+
+```json
+[
+  {"content": "Phase 1: 参数验证与工作区准备", "status": "in_progress"},
+  {"content": "Phase 2: 并行 Agent 提取 (Style + Animation + Layout)", "status": "pending"},
+  {"content": "Phase 3: 参考包生成 (preview.html + preview.css)", "status": "pending"},
+  {"content": "Phase 4: 知识资产固化 (manifest + codify-to-knowhow)", "status": "pending"}
+]
+```
+
+---
+
+## Phase 1: Parameter Validation & Workspace Setup (Inline)
+
+### Step 1.1: Parse Arguments
+
+从 `$ARGUMENTS` 中解析：
+
+- `source_path` (positional, required) — 源代码目录
+- `--package-name <name>` — 包名（可选，默认从源目录自动生成）
+- `--output-dir <path>` — 输出目录（默认 `.workflow/reference_style`）
+- `--overwrite` — 允许覆盖已存在的包目录
+
+```bash
+# 验证 source_path 存在
+if [ -z "$source_path" ]; then
+  echo "E001: Source path argument required"
+  echo "USAGE: /maestro-ui-codify <source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+  exit 1
+fi
+
+if [ ! -d "$source_path" ]; then
+  echo "E002: Source path not found or not a directory: $source_path"
+  exit 1
+fi
+
+source_path=$(cd "$source_path" && pwd)
+echo "Source: $source_path"
+```
+
+### Step 1.2: Resolve Package Name
+
+```bash
+# 自动生成包名: 目录名转 kebab-case，附加日期
+if [ -z "$package_name" ]; then
+  dir_name=$(basename "$source_path")
+  package_name=$(echo "$dir_name" | tr '[:upper:]' '[:lower:]' | tr ' _' '-' | sed 's/[^a-z0-9-]//g')
+  package_name="${package_name}-style"
+fi
+
+# 验证包名格式
+if ! [[ "$package_name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "ERROR: Invalid package name '$package_name'. Use lowercase, alphanumeric, hyphens only."
+  exit 1
+fi
+
+echo "Package name: $package_name"
+```
+
+### Step 1.3: Setup Directories
+
+```bash
+output_dir="${output_dir:-.workflow/reference_style}"
+package_dir="${output_dir}/${package_name}"
+
+# 覆盖保护
+if [ -d "$package_dir" ] && [ "$(ls -A "$package_dir" 2>/dev/null)" ]; then
+  if [ "$overwrite" != "true" ]; then
+    echo "E003: Package directory exists: $package_dir"
+    echo "HINT: Use --overwrite to replace, or choose a different --package-name"
+    exit 1
+  fi
+  echo "INFO: Overwriting existing package '$package_name'"
+fi
+
+# 创建临时工作区
+timestamp=$(date +%Y%m%d%H%M%S)
+temp_dir=".workflow/codify-temp-${timestamp}"
+mkdir -p "$temp_dir/style-extraction/style-1"
+mkdir -p "$temp_dir/animation-extraction"
+mkdir -p "$temp_dir/layout-extraction"
+mkdir -p "$temp_dir/.intermediates/import-analysis"
+mkdir -p "$package_dir"
+
+echo "[Phase 1] Setup complete"
+echo "  Source: $source_path"
+echo "  Package: $package_name"
+echo "  Temp workspace: $temp_dir"
+echo "  Output: $package_dir"
+```
+
+**TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress.
+
+---
+
+## Phase 2: Parallel Agent Extraction (Deferred)
+
+**Read** `@~/.maestro/workflows/ui-codify-extract.md` then execute.
+
+Variables available to Phase 2:
+- `source_path` — absolute path to source directory
+- `temp_dir` — temporary workspace path (e.g. `.workflow/codify-temp-20260510143022`)
+
+Phase 2 writes:
+- `${temp_dir}/style-extraction/style-1/design-tokens.json`
+- `${temp_dir}/animation-extraction/animation-tokens.json`
+- `${temp_dir}/layout-extraction/layout-templates.json`
+
+**TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress.
+
+---
+
+## Phase 3: Reference Package Generation (Deferred)
+
+**Read** `@~/.maestro/workflows/ui-codify-package.md` then execute.
+
+Variables available to Phase 3:
+- `temp_dir` — temporary workspace with extraction results
+- `package_dir` — target package directory
+- `package_name` — package name
+
+Phase 3 writes:
+- `${package_dir}/design-tokens.json`
+- `${package_dir}/layout-templates.json`
+- `${package_dir}/animation-tokens.json` (if available)
+- `${package_dir}/preview.html`
+- `${package_dir}/preview.css`
+
+**TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress.
+
+---
+
+## Phase 4: Knowledge Asset Generation (Deferred)
+
+**Read** `@~/.maestro/workflows/ui-codify-knowhow.md` then execute.
+
+Variables available to Phase 4:
+- `package_dir` — package directory with all token files
+- `package_name` — package name (used as slug)
+- `temp_dir` — temporary workspace (to clean up)
+
+Phase 4 writes:
+- `${package_dir}/knowhow-manifest.json`
+- Then calls `/codify-to-knowhow ${package_dir}` via Skill tool
+
+**TodoWrite**: Mark Phase 4 completed (all tasks done).
+
+---
+
+## Error Handling
+
+| Phase | Error | Recovery |
+|-------|-------|----------|
+| 1 | E001: Missing source path | Report usage, exit |
+| 1 | E002: Source not found | Report path, exit |
+| 1 | E003: Package exists | Suggest --overwrite, exit |
+| 2 | Agent failure | Report which agent failed, continue with partial results |
+| 2 | No files discovered | Report empty discovery, exit |
+| 3 | Token copy failed | Report missing file, exit |
+| 3 | Preview generation failed | Report error, continue (preview is non-critical) |
+| 4 | Manifest build failed | Report error, package still usable without knowhow |
+| 4 | codify-to-knowhow failed | Report error, manifest remains for manual retry |
+
+## Completion Message
+
+```
+UI Design System Codified!
+
+Package: {package_name}
+Location: {package_dir}
+
+Files:
+  design-tokens.json       Design tokens (colors, typography, spacing)
+  layout-templates.json    Component patterns ({universal_count} universal, {specialized_count} specialized)
+  animation-tokens.json    Animation tokens {if exists else "(not found)"}
+  preview.html             Interactive showcase
+  preview.css              Showcase styling
+  knowhow-manifest.json    Knowledge asset manifest
+
+Knowledge Assets:
+  Knowhow: AST-{package_name}-tokens, AST-{package_name}-components{, DCS-{package_name}-decisions}
+  Specs: {spec_count} entries (coding + arch)
+
+Open preview:
+  file://{absolute_path}/preview.html
+
+Next steps:
+  maestro wiki list --role implement    # Browse by role
+  maestro spec load --keyword {package_name}    # Load related specs
+```

package/workflows/verify.md

@@ -42,7 +42,7 @@ Milestone mode creates output dir: .workflow/scratch/verify-{milestone_slug}-{da
 ## V0: Load Project Specs
 
 ```
-specs_content = maestro spec load --category quality
+specs_content = maestro spec load --role review
 ```
 
 Pass specs_content to verifier agent as quality standards context.

package/workflows/wiki-connect.md

@@ -28,7 +28,7 @@ Knowledge graph link discovery and health improvement. Analyzes the unified wiki
 
 | Flag | Effect |
 |------|--------|
-| `--scope <type>` | Limit to wiki type: spec, knowhow, note, lesson, issue. Default: all |
+| `--scope <type>` | Limit to wiki type: spec, knowhow, note, issue. Default: all |
 | `--min-similarity N` | Minimum similarity score 0.0-1.0 (default: 0.3) |
 | `--fix` | Auto-apply top suggestions via `maestro wiki update` |
 | `--max N` | Maximum suggestions to generate (default: 20) |
@@ -68,7 +68,7 @@ For connected pairs A → B and B → C:
 
 ### 2d. Type Bridge
 Detect entries of different types referencing the same concept:
-- e.g., `spec-auth` and `lesson-auth-gotcha` — same domain, different perspectives
+- e.g., `spec-auth` and `knowhow-auth-gotcha` — same domain, different perspectives
 - Use tag overlap + title keyword match to detect shared concepts
 - Only suggest if entries are currently unlinked
 
@@ -99,7 +99,7 @@ Baseline health: 72/100 | Orphans: 8 | Broken links: 3
 #  Score  Source              → Target              Reason
 1  0.85   memory-auth-flow    → spec-auth           tag overlap (auth, security) + type bridge
 2  0.71   note-cache-pattern  → spec-performance    title BM25 match + type bridge
-3  0.65   lesson-retry-fix    → spec-error-handling  tag overlap (error, retry)
+3  0.65   knowhow-retry-fix   → spec-error-handling  tag overlap (error, retry)
 ...
 
 Projected health after fix: 81/100 (+9)
@@ -120,14 +120,14 @@ After all updates: re-run `maestro wiki health`, report applied/skipped counts a
 
 ## Stage 6: Persist & Report
 
-1. Write `.workflow/learning/wiki-connections-{YYYY-MM-DD}.md`:
+1. Write `.workflow/knowhow/KNW-wiki-connections-{YYYY-MM-DD}.md`:
    - Baseline vs final health scores
    - All suggestions (applied and unapplied) with scores
    - Orphan rescue results
    - Graph structure observations (hub concentration, type distribution)
    
-2. Append graph insights to `.workflow/learning/lessons.jsonl`:
-   - `source: "wiki-connect"`, `category: "technique"`
+2. Append graph insights as `<spec-entry>` to `.workflow/specs/learnings.md`:
+   - `source="wiki-connect"`, `category="technique"`
    - e.g., "Auth entries poorly cross-referenced", "Memory entries have highest orphan rate"
 
 3. Display summary:
@@ -135,7 +135,7 @@ After all updates: re-run `maestro wiki health`, report applied/skipped counts a
 == Wiki Connect Complete ==
 Suggestions:  {total} ({applied} applied, {skipped} skipped)
 Health:       {baseline} → {new} ({delta})
-Report:       .workflow/learning/wiki-connections-{date}.md
+Report:       .workflow/knowhow/KNW-wiki-connections-{date}.md
 ```
 
 ---

package/workflows/wiki-digest.md

@@ -13,7 +13,7 @@ Unlike `maestro wiki list` which shows raw entries, this workflow synthesizes an
 - `.workflow/` initialized
 - Wiki entries exist (at least 5 for meaningful clustering)
 - `maestro wiki` CLI available
-- `.workflow/learning/lessons.jsonl` exists (optional, for cross-reference)
+- `.workflow/specs/learnings.md` exists (optional, for cross-reference)
 
 ---
 
@@ -32,7 +32,7 @@ Unlike `maestro wiki list` which shows raw entries, this workflow synthesizes an
 |------|--------|
 | `<topic>` | Search wiki for matching entries via BM25 |
 | `--recent N` | Entries updated within last N days |
-| `--type <type>` | Filter by wiki type: spec, knowhow, note, lesson, issue |
+| `--type <type>` | Filter by wiki type: spec, knowhow, note, issue |
 | `--format brief\|full` | `brief` = compact (default), `full` = detailed per-entry |
 | `--create-issues` | Auto-create knowledge-gap issues in `issues.jsonl` |
 
@@ -82,18 +82,18 @@ Top 3-5 most important entries by:
 - **Broken links**: `[[references]]` that don't resolve within the theme
 - **Orphans**: entries in this theme with no connections
 - **TODO markers**: entries with `?`, "TODO", "TBD" in title or body
-- **Missing perspectives**: theme has specs but no lessons? Issues but no decisions?
+- **Missing perspectives**: theme has specs but no knowhow? Issues but no decisions?
 
 ### Health Score
 Per-theme health adapted from wiki health formula (entries, connectivity, completeness).
 
 ---
 
-## Stage 4: Cross-Reference with Lessons
+## Stage 4: Cross-Reference with Knowhow Insights
 
-Search `.workflow/learning/lessons.jsonl` for keyword matches against each theme. Flag **unlinked insights** -- lessons matching a theme but not referenced by any wiki entry in that theme.
+Search via `maestro wiki search` or parse `.workflow/specs/learnings.md` for keyword matches against each theme. Flag **unlinked insights** — learning entries matching a theme but not referenced by any wiki entry in that theme.
 
-If `lessons.jsonl` not found, skip with W002 warning.
+If `learnings.md` not found, skip with W002 warning.
 
 ---
 
@@ -104,8 +104,8 @@ Build a type × theme matrix showing knowledge density:
 ```
               Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
 spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
-memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
-lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
+knowhow       ░░░░░      ████░      ██░░░      ░░░░░      ███░░
+note          █░░░░      ██░░░      ████░      █░░░░      ░░░░░
 issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
 
 Legend: █ = entries exist, ░ = sparse/missing
@@ -117,7 +117,7 @@ Empty cells = knowledge gaps. Each gap becomes a candidate for Stage 7.
 
 ## Stage 6: Write Digest
 
-Produce `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md`:
+Produce `.workflow/knowhow/KNW-digest-{slug}-{YYYY-MM-DD}.md`:
 
 ```markdown
 # Knowledge Digest: {scope description}
@@ -140,10 +140,10 @@ Produce `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md`:
 ## Knowledge Gaps
 | Gap | Theme | Type Missing | Suggested Action |
 |-----|-------|-------------|-----------------|
-| No lessons for auth patterns | Security | lesson | /learn-decompose src/auth/ |
+| No knowhow for auth patterns | Security | knowhow | /learn-decompose src/auth/ |
 
 ## Unlinked Insights
-{lessons.jsonl entries not connected to wiki graph}
+{knowhow entries not connected to wiki graph}
 
 ## Recommended Actions
 1. {action}: {reason}
@@ -160,8 +160,8 @@ For each knowledge gap from Stage 5: dedup against `.workflow/issues/issues.json
 
 ## Stage 8: Persist
 
-1. Write digest file to `.workflow/learning/`
-2. Append meta-insights to `.workflow/learning/lessons.jsonl` (`source: "wiki-digest"`, `category: "technique"`)
+1. Write digest file to `.workflow/knowhow/`
+2. Append meta-insights as `<spec-entry>` to `.workflow/specs/learnings.md` (`source="wiki-digest"`, `category="technique"`)
 3. Display summary: scope, entry count, theme count, gap count, created issues (if applicable), report path.
 
 ---

package/workflows/wiki-manage.md

@@ -28,7 +28,7 @@ Complements `wiki-connect.md` (link discovery) and `wiki-digest.md` (synthesis)
 
 | Flag | Effect |
 |------|--------|
-| `--type <type>` | Filter: spec, knowhow, note, lesson, issue |
+| `--type <type>` | Filter: spec, knowhow, note, issue |
 | `--fix` | Auto-fix issues during cleanup |
 | `--json` | JSON output |