maestro-flow 0.3.43 → 0.3.45

package/.codex/skills/maestro-tools-execute/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by role or name
+argument-hint: "[tool-name | --category <category>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
+
+<purpose>
+Load registered tool specs and execute them step-by-step. Two invocation modes:
+
+1. **Direct** — Specify tool name, load full steps, execute sequentially
+2. **Category-based** — List available tools for a category, user selects, then execute
+
+Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
+</purpose>
+
+<context>
+$ARGUMENTS — Tool name, keyword, or --category filter
+
+```bash
+$maestro-tools-execute "integration-test"
+$maestro-tools-execute "--category coding"
+$maestro-tools-execute "--category review --keyword api"
+$maestro-tools-execute
+```
+
+Empty arguments enters interactive mode: list all tools for user selection.
+</context>
+
+<execution>
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro spec load --category coding --keyword <name>
+```
+Match tool entries whose title or keywords contain the name.
+
+**By category**:
+```bash
+maestro spec load --category <category>
+```
+Extract tool entries from output, list available tools.
+
+**Empty args**:
+Load all tool entries, present to user with AskUserQuestion for selection.
+
+### Step 2: Display Tool
+
+Show tool information:
+- Name, category, keywords
+- Steps overview (for ref entries, expand knowhow detail first)
+
+Expand ref entries:
+```bash
+maestro wiki load <knowhow-id>
+```
+
+### Step 3: Confirm Execution
+
+Ask user:
+- Execute steps as-is?
+- Adjust parameters/scope?
+- View only, do not execute?
+
+### Step 4: Step-by-Step Execution
+
+Follow the tool definition steps in order:
+1. Read current step description
+2. Execute step action (file ops, commands, code changes, etc.)
+3. Verify step completion
+4. Report progress: `[Step N/M] done — <step_name>`
+5. Proceed to next step
+
+**Blocker handling**:
+- Step fails → report error, ask user: retry / skip / abort
+- Needs user input → AskUserQuestion for parameters
+- Prerequisites unmet → show missing items, ask how to proceed
+
+### Step 5: Report Results
+
+After completion, output:
+- Completed steps list
+- Skipped/failed steps (if any)
+- Artifacts produced (generated files, test results, etc.)
+- Suggested next actions
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | No matching tool found — check name/keyword |
+| E002 | warning | Multiple tools match — list options for user selection |
+| E003 | warning | Step execution failed — ask user how to proceed |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool correctly loaded (ref expanded if applicable)
+- [ ] User confirmed before execution starts
+- [ ] Each step has progress feedback
+- [ ] Blockers handled interactively
+- [ ] Results reported clearly
+</success_criteria>

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: maestro-tools-register
+description: Register tool specs - extract, generate, or optimize reusable process definitions
+argument-hint: "[description or intent]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
+
+<purpose>
+Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter. Once registered, entries are auto-discovered by downstream agents via `spec load --category` — plan agents pick up design/architecture flows, test agents pick up verification methods, coding agents pick up execution steps.
+
+Three modes:
+
+1. **Extract** — Pull reusable processes from conversations/code/docs
+2. **Generate** — Create new tool definitions from user description
+3. **Optimize** — Improve existing tool spec steps, structure, clarity
+
+Short processes (<10 steps) inline; long processes (>=10 steps or with code examples) use ref mode with knowhow detail doc (RCP-/DOC-).
+</purpose>
+
+<context>
+$ARGUMENTS — User intent description, or empty (interactive guidance)
+
+```bash
+$maestro-tools-register "extract OAuth PKCE token exchange flow from src/auth/"
+$maestro-tools-register "generate Stripe webhook idempotency verification"
+$maestro-tools-register "generate E2E checkout flow with payment gateway mock setup"
+$maestro-tools-register "optimize e2e-checkout tool"
+```
+
+**Tool registration**: Creates knowhow documents in `knowhow/` folder with `tool: true` in YAML frontmatter. Tools are auto-discovered by `spec load` based on category + tool flag.
+
+**Knowhow format**:
+```yaml
+---
+title: Tool Name
+type: recipe
+category: coding
+summary: "Use when <timing>. <scope description>"
+tags: [testing, api]
+tool: true
+---
+Step content...
+```
+</context>
+
+<execution>
+
+### Step 1: Intent Detection
+
+Parse $ARGUMENTS to determine mode:
+- Contains "extract" → extract mode
+- Contains "optimize/improve" → optimize mode
+- Other → generate mode
+- Empty → ask user with AskUserQuestion
+
+### Step 2: Gather Information
+
+**Extract mode**:
+- Identify source (current conversation, specified files, codebase scan)
+- Extract step sequence, prerequisites, expected outputs
+
+**Generate mode**:
+- Confirm tool name, applicable roles, target scenario
+- If unclear, ask user with AskUserQuestion
+
+**Optimize mode**:
+- Load existing tool: `maestro spec load --category coding --keyword <name>`
+- Analyze improvement points (step splitting, prerequisites, error handling)
+
+**For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
+
+### Step 3: Determine Category
+
+Infer applicable category from context, or ask user:
+- coding — execution tools (build, deploy, integrate)
+- test — testing tools (test flows, verification steps)
+- review — review tools (checklists, audit standards)
+- arch — planning tools (design flows, analysis steps)
+- debug — analysis tools (diagnostic flows, investigation steps)
+
+### Step 4: Decide Inline vs Ref
+
+- Steps <10 and no code blocks → **inline mode**
+- Steps >=10 or contains code examples/config → **ref mode**
+
+### Step 5: Write
+
+**Description format**: First line after `### Title` must state **when to use** this tool (the usage timing from Step 2). This is critical for ref entries — `spec load` only shows the first 200 chars after the heading as the summary.
+
+```
+### {Title}
+
+Use when {timing/trigger condition}.
+
+1. Step one ...
+```
+
+**Inline mode**:
+Create a knowhow document in `knowhow/` with `tool: true` frontmatter:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+summary: "Use when <timing>. <scope description>"
+tags: [<keywords>]
+tool: true
+---
+Use when <timing>.
+
+1. <step1>
+2. <step2>
+```
+
+**Ref mode**:
+1. Generate knowhow detail document (RCP- or DOC- prefix). YAML frontmatter must include `summary` with usage timing and `tool: true`:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+summary: "Use when <timing>. <scope description>"
+tags: [<keywords>]
+tool: true
+---
+```
+
+### Step 6: Verify
+
+- `maestro spec load --category <category> --keyword <keyword>` to confirm loadable
+- Display result: title, category, keywords, storage location
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` does not exist — run `maestro spec init` |
+| E002 | warning | Duplicate tool name detected — confirm overwrite/optimize |
+| E003 | fatal | category parameter empty — tools must declare applicable category |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category attribute correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Loadable via `spec load --category <category>`
+- [ ] Long processes use ref mode with knowhow file created
+</success_criteria>

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -0,0 +1,398 @@
+---
+name: maestro-ui-codify
+description: Extract design system from code, generate reference package, persist as knowledge assets
+argument-hint: "<source-path> [--package-name <name>] [--output-dir <path>] [--overwrite] [-y]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Wave-based UI design system codification using `spawn_agents_on_csv`. Diamond topology: file discovery (Wave 1), parallel style/animation/layout extraction (Wave 2), reference package generation (Wave 3), knowledge asset persistence (Wave 4).
+
+**Core workflow**: Validate & Setup -> File Discovery -> 3-Agent Extraction -> Package Generation -> Knowhow Persistence
+
+```
++---------------------------------------------------------------------------+
+|                  UI CODIFY CSV WAVE WORKFLOW                               |
++---------------------------------------------------------------------------+
+|                                                                           |
+|  Step 1-2: Parse & Validate (inline)                                      |
+|     +-- Parse source-path, --package-name, --output-dir, --overwrite      |
+|     +-- Validate source directory exists                                  |
+|     +-- Resolve package name (auto or explicit)                           |
+|     +-- Setup workspace directories                                       |
+|                                                                           |
+|  Step 3: Generate tasks.csv                                               |
+|     +-- Wave 1: File discovery (1 agent, barrier)                         |
+|     +-- Wave 2: Parallel extraction (3 agents)                            |
+|     |   +-- Style Agent: design-tokens.json                               |
+|     |   +-- Animation Agent: animation-tokens.json                        |
+|     |   +-- Layout Agent: layout-templates.json                           |
+|     +-- Wave 3: Reference package (1 agent, barrier)                      |
+|     |   +-- Copy tokens to package dir                                    |
+|     |   +-- Generate preview.html + preview.css                           |
+|     +-- Wave 4: Knowledge assets (1 agent, barrier)                       |
+|         +-- Build knowhow-manifest.json                                   |
+|         +-- Write knowhow files + spec entries                            |
+|         +-- Cleanup temp workspace                                        |
+|                                                                           |
+|  Step 4: Wave Execution via spawn_agents_on_csv                           |
+|                                                                           |
+|  Step 5: Results & Completion Report                                      |
+|                                                                           |
++---------------------------------------------------------------------------+
+```
+
+</purpose>
+
+<context>
+```bash
+$maestro-ui-codify "src/components"
+$maestro-ui-codify "src/components" --package-name my-design-v1
+$maestro-ui-codify "src/styles" --output-dir .workflow/packages --overwrite -y
+```
+
+**Flags**:
+- `<source-path>` (positional, required): Directory containing CSS/SCSS/JS/TS/HTML source files
+- `--package-name <name>`: Package name for reference output (default: auto from source directory)
+- `--output-dir <path>`: Output directory (default: `.workflow/reference_style`)
+- `--overwrite`: Allow overwriting existing package directory
+- `-y, --yes`: Skip all confirmations
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final)
+**Package Output**: `{output-dir}/{package-name}/` with design-tokens.json, layout-templates.json, animation-tokens.json, preview.html, preview.css, knowhow-manifest.json
+</context>
+
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,wave,title,description,agent_type,deps,status,findings,output_path,error
+"discover-1","1","Discover design files","Scan source directory, categorize files by type (CSS/SCSS/JS/TS/HTML), build file inventory with import relationships","discover","","","","",""
+"style-1","2","Extract visual design tokens","Extract color, typography, spacing, border, shadow tokens from source files. Output design-tokens.json","extract-style","discover-1","","","",""
+"anim-1","2","Extract animation tokens","Extract animation/transition declarations: keyframes, durations, easings, motion patterns. Output animation-tokens.json","extract-animation","discover-1","","","",""
+"layout-1","2","Extract layout patterns","Extract component layout patterns: grid/flex systems, responsive breakpoints, container patterns. Output layout-templates.json","extract-layout","discover-1","","","",""
+"package-1","3","Generate reference package","Copy token JSONs to package dir, generate preview.html + preview.css interactive showcase","package","style-1;anim-1;layout-1","","","",""
+"knowhow-1","4","Build knowledge assets","Read token JSONs, build knowhow-manifest.json, write knowhow files + spec entries, cleanup temp workspace","knowhow","package-1","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier |
+| `wave` | Input | Wave number (1=discover, 2=extract, 3=package, 4=knowhow) |
+| `title` | Input | Short task title |
+| `description` | Input | Detailed instructions for this task |
+| `agent_type` | Input | Agent type: discover/extract-style/extract-animation/extract-layout/package/knowhow |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `status` | Output | `pending` -> `completed` / `failed` |
+| `findings` | Output | Key findings summary (max 500 chars) |
+| `output_path` | Output | Path to generated artifact |
+| `error` | Output | Error message if failed |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-ui-codify-{slug}/
++-- tasks.csv
++-- results.csv
++-- wave-{N}.csv (temporary)
+```
+
+</csv_schema>
+
+<invariants>
+1. **Start Immediately**: First action is argument parsing, then validation
+2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state
+4. **Context Propagation**: Wave 2 agents receive file discovery findings via prev_context
+5. **Animation is Optional**: Missing animation-tokens.json is W001 warning, not fatal
+6. **Idempotent Package**: --overwrite required to replace existing package directory
+7. **Cleanup Temp Files**: Remove wave-{N}.csv after results merged, remove temp workspace after Wave 4
+8. **DO NOT STOP**: Continuous execution until all waves complete
+</invariants>
+
+<execution>
+
+### Step 1: Parse Arguments
+
+**Parse from `$ARGUMENTS`**:
+
+| Variable | Source | Default |
+|----------|--------|---------|
+| `source_path` | positional (required) | ERROR if missing |
+| `package_name` | `--package-name <name>` | auto from source dir |
+| `output_dir` | `--output-dir <path>` | `.workflow/reference_style` |
+| `overwrite` | `--overwrite` | false |
+| `AUTO_YES` | `-y` or `--yes` | false |
+
+### Step 2: Validate & Setup
+
+**2a: Validate source path**:
+
+```bash
+# E001: Source path required
+test -n "$source_path" || { echo "E001: Source path argument required"; exit 1; }
+
+# E002: Source path must be a directory
+test -d "$source_path" || { echo "E002: Source path not found or not a directory: $source_path"; exit 1; }
+
+source_path=$(cd "$source_path" && pwd)
+```
+
+**2b: Resolve package name**:
+
+```bash
+# Auto-generate: directory name -> kebab-case + "-style" suffix
+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
+```
+
+**2c: Setup directories**:
+
+```bash
+output_dir="${output_dir:-.workflow/reference_style}"
+package_dir="${output_dir}/${package_name}"
+
+# E003: Overwrite protection
+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
+fi
+
+# Create temp workspace + package dir
+timestamp=$(date +%Y%m%d%H%M%S)
+temp_dir=".workflow/codify-temp-${timestamp}"
+mkdir -p "$temp_dir"
+mkdir -p "$package_dir"
+
+# Session directory
+session_slug=$(echo "$package_name" | head -c 40)
+session_date=$(date -u +%Y%m%d)
+sessionFolder=".workflow/.csv-wave/${session_date}-ui-codify-${session_slug}"
+mkdir -p "$sessionFolder"
+```
+
+### Step 3: Generate tasks.csv
+
+Build the master CSV with 4 waves. The `description` column contains full agent instructions.
+
+**Wave 1 — File Discovery** (1 agent, barrier):
+
+Description template:
+```
+Scan source directory '${source_path}' for design-relevant files. Categorize by type:
+- CSS/SCSS files: stylesheets with design tokens
+- JS/TS files: style objects, theme configs, styled-components
+- HTML files: template structure with inline styles
+
+Build file inventory JSON at '${temp_dir}/file-inventory.json':
+{
+  "source_path": "${source_path}",
+  "files": [
+    { "path": "...", "type": "css|scss|js|ts|html", "category": "tokens|components|layout|animation", "size": N }
+  ],
+  "summary": { "total": N, "by_type": {...}, "by_category": {...} }
+}
+
+Use Glob to find files, Read to sample content for categorization. Report total file count and category breakdown in findings.
+```
+
+**Wave 2 — Parallel Extraction** (3 agents):
+
+Each agent receives file discovery findings via `prev_context`. Agent prompts reference workflow files for detailed extraction logic:
+
+- **Style Agent**: Follow `@~/.maestro/workflows/ui-codify-extract.md` Style Agent section. Source: `${source_path}`. Read file inventory from `${temp_dir}/file-inventory.json`. Write `${temp_dir}/design-tokens.json` with color, typography, spacing, border, shadow tokens.
+- **Animation Agent**: Follow `@~/.maestro/workflows/ui-codify-extract.md` Animation Agent section. Source: `${source_path}`. Read file inventory from `${temp_dir}/file-inventory.json`. Write `${temp_dir}/animation-tokens.json` with keyframes, transitions, easings. Optional — W001 if no animations found.
+- **Layout Agent**: Follow `@~/.maestro/workflows/ui-codify-extract.md` Layout Agent section. Source: `${source_path}`. Read file inventory from `${temp_dir}/file-inventory.json`. Write `${temp_dir}/layout-templates.json` with grid/flex systems, breakpoints, component patterns.
+
+**Wave 3 — Reference Package** (1 agent, barrier):
+
+Description template:
+```
+Follow @~/.maestro/workflows/ui-codify-package.md to generate reference package.
+
+Copy token files from '${temp_dir}' to '${package_dir}':
+- design-tokens.json (required)
+- animation-tokens.json (optional, skip if missing)
+- layout-templates.json (required)
+
+Generate preview.html + preview.css in '${package_dir}' as interactive token showcase.
+Preview must display all extracted tokens visually: color swatches, typography samples, spacing scale, animation demos.
+
+Report file counts and package size in findings.
+```
+
+**Wave 4 — Knowledge Assets** (1 agent, barrier):
+
+Description template:
+```
+Follow @~/.maestro/workflows/ui-codify-knowhow.md to build knowledge assets.
+
+1. Read token JSONs from '${package_dir}' (design-tokens.json, layout-templates.json, animation-tokens.json if exists)
+2. Build knowhow-manifest.json in '${package_dir}' with:
+   - slug: '${package_name}'
+   - domain: 'ui-design'
+   - roles: ['implement', 'review']
+   - packagePath: '${package_dir}'
+   - knowhow[]: AST- entries for tokens and components
+   - specs[]: coding + arch entries with ref links to knowhow files
+3. Write knowhow files to .workflow/knowhow/ per manifest.knowhow[]
+4. Write spec entries per manifest.specs[] using maestro spec add CLI (fallback: direct file append)
+5. Refresh wiki index: maestro wiki health
+6. Cleanup temp workspace: rm -rf '${temp_dir}'
+
+Report knowhow file count and spec entry count in findings.
+```
+
+Write `tasks.csv` to `${sessionFolder}/tasks.csv`.
+
+### Step 4: Wave Execution
+
+Execute waves sequentially via `spawn_agents_on_csv`.
+
+#### Wave 1: File Discovery (Barrier)
+
+Filter `wave == 1 && status == pending` from master CSV. Write `wave-1.csv`.
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: `You are scanning a source directory for design-relevant files. Read the 'description' column for full instructions. Use Glob to find files, Read to sample content. Write file inventory JSON to the specified path. Report findings as a concise summary.`,
+  max_concurrency: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-1.csv`.
+
+#### Wave 2: Parallel Extraction (3 agents)
+
+Filter `wave == 2 && status == pending`. Build `prev_context` from wave 1 findings (file inventory summary). Write `wave-2.csv` with `prev_context` column.
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-2.csv`,
+  id_column: "id",
+  instruction: `You are extracting design tokens from source code. Read the 'description' column for your specific extraction task. Use prev_context for file inventory from discovery phase. Read source files, extract tokens, write output JSON to the specified path.`,
+  max_concurrency: 3,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-2.csv`.
+
+**Degradation**: If animation agent fails (W001), continue — animation is optional. If style or layout agent fails, warn but continue with available results.
+
+#### Wave 3: Reference Package (Barrier)
+
+Filter `wave == 3 && status == pending`. Build `prev_context` from wave 2 findings (extraction summaries + output paths). Write `wave-3.csv` with `prev_context`.
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-3.csv`,
+  id_column: "id",
+  instruction: `You are generating a reference design package. Read the 'description' column for full instructions. Copy token files, generate preview.html and preview.css. Report package contents in findings.`,
+  max_concurrency: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionFolder}/wave-3-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-3.csv`.
+
+#### Wave 4: Knowledge Assets (Barrier)
+
+Filter `wave == 4 && status == pending`. Build `prev_context` from wave 3 findings (package contents). Write `wave-4.csv` with `prev_context`.
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-4.csv`,
+  id_column: "id",
+  instruction: `You are building knowledge assets from a design package. Read the 'description' column for full instructions. Build manifest, write knowhow files, create spec entries, refresh wiki index, cleanup temp files. Report asset counts in findings.`,
+  max_concurrency: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionFolder}/wave-4-results.csv`,
+  output_schema: { id, status: ["completed"|"failed"], findings, output_path, error }
+})
+```
+
+Merge results into master `tasks.csv`, delete `wave-4.csv`.
+
+### Step 5: Results & Completion
+
+1. Read final master `tasks.csv`
+2. Export as `results.csv`
+3. Display completion report:
+
+```
+UI Design System Codified!
+
+Package: {package_name}
+Location: {package_dir}
+
+Files:
+  design-tokens.json       Design tokens (colors, typography, spacing)
+  layout-templates.json    Component patterns
+  animation-tokens.json    Animation tokens {or "(not found)"}
+  preview.html             Interactive showcase
+  preview.css              Showcase styling
+  knowhow-manifest.json    Knowledge asset manifest
+
+Knowledge Assets:
+  Knowhow: {knowhow_count} files created
+  Specs: {spec_count} entries created
+
+Open preview:
+  file://{absolute_path}/preview.html
+
+Next steps:
+  maestro wiki list --category coding    # Browse by role
+  maestro spec load --keyword {package_name}    # Load related specs
+```
+
+</execution>
+
+<error_codes>
+
+| Error | Severity | Resolution |
+|-------|----------|------------|
+| E001: Source path required | fatal | Report usage, abort |
+| E002: Source not found | fatal | Report path, abort |
+| E003: Package exists | fatal | Suggest --overwrite, abort |
+| W001: No animations found | warning | Continue without animation-tokens.json |
+| Wave 1 failed | fatal | No files discovered, abort |
+| Wave 2 partial failure | degraded | Continue with available extraction results |
+| Wave 3 failed | fatal | Package generation failed, abort |
+| Wave 4 failed | degraded | Package still usable, manifest remains for manual retry |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Source path validated and session folder created
+- [ ] File discovery completed with inventory JSON
+- [ ] design-tokens.json generated with color, typography, spacing tokens
+- [ ] layout-templates.json generated with component patterns
+- [ ] animation-tokens.json generated (optional, W001 if missing)
+- [ ] preview.html + preview.css generated as interactive showcase
+- [ ] knowhow-manifest.json created with AST assets and spec entries
+- [ ] Knowhow files written to .workflow/knowhow/
+- [ ] Spec entries written via maestro spec add
+- [ ] Wiki index refreshed
+- [ ] Temporary workspace cleaned up
+- [ ] results.csv exported
+</success_criteria>