maestro-flow 0.3.45 → 0.3.47

package/.claude/skills/maestro-help/phases/02-search-present.md

@@ -0,0 +1,181 @@
+# Phase 2: Search & Present
+
+查询 catalog.json 并格式化呈现结果。覆盖 Mode 1/2/3/6/7。
+
+## Objective
+
+- 根据 Phase 1 输出的 mode 和 query 搜索 catalog
+- 读取 source 文件获取详情（Mode 2）
+- 检测项目状态提供智能推荐（Mode 3）
+- 格式化呈现搜索结果
+
+## Execution
+
+### Mode 1: Command Search
+
+```
+1. Read catalog.json
+2. Search commands[] + cli_commands[]:
+   - Filter by: name contains query (case-insensitive)
+   - OR: description contains query
+   - OR: category matches query
+3. Sort by relevance (exact name match > starts with > contains)
+4. Present top 5 results:
+```
+
+**输出格式**:
+
+```markdown
+找到 {N} 个匹配命令：
+
+**/{command-name}** — {description}
+  分类: {category} | 详细: {source file exists? → "查看详情 →" : "catalog only"}
+
+**/{command-name-2}** — {description}
+  ...
+```
+
+### Mode 2: Command Documentation
+
+```
+1. Locate command in catalog.json commands[] by name
+2. Read the source file (e.g., "../../commands/maestro-analyze.md")
+3. Extract key sections:
+   - <purpose> content
+   - argument-hint
+   - usage examples from <context>
+4. If a guide file references this command, read relevant section
+5. Present structured documentation:
+```
+
+**输出格式**:
+
+```markdown
+## /{command-name}
+
+**用途**: {description}
+
+**参数**: {argument-hint}
+
+**用法**:
+{extracted examples or usage patterns}
+
+**分类**: {category}
+
+**相关 Guide**: {guide file name if applicable}
+```
+
+**Guide 映射**:
+
+| 命令 | Guide 文档 |
+|------|-----------|
+| maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
+| maestro-init/roadmap | `guide/quick-start-guide.md` |
+| maestro-ralph | `guide/maestro-ralph-guide.md` |
+| maestro (协调器) | `guide/maestro-coordinator-guide.md` |
+| manage-* | `guide/command-usage-guide.md` (管理) |
+| quality-* | `guide/command-usage-guide.md` (质量) |
+| delegate | `guide/delegate-async-guide.md` |
+| overlay/amend | `guide/overlay-guide.md` |
+
+### Mode 3: Smart Recommendations
+
+```
+1. Detect project state from Phase 1
+2. Match state to workflow template from catalog.workflows
+3. Present recommendations with WHY:
+```
+
+**状态 → 推荐映射**:
+
+| 当前状态 | 推荐命令 | 原因 |
+|---------|---------|------|
+| 无 .workflow/ | `/maestro-init` | 项目未初始化，需要先创建工作区 |
+| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图指导后续 Phase |
+| roadmap 完成，phase=pending | `/maestro-analyze` | 准备开始分析阶段 |
+| analyze 完成 | `/maestro-plan` | 分析完成，进入规划 |
+| plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
+| execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
+| verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |
+| verify 通过 | `/quality-review` | 进入质量管线 |
+| quality 全通过 | `/maestro-milestone-audit` | 准备里程碑审计 |
+| 所有 Phase 完成 | `/maestro-milestone-complete` | 里程碑可以关闭 |
+
+### Mode 6: Skill & Agent Browsing
+
+**Skills**:
+```
+1. Read catalog.json skills[]
+2. If category specified: filter by category
+3. Group by category: meta / team / knowledge
+4. Present:
+```
+
+```markdown
+## Skills ({total} 个)
+
+### Meta (2)
+- **workflow-skill-designer** — 设计 orchestrator+phases 工作流 skill
+- **skill-iter-tune** — 迭代 execute-evaluate-improve 调优
+
+### Team (6)
+- **team-coordinate** — 通用团队协调，动态生成 role-specs
+- **team-executor** — 团队执行，恢复会话
+- **team-lifecycle-v4** — 8 角色完整生命周期
+- **team-quality-assurance** — QA 质量保障流水线
+- **team-review** — 多维度代码审查
+- **team-tech-debt** — 技术债务识别和清理
+- **team-testing** — 测试规划和执行
+
+### Knowledge (1)
+- **codify-to-knowhow** — Manifest 驱动的知识资产生成
+```
+
+**Agents**:
+```
+1. Read catalog.json agents[]
+2. Group by category: workflow / team / planning / cli / ui
+3. Present with category headers
+```
+
+### Mode 7: CLI Command Reference
+
+```
+1. Read catalog.json cli_commands[]
+2. Group by category: setup / dashboard / execution / knowledge / config / team / visualization
+3. Present table with command, alias, description:
+```
+
+```markdown
+## CLI 终端命令 (21 个)
+
+### 安装与更新 (setup)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro install` | — | 安装 Maestro 资源 |
+| `maestro uninstall` | — | 卸载已安装资源 |
+| `maestro update` | — | 检查/安装最新版本 |
+| `maestro launcher` | — | Claude Code 启动器 |
+
+### 任务执行 (execution)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro delegate` | — | 委派任务给 AI 智能体 |
+| `maestro coordinate` | `coord` | 图工作流协调器 |
+| `maestro cli` | — | 运行 CLI 智能体工具 |
+| `maestro run` | — | 执行指定工作流 |
+| `maestro serve` | — | 启动工作流服务器 |
+...
+```
+
+## Error Handling
+
+| 场景 | 处理 |
+|------|------|
+| 搜索无结果 | 模糊匹配最近命令，建议使用 `/maestro-help` 查看全部 |
+| Source 文件不存在 | 仅提供 catalog 描述，标注 "详细信息不可用" |
+| Catalog 读取失败 | 回退到 Glob 扫描 .claude/commands/*.md |
+
+## Output
+
+格式化的搜索/文档/推荐结果，直接展示给用户。

package/.claude/skills/maestro-help/phases/03-workflow-guide.md

@@ -0,0 +1,186 @@
+# Phase 3: Workflow Guide
+
+工作流推荐和新手引导。覆盖 Mode 4/5。
+
+## Objective
+
+- 根据用户任务推荐最合适的工作流
+- 为新手提供入门指引
+- 给出具体命令序列和说明
+
+## Execution
+
+### Mode 4: Workflow Guide
+
+根据用户描述的任务类型推荐工作流：
+
+#### Step 4.1: 任务分类
+
+```javascript
+// 任务类型识别
+const taskPatterns = [
+  { type: "new_project", patterns: ["新项目", "从头开始", "new project", "创建项目"] },
+  { type: "feature", patterns: ["添加功能", "新功能", "add feature", "实现"] },
+  { type: "bugfix", patterns: ["修复", "bug", "fix", "问题"] },
+  { type: "refactor", patterns: ["重构", "refactor", "优化", "改进"] },
+  { type: "analysis", patterns: ["分析", "analyze", "调查", "investigate"] },
+  { type: "review", patterns: ["审查", "review", "检查", "check"] },
+  { type: "test", patterns: ["测试", "test", "验证"] },
+  { type: "explore", patterns: ["探索", "explore", "头脑风暴", "brainstorm"] },
+  { type: "knowledge", patterns: ["知识", "knowhow", "学习", "learn"] },
+]
+```
+
+#### Step 4.2: 推荐工作流
+
+**新项目** (复杂度: 高):
+
+```markdown
+## 新项目工作流
+
+### 路径 1: 最简路径（适合快速启动）
+1. `/maestro-init` — 初始化 .workflow/ 目录
+2. `/maestro-roadmap "项目目标" -y` — 生成路线图
+3. 按里程碑执行: analyze → plan → execute → verify
+
+### 路径 2: 从头脑风暴开始（适合需要创意探索）
+1. `/maestro-brainstorm "项目描述"` — 多角色头脑风暴
+2. `/maestro-init --from-brainstorm ANL-xxx` — 基于分析初始化
+3. `/maestro-roadmap "创建路线图" -y`
+
+### 路径 3: 完整规范链（适合大型项目）
+1. `/maestro-init`
+2. `/maestro-spec-generate` — 7 阶段规范生成
+```
+
+**功能开发** (复杂度: 中):
+
+```markdown
+## 功能开发工作流
+
+### 主干管线（标准流程）
+1. `/maestro-analyze [phase]` — 分析需求和现有代码
+2. `/maestro-plan [phase]` — 生成执行计划
+3. `/maestro-execute [phase]` — 执行实现
+4. `/maestro-verify [phase]` — 验证成果
+
+### 快速渠道（简单功能）
+1. `/maestro-quick "功能描述"` — 一键完成
+
+### 全自动
+1. `/maestro -y "功能描述"` — 自动选择并执行完整流程
+```
+
+**Bug 修复** (复杂度: 低-中):
+
+```markdown
+## Bug 修复工作流
+
+### 快速修复（已知问题）
+1. `/maestro-quick "修复 Bug 描述"`
+
+### Issue 闭环（需要追踪）
+1. `/manage-issue-discover by-prompt "问题描述"` — 发现 Issue
+2. `/manage-issue create --title "Bug 标题" --severity high` — 创建 Issue
+3. `/maestro-analyze --gaps ISS-xxx` — 根因分析
+4. `/maestro-plan --gaps` — 方案规划
+5. `/maestro-execute` — 执行修复
+6. `/manage-issue close ISS-xxx --resolution "Fixed"` — 关闭 Issue
+```
+
+**代码审查**:
+
+```markdown
+## 质量管线
+
+1. `/quality-review [phase] --level standard` — 多维代码审查
+2. `/quality-auto-test [phase]` — 自动测试（智能路由）
+3. `/quality-test [phase]` — 业务测试（UAT）
+
+### 测试失败修复循环
+1. `/quality-debug --from-uat [phase]` — 诊断失败
+2. `/maestro-plan [phase] --gaps` — 生成修复计划
+3. `/maestro-execute [phase]` — 执行修复
+4. `/quality-auto-test [phase] --re-run` — 重跑失败场景
+```
+
+#### Step 4.3: 工作流全景图
+
+对需要全景视角的用户，展示 Mermaid 图：
+
+```
+主干管线: analyze → plan → execute → verify → quality (review/test) → milestone-audit → milestone-complete
+快速渠道: maestro-quick → (直接完成)
+Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
+全自动: /maestro -y → (自动路由)
+```
+
+#### Step 4.4: 关键概念说明
+
+对不熟悉 Maestro 的用户，简要说明核心概念：
+
+```markdown
+## 核心概念
+
+- **Milestone**: 项目阶段，包含多个 Phase
+- **Phase**: 单个工作单元，走 analyze → plan → execute → verify 生命周期
+- **Overlay**: 非侵入式命令补丁，扩展命令行为而不修改源文件
+- **Delegate**: 将子任务委派给外部 AI 工具（Gemini/Claude/Codex）
+- **Spec**: 项目规范，自动注入到工作流中作为约束
+- **Wiki**: 知识图谱，存储详细技术文档
+- **Ralph**: 自适应决策引擎，动态调整执行链
+```
+
+### Mode 5: Beginner Onboarding
+
+#### Step 5.1: 展示核心命令
+
+从 `catalog.json essential_commands[]` 读取核心命令列表：
+
+```markdown
+## Maestro Flow 快速入门
+
+### 10 个核心命令
+
+| # | 命令 | 用途 | 何时使用 |
+|---|------|------|---------|
+| 1 | `/maestro` | 智能协调器 | 不确定用哪个命令时，告诉它你的目标 |
+| 2 | `/maestro-init` | 初始化项目 | 首次使用，创建 .workflow/ 结构 |
+| 3 | `/maestro-roadmap` | 生成路线图 | 初始化后，规划里程碑 |
+| 4 | `/maestro-analyze` | 分析 | 开始一个 Phase 的分析 |
+| 5 | `/maestro-plan` | 规划 | 分析完成后，生成执行计划 |
+| 6 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
+| 7 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
+| 8 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 9 | `/quality-review` | 代码审查 | 执行后进行质量检查 |
+| 10 | `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
+```
+
+#### Step 5.2: 快速入门路径
+
+```markdown
+### 5 分钟上手
+
+1. **安装**: `maestro install --force`
+2. **初始化**: `/maestro-init`
+3. **开始工作**: `/maestro "你的任务描述"` — 自动选择最佳工作流
+
+### 10 分钟深入
+
+阅读 `guide/quick-start-guide.md` 了解完整功能。
+```
+
+#### Step 5.3: 分类浏览引导
+
+```markdown
+### 想了解更多？
+
+- **全部命令**: `/maestro-help` 查看完整目录
+- **工作流指南**: `/maestro-help workflow` 了解工作流选择
+- **Skill 浏览**: `/maestro-help skills` 查看可用 Skill
+- **CLI 命令**: `/maestro-help cli` 查看终端命令
+```
+
+## Output
+
+结构化的工作流推荐或新手引导内容，直接展示给用户。

package/.claude/skills/maestro-impeccable/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: maestro-impeccable
+description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
+version: 1.0.0
+user-invocable: true
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target] [--skip-harvest] [-y]"
+allowed-tools:
+  - Bash(maestro impeccable *)
+  - Write
+---
+
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. Automatically harvests design knowledge to `.workflow/knowhow/` for cross-session accumulation.
+
+## Setup
+
+Before any design work or file edits:
+
+1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
+2. Identify the register and load the matching register reference (brand.md or product.md).
+3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** Non-negotiable: `craft` without `craft.md` loaded means skipping the shape-and-confirm step.
+
+Skipping these produces generic output that ignores the project.
+
+### 1. Context gathering
+
+Two files, case-insensitive. PRODUCT.md and DESIGN.md are stored at `.workflow/impeccable/`.
+
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
+
+Both are registered in the spec system under category `ui` via `spec add`. Load with:
+
+```bash
+maestro spec load --category ui
+```
+
+This surfaces all design context (product + visual) from `.workflow/specs/ui-conventions.md`. If specs are not initialized, fall back to the legacy loader:
+
+```bash
+maestro impeccable load-context
+```
+
+Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq`.
+
+If the output is already in this session, don't re-run. Exceptions: you just ran `teach` or `document` (they rewrite the files and re-register specs), or the user manually edited one.
+
+`live` already warms context via `maestro impeccable live`. If you've run `live`, skip context loading.
+
+If PRODUCT.md is missing/empty/placeholder (`[TODO]`, <200 chars): run `teach`, then resume the original task. If the original task was `craft`, resume into `shape` first.
+
+If DESIGN.md is missing: nudge once per session (*"Run `/maestro-impeccable document` for more on-brand output"*), then proceed.
+
+### 2. Register
+
+Every design task is **brand** (marketing, landing, campaign: design IS the product) or **product** (app UI, admin, dashboard: design SERVES the product).
+
+Identify before designing. Priority: (1) cue in the task; (2) surface in focus; (3) `register` field in PRODUCT.md. First match wins.
+
+Load the matching reference: [brand.md](~/.maestro/workflows/impeccable/brand.md) or [product.md](~/.maestro/workflows/impeccable/product.md).
+
+## Shared design laws
+
+Apply to every design, both registers. Match complexity to vision. Vary across projects; never converge on the same choices.
+
+### Color
+
+- Use OKLCH. Reduce chroma near lightness extremes.
+- Never `#000` or `#fff`. Tint neutrals toward brand hue (chroma 0.005-0.01).
+- Pick **color strategy** first: Restrained → Committed → Full palette → Drenched.
+
+### Theme
+
+Write one sentence of physical scene before choosing dark/light. Run the sentence, not the category.
+
+### Typography
+
+- Body line length: 65-75ch.
+- Hierarchy: scale + weight contrast (≥1.25 ratio).
+
+### Layout
+
+- Vary spacing for rhythm. Cards only when truly best affordance. No nested cards.
+
+### Motion
+
+- No CSS layout property animations. Ease-out with exponential curves.
+
+### Absolute bans
+
+Match-and-refuse: side-stripe borders, gradient text, glassmorphism as default, hero-metric template, identical card grids, modal as first thought.
+
+### Copy
+
+Every word earns its place. No em dashes.
+
+### AI slop test
+
+Two-altitude category-reflex check. If someone could guess theme+palette from category alone, or guess aesthetic family from category+anti-references, rework until neither is obvious.
+
+See [~/.maestro/workflows/impeccable/brand.md](~/.maestro/workflows/impeccable/brand.md) for reflex-reject aesthetic lanes.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Shape, then build end-to-end | [~/.maestro/workflows/impeccable/craft.md](~/.maestro/workflows/impeccable/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before code | [~/.maestro/workflows/impeccable/shape.md](~/.maestro/workflows/impeccable/shape.md) |
+| `teach` | Build | Set up PRODUCT.md and DESIGN.md | [~/.maestro/workflows/impeccable/teach.md](~/.maestro/workflows/impeccable/teach.md) |
+| `document` | Build | Generate DESIGN.md from code | [~/.maestro/workflows/impeccable/document.md](~/.maestro/workflows/impeccable/document.md) |
+| `extract [target]` | Build | Pull tokens/components into design system | [~/.maestro/workflows/impeccable/extract.md](~/.maestro/workflows/impeccable/extract.md) |
+| `critique [target]` | Evaluate | UX review with heuristic scoring | [~/.maestro/workflows/impeccable/critique.md](~/.maestro/workflows/impeccable/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks | [~/.maestro/workflows/impeccable/audit.md](~/.maestro/workflows/impeccable/audit.md) |
+| `polish [target]` | Refine | Final quality pass | [~/.maestro/workflows/impeccable/polish.md](~/.maestro/workflows/impeccable/polish.md) |
+| `bolder [target]` | Refine | Amplify bland designs | [~/.maestro/workflows/impeccable/bolder.md](~/.maestro/workflows/impeccable/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive designs | [~/.maestro/workflows/impeccable/quieter.md](~/.maestro/workflows/impeccable/quieter.md) |
+| `distill [target]` | Refine | Strip to essence | [~/.maestro/workflows/impeccable/distill.md](~/.maestro/workflows/impeccable/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [~/.maestro/workflows/impeccable/harden.md](~/.maestro/workflows/impeccable/harden.md) |
+| `onboard [target]` | Refine | First-run flows, empty states | [~/.maestro/workflows/impeccable/onboard.md](~/.maestro/workflows/impeccable/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful motion | [~/.maestro/workflows/impeccable/animate.md](~/.maestro/workflows/impeccable/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color | [~/.maestro/workflows/impeccable/colorize.md](~/.maestro/workflows/impeccable/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography | [~/.maestro/workflows/impeccable/typeset.md](~/.maestro/workflows/impeccable/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, hierarchy | [~/.maestro/workflows/impeccable/layout.md](~/.maestro/workflows/impeccable/layout.md) |
+| `delight [target]` | Enhance | Add personality | [~/.maestro/workflows/impeccable/delight.md](~/.maestro/workflows/impeccable/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [~/.maestro/workflows/impeccable/overdrive.md](~/.maestro/workflows/impeccable/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy and labels | [~/.maestro/workflows/impeccable/clarify.md](~/.maestro/workflows/impeccable/clarify.md) |
+| `adapt [target]` | Fix | Adapt for devices/screens | [~/.maestro/workflows/impeccable/adapt.md](~/.maestro/workflows/impeccable/adapt.md) |
+| `optimize [target]` | Fix | Fix UI performance | [~/.maestro/workflows/impeccable/optimize.md](~/.maestro/workflows/impeccable/optimize.md) |
+| `live` | Iterate | Browser-based variant generation | [~/.maestro/workflows/impeccable/live.md](~/.maestro/workflows/impeccable/live.md) |
+
+### Routing rules
+
+1. **No argument**: render command menu grouped by category.
+2. **First word matches command**: load its reference file, follow instructions. Rest is target.
+3. **No match**: general design invocation with full argument as context.
+
+## Harvest — Design Knowledge Accumulation
+
+After every command execution (except `live`), harvest design decisions into `.workflow/knowhow/` for cross-session reuse. Skip if `--skip-harvest` flag is set.
+
+### Harvest routing
+
+| Command | Type | Prefix | Extract |
+|---------|------|--------|---------|
+| craft | decision + asset | DCS- + AST- | Design decisions + tokens (dual entry) |
+| shape | decision | DCS- | Key decisions from brief |
+| teach | reference | REF- | Brand/user/principles from PRODUCT.md |
+| document | asset | AST- | Token system from DESIGN.md YAML |
+| extract | asset | AST- | Design system patterns |
+| critique | tip | TIP- | Scores + P0/P1 findings |
+| audit | tip | TIP- | 5-dimension scores |
+| polish | tip | TIP- | Polish points |
+| bolder/quieter/distill | decision | DCS- | Direction decisions |
+| harden/onboard | tip | TIP- | Patterns applied |
+| animate | decision | DCS- | Animation strategy |
+| colorize | decision | DCS- | Color strategy + OKLCH values |
+| typeset | decision | DCS- | Typography decisions |
+| layout | decision | DCS- | Layout/spacing decisions |
+| delight/overdrive | decision | DCS- | Creative decisions |
+| clarify/adapt/optimize | tip | TIP- | Fix points |
+
+### Harvest execution
+
+1. **Determine type** from routing table.
+2. **Extract** from output files (document, critique) or conversation context (others).
+3. **Write knowhow**:
+   - DCS-/TIP-/REF- → `store_knowhow` MCP: `{operation: "add", type, title: "maestro-impeccable <cmd>: <description>", body, tags: ["impeccable", "<cmd>", ...]}`
+   - AST- → Write to `.workflow/knowhow/AST-impeccable-<slug>-<YYYYMMDD>.md` with YAML frontmatter (`category: ui`)
+4. **Spec index** (DCS-/AST- only): `maestro spec add ui "<title>" "<summary>" --keywords impeccable,<cmd>,... --ref knowhow/<file>`
+5. **Report**: one-line summary with knowhow ID.

package/.codex/agents/team-supervisor.toml

@@ -0,0 +1,40 @@
+name = "team_supervisor"
+description = "Resident pipeline supervisor. Spawned once, woken via followup_task for checkpoint verification. Read-only."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are a resident pipeline supervisor (message-driven lifecycle).
+
+## Lifecycle
+Init -> idle -> [wake -> execute checkpoint -> idle]* -> shutdown
+
+Unlike team_worker (task-driven), you are message-driven:
+- Spawned once at session start
+- Woken by coordinator via followup_task with checkpoint requests
+- Stay alive across checkpoints, maintaining context continuity
+
+## Boot Protocol
+1. Parse role assignment from message (role_spec, session, session_id, requirement)
+2. Read role_spec to load checkpoint definitions
+3. Load baseline context (all role states, session state)
+4. Report ready via report_agent_job_result
+5. Wait for checkpoint requests via followup_task
+
+## Per Checkpoint
+1. Parse checkpoint request from followup_task message (task_id, scope)
+2. Read artifacts specified in checkpoint scope
+3. Load incremental context (new data since last wake)
+4. Optionally read worker progress milestones from team_msg for risk assessment
+5. Verify cross-artifact consistency per role.md definitions
+6. Issue verdict: pass (>= 0.8), warn (0.5-0.79), block (< 0.5)
+7. Write report to discoveries/{checkpoint_id}.json
+8. Report findings via report_agent_job_result
+
+## Constraints
+- Read-only: never modify source artifacts
+- Never issue pass when critical inconsistencies exist
+- Never block for minor style issues
+- Only communicate with coordinator
+"""

package/.codex/agents/team-worker.toml

@@ -0,0 +1,63 @@
+name = "team_worker"
+description = "Generic team worker agent. Role-specific behavior loaded from role.md at spawn time via message parameter."
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are a team worker agent. You execute a specific role within a team pipeline.
+
+## Boot Protocol
+1. Parse role assignment from message (role, role_spec path, session, session_id, requirement)
+2. Read role_spec file to load Phase 2-4 domain instructions
+3. Read session state from session path
+4. Execute built-in Phase 1 (task discovery from tasks.json)
+5. Execute role-specific Phase 2-4 defined in role.md
+6. Report progress milestones via team_msg at phase boundaries
+7. Write deliverables to session artifacts directory
+8. Write findings to discoveries/{task_id}.json
+9. Report completion via team_msg type="task_complete" + report_agent_job_result
+
+## Task State
+- tasks.json is source of truth (NOT CSV)
+- Filter tasks by your role prefix + status=pending + no blocked deps
+- Update task status in tasks.json (pending -> in_progress -> completed)
+
+## Inner Loop
+If inner_loop=true, process ALL same-prefix tasks sequentially:
+  Phase 1 -> Phase 2-4 -> Phase 5-L (loop) -> repeat
+  Until no more same-prefix pending tasks -> Phase 5-F (final report)
+
+## Progress Milestones
+Report progress via mcp__maestro-tools__team_msg at natural phase boundaries:
+- type="progress" with progress_pct, phase, status
+- type="blocker" immediately on errors (don't wait for next milestone)
+- type="task_complete" after report_agent_job_result
+See agent-instruction.md "Progress Milestone Protocol" for format.
+
+## Output Schema
+{
+  "id": "<task_id>",
+  "status": "completed | failed",
+  "role": "<role_name>",
+  "findings": "<max 500 chars>",
+  "artifact": "<artifact_path>",
+  "files_modified": [],
+  "error": ""
+}
+
+## Constraints
+- Only process tasks matching your role prefix
+- Never modify tasks outside your scope
+- Report to coordinator via team_msg + report_agent_job_result
+- Use CLI tools (maestro delegate) or direct tools for exploration
+
+## Maestro Delegate Execution (MANDATORY)
+When calling `maestro delegate` via exec_command:
+1. Set yield_time_ms: 30000 (initial 30s wait)
+2. If session_id returned (command still running) → poll with write_stdin(session_id, chars="", yield_time_ms=15000→60000) in a loop
+3. NEVER skip polling, NEVER abandon — delegate output is required
+4. Increase poll interval: 15s → 30s → 60s (cap)
+5. Parse result only after command completes
+Protocol: @~/.maestro/workflows/delegate-protocol.codex.md
+"""

package/.codex/skills/learn-decompose/SKILL.md

@@ -50,7 +50,7 @@ $ARGUMENTS — target path/module and optional flags.
 Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
 Extract remaining text as target path/module.
 
-Resolve target to file list. Load existing patterns from `coding-conventions.md` + `specs/learnings.md` for dedup set.
+Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `specs/learnings.md` for dedup set. Browse wiki: `maestro wiki list --category coding`, load relevant entries.
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 

package/.codex/skills/learn-investigate/SKILL.md

@@ -28,7 +28,8 @@ $ARGUMENTS — question text and optional flags.
 
 ### Stage 1: Frame the Question
 - Parse question, generate slug, create investigation directory
-- Search prior knowledge: wiki search, grep specs/learnings.md, read debug-notes.md
+- Load debug specs: `maestro spec load --category debug` for known issues and patterns
+- Search prior knowledge: `maestro wiki list --category debug`, wiki search, grep specs/learnings.md
 - Write initial `understanding.md`
 
 ### Stage 2: Evidence Collection