maestro-flow 0.5.2 → 0.5.31

package/workflows/ui-style.md

@@ -1,199 +1,199 @@
-# UI Style Workflow (ui-ux-pro-max powered)
-
-Lightweight design workflow delegating to ui-ux-pro-max for design system generation.
-Command owns: requirements gathering, variant presentation, user selection, solidification.
-
-Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
-
----
-
-## Prerequisites
-
-- `.workflow/` directory initialized
-- Phase directory OR scratch mode
-- Python 3 + ui-ux-pro-max skill installed (SKILL_PATH resolved by command)
-
----
-
-## Phase Resolution
-
-```
-If argument is phase number/slug:
-  Resolve PHASE_DIR from state.json artifact registry. Error if not found.
-  SCRATCH_MODE = false
-
-If argument is topic text (scratch mode):
-  PHASE_DIR = .workflow/scratch/{YYYYMMDD}-ui-design-{slug}
-  Create directory + minimal index.json (type="ui-design", goal=topic).
-  SCRATCH_MODE = true
-```
-
----
-
-## Flag Processing
-
-| Flag | Default | Effect |
-|------|---------|--------|
-| `--styles N` | 3 | Number of style variants (2-5) |
-| `--stack <stack>` | html-tailwind | Tech stack for guidelines |
-| `--targets <pages>` | (inferred) | Comma-separated page targets |
-| `--persist` | false | Save with hierarchical page overrides |
-| `-y` | false | Auto mode: skip interactive selection |
-
----
-
-### Step 1: Setup
-
-**1a. Parse flags** from $ARGUMENTS: `--styles N` (2-5, default 3), `--stack` (default html-tailwind), `--targets` (comma-separated), `--persist`, `-y`/`--yes`.
-
-**1b. Create output directories:** `${PHASE_DIR}/design-ref/prototypes/` and `design-ref/layout-templates/`.
-
-**1c. Display banner** with phase, style count, stack, targets.
-
----
-
-### Step 2: Gather Requirements Context
-
-Gather context from available sources:
-- **2a.** Phase context.md: product type, industry, audience, preferences
-- **2b.** Brainstorm results: visual direction keywords, persona, product type
-- **2c.** Blueprint reference (index.json.blueprint_ref): UI-relevant requirements
-
-**2d. Synthesize design brief:** product_type, industry, style_keywords, audience.
-
-**2e. Infer targets** from phase goal / brainstorm / spec. Fallback: `["home"]`.
-
-**2f. Interactive brief review** (skip if -y): present brief, allow adjustments.
-
----
-
-### Step 3: Generate Style Variants via ui-ux-pro-max
-
-**Purpose:** Call ui-ux-pro-max multiple times with different keyword emphasis to produce contrasting variants.
-
-#### 3a. Build variant keyword sets
-
-Generate `styleCount` contrasting keyword sets (e.g., conservative/expressive/premium directions).
-
-#### 3b. Call ui-ux-pro-max for each variant (parallel)
-
-```bash
-# Per variant — design system
-python3 "${SKILL_PATH}" "${variant_keywords[N]}" --design-system -p "${project_name}" -f markdown
-
-# Once — stack guidelines + domain supplements
-python3 "${SKILL_PATH}" "layout responsive form component" --stack ${stack}
-python3 "${SKILL_PATH}" "${industry} ${product_type}" --domain color
-python3 "${SKILL_PATH}" "accessibility animation interaction" --domain ux
-```
-
-Save variants to `${PHASE_DIR}/design-ref/prototypes/variant-{N}-system.md`.
-
-#### 3c. Present variants (skip if -y)
-
-Display each variant summary (pattern, colors, typography, effects, anti-patterns).
-User selects: [1-N | "redo" | "all"]. Auto mode selects variant 1.
-
----
-
-### Step 4: Solidify Selected Design
-
-**Purpose:** Map ui-ux-pro-max output to design-ref/ structure for downstream plan/execute.
-
-#### 4a. Persist via ui-ux-pro-max
-
-```bash
-python3 "${SKILL_PATH}" "${selected_variant_keywords}" --design-system --persist -p "${project_name}"
-# If --persist + targets: generate page overrides per target with --page "${target}"
-```
-
-#### 4b. Generate design-tokens.json
-
-Spawn agent to extract structured tokens from MASTER.md into `${PHASE_DIR}/design-ref/design-tokens.json`.
-
-**Token schema keys:** colors (brand/surface/semantic/text/border in OKLCH), typography (family/size/weight/line_height/combinations), spacing, border_radius, shadows, component_styles (button/card/input), breakpoints.
-
-**Rules:** hex/rgb to OKLCH, var() references in combinations/components, WCAG AA contrast (4.5:1 text, 3:1 UI).
-
-#### 4c. Generate animation-tokens.json
-
-Spawn agent to generate `${PHASE_DIR}/design-ref/animation-tokens.json` from design-tokens + MASTER.md.
-
-**Token schema keys:** duration (instant-slower), easing (ease-out/ease-in-out/spring), transitions, keyframes, interactions (hover states), reduced_motion (prefers-reduced-motion strategy).
-
-#### 4d. Map files to design-ref/
-
-Copy `design-system/MASTER.md` and `design-system/pages/*.md` (if generated) to `${PHASE_DIR}/design-ref/`.
-
-#### 4e. Write selection.json
-
-```json
-{
-  "selected_variant": 1,
-  "variant_name": "{pattern_name} — {style_name}",
-  "selection_mode": "user_choice|auto",
-  "source": "ui-ux-pro-max",
-  "keywords": "{selected_variant_keywords}",
-  "selected_at": "ISO timestamp"
-}
-```
-
-#### 4f. Optional: Generate HTML prototype
-
-For each target, spawn agent to create `${PHASE_DIR}/design-ref/prototypes/${target}.html` from design-tokens + animation-tokens + MASTER.md.
-
-**Rules:** standalone HTML with embedded CSS, realistic content (not lorem ipsum), SVG icons (Heroicons/Lucide CDN), cursor-pointer on clickables, responsive (375/768/1024px), WCAG AA, prefers-reduced-motion.
-
-#### 4g. Update index.json
-
-```json
-{
-  "design_ref": {
-    "status": "selected",
-    "variant": "{variant_name}",
-    "source": "ui-ux-pro-max",
-    "master": "design-ref/MASTER.md",
-    "tokens": "design-ref/design-tokens.json",
-    "animation": "design-ref/animation-tokens.json",
-    "prototypes": "design-ref/prototypes/",
-    "created_at": "ISO timestamp"
-  }
-}
-```
-
----
-
-## Escalation
-
-If the design needs exceed ui-ux-pro-max capabilities (e.g., multi-layout matrix, 6D attribute space exploration, full style x layout x target prototype grid), suggest:
-
-```
-For advanced multi-layer design exploration:
-  /maestro-impeccable --chain build {target}
-```
-
----
-
-## Integration with maestro-plan
-
-Same as ui-design.md — plan.md Step 4b detects `design-ref/MASTER.md` and includes tokens in task `read_first[]`.
-
----
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| ui-ux-pro-max returns empty | Retry with broader keywords, then abort |
-| Token extraction agent fails | Retry once, warn if still fails |
-| User cancels selection | Save all variants, exit without solidification |
-
----
-
-## State Updates
-
-| When | Field | Value |
-|------|-------|-------|
-| Step 1 start | index.json.status | "designing" |
-| Step 4 complete | index.json.design_ref.status | "selected" |
-| Step 4 complete | index.json.updated_at | Current timestamp |
+# UI Style Workflow (ui-ux-pro-max powered)
+
+Lightweight design workflow delegating to ui-ux-pro-max for design system generation.
+Command owns: requirements gathering, variant presentation, user selection, solidification.
+
+Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
+
+---
+
+## Prerequisites
+
+- `.workflow/` directory initialized
+- Phase directory OR scratch mode
+- Python 3 + ui-ux-pro-max skill installed (SKILL_PATH resolved by command)
+
+---
+
+## Phase Resolution
+
+```
+If argument is phase number/slug:
+  Resolve PHASE_DIR from state.json artifact registry. Error if not found.
+  SCRATCH_MODE = false
+
+If argument is topic text (scratch mode):
+  PHASE_DIR = .workflow/scratch/{YYYYMMDD}-ui-design-{slug}
+  Create directory + minimal index.json (type="ui-design", goal=topic).
+  SCRATCH_MODE = true
+```
+
+---
+
+## Flag Processing
+
+| Flag | Default | Effect |
+|------|---------|--------|
+| `--styles N` | 3 | Number of style variants (2-5) |
+| `--stack <stack>` | html-tailwind | Tech stack for guidelines |
+| `--targets <pages>` | (inferred) | Comma-separated page targets |
+| `--persist` | false | Save with hierarchical page overrides |
+| `-y` | false | Auto mode: skip interactive selection |
+
+---
+
+### Step 1: Setup
+
+**1a. Parse flags** from $ARGUMENTS: `--styles N` (2-5, default 3), `--stack` (default html-tailwind), `--targets` (comma-separated), `--persist`, `-y`/`--yes`.
+
+**1b. Create output directories:** `${PHASE_DIR}/design-ref/prototypes/` and `design-ref/layout-templates/`.
+
+**1c. Display banner** with phase, style count, stack, targets.
+
+---
+
+### Step 2: Gather Requirements Context
+
+Gather context from available sources:
+- **2a.** Phase context.md: product type, industry, audience, preferences
+- **2b.** Brainstorm results: visual direction keywords, persona, product type
+- **2c.** Blueprint reference (index.json.blueprint_ref): UI-relevant requirements
+
+**2d. Synthesize design brief:** product_type, industry, style_keywords, audience.
+
+**2e. Infer targets** from phase goal / brainstorm / spec. Fallback: `["home"]`.
+
+**2f. Interactive brief review** (skip if -y): present brief, allow adjustments.
+
+---
+
+### Step 3: Generate Style Variants via ui-ux-pro-max
+
+**Purpose:** Call ui-ux-pro-max multiple times with different keyword emphasis to produce contrasting variants.
+
+#### 3a. Build variant keyword sets
+
+Generate `styleCount` contrasting keyword sets (e.g., conservative/expressive/premium directions).
+
+#### 3b. Call ui-ux-pro-max for each variant (parallel)
+
+```bash
+# Per variant — design system
+python3 "${SKILL_PATH}" "${variant_keywords[N]}" --design-system -p "${project_name}" -f markdown
+
+# Once — stack guidelines + domain supplements
+python3 "${SKILL_PATH}" "layout responsive form component" --stack ${stack}
+python3 "${SKILL_PATH}" "${industry} ${product_type}" --domain color
+python3 "${SKILL_PATH}" "accessibility animation interaction" --domain ux
+```
+
+Save variants to `${PHASE_DIR}/design-ref/prototypes/variant-{N}-system.md`.
+
+#### 3c. Present variants (skip if -y)
+
+Display each variant summary (pattern, colors, typography, effects, anti-patterns).
+User selects: [1-N | "redo" | "all"]. Auto mode selects variant 1.
+
+---
+
+### Step 4: Solidify Selected Design
+
+**Purpose:** Map ui-ux-pro-max output to design-ref/ structure for downstream plan/execute.
+
+#### 4a. Persist via ui-ux-pro-max
+
+```bash
+python3 "${SKILL_PATH}" "${selected_variant_keywords}" --design-system --persist -p "${project_name}"
+# If --persist + targets: generate page overrides per target with --page "${target}"
+```
+
+#### 4b. Generate design-tokens.json
+
+Spawn agent to extract structured tokens from MASTER.md into `${PHASE_DIR}/design-ref/design-tokens.json`.
+
+**Token schema keys:** colors (brand/surface/semantic/text/border in OKLCH), typography (family/size/weight/line_height/combinations), spacing, border_radius, shadows, component_styles (button/card/input), breakpoints.
+
+**Rules:** hex/rgb to OKLCH, var() references in combinations/components, WCAG AA contrast (4.5:1 text, 3:1 UI).
+
+#### 4c. Generate animation-tokens.json
+
+Spawn agent to generate `${PHASE_DIR}/design-ref/animation-tokens.json` from design-tokens + MASTER.md.
+
+**Token schema keys:** duration (instant-slower), easing (ease-out/ease-in-out/spring), transitions, keyframes, interactions (hover states), reduced_motion (prefers-reduced-motion strategy).
+
+#### 4d. Map files to design-ref/
+
+Copy `design-system/MASTER.md` and `design-system/pages/*.md` (if generated) to `${PHASE_DIR}/design-ref/`.
+
+#### 4e. Write selection.json
+
+```json
+{
+  "selected_variant": 1,
+  "variant_name": "{pattern_name} — {style_name}",
+  "selection_mode": "user_choice|auto",
+  "source": "ui-ux-pro-max",
+  "keywords": "{selected_variant_keywords}",
+  "selected_at": "ISO timestamp"
+}
+```
+
+#### 4f. Optional: Generate HTML prototype
+
+For each target, spawn agent to create `${PHASE_DIR}/design-ref/prototypes/${target}.html` from design-tokens + animation-tokens + MASTER.md.
+
+**Rules:** standalone HTML with embedded CSS, realistic content (not lorem ipsum), SVG icons (Heroicons/Lucide CDN), cursor-pointer on clickables, responsive (375/768/1024px), WCAG AA, prefers-reduced-motion.
+
+#### 4g. Update index.json
+
+```json
+{
+  "design_ref": {
+    "status": "selected",
+    "variant": "{variant_name}",
+    "source": "ui-ux-pro-max",
+    "master": "design-ref/MASTER.md",
+    "tokens": "design-ref/design-tokens.json",
+    "animation": "design-ref/animation-tokens.json",
+    "prototypes": "design-ref/prototypes/",
+    "created_at": "ISO timestamp"
+  }
+}
+```
+
+---
+
+## Escalation
+
+If the design needs exceed ui-ux-pro-max capabilities (e.g., multi-layout matrix, 6D attribute space exploration, full style x layout x target prototype grid), suggest:
+
+```
+For advanced multi-layer design exploration:
+  /maestro-impeccable --chain build {target}
+```
+
+---
+
+## Integration with maestro-plan
+
+Same as ui-design.md — plan.md Step 4b detects `design-ref/MASTER.md` and includes tokens in task `read_first[]`.
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| ui-ux-pro-max returns empty | Retry with broader keywords, then abort |
+| Token extraction agent fails | Retry once, warn if still fails |
+| User cancels selection | Save all variants, exit without solidification |
+
+---
+
+## State Updates
+
+| When | Field | Value |
+|------|-------|-------|
+| Step 1 start | index.json.status | "designing" |
+| Step 4 complete | index.json.design_ref.status | "selected" |
+| Step 4 complete | index.json.updated_at | Current timestamp |

package/workflows/updates/update-v3-setup.md

@@ -18,24 +18,16 @@ v2→v3 迁移后的环境配置。验证并引导用户完成知识系统、Cod
   - wiki search    → maestro search
 ```
 
-## Step 2: CodeGraph 安装
+## Step 2: MaestroGraph 初始化
 
 ```
-1. 检测：node -e "require('@colbymchenry/codegraph')" 2>&1
-2. IF 已安装 → 显示 "CodeGraph：已安装"
-3. IF 未安装 → 显示：
-     "可选：@colbymchenry/codegraph（tree-sitter 代码分析）"
-     "启用函数级 KG，提供 callers/callees 查询。"
-     "安装：npm install -g @colbymchenry/codegraph"
-   
-   AskUserQuestion: "是否安装 CodeGraph？"
-   Options: [安装 / 跳过]
-   IF 安装：
-     Bash: npm install -g @colbymchenry/codegraph
+1. 检测：maestro kg health
+2. IF 已初始化 → 显示 "MaestroGraph：已就绪"
+3. IF 未初始化：
+     Bash: maestro kg sync
+     显示 "MaestroGraph 索引已初始化"
 
-4. IF 已安装 AND 无索引：
-     Bash: maestro kg index --sqlite
-     显示 "KG 索引已初始化"
+注：代码分析引擎 (tree-sitter) 已内置，无需安装额外依赖。
 ```
 
 ## Step 3: Hook 升级