maestro-flow-one 0.1.0

package/claude/maestro-flow/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: maestro-flow
+description: Unified workflow command collection — intent routing, minimal closed-loop chain selection, step-by-step execution. All 49 maestro commands in one skill.
+argument-hint: "\"intent\" [-y] [--chain <name>] [--cmd <name> <args>] | list | status | continue | execute"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - AskUserQuestion
+---
+
+<purpose>
+Single-entry skill packaging all 49 Maestro workflow commands (Claude Code variant).
+
+Two execution modes:
+1. **Router** (default): Analyze intent -> match chain template -> create session -> step execution
+2. **Direct** (`--cmd <name> <args>`): Load and execute a specific command inline
+
+Execution uses `maestro-flow next/done` CLI for step lifecycle management.
+Commands loaded via `maestro-flow resolve` + `Read()` for inline execution.
+External steps delegated via `maestro delegate --to claude "/maestro-flow --cmd ..."`.
+
+Session path: `.workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS -- intent text, flags, or special keywords.
+
+**State files:**
+- `.workflow/state.json` -- project artifact registry (optional)
+- `.workflow/.maestro/flow-*/status.json` -- flow session state
+</context>
+
+<execution>
+
+## Step 1: Parse & Route
+
+```
+Parse $ARGUMENTS:
+
+  --cmd <name> <remaining-args>
+    -> Step 1a: Direct Command Execution
+    -> End.
+
+  list
+    -> Bash: maestro-flow list
+    -> End.
+
+  status [session-id]
+    -> Bash: maestro-flow status [session-id]
+    -> End.
+
+  chains
+    -> Bash: maestro-flow chains
+    -> End.
+
+  execute | continue
+    -> Find latest running flow session
+    -> If not found: "No running flow session." End.
+    -> Phase 2 (Step Execution Loop)
+
+  --chain <name> [-y] <remaining>
+    -> Force chain selection, go to Step 4
+
+  -y / --yes
+    -> auto_confirm = true
+
+  Other text
+    -> intent = remaining text -> Step 2
+```
+
+### Step 1a: Direct Command Execution (--cmd)
+
+```
+1. Bash: maestro-flow resolve <name>
+   -> Returns absolute path to command .md file
+
+2. If NOT_FOUND -> Error. End.
+
+3. Read() the command .md file
+
+4. Set $ARGUMENTS = <remaining-args>
+
+5. Follow the command's <execution> section completely
+
+End.
+```
+
+---
+
+## Step 2: Read Project State (optional)
+
+```
+If .workflow/state.json exists:
+  Read -> extract: current_milestone, milestones, artifacts
+If not: state_summary = "Project not initialized"
+```
+
+## Step 3: Intent Analysis & Chain Matching
+
+```
+Bash: maestro-flow suggest "{intent}"
+
+Display top 3 chain options
+AskUserQuestion: select chain / single command / Cancel
+
+If auto_confirm: pick highest scoring chain
+If single command: --cmd -> Step 1a
+If chain selected: -> Step 4
+```
+
+---
+
+## Step 4: Build Session
+
+### 4.1: Create session from template
+
+```
+session_id = "flow-{YYYYMMDD-HHmmss}"
+session_dir = .workflow/.maestro/{session_id}/
+
+Build steps[] from selected chain template.
+Write status.json.
+Display chain steps, confirm (or auto if -y).
+```
+
+Fall through to Phase 2.
+
+---
+
+## Phase 2: Step Execution Loop
+
+### 2.1: Load next step
+
+```
+Bash: maestro-flow next
+```
+
+Parse output:
+- `NO_SESSION` -> End.
+- `SESSION_COMPLETE` -> Display summary. End.
+- `STEP: idx/total` + `TYPE` + `SKILL` + `ARGS` + `PATH` + `---COMMAND---` -> continue
+
+### 2.2: Route by type
+
+```
+If TYPE == "decision" -> Step 2.3 (Decision Evaluation)
+If TYPE == "internal" -> Step 2.4 (Internal Execution)
+If TYPE == "external" -> Step 2.5 (External Execution)
+```
+
+### 2.3: Decision Evaluation
+
+**Quality-gate decisions** (post-verify, post-review, post-test, post-business-test):
+
+```
+Resolve artifact dir from .workflow/state.json
+
+Bash({
+  command: `maestro delegate "evaluate ${decision} quality gate
+CONTEXT: @${result_files}
+---VERDICT---
+STATUS: proceed | fix | escalate
+REASON: one-line
+GAP_SUMMARY: details
+CONFIDENCE: high | medium | low
+---END---" --role analyze --mode analysis`,
+  run_in_background: true
+})
+STOP -- wait for callback.
+```
+
+On callback: parse verdict, apply (proceed/fix-loop/escalate).
+
+**Structural decisions** (post-milestone): evaluate directly.
+
+After decision: `Bash: maestro-flow done` -> loop to 2.1.
+
+### 2.4: Internal Execution
+
+The command content was loaded by `maestro-flow next` (after `---COMMAND---`).
+
+```
+1. Parse loaded command .md
+2. Set $ARGUMENTS = ARGS (with auto-flag if session.auto_mode)
+3. Follow <execution> section completely
+
+Auto flags: maestro-init -y, maestro-plan -y, maestro-execute -y,
+            quality-test -y --auto-fix, etc.
+
+On complete: Bash: maestro-flow done -> loop to 2.1
+On failure: -> Step 2.6
+```
+
+### 2.5: External Execution
+
+```
+Bash({
+  command: `maestro delegate --to claude "Execute: /maestro-flow --cmd {SKILL} {ARGS}" --mode write`,
+  run_in_background: true,
+  timeout: 600000
+})
+STOP -- wait for callback.
+
+On callback:
+  On success: Bash: maestro-flow done -> loop to 2.1
+  On failure: -> Step 2.6
+```
+
+### 2.6: Handle Failure
+
+```
+Auto mode: retry once (maestro-flow step {id} {idx} pending), then skip
+Interactive: AskUserQuestion retry/skip/abort
+```
+
+---
+
+## Phase 3: Completion
+
+```
+Display session summary with step statuses.
+End.
+```
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and no running session | Prompt for intent |
+| E002 | error | Command not found for --cmd | maestro-flow list |
+| E003 | error | No matching chain template | maestro-flow chains |
+| E004 | error | Delegate verdict parse failed | Fallback: treat as "fix" |
+</error_codes>

package/claude/maestro-flow/chains/templates.json

@@ -0,0 +1,256 @@
+{
+  "version": "2.0",
+  "decision_types": {
+    "post-verify": {
+      "evaluates": "verification.json",
+      "verdict_prompt": "评估验证结果: passed/failed 状态, gaps 严重性",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify"]
+    },
+    "post-review": {
+      "evaluates": "review.json",
+      "verdict_prompt": "评估代码审查结果: verdict PASS/WARN/BLOCK",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "quality-review", "decision:post-review"]
+    },
+    "post-test": {
+      "evaluates": "uat.md, test-results.json",
+      "verdict_prompt": "评估测试结果: 通过率, 失败用例严重性",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify", "quality-test", "decision:post-test"]
+    },
+    "post-business-test": {
+      "evaluates": "business-test-results.json",
+      "verdict_prompt": "评估业务测试结果: 需求覆盖率, 失败场景",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify", "quality-auto-test", "decision:post-business-test"]
+    },
+    "post-milestone": {
+      "evaluates": "state.json",
+      "verdict_prompt": "检查是否有下一个 milestone",
+      "structural": true
+    }
+  },
+  "templates": {
+    "quick-fix": {
+      "description": "Diagnose and fix a known bug",
+      "category": "quick-fix",
+      "triggers": ["fix", "debug", "bug", "error", "crash", "broken"],
+      "steps": [
+        { "cmd": "quality-debug", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "maestro-plan", "args": "{phase} --gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "issue-fix": {
+      "description": "Analyze, plan, fix, and close a tracked issue",
+      "category": "quick-fix",
+      "triggers": ["issue", "ISS-", "ticket"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "--gaps {issue_id}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "--gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "manage-issue", "args": "close {issue_id} --resolution fixed", "type": "internal" }
+      ]
+    },
+    "analyze-plan-execute": {
+      "description": "Fast track: analyze, plan, and implement",
+      "category": "feature-build",
+      "triggers": ["implement", "build", "create", "develop", "add feature"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "\"{intent}\"", "type": "external" },
+        { "cmd": "maestro-plan", "args": "--dir {scratch_dir}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "--dir {scratch_dir}", "type": "external" }
+      ]
+    },
+    "plan-execute-verify": {
+      "description": "Full phase: plan, execute, verify with quality gate",
+      "category": "feature-build",
+      "triggers": ["plan and execute", "phase", "plan execute"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "execute-verify": {
+      "description": "Execute existing plan and verify",
+      "category": "feature-build",
+      "triggers": ["execute", "run plan", "implement plan"],
+      "steps": [
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" }
+      ]
+    },
+    "quality-loop": {
+      "description": "Full quality check: verify, review, test with decision gates",
+      "category": "quality-check",
+      "triggers": ["check quality", "review and test", "quality", "qa"],
+      "steps": [
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "review-fix": {
+      "description": "Fix review-blocked issues",
+      "category": "quality-check",
+      "triggers": ["fix review", "review block", "review fail"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase} --gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "brainstorm-driven": {
+      "description": "Explore idea then plan and build",
+      "category": "explore",
+      "triggers": ["brainstorm", "explore idea", "ideate"],
+      "steps": [
+        { "cmd": "maestro-brainstorm", "args": "\"{intent}\"", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "roadmap-driven": {
+      "description": "From requirements to roadmap to first phase with gates",
+      "category": "lifecycle",
+      "triggers": ["roadmap", "from requirements", "start project", "new project"],
+      "steps": [
+        { "cmd": "maestro-init", "args": "", "type": "internal" },
+        { "cmd": "maestro-roadmap", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "maestro-analyze", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "full-lifecycle": {
+      "description": "Complete phase lifecycle with all quality gates (ralph-equivalent)",
+      "category": "lifecycle",
+      "triggers": ["full lifecycle", "complete phase", "lifecycle", "ralph"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-business-test", "args": "", "type": "decision", "decision": "post-business-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-complete", "args": "", "type": "internal" },
+        { "cmd": "decision:post-milestone", "args": "", "type": "decision", "decision": "post-milestone" }
+      ]
+    },
+    "standard-lifecycle": {
+      "description": "Standard phase lifecycle: verify + review + test gates",
+      "category": "lifecycle",
+      "triggers": ["standard lifecycle", "standard phase", "standard"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" }
+      ]
+    },
+    "milestone-close": {
+      "description": "Audit and close current milestone",
+      "category": "milestone",
+      "triggers": ["close milestone", "complete milestone", "milestone done"],
+      "steps": [
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-complete", "args": "", "type": "internal" },
+        { "cmd": "decision:post-milestone", "args": "", "type": "decision", "decision": "post-milestone" }
+      ]
+    },
+    "milestone-release": {
+      "description": "Audit and release milestone with version tag",
+      "category": "milestone",
+      "triggers": ["release", "publish", "tag version", "ship"],
+      "steps": [
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-release", "args": "", "type": "internal" }
+      ]
+    },
+    "learn-deep": {
+      "description": "Deep module understanding: read, decompose, critique",
+      "category": "explore",
+      "triggers": ["understand", "deep learn", "study", "learn module"],
+      "steps": [
+        { "cmd": "learn-follow", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "learn-decompose", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "learn-second-opinion", "args": "\"{intent}\" --mode challenge", "type": "internal" }
+      ]
+    }
+  },
+  "single_commands": {
+    "status": "manage-status",
+    "init": "maestro-init",
+    "analyze": "maestro-analyze",
+    "plan": "maestro-plan",
+    "execute": "maestro-execute",
+    "verify": "maestro-verify",
+    "review": "quality-review",
+    "test": "quality-test",
+    "auto-test": "quality-auto-test",
+    "debug": "quality-debug",
+    "refactor": "quality-refactor",
+    "sync": "quality-sync",
+    "retrospective": "quality-retrospective",
+    "issue": "manage-issue",
+    "discover-issues": "manage-issue-discover",
+    "harvest": "manage-harvest",
+    "knowhow": "manage-knowhow",
+    "knowhow-capture": "manage-knowhow-capture",
+    "spec-add": "spec-add",
+    "spec-load": "spec-load",
+    "spec-remove": "spec-remove",
+    "spec-setup": "spec-setup",
+    "wiki": "manage-wiki",
+    "wiki-connect": "wiki-connect",
+    "wiki-digest": "wiki-digest",
+    "brainstorm": "maestro-brainstorm",
+    "roadmap": "maestro-roadmap",
+    "fork": "maestro-fork",
+    "merge": "maestro-merge",
+    "quick": "maestro-quick",
+    "learn-follow": "learn-follow",
+    "learn-investigate": "learn-investigate",
+    "learn-decompose": "learn-decompose",
+    "learn-retro": "learn-retro",
+    "learn-second-opinion": "learn-second-opinion",
+    "amend": "maestro-amend",
+    "compose": "maestro-composer",
+    "play": "maestro-player",
+    "update": "maestro-update",
+    "ui-design": "maestro-ui-design",
+    "milestone-audit": "maestro-milestone-audit",
+    "milestone-complete": "maestro-milestone-complete",
+    "milestone-release": "maestro-milestone-release",
+    "codebase-rebuild": "manage-codebase-rebuild",
+    "codebase-refresh": "manage-codebase-refresh"
+  }
+}

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

@@ -0,0 +1,176 @@
+---
+name: learn-decompose
+description: Decompose code into cataloged design patterns, saving findings to specs and wiki
+argument-hint: "<path|module> [--patterns <list>] [--save-spec] [--save-wiki]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - 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.
+</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: "maestro-flow", args: "--cmd 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/learning/decompose-{slug}-{YYYY-MM-DD}.md` — Pattern decomposition report
+- `.workflow/learning/lessons.jsonl` — One insight per discovered pattern (source: "decompose")
+- `.workflow/learning/learning-index.json` — Updated index
+- 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/learning/lessons.jsonl` — Previously identified patterns (for dedup)
+</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 `lessons.jsonl` for entries with `category: "pattern"` — 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 lessons), 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/learning/decompose-{slug}-{date}.md`
+2. Append each **new** pattern to `lessons.jsonl`:
+   - `source: "decompose"`, `category: "pattern"`, `confidence: <level>`
+   - Tags: `["decompose", "{dimension}", "{target-slug}"]`
+   - Stable INS-id from `hash("decompose" + target + pattern_name)`
+3. Update `learning-index.json`
+4. If `--save-spec`: for each new pattern, invoke `Skill({ skill: "maestro-flow", args: "--cmd spec-add 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>
+
+<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 |
+</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 `decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] `learning-index.json` updated
+- [ ] If --save-spec: spec entries created for new patterns
+- [ ] If --save-wiki: wiki notes created per dimension group
+- [ ] No files modified outside `.workflow/learning/` (and optionally specs/wiki)
+- [ ] Summary displayed with pattern counts and next-step routing
+</success_criteria>