pi-maestro-flow 0.2.0

package/skills/prompt-generator/SKILL.md

@@ -0,0 +1,470 @@
+---
+name: prompt-generator
+description: "Generate or convert Claude Code prompt files — command orchestrators, skill files, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on \"create command\", \"new command\", \"create skill\", \"new skill\", \"create agent\", \"new agent\", \"convert command\", \"convert skill\", \"convert agent\", \"prompt generator\", \"优化\"."
+allowed-tools: Read Write Edit Bash Glob AskUserQuestion
+---
+
+<purpose>
+Generate or convert Claude Code prompt files with concrete, domain-specific content. Four modes:
+
+- **Create command** — new orchestration workflow at `.claude/commands/` or `~/.claude/commands/`
+- **Create skill** — new skill file at `.claude/skills/*/SKILL.md` (progressive loading, no @ refs)
+- **Create agent** — new role + expertise file at `.claude/agents/`
+- **Convert** — restyle existing command/skill/agent to GSD conventions with zero content loss
+
+Content separation principle (from GSD): commands/skills own orchestration flow; agents own domain knowledge. Skills are a variant of commands but loaded progressively inline — they CANNOT use `@` file references.
+
+Invoked when user requests "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", or "优化".
+</purpose>
+
+<required_reading>
+- @.claude/skills/prompt-generator/specs/command-design-spec.md
+- @.claude/skills/prompt-generator/specs/agent-design-spec.md
+- @.claude/skills/prompt-generator/specs/conversion-spec.md
+- @.claude/skills/prompt-generator/templates/command-md.md
+- @.claude/skills/prompt-generator/templates/agent-md.md
+</required_reading>
+
+<process>
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## 1. Determine Artifact Type
+
+Parse `$ARGUMENTS` to determine what to generate.
+
+| Signal | Type |
+|--------|------|
+| "command", "workflow", "orchestrator" in args | `command` |
+| "skill", "SKILL.md" in args, or path contains `.claude/skills/` | `skill` |
+| "agent", "role", "worker" in args | `agent` |
+| "convert", "restyle", "refactor", "optimize", "优化" + file path in args | `convert` |
+| Ambiguous or missing | Ask user |
+
+**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args. Auto-detect source type from path:
+- `.claude/commands/` → command
+- `.claude/skills/*/SKILL.md` → skill
+- `.claude/agents/` → agent
+
+**Skill vs Command distinction:** Skills (`.claude/skills/*/SKILL.md`) are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — only `Read()` tool calls within process steps. See `@specs/command-design-spec.md` → "Skill Variant" section.
+
+If ambiguous:
+
+```
+AskUserQuestion(
+  header: "Artifact Type",
+  question: "What type of prompt file do you want to generate?",
+  options: [
+    { label: "Command", description: "New orchestration workflow — process steps, user interaction, agent spawning" },
+    { label: "Skill", description: "New skill file — progressive loading, no @ refs, inline Read() for external files" },
+    { label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
+    { label: "Convert", description: "Restyle existing command/agent/skill to GSD conventions (zero content loss)" }
+  ]
+)
+```
+
+Store as `$ARTIFACT_TYPE` (`command` | `skill` | `agent` | `convert`).
+
+## 2. Validate Parameters
+
+**If `$ARTIFACT_TYPE` is `convert`:** Skip to Step 2c.
+
+Extract from `$ARGUMENTS` or ask interactively:
+
+**Common parameters (create mode):**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$NAME` | Yes | `/^[a-z][a-z0-9-]*$/` | `deploy`, `gsd-planner` |
+| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy to production with rollback"` |
+
+**Command-specific parameters:**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
+| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` | `issue`, `workflow` |
+| `$ARGUMENT_HINT` | No | any string | `"<phase> [--skip-verify]"` |
+
+**Agent-specific parameters:**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$TOOLS` | No | comma-separated tool names | `Read, Write, Bash, Glob` |
+| `$SPAWNED_BY` | No | which command spawns this agent | `/plan-phase orchestrator` |
+
+Normalize: trim + lowercase for `$NAME`, `$LOCATION`, `$GROUP`.
+
+## 3. Resolve Target Path
+
+**Command:**
+
+| Location | Base |
+|----------|------|
+| `project` | `.claude/commands` |
+| `user` | `~/.claude/commands` |
+
+```
+If $GROUP:
+  $TARGET_PATH = {base}/{$GROUP}/{$NAME}.md
+Else:
+  $TARGET_PATH = {base}/{$NAME}.md
+```
+
+**Skill:**
+
+```
+$TARGET_PATH = .claude/skills/{$NAME}/SKILL.md
+```
+
+**Agent:**
+
+```
+$TARGET_PATH = .claude/agents/{$NAME}.md
+```
+
+Check if `$TARGET_PATH` exists → `$FILE_EXISTS`.
+
+## 4. Gather Requirements
+
+**4a. Pattern discovery** — Find 3+ similar files in the project for style reference:
+
+```bash
+# For commands: scan existing commands
+ls .claude/commands/**/*.md 2>/dev/null | head -5
+
+# For agents: scan existing agents
+ls .claude/agents/*.md 2>/dev/null | head -5
+```
+
+Read 1-2 similar files to extract patterns: section structure, naming conventions, XML tag usage, prompt style.
+
+**4b. Domain inference** from `$NAME`, `$DESCRIPTION`, and context:
+
+| Signal | Extract |
+|--------|---------|
+| `$NAME` | Action verb → step/section naming |
+| `$DESCRIPTION` | Domain keywords → content structure |
+| `$ARGUMENT_HINT` | Flags → parse_input logic (command only) |
+| `$SPAWNED_BY` | Upstream contract → role boundary (agent only) |
+
+**For commands — determine complexity:**
+
+| Complexity | Criteria | Steps |
+|------------|----------|-------|
+| Simple | Single action, no flags | 3-5 numbered steps |
+| Standard | 1-2 flags, clear workflow | 5-8 numbered steps |
+| Complex | Multiple flags, agent spawning | 8-14 numbered steps |
+
+**For agents — determine expertise scope:**
+
+| Scope | Criteria | Sections |
+|-------|----------|----------|
+| Focused | Single responsibility | `<role>` + 1-2 domain sections |
+| Standard | Multi-aspect domain | `<role>` + 2-4 domain sections |
+| Expert | Deep domain with rules | `<role>` + 4-6 domain sections |
+
+If unclear, ask user with AskUserQuestion.
+
+## 5. Generate Content
+
+Route to the appropriate generation logic based on `$ARTIFACT_TYPE`.
+
+### 5a. Command Generation
+
+Follow `@specs/command-design-spec.md` and `@templates/command-md.md`.
+
+Generate a complete command file with:
+
+1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
+2. **`<required_reading>`** — @ references to context files
+3. **`<process>`** — numbered steps (GSD workflow style):
+   - Step 1: Initialize / parse arguments
+   - Steps 2-N: Domain-specific orchestration logic
+   - Each step: banner display, validation, agent spawning via `Agent()`, error handling
+   - Final step: status display + `<offer_next>` with next actions
+4. **`<success_criteria>`** — checkbox list of verifiable conditions
+
+**Command writing rules:**
+- Steps are **numbered** (`## 1.`, `## 2.`) — follow `plan-phase.md` and `new-project.md` style
+- Use banners for phase transitions: `━━━ SKILL ► ACTION ━━━`
+- Agent spawning uses `Agent({ subagent_type, prompt, description, run_in_background })` pattern
+- Prompt to agents uses `<objective>`, `<files_to_read>`, `<output>` blocks
+- Include `<offer_next>` block with formatted completion status
+- Handle agent return markers: `## TASK COMPLETE`, `## TASK BLOCKED`, `## CHECKPOINT REACHED`
+- Shell blocks use heredoc for multi-line, quote all variables
+- Include `<auto_mode>` section if command supports `--auto` flag
+
+### 5a-skill. Skill Generation (variant of command)
+
+Follow `@specs/command-design-spec.md` → "Skill Variant" section.
+
+Skills are command-like orchestrators but loaded **progressively inline** — they CANNOT use `@` file references.
+
+Generate a complete skill file with:
+
+1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
+2. **NO `<required_reading>`** — skills cannot use `@` refs. External files loaded via `Read()` within process steps.
+3. **`<process>`** — numbered steps (GSD workflow style):
+   - Step 1: Initialize / parse arguments / set workflow preferences
+   - Steps 2-N: Domain-specific orchestration logic with inline `Read("phases/...")` for phase files
+   - Each step: validation, agent spawning via `Agent()`, error handling
+   - Final step: completion status or handoff to next skill via `Skill()`
+4. **`<success_criteria>`** — checkbox list of verifiable conditions
+
+**Skill-specific writing rules:**
+- **NO `<required_reading>` tag** — `@` syntax not supported in skills
+- **NO `@path` references** anywhere in the file — use `Read("path")` within `<process>` steps
+- Phase files loaded on-demand: `Read("phases/01-xxx.md")` within the step that needs it
+- Frontmatter uses `allowed-tools:` (not `argument-hint:`)
+- `<offer_next>` is optional — skills often chain via `Skill()` calls
+- `<auto_mode>` can be inline within `<process>` step 1 or as standalone section
+
+### 5b. Agent Generation
+
+Follow `@specs/agent-design-spec.md` and `@templates/agent-md.md`.
+
+Generate a complete agent definition with:
+
+1. **YAML frontmatter** — name, description, tools, color (optional)
+2. **`<role>`** — identity + spawned-by + core responsibilities + mandatory initial read
+3. **Domain sections** (2-6 based on scope):
+   - `<philosophy>` — guiding principles, anti-patterns
+   - `<context_fidelity>` — how to honor upstream decisions
+   - `<task_breakdown>` / `<output_format>` — concrete output rules with examples
+   - `<quality_gate>` — self-check criteria before returning
+   - Custom domain sections as needed
+4. **Output contract** — structured return markers to orchestrator
+
+**Agent writing rules:**
+- `<role>` is ALWAYS first after frontmatter — defines identity
+- Each section owns ONE concern — no cross-cutting
+- Include concrete examples (good vs bad comparison tables) in every domain section
+- Include decision/routing tables for conditional logic
+- Quality gate uses checkbox format for self-verification
+- Agent does NOT contain orchestration logic, user interaction, or argument parsing
+
+### 5c. Convert Mode (Restyle Existing File)
+
+**CRITICAL: Zero content loss.** Follow `@specs/conversion-spec.md`.
+
+**Step 5c.1: Read and inventory source file.**
+
+Read `$SOURCE_PATH` completely. Build content inventory:
+
+```
+$INVENTORY = {
+  frontmatter: { fields extracted },
+  sections: [ { name, tag, line_range, line_count, has_code_blocks, has_tables } ],
+  code_blocks: count,
+  tables: count,
+  total_lines: count
+}
+```
+
+**Step 5c.2: Classify source type.**
+
+| Signal | Type |
+|--------|------|
+| Path in `.claude/skills/*/SKILL.md` | skill |
+| `allowed-tools:` in frontmatter + path in `.claude/skills/` | skill |
+| Contains `<process>`, `<step>`, numbered `## N.` steps | command |
+| Contains `<role>`, `tools:` in frontmatter, domain sections | agent |
+| Flat markdown with `## Implementation`, `## Phase N` + in skills dir | skill (unstructured) |
+| Flat markdown with `## Implementation`, `## Phase N` + in commands dir | command (unstructured) |
+| Flat prose with role description, no process steps | agent (unstructured) |
+
+**Skill-specific conversion rules:**
+- **NO `<required_reading>`** — skills cannot use `@` file references (progressive loading)
+- **NO `@path` references** anywhere — replace with `Read("path")` within `<process>` steps
+- If source has `@specs/...` or `@phases/...` refs, convert to `Read("specs/...")` / `Read("phases/...")`
+- Follow `@specs/conversion-spec.md` → "Skill Conversion Rules" section
+
+**Step 5c.3: Build conversion map.**
+
+Map every source section to its target location. Follow `@specs/conversion-spec.md` transformation rules.
+
+**MANDATORY**: Every line of source content must appear in the conversion map. If a source section has no clear target, keep it as a custom section.
+
+**Step 5c.4: Generate converted content.**
+
+Apply structural transformations while preserving ALL content verbatim:
+- Rewrap into GSD XML tags
+- Restructure sections to match target template ordering
+- Add missing required sections (empty `<quality_gate>`, `<output_contract>`) with `TODO` markers
+- Preserve all code blocks, tables, examples, shell commands exactly as-is
+
+**Step 5c.5: Content loss verification (MANDATORY).**
+
+Compare source and output:
+
+| Metric | Source | Output | Pass? |
+|--------|--------|--------|-------|
+| Total lines | `$SRC_LINES` | `$OUT_LINES` | output >= source × 0.95 |
+| Code blocks | `$SRC_BLOCKS` | `$OUT_BLOCKS` | output >= source |
+| Tables | `$SRC_TABLES` | `$OUT_TABLES` | output >= source |
+| Sections | `$SRC_SECTIONS` | `$OUT_SECTIONS` | output >= source |
+
+If ANY metric fails → STOP, display diff, ask user before proceeding.
+
+Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies output path.
+
+### Content quality rules (both types):
+- NO bracket placeholders (`[Describe...]`) — all content concrete
+- NO generic instructions ("handle errors appropriately") — be specific
+- Include domain-specific examples derived from `$DESCRIPTION`
+- Every shell block: heredoc for multi-line, quoted variables, error exits
+
+## 6. Quality Gate
+
+**MANDATORY before writing.** Read back the generated content and validate against type-specific checks.
+
+### 6a. Structural Validation (both types)
+
+| Check | Pass Condition |
+|-------|---------------|
+| YAML frontmatter | Has `name` + `description` |
+| No placeholders | Zero `[...]` or `{...}` bracket placeholders in prose |
+| Concrete content | Every section has actionable content, not descriptions of what to write |
+| Section count | Command: 3+ sections; Agent: 4+ sections |
+
+### 6b. Command-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| `<purpose>` | 2-3 sentences, no placeholders |
+| `<process>` with numbered steps | At least 3 `## N.` headers |
+| Step 1 is initialization | Parses args or loads context |
+| Last step is status/report | Displays results or routes to `<offer_next>` |
+| Agent spawning (if complex) | `Agent({` call with `subagent_type` |
+| Agent prompt structure | `<files_to_read>` + `<objective>` or `<output>` blocks |
+| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers |
+| `<offer_next>` | Banner + summary + next command suggestion |
+| `<success_criteria>` | 4+ checkbox items, all verifiable |
+| Content separation | No domain expertise embedded — only orchestration |
+
+### 6b-skill. Skill-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| `<purpose>` | 2-3 sentences, no placeholders |
+| **NO `<required_reading>`** | Must NOT contain `<required_reading>` tag |
+| **NO `@` file references** | Zero `@specs/`, `@phases/`, `@./` patterns in prose |
+| `<process>` with numbered steps | At least 3 `## N.` headers |
+| Step 1 is initialization | Parses args, sets workflow preferences |
+| Phase file loading | Uses `Read("phases/...")` within process steps (if has phases) |
+| `<success_criteria>` | 4+ checkbox items, all verifiable |
+| Frontmatter `allowed-tools` | Present and lists required tools |
+| Content separation | No domain expertise embedded — only orchestration |
+
+### 6c. Agent-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| YAML `tools` field | Lists tools agent needs |
+| `<role>` is first section | Appears before any domain section |
+| `<role>` has spawned-by | States which command spawns it |
+| `<role>` has mandatory read | `<files_to_read>` instruction present |
+| `<role>` has responsibilities | 3+ bullet points with verb phrases |
+| Domain sections named | After domain concepts, not generic (`<rules>`, `<guidelines>`) |
+| Examples present | Each domain section has 1+ comparison table or decision table |
+| `<output_contract>` | Defines return markers (COMPLETE/BLOCKED/CHECKPOINT) |
+| `<quality_gate>` | 3+ checkbox self-check items |
+| Content separation | No `AskUserQuestion`, no banner display, no argument parsing |
+
+### 6d. Quality Gate Result
+
+Count errors and warnings:
+
+| Gate | Condition | Action |
+|------|-----------|--------|
+| **PASS** | 0 errors, 0-2 warnings | Proceed to write |
+| **REVIEW** | 1-2 errors or 3+ warnings | Fix errors, display warnings |
+| **FAIL** | 3+ errors | Re-generate from step 5 |
+
+If FAIL and second attempt also fails:
+
+```
+AskUserQuestion(
+  header: "Quality Gate Failed",
+  question: "Generated content failed quality checks twice. How to proceed?",
+  options: [
+    { label: "Show issues and proceed", description: "Write as-is, fix manually" },
+    { label: "Provide more context", description: "I'll give additional details" },
+    { label: "Abort", description: "Cancel generation" }
+  ]
+)
+```
+
+## 7. Write and Verify
+
+**If `$FILE_EXISTS`:** Warn user before overwriting.
+
+```bash
+mkdir -p "$(dirname "$TARGET_PATH")"
+```
+
+Write content to `$TARGET_PATH` using Write tool.
+
+**Post-write verification** — Read back and confirm file integrity:
+- File exists and is non-empty
+- Content matches what was generated (no corruption)
+- File size is reasonable (command: 50-500 lines; agent: 80-600 lines)
+
+**If verification fails:** Fix in-place with Edit tool.
+
+## 8. Present Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PROMPT-GEN ► {COMMAND|AGENT} GENERATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Type: {command | agent}
+File: {$TARGET_PATH}
+Name: {$NAME}
+
+| Section | Status |
+|---------|--------|
+| {section 1} | concrete |
+| {section 2} | concrete |
+| ... | ... |
+
+Quality Gate: {PASS | REVIEW (N warnings)}
+
+───────────────────────────────────────────────────────
+
+## Next Up
+
+1. Review: cat {$TARGET_PATH}
+2. Test: /{invocation}
+
+**If command + needs an agent:**
+  /prompt-generator agent {agent-name} "{agent description}"
+
+**If agent + needs a command:**
+  /prompt-generator command {command-name} "{command description}"
+
+───────────────────────────────────────────────────────
+```
+
+</process>
+
+<success_criteria>
+- [ ] Artifact type determined (command or agent)
+- [ ] All required parameters validated
+- [ ] Target path resolved correctly
+- [ ] 1-2 similar existing files read for pattern reference
+- [ ] Domain requirements gathered from description
+- [ ] Content generated with concrete, domain-specific logic
+- [ ] GSD content separation respected (commands = orchestration, agents = expertise)
+- [ ] Quality gate passed (structural + type-specific checks)
+- [ ] No bracket placeholders in final output
+- [ ] File written and post-write verified
+- [ ] Status banner displayed with quality gate result
+</success_criteria>

package/skills/quality-auto-test/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: quality-auto-test
+description: "Use when test coverage needs automated expansion or existing tests need iterative convergence Arguments: <phase> [-y] [-c N] [--max-iter N] [--layer L0|L1|L2|L3] [--dry-run] [--re-run]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Unified automated testing via CSV layer pipeline. Auto-selects scenario source from project state (specs / coverage gaps / code exploration), then: discover → plan → build CSV → write tests (parallel) → execute → diagnose failures (parallel) → iterate → report.
+
+Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-iter 1` = single-pass; default = full iterative cycle.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/auto-test.md
+</required_reading>
+
+<context>
+Phase or task: $ARGUMENTS (required — phase number)
+
+**Flags:**
+- `-c N` — Resume from iteration N of an existing session (skips setup, resumes from last checkpoint)
+- `-y` — Skip confirmation prompts for artifact registration and issue creation
+- `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
+- `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
+- `--dry-run` — Generate test plan only, do not execute
+- `--re-run` — Re-run only previously failed/blocked scenarios
+
+**Intelligent routing** (auto-detected from project state):
+
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
+| 1 | Active session exists (state.json status=running) | Resume | — |
+| 2 | --re-run flag + previous failures | Re-run | — |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
+
+Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
+
+### Pre-load context (before test generation)
+
+1. **Test specs + tools**: Run `maestro load --type spec --category test` to load test conventions (framework, patterns, naming). Apply to all generated tests.
+2. **Coding specs**: Run `maestro load --type spec --category coding` to understand coding patterns for accurate test targeting.
+3. **Role Knowledge**:
+   - Browse: `maestro search --category test`
+   - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-auto-test-P{N}-{slug}/` or `.workflow/state.json` only. Source code modifications are limited to test files generated by this command. NEVER modify existing production source code.
+</context>
+
+<invariants>
+1. **Test code isolation** — generated tests MUST be written to test directories following existing project conventions. NEVER modify production source code to make tests pass.
+2. **RED-GREEN integrity** — tests MUST be written to fail first (RED), then verified to pass against implementation (GREEN). NEVER write tests that pass trivially or assert nothing.
+3. **Layer ordering is strict** — L0→L3 execution is sequential and fail-fast. NEVER skip a layer or run L2 before L1 passes.
+4. **Existing tests are sacred** — NEVER modify, delete, or overwrite existing test files. New tests are additive only.
+5. **Convergence requires evidence** — pass rate and confidence score MUST be computed from actual execution results. NEVER infer or estimate pass rates without running tests.
+6. **Iteration has bounds** — outer iteration MUST NOT exceed `--max-iter` (default 5). Inner test_defect fix MUST NOT exceed 3 attempts per scenario before escalating.
+7. **Traceability is mandatory for spec source** — when route=spec, every test scenario MUST trace back to a REQ-*.md requirement. Untraceable tests are flagged.
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/auto-test.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Plan** (Route Selection → CSV Generation)
+- REQUIRED: Phase resolved from artifact registry. E001/E002 if missing.
+- REQUIRED: Route auto-selected (spec/gap/code) from project state.
+- REQUIRED: Test infrastructure discovered (framework, patterns, conventions).
+- BLOCKED if missing: cannot generate test plan without route and framework.
+
+**GATE 2: Plan → Write** (CSV → Test Generation)
+- REQUIRED: test-plan.json generated with layer distribution (L0→L3).
+- REQUIRED: User confirmed plan (unless `--dry-run` stops here).
+- BLOCKED if plan missing or rejected: do not write tests.
+
+**GATE 3: Write → Execute** (Test Generation → Execution)
+- REQUIRED: All planned test files written following existing patterns.
+- REQUIRED: Tests follow RED-GREEN methodology.
+- BLOCKED if tests incomplete: finish writing before execution.
+
+**GATE 4: Execute → Report** (Iteration → Completion)
+- REQUIRED: Progressive execution completed (L0→L3, fail-fast on critical).
+- REQUIRED: Iteration engine ran (inner: test_defect fix, outer: strategy adjust).
+- REQUIRED: Confidence scored with 5-dimension factor model (>= 60%).
+- REQUIRED: Pressure pass completed on highest-pass-rate layer.
+- BLOCKED if iteration incomplete: continue iterating before reporting.
+
+**Command-specific extensions (not in workflow):**
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, suggest quality-debug
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+
+Unless `-y` flag is set, confirm before writing:
+```
+AskUserQuestion("Register auto-test artifact TST-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to next-step routing
+```
+
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-auto-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+**Next-step routing on completion:**
+- Converged (>=95%) → `/quality-review {phase}`
+- All requirements verified (spec source) → `/maestro-milestone-audit`
+- Bugs discovered → `/quality-debug --from-uat {phase}`
+- Max iter, >80% → `/quality-test {phase}` for manual UAT
+- Max iter, <80% → `/quality-debug {phase}`
+- Coverage still low → `/quality-auto-test {phase} --layer {missing}`
+- Re-run all pass → `/quality-review {phase}`
+- Single pass, all pass → `/quality-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required (no active sessions) | Prompt user for phase number |
+| E002 | error | Phase not found in artifact registry | Check state.json artifacts |
+| E003 | error | No test framework detected | Install test framework or configure test runner |
+| W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
+| W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
+| W003 | warning | Degraded spec mode (no full spec package) | Consider running /maestro-blueprint |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved from artifact registry
+- [ ] Route auto-selected from project state (spec/gap/code)
+- [ ] Active sessions checked, resume offered if applicable
+- [ ] Scenarios extracted and normalized to unified format
+- [ ] Test infrastructure discovered (framework, patterns, conventions)
+- [ ] test-plan.json generated with layer distribution
+- [ ] User confirmed plan (or --dry-run stopped here)
+- [ ] Tests written following RED-GREEN methodology and existing patterns
+- [ ] Tests executed progressively (L0→L3) with fail-fast on critical
+- [ ] Iteration engine ran (inner: test_defect fix, outer: strategy adjust)
+- [ ] state.json, report.json, reflection-log.md written
+- [ ] Test confidence scored per iteration (Step 7.5) with 5-dimension factor model
+- [ ] Convergence check includes confidence >= 60% alongside pass_rate threshold
+- [ ] Pressure pass completed on highest-pass-rate layer before completion
+- [ ] report.json includes confidence section
+- [ ] index.json updated with auto_test section
+- [ ] If spec source: traceability matrix built, traceability.md written
+- [ ] If failures: issues created in issues.jsonl (confirmed by user unless `-y`)
+- [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
+- [ ] Next step routed based on convergence status
+</success_criteria>