pi-maestro-flow 0.2.0

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

@@ -0,0 +1,192 @@
+---
+name: maestro-tools-register
+description: "Register tool specs - extract, generate, or optimize Arguments: [<description>] [--extract <path>] [--optimize <name>]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion Agent
+---
+
+<purpose>
+Codify reusable business processes as knowhow documents with `tool: true` in `.workflow/knowhow/`.
+Four modes: Extract, Generate, Optimize, Promote. Short processes inline; long use ref mode.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Intent description
+
+**Examples**:
+```
+/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
+/maestro-tools-register promote RCP-db-migration-rollback as test tool
+/maestro-tools-register promote knowhow-auth-api to coding tool
+```
+</context>
+
+<invariants>
+1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords`, and `summary` in YAML frontmatter; missing fields → reject write
+2. **No duplicate names** — tool title MUST be unique within its category; duplicate detection → E002 warning with overwrite/optimize confirmation
+3. **Category required** — every tool MUST declare exactly one category from: coding, test, review, arch, debug; empty category → E003
+4. **Confirmation gate** — MUST AskUserQuestion before writing knowhow document and spec ref entry; NEVER persist without user confirmation
+5. **Promote is in-place** — promote mode MUST update existing knowhow frontmatter via `maestro wiki update`; NEVER recreate the document
+6. **Output boundary** — ALL file writes MUST target .workflow/knowhow/ (tool documents) and .workflow/specs/ (ref entries via maestro spec add) only. NEVER modify source code or files outside these paths
+7. **Description format** — first line after `### Title` MUST state "Use when ..." (usage timing); this is critical for ref entry summary visibility in spec-load
+</invariants>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Gather**
+- REQUIRED: Mode determined (extract/generate/optimize/promote) from argument parsing.
+- REQUIRED: For optimize/promote modes, target tool/document exists and is loadable.
+- BLOCKED if: empty args without user response to AskUserQuestion.
+
+**GATE 2: Gather → Write**
+- REQUIRED: Tool name, category, and usage timing confirmed.
+- REQUIRED: Steps extracted or generated (extract: ≥1 step, generate: user-confirmed scope).
+- REQUIRED: Inline vs ref mode decided based on step count.
+- REQUIRED: User confirmed via AskUserQuestion (title, category, keywords, summary, step count).
+- BLOCKED if: E001 (.workflow/specs/ not initialized), E003 (no category), user cancels.
+
+**GATE 3: Write → Verify**
+- REQUIRED: Knowhow document written with `tool: true` frontmatter (or updated in-place for promote).
+- REQUIRED: Spec ref entry registered (if user confirmed).
+- BLOCKED if: write failed or spec add returned error.
+
+### Step 1: Intent Detection
+
+Parse $ARGUMENTS to determine mode:
+- Contains "extract" → extract mode
+- Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote 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 search "<name>" --type knowhow` → `maestro load --type knowhow --id <id>`
+- Analyze improvement points (step splitting, prerequisites, error handling)
+
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
+- Do NOT recreate the document — modify in place
+
+### Step 3: Determine Category
+
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
+
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- API verification steps (how to test) → `category: test` (RCP-*, tool: true)
+- Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
+
+### 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 ...
+```
+
+**Confirm before writing** — Use `AskUserQuestion` to show the user the planned knowhow document (title, category, keywords, summary, step count) and spec ref entry before persisting:
+
+```
+question: "确认写入以下 knowhow 工具文档？"
+options:
+  - label: "确认写入"
+    description: "knowhow: {title} (category: {category}, keywords: {keywords}), spec ref entry"
+  - label: "修改后写入"
+    description: "调整 title/category/keywords 后重新确认"
+  - label: "取消"
+    description: "不写入任何文件"
+```
+
+User confirms → proceed; user edits → re-gather; user cancels → END.
+
+**Create knowhow tool document** in `.workflow/knowhow/` with `tool: true` in YAML frontmatter:
+```yaml
+---
+title: <Title>
+type: recipe
+category: <category>
+keywords: [<keywords>]
+tool: true
+summary: "Use when <timing>. <scope description>"
+---
+
+## Steps
+1. Step one ...
+```
+
+**Optionally register spec ref entry** (after user confirmation above) for index discoverability:
+```bash
+maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
+  --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+```
+
+### Step 6: Verify
+
+- `maestro load --type spec --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 a category |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] category correctly set
+- [ ] keywords auto-extracted (3-5 terms)
+- [ ] Description starts with "Use when ..." (usage timing)
+- [ ] Loadable via `spec load --category <category>`
+- [ ] Long processes use ref mode with knowhow file created
+- [ ] Ref knowhow YAML includes `summary` with usage timing
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Tool registered, want to test | `/maestro-tools-execute <name>` |
+| Want to register another | `/maestro-tools-register` |
+| Tool for test agents | `/spec-load --category test` to verify discovery |
+</completion>

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

@@ -0,0 +1,127 @@
+---
+name: maestro-ui-codify
+description: "Extract design system from code, generate reference package, persist as knowledge assets Arguments: <source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent Skill AskUserQuestion
+---
+
+<purpose>
+Extract design system from source code into tokens, reference package, and knowledge assets.
+4-phase pipeline: validate → extract → package → knowhow.
+</purpose>
+
+<deferred_reading>
+- [ui-codify.md](~/.maestro/workflows/ui-codify.md) — read always (main workflow orchestrator)
+- [ui-codify-extract.md](~/.maestro/workflows/ui-codify-extract.md) — read when Phase 2 starts (style extraction with 3 agents)
+- [ui-codify-package.md](~/.maestro/workflows/ui-codify-package.md) — read when Phase 3 starts (reference package generation)
+- [ui-codify-knowhow.md](~/.maestro/workflows/ui-codify-knowhow.md) — read when Phase 4 starts (knowledge asset generation)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — source path (required) with optional flags.
+
+Flags:
+- `<source-path>` (positional, required): Directory containing CSS/SCSS/JS/TS/HTML source files
+- `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
+- `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
+- `--overwrite`: Allow overwriting existing package directory
+
+**Output boundary**: ALL file writes MUST target the `--output-dir` path (default: `.workflow/reference_style/`) for reference packages, and `.workflow/knowhow/` for knowledge assets (via `codify-to-knowhow`). NEVER modify the source directory being analyzed.
+</context>
+
+<invariants>
+1. **Source read-only** — the source path being analyzed MUST NOT be modified; extraction is purely read-only
+2. **Phase-sequential loading** — workflow files (ui-codify-extract, ui-codify-package, ui-codify-knowhow) MUST be read only when their phase starts; NEVER load all phases eagerly
+3. **User confirmation before knowhow** — Phase 3→4 gate MUST present AskUserQuestion before generating knowledge assets; NEVER auto-proceed to knowhow generation
+4. **Overwrite protection** — existing package directory MUST NOT be overwritten without `--overwrite` flag (E003)
+5. **Artifact completeness** — all 5 required artifacts MUST exist before reporting completion; NEVER skip artifact verification
+6. **Token-first extraction** — design-tokens.json MUST be generated before layout-templates.json; layout extraction depends on token foundation
+</invariants>
+
+<execution>
+## 1. Load UI Specs
+
+Load project UI conventions before extracting design system:
+
+```bash
+maestro load --type spec --category ui
+```
+
+## 2. Execute Workflow
+
+Route to `~/.maestro/workflows/ui-codify.md` and follow completely.
+
+The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files. Each phase reads its workflow file only when execution reaches that phase.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE Phase 1 → Phase 2: Validation → Extraction**
+- REQUIRED: Source path validated and file discovery completed.
+- REQUIRED: design-tokens.json generated with color, typography, spacing tokens.
+- BLOCKED if missing: source path invalid (E002) or design-tokens.json not generated — extraction cannot proceed without token foundation.
+
+**GATE Phase 2 → Phase 3: Extraction → Package**
+- REQUIRED: layout-templates.json generated with component patterns.
+- BLOCKED if missing: layout-templates.json absent — package generation requires component patterns as input.
+
+**GATE Phase 3 → Phase 4: Package → Knowhow**
+- REQUIRED: preview.html + preview.css generated as interactive showcase.
+- BLOCKED if missing: preview artifacts not generated — knowhow phase needs rendered reference for validation.
+- REQUIRED: AskUserQuestion confirmation before proceeding to knowhow generation:
+  ```
+  question: "Preview 生成完成。是否继续将设计系统持久化为 knowhow 知识资产？"
+  options:
+    - label: "继续生成 knowhow"
+      description: "调用 codify-to-knowhow 写入 AST/DCS assets 和 spec entries"
+    - label: "仅保留 preview，跳过 knowhow"
+      description: "保留 preview.html + preview.css，不写入知识库"
+  ```
+
+**GATE Phase 4 → Completion: Knowhow → Done**
+- REQUIRED: knowhow-manifest.json created with AST/DCS assets and spec entries.
+- REQUIRED: codify-to-knowhow called and completed (only after user confirmation at Phase 3→4 gate).
+- BLOCKED if missing: knowhow-manifest.json absent or codify-to-knowhow not invoked — knowledge assets not persisted.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "design-tokens.json",      // Phase 1
+  "layout-templates.json",   // Phase 2
+  "preview.html",            // Phase 3
+  "preview.css",             // Phase 3
+  "knowhow-manifest.json"    // Phase 4
+]
+```
+If any artifact is missing: DO NOT report completion.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | Source path argument required | parse_input |
+| E002 | error | Source path not found or not a directory | validate |
+| E003 | error | Package directory exists without --overwrite flag | validate |
+| W001 | warning | animation-tokens.json not found (optional, extraction continues) | extract |
+</error_codes>
+
+<success_criteria>
+- [ ] UI specs loaded via `spec load --category ui` (if available)
+- [ ] Source path validated and file discovery completed
+- [ ] design-tokens.json generated with color, typography, spacing tokens
+- [ ] layout-templates.json generated with component patterns (universal/specialized)
+- [ ] animation-tokens.json generated (optional, W001 if missing)
+- [ ] preview.html + preview.css generated as interactive showcase
+- [ ] knowhow-manifest.json created with AST/DCS assets and spec entries
+- [ ] codify-to-knowhow called and completed successfully
+- [ ] Temporary workspace cleaned up
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Codify complete | Use extracted tokens in `maestro impeccable craft` for new builds |
+| Design system needs refinement | `maestro impeccable document` to regenerate DESIGN.md |
+| Knowledge assets persisted | `maestro search --type knowhow "design system"` to verify |
+</completion>