maestro-flow 0.5.46 → 0.5.47

package/.agy/skills/maestro-amend/SKILL.md

@@ -39,8 +39,19 @@ Multiple combinable. No flags + no description → interactive (scan + ask_quest
 **CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
 
 **Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. NEVER modify `.claude/commands/*.md` directly — overlay installation is handled by `maestro overlay add`.
 </context>
 
+<invariants>
+1. **Non-invasive only** — amendments MUST use the overlay system (`~/.maestro/overlays/*.json`); direct edits to `.claude/commands/*.md` are NEVER permitted
+2. **Idempotent patches** — re-running the same amendment MUST produce identical overlay JSON; overlay markers prevent duplicate injection
+3. **Pristine source reads** — signal diagnosis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals), not installed copies
+4. **Code bugs excluded** — signals classified as code bugs MUST be routed to `/maestro-quick` or `/maestro-plan --gaps`, NEVER patched via overlay
+5. **User confirmation before install** — overlay JSON MUST be previewed and confirmed by the user before `maestro overlay add` runs (unless `-y`)
+6. **Section existence verified** — target section MUST be confirmed to exist in the pristine source before drafting a patch; missing sections trigger `new-section` mode
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-companion/SKILL.md

@@ -46,12 +46,23 @@ $ARGUMENTS — mode + optional flags.
 
 Auto-detection: if `--type` not provided, infer from `--task` description keywords.
 
+**Output boundary**: ALL file writes MUST target `.workflow/.scratchpad/` (companion docs + `.companion-active` pointer) only. Promotion writes (spec/knowhow) are delegated to `spec-add` / `manage-knowhow-capture` skills. NEVER modify source code, `.workflow/state.json`, or files outside `.workflow/.scratchpad/`.
+
 **Companion document:**
 - Path: `.workflow/.scratchpad/companion-{YYYYMMDD-HHmmss}.md`
 - Active doc tracking: `.workflow/.scratchpad/.companion-active` (stores path of current companion doc)
 - Format: YAML frontmatter (rich metadata) + typed sections + timestamped entries
 </context>
 
+<invariants>
+1. **No session creation** — companion NEVER creates workflow sessions, NEVER writes to state.json
+2. **Side-car only** — companion MUST NOT modify source code or execute implementation tasks; it is strictly a knowledge loading + recording utility
+3. **One active doc** — only one `.companion-active` pointer SHALL exist at a time; creating a new companion doc MUST clear any stale pointer
+4. **Append-only entries** — note mode MUST append entries; NEVER overwrite or reorder existing entries
+5. **Promotion via delegation** — spec/knowhow promotion MUST route through `spec-add` / `manage-knowhow-capture` skills; companion NEVER writes directly to `.workflow/specs/` or `.workflow/knowhow/`
+6. **Type-template integrity** — context template sections MUST match the resolved `task_type`; NEVER mix templates from different types
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-composer/SKILL.md

@@ -40,8 +40,19 @@ $ARGUMENTS — natural language description, or flags.
 1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
 2. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Informs executor argument defaults and context injection.
 3. Optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/templates/workflows/` (template JSON + index.json) and `.workflow/templates/design-drafts/` (intermediate drafts) only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
+<invariants>
+1. **Max 20 nodes** — workflow templates MUST NOT exceed 20 nodes; larger workflows MUST be split into sub-workflows
+2. **Acyclic DAG** — generated template MUST be a directed acyclic graph; cycles MUST be detected and rejected before persistence
+3. **No orphan nodes** — every node MUST be reachable from at least one edge; unreachable nodes MUST be flagged
+4. **Confirmation before write** — template JSON MUST be shown to user via ask_question before writing to `~/.maestro/templates/workflows/`; cancellation saves draft only
+5. **Draft preservation** — abandoning at any confirmation gate MUST save current progress to design-drafts directory; NEVER discard user's partial work
+6. **Deferred reading only** — node-catalog and template-schema MUST be read at their designated phases (P2, P5), NEVER loaded eagerly at startup
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-guard/SKILL.md

@@ -30,10 +30,35 @@ $ARGUMENTS — Parse subcommand and optional path argument.
 
 **Enforcement:** The `workflow-guard` hook (PreToolUse on Write/Edit) reads this config
 and blocks operations targeting files outside boundaries. Requires hooks level >= `full`.
+
+**Output boundary**: ALL file writes MUST target `.workflow/config.json` (guard section) only. NEVER modify hook files, `.claude/settings.json`, or source code.
 </context>
 
+<invariants>
+1. **Config-only mutation** — guard MUST only modify the `guard` section of `.workflow/config.json`; NEVER touch other config sections or files
+2. **Non-destructive** — `off` MUST preserve existing paths and mode; NEVER clear the path list when disabling
+3. **Mode switch confirmation** — switching between allow/deny mode MUST require ask_question confirmation when existing paths will be cleared
+4. **Hook dependency** — guard MUST warn when enabled but `workflow-guard` hook is not active (hooks level < full)
+5. **Path normalization** — all paths MUST use forward slashes with trailing slash for directories; NEVER store raw backslash paths
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Config Read**
+- REQUIRED: Subcommand parsed (on/off/status/allow/deny) or defaulted to `status`.
+- BLOCKED if: invalid subcommand provided.
+
+**GATE 2: Config Read → Execute**
+- REQUIRED: `.workflow/config.json` read successfully or initialized with empty guard section.
+- BLOCKED if: file unreadable and cannot be created (E001).
+
+**GATE 3: Execute → Confirm**
+- REQUIRED: Config mutation applied (for on/off/allow/deny) or status displayed (for status).
+- REQUIRED: Mode-switch ask_question answered (for allow↔deny transitions with existing paths).
+- BLOCKED if: user declines mode switch.
+
 **Step 1: Parse subcommand**
 
 Extract from $ARGUMENTS:

package/.agy/skills/maestro-init/SKILL.md

@@ -40,8 +40,18 @@ $ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for aut
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
+
+**Output boundary**: ALL file writes MUST target `.workflow/` (project.md, state.json, config.json, specs/) only. NEVER modify source code or files outside `.workflow/`.
 </context>
 
+<invariants>
+1. **Idempotent init** — re-running init on an already-initialized project MUST detect existing `.workflow/` and warn (E002); NEVER silently overwrite existing state
+2. **Scope guard** — init MUST only make initialization decisions; NEVER prejudge roadmap structure, plan scope, or implementation details
+3. **All artifacts required** — init MUST NOT report completion until project.md, state.json, and config.json all exist; missing artifacts MUST be created before exit
+4. **Template-driven** — deferred templates (project.md, state.json, config.json) MUST be read from `~/.maestro/templates/` and customized; NEVER generate from scratch without template
+5. **Interview writes back** — all interactive decisions MUST be written to project.md/config.json before proceeding to research or completion; NEVER leave decisions unrecorded
+</invariants>
+
 <interview_protocol>
 Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
@@ -54,6 +64,24 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 </interview_protocol>
 
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Pre-flight → Interview**
+- REQUIRED: `.workflow/` existence check completed.
+- REQUIRED: `--from` source validated (if provided).
+- BLOCKED if: E002 (greenfield conflict with existing `.workflow/`) unresolved.
+
+**GATE 2: Interview → Research**
+- REQUIRED: All interview decisions recorded in project.md and config.json.
+- REQUIRED: `.workflow/` directory created with initial structure.
+- BLOCKED if: interview decisions not yet written to files.
+
+**GATE 3: Research → Completion**
+- REQUIRED: All 3 required artifacts exist (project.md, state.json, config.json).
+- REQUIRED: `.workflow/specs/` initialized.
+- BLOCKED if: any artifact missing — write it before reporting completion.
+
 ### Pre-flight
 
 1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)

package/.agy/skills/maestro-overlay/SKILL.md

@@ -33,8 +33,19 @@ Turn natural-language instructions into command overlays — JSON patch files th
 **Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
 
 **Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. Command file patching is handled by `maestro overlay add` — this skill NEVER modifies `.claude/commands/*.md` directly.
 </context>
 
+<invariants>
+1. **Non-invasive** — overlays MUST use hashed HTML-comment markers for injection; NEVER edit command file content directly outside the overlay system
+2. **Idempotent** — re-running `maestro overlay apply` with the same overlay JSON MUST produce no file changes
+3. **Creation only** — this skill MUST only create overlays; listing and removal are handled by `maestro overlay list` (ink TUI)
+4. **Pristine source preferred** — injection point analysis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals) first, fall back to `~/.claude/commands/` only if pristine unavailable
+5. **User approval before write** — overlay JSON MUST be shown and approved via ask_question before writing to disk; NEVER auto-install without confirmation
+6. **Chain skip option mandatory** — if a skill chain is configured, the injected content MUST include a "Skip" option in ask_question; NEVER force the user into a chain
+</invariants>
+
 <execution>
 ### 1. Parse user intent
 

package/.agy/skills/maestro-player/SKILL.md

@@ -68,8 +68,19 @@ $ARGUMENTS — template slug/path, or flags.
   "last_checkpoint": null
 }
 ```
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/player-*/` (session status.json + step outputs) only. Template files (`~/.maestro/templates/workflows/`) are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
+<invariants>
+1. **Resume-safe** — status.json MUST be updated after every step change; an interrupted session MUST be resumable from the last checkpoint via `-c`
+2. **One step at a time** — execution loop MUST process steps sequentially in topological order; parallel steps share a batch index but NEVER run concurrently within the player
+3. **CLI nodes async** — cli-type nodes MUST use `run_command(run_in_background: true)` + STOP pattern; NEVER block the main thread on delegate execution
+4. **Templates read-only** — player MUST NOT modify template JSON files; runtime state belongs in status.json only
+5. **Failure requires user decision** — on step failure without explicit `on_fail`, player MUST prompt via ask_question (Retry/Skip/Abort); NEVER silently skip or auto-abort
+6. **Reference resolution at runtime** — `{N-xxx.field}` and `{prev_*}` references MUST be resolved at execution time from status.json step results, NEVER pre-resolved during init
+</invariants>
+
 <state_machine>
 
 <states>

package/.agy/skills/maestro-quick/SKILL.md

@@ -41,9 +41,38 @@ Parse for:
    - Browse: `maestro search --category coding`
    - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
 3. All are optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/` (task directory, plan.json, summaries) and modified source files as defined in plan.json tasks. State.json scratch entry is implicit workflow tracking.
 </context>
 
+<invariants>
+1. **Atomic commits** — each task execution MUST produce a commit with only the files modified by that task; NEVER stage unrelated files
+2. **Evidence-based summaries** — task summaries MUST include concrete evidence (files changed, tests run, commands executed); NEVER accept "task completed successfully" as a summary
+3. **Plan before execute** — plan.json MUST be written before any task execution begins; NEVER skip planning even for single-task workflows
+4. **Scratch isolation** — all workflow artifacts MUST live under `.workflow/scratch/{task-dir}/`; NEVER write workflow metadata outside this directory
+5. **Commit confirmation** — staged files and commit message MUST be shown via ask_question before committing (unless `-y`); NEVER auto-commit without user awareness
+</invariants>
+
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Planning**
+- REQUIRED: Task description parsed and scratch directory created.
+- REQUIRED: Coding specs loaded (optional but attempted).
+- BLOCKED if: no task description (E001) or scratch directory creation failed (E002).
+
+**GATE 2: Planning → Execution**
+- REQUIRED: plan.json written with task definitions.
+- REQUIRED: --discuss decisions extracted and recorded (if flag set).
+- BLOCKED if: plan.json missing or empty.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All tasks executed with `.summaries/TASK-*-summary.md` written per task.
+- REQUIRED: Each summary contains concrete evidence of completion.
+- REQUIRED: --full verification passed (if flag set).
+- BLOCKED if: any task summary missing or lacking evidence.
+
 Follow '~/.maestro/workflows/quick.md' completely.
 
 ### Artifact Verification (before completion)

package/.agy/skills/maestro-swarm-workflow/SKILL.md

@@ -42,6 +42,8 @@ Remaining        → intent
 | `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
 | `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
 | `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -195,6 +197,29 @@ Workflow 返回 JSON 后：
 6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Route**
+- REQUIRED: Intent text or `--script` flag parsed successfully.
+- BLOCKED if: no intent and no `--script` (E001).
+
+**GATE 2: Route → Context Assembly**
+- REQUIRED: Target script resolved unambiguously (single match or user-selected from candidates).
+- BLOCKED if: ambiguous routing without user resolution (E002).
+
+**GATE 3: Context → Dispatch**
+- REQUIRED: Args payload assembled with all required fields for target script.
+- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- BLOCKED if: script file not found (E003) or required args missing.
+
+**GATE 4: Dispatch → Ingest**
+- REQUIRED: Workflow execution completed (success or partial results available).
+- BLOCKED if: Workflow execution failed entirely (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 与 Ralph 集成

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

@@ -37,8 +37,37 @@ $ARGUMENTS — Tool name, keyword, or --category filter
 Empty arguments enters interactive mode: list all tools for user selection.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST ask_question before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded via `maestro load --type knowhow`).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via ask_question (execute as-is / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
 ### Step 1: Load Tool
 
 **By name**:

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

@@ -37,8 +37,37 @@ $ARGUMENTS — Intent description
 ```
 </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 ask_question 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 ask_question.
+
+**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 ask_question (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:

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

@@ -34,8 +34,19 @@ Flags:
 - `--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 ask_question 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
 

package/.agy/skills/maestro-universal-workflow/SKILL.md

@@ -32,6 +32,8 @@ Remaining         → intent
 **Library locations:**
 - Fixed scripts: `~/.maestro/workflows/swarm/wf-*.js`
 - Dynamic scripts: `~/.maestro/workflows/dynamic/uwf-*.js`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/workflows/dynamic/` (generated scripts) and `.workflow/scratch/{YYYYMMDD}-uwf-*/` (execution results). Fixed scripts at `~/.maestro/workflows/swarm/` are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -508,6 +510,36 @@ Findings: ${digest}
 12. **无反斜杠路径** — 字符串中路径用正斜杠（`\u`、`\a` 等会被解析为转义序列）
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Scan**
+- REQUIRED: Intent text or `--from`/`--resume` flag parsed.
+- BLOCKED if: no intent and no flags (E001).
+
+**GATE 2: Scan → Design/Execute**
+- REQUIRED: Library scan completed (both `swarm/` and `dynamic/` directories).
+- REQUIRED: User decision if matches found (reuse existing vs generate new).
+- BLOCKED if: scan fails to read script directories.
+
+**GATE 3: Design → Generate**
+- REQUIRED: Task decomposition completed with work_items, decision_points, data_flow.
+- REQUIRED: Phase orchestration and adversarial pattern selection determined by depth.
+- BLOCKED if: task cannot be decomposed (E002).
+
+**GATE 4: Generate → Execute**
+- REQUIRED: Script written to `~/.maestro/workflows/dynamic/uwf-{slug}.js`.
+- REQUIRED: `node --check` syntax validation passed.
+- REQUIRED: User confirmation via ask_question (unless resuming).
+- BLOCKED if: syntax validation fails after 2 retries (E003).
+
+**GATE 5: Execute → Persist**
+- REQUIRED: Workflow execution completed via `scriptPath` invocation.
+- BLOCKED if: Workflow execution failed (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 使用示例
@@ -568,3 +600,30 @@ universal-workflow 扫描时会同时检查 swarm/ 和 dynamic/ 目录，
 | E005 | 持久化失败 | 展示脚本内容，让用户手动保存 |
 
 </appendix>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent and no --from/--resume flag | Prompt user for intent text |
+| E002 | error | Task decomposition failed — cannot identify work_items | Require more specific intent description |
+| E003 | error | Generated script syntax error after 2 retries | Show script content + error for manual fix |
+| E004 | error | Workflow execution failed | Show error, offer --resume with runId |
+| E005 | error | Script persistence failed (filesystem write error) | Show script content for manual save |
+| W001 | warning | No matching scripts found in library scan | Proceed directly to S_DESIGN |
+| W002 | warning | Adversarial gate confidence < 50% | Flag low-confidence decision, suggest --depth deep |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and flags extracted (--name, --depth, --dry-run, --from, --resume)
+- [ ] Library scan completed across both swarm/ and dynamic/ directories
+- [ ] User decision captured if matching scripts found (reuse vs generate)
+- [ ] Task decomposition produced: work_items, decision_points, data_flow
+- [ ] Adversarial pattern selected per decision_point according to depth level
+- [ ] Blueprint presented to user with estimated agent count
+- [ ] Script generated as pure JavaScript with all 12 generation rules enforced
+- [ ] `node --check` syntax validation passed
+- [ ] User confirmation obtained before execution (unless --resume)
+- [ ] Workflow executed via scriptPath (not inline script string)
+- [ ] Script persisted to `~/.maestro/workflows/dynamic/uwf-{slug}.js`
+- [ ] Completion summary displayed with reuse/resume commands
+</success_criteria>

package/.agy/skills/maestro-update/SKILL.md

@@ -29,10 +29,38 @@ $ARGUMENTS — optional flags.
 - `update-v{TO}-setup.md` — post-migration setup for version {TO}
 
 **Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
+
+**Output boundary**: ALL file writes MUST target `.workflow/state.json` (version bump), `.workflow/state.json.backup-*` (backup), and `.workflow/` config files touched by version-specific setup. NEVER modify source code or `src/migrations/` files.
 </context>
 
+<invariants>
+1. **Backup before migration** — a timestamped backup of `.workflow/state.json` MUST be created before any schema migration runs; NEVER execute migration without backup
+2. **Idempotent** — running update when already on latest version MUST be a no-op (display "up to date"); NEVER re-apply migrations
+3. **Confirmation before execute** — migration diff MUST be displayed and user MUST confirm via ask_question before execution (unless `--force`); NEVER silently apply schema changes
+4. **Migration diff always visible** — even with `--force`, the migration diff MUST be displayed for audit visibility; NEVER skip diff display
+5. **Restore path on failure** — if migration fails, the backup restore command MUST be displayed; NEVER leave user without recovery instructions
+6. **Sequential migration** — all intermediate version steps MUST be applied in order by the schema registry; NEVER skip intermediate versions
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Detect → Check**
+- REQUIRED: Current version read from `.workflow/state.json`.
+- BLOCKED if: state.json missing or unreadable (E001).
+
+**GATE 2: Check → Execute**
+- REQUIRED: Dry-run migration check completed; target version identified.
+- REQUIRED: User confirmation via ask_question (unless `--force`).
+- BLOCKED if: already up to date (display message and exit) or user cancels.
+
+**GATE 3: Execute → Summary**
+- REQUIRED: Backup created at `.workflow/state.json.backup-v{current}-{timestamp}`.
+- REQUIRED: Schema migration completed successfully.
+- REQUIRED: Version-specific setup doc followed (if exists).
+- BLOCKED if: migration failed — display restore command and exit.
+
 ### Step 1: Detect Version
 
 ```
@@ -105,6 +133,16 @@ Next steps:
 
 </execution>
 
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/state.json` not found or unreadable | Run `/maestro-init` first |
+| E002 | error | Schema migration failed (npx tsx returned error) | Display backup restore command: `cp .workflow/state.json.backup-* .workflow/state.json` |
+| E003 | error | Version-specific setup doc failed to execute | Manual setup: read `~/.maestro/workflows/updates/update-v{target}-setup.md` |
+| W001 | warning | No version-specific setup doc found for target version | Proceed without setup; schema migration alone is sufficient |
+| W002 | warning | `--setup-only` but no setup script exists for current version | Display message and exit |
+</error_codes>
+
 <success_criteria>
 - [ ] Current version detected from state.json
 - [ ] Schema migrations run automatically (no manual intermediate steps)

package/.agy/skills/manage-codebase-rebuild/SKILL.md

@@ -46,13 +46,42 @@ $ARGUMENTS -- optional flags.
 - `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
 - `.workflow/codebase/doc-index.json` -- generated documentation index
 - `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
+
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `.workflow/project.md` (Tech Stack section only). NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Destructive with confirmation** — rebuild clears `.workflow/codebase/` entirely; MUST confirm with user unless `--force` is set
+2. **Commit confirmation** — git commit MUST be confirmed by user unless `--force` is set; `--skip-commit` bypasses commit entirely
+3. **Partial failure tolerance** — if 1-3 mapper agents fail, proceed with partial results (W001); only abort if all 4 fail (E002)
+4. **Focus scoping** — when `--focus <area>` is set, MUST only regenerate docs relevant to that scope; leave unrelated docs untouched
+5. **State update** — MUST update state.json with rebuild timestamp on completion
+6. **KG pipeline mandatory** — MUST run `maestro kg index` after doc regeneration; KG validation failure is non-fatal (W003)
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 
 **When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Confirmation → Mapping** (Pre-flight → Agent spawn)
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- REQUIRED: User confirmed rebuild (or `--force` set). W002 if existing docs found.
+- BLOCKED if user declines confirmation.
+
+**GATE 2: Mapping → KG Pipeline** (Agent results → Knowledge Graph)
+- REQUIRED: At least 1 of 4 mapper agents returned valid results.
+- REQUIRED: All output files written to `.workflow/codebase/`.
+- REQUIRED: doc-index.json generated and valid.
+- BLOCKED if all 4 mapper agents failed (E002).
+
+**GATE 3: KG Pipeline → Commit** (Knowledge Graph → Git)
+- REQUIRED: `maestro kg index` executed (W003 if validation fails — non-blocking).
+- REQUIRED: state.json updated with rebuild timestamp.
+- REQUIRED: If not `--skip-commit`: user confirmed git commit (or `--force` set).
+- BLOCKED if state.json update fails.
 </execution>
 
 <completion>

package/.agy/skills/manage-drift-realign/SKILL.md

@@ -60,8 +60,20 @@ Arguments: $ARGUMENTS
 - `.workflow/project.md`
 
 使用 `maestro timeline` CLI 构建统一的 git+session 时间线。
+
+**Output boundary**: ALL file writes MUST target `.workflow/` metadata files (specs, codebase docs, roadmap.md, state.json, issues.jsonl) or `.workflow/.trash/drift-realign-{timestamp}/` (backups) or `.workflow/.drift-realign/` (session details). NEVER modify source code files.
 </context>
 
+<invariants>
+1. **Code-as-Truth** — 代码是唯一真理源；当文档说 X 但代码做 Y 时，文档漂移，NEVER 反向修改代码来匹配文档
+2. **Backup before mutate** — MUST create backup tarball in `.workflow/.trash/` before any file modification (E005 if backup fails)
+3. **Never modify source code** — drift-realign only updates `.workflow/` metadata; source code files are read-only
+4. **Mutual exclusion** — `--report` 与 `--auto-archive` 互斥；同时传入 MUST trigger E006
+5. **Auto-depth escalation** — `drift_window` > 180 天 MUST auto-upgrade to `--depth deep` with W002 warning
+6. **Audit trail** — every triage decision MUST be logged in `drift-log.jsonl` with finding ID, action, and timestamp
+7. **Rebuild trigger** — codebase scope 的 3+ P0 finding MUST auto-trigger `/quality-sync --full` after triage
+</invariants>
+
 <execution>
 Follow `~/.maestro/workflows/drift-realign.md` Stages 1-9 in order.
 

package/.agy/skills/manage-harvest/SKILL.md

@@ -39,17 +39,41 @@ Arguments: $ARGUMENTS
 - `-y` / `--yes` — Skip confirmation prompts for all write operations (artifact selection, routing decisions, store writes). Useful for CI or batch harvesting.
 
 Additional flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/`, `.workflow/specs/`, `.workflow/issues/`, `.workflow/wiki/`, `.workflow/harvest/`, or `.workflow/state.json` only. NEVER modify source code, source artifacts, or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only until routing** — extraction and classification happen in-memory; no files written until Stage 6
+2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
+3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
+4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
+5. **Conflict pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category; set `confidence="low"` and log conflict note if semantic conflict detected
+6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
+7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
+</invariants>
+
 <execution>
 Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 
-**Key invariants:**
-1. **Read-only until Stage 6** — extraction and classification happen in-memory.
-2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
-3. **Never modify source artifacts** — harvest is purely extractive.
-4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
-5. **Conflict pre-check on spec routing** — when routing to spec (Stage 6b), compare new entry against existing specs with same keywords/category. If semantic conflict detected, set `confidence="low"` on the new entry and log conflict note. Use `maestro spec conflict mark` if contradiction is clear.
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Discovery → Extraction** (Stages 1-3 → Stage 4)
+- REQUIRED: Source artifacts discovered and mode resolved (scan/session/path).
+- REQUIRED: User selected artifact(s) to harvest (or auto-selected via session/path mode, or `-y`).
+- BLOCKED if no harvestable artifacts found (W001) or invalid source (E004/E005).
+
+**GATE 2: Extraction → Routing** (Stage 4 → Stage 5-6)
+- REQUIRED: All files in selected artifacts loaded and parsed.
+- REQUIRED: Knowledge fragments extracted with category, confidence, and tags.
+- REQUIRED: Fragments filtered by `--min-confidence`.
+- BLOCKED if extraction produces zero fragments.
+
+**GATE 3: Routing → Write** (Stage 6 → Stage 7-8)
+- REQUIRED: Routing classification applied (auto or forced by `--to`).
+- REQUIRED: Dedup check passed against harvest-log.jsonl and existing stores.
+- REQUIRED: If `--dry-run`: preview displayed, no files written — GATE blocks further writes.
+- BLOCKED if dedup check fails or store paths unresolvable.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.