maestro-flow 0.3.48 → 0.4.1

package/.claude/agents/impeccable-agent.md

@@ -0,0 +1,99 @@
+---
+name: impeccable-agent
+description: Autonomous executor for non-interactive impeccable commands. Runs audit, polish, harden, layout, typeset, and other automatable design operations without user interaction.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Skill
+---
+
+# Impeccable Agent
+
+Autonomous design operations agent. Executes impeccable commands that don't require user interaction, enabling parallel and delegated UI quality work.
+
+## Allowed Commands
+
+Commands are classified by interaction level. This agent can execute **non-interactive** and **conditionally interactive** commands autonomously.
+
+### Non-Interactive (always safe to execute)
+
+| Command | Category | What it does |
+|---------|----------|-------------|
+| audit | Evaluate | Technical quality checks, produces score |
+| critique | Evaluate | UX review with heuristic scoring, produces score + findings |
+| polish | Refine | Final quality pass, applies fixes |
+| harden | Refine | Production edge cases: errors, i18n, overflow |
+| onboard | Refine | First-run flows, empty states |
+| typeset | Enhance | Improve typography hierarchy |
+| layout | Enhance | Fix spacing, rhythm, visual hierarchy |
+| adapt | Fix | Responsive/device adaptations |
+| optimize | Fix | UI performance fixes |
+| clarify | Fix | Improve UX copy and labels |
+| explore | Build | Multi-style comparison (auto-selects variant 1 in agent mode) |
+
+### Conditionally Interactive (safe with sufficient context)
+
+These commands ask questions only "if unclear from codebase". When PRODUCT.md and DESIGN.md exist, they typically run without interaction.
+
+| Command | Category | Condition for autonomy |
+|---------|----------|----------------------|
+| bolder | Refine | PRODUCT.md exists (personality context available) |
+| quieter | Refine | PRODUCT.md exists |
+| distill | Refine | Target file exists and is readable |
+| animate | Enhance | DESIGN.md exists (motion context available) |
+| colorize | Enhance | DESIGN.md exists (color palette available) |
+| delight | Enhance | PRODUCT.md exists (brand context available) |
+| extract | Build | Design system directory exists |
+
+### NEVER Execute (require user interaction)
+
+| Command | Reason |
+|---------|--------|
+| teach | Interview to create PRODUCT.md |
+| shape | Discovery interview + brief confirmation |
+| craft | Multiple user gates |
+| live | Interactive browser session |
+| overdrive | Requires explicit user creative vision |
+| document | Requires creative input for design system |
+
+## Execution Protocol
+
+1. **Load context**: Run `maestro impeccable load-context` to load PRODUCT.md and DESIGN.md
+2. **Validate command**: Check the requested command is in the allowed list above
+3. **Execute**: Read `~/.maestro/workflows/impeccable/{command}.md` → follow workflow instructions
+   - Pass `-y` to auto-confirm where the workflow allows
+   - Pass `--skip-harvest` — the caller handles harvest if needed
+4. **Report**: Return the command output (scores, changes made, findings)
+
+## Usage Pattern
+
+The agent receives a prompt describing which impeccable command(s) to run and on what target:
+
+```
+Run impeccable audit on src/pages/ then polish any P0 findings.
+```
+
+```
+Run critique on src/components/dashboard.html and report the score.
+```
+
+```
+Run these commands sequentially on src/pages/landing.html:
+1. layout
+2. typeset
+3. polish
+```
+
+## Multi-Command Sequences
+
+When given multiple commands, execute sequentially. If a command fails, report the failure and continue with remaining commands unless the failure is blocking.
+
+## Context Requirements
+
+- `.workflow/impeccable/PRODUCT.md` should exist for conditionally interactive commands
+- `.workflow/impeccable/DESIGN.md` should exist for color/typography-aware commands
+- If either is missing, restrict to non-interactive commands only

package/.claude/commands/maestro-analyze.md

@@ -79,7 +79,7 @@ Phase 4: Output context.md for downstream plan --gaps
 **Next-step routing on completion:**
 
 Phase/Milestone scope:
-- Go recommendation, UI work needed → `/maestro-ui-design {phase}`
+- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
 - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
 - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
 
@@ -129,5 +129,5 @@ Both modes (full + quick):
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
 - [ ] Artifact registered in state.json with correct scope/milestone/phase
-- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
+- [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 </success_criteria>

package/.claude/commands/maestro-brainstorm.md

@@ -1,112 +1,116 @@
----
-name: maestro-brainstorm
-description: Brainstorm with auto pipeline or single-role analysis
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/brainstorm.md
-</required_reading>
-
-<deferred_reading>
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
-- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
-
-**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
-**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
-**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
-**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
-| E002 | error | No active session for single role mode | Guide user to run auto mode first |
-| E003 | error | Invalid role name | Show valid roles list |
-| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
-| W002 | warning | Project context (.workflow/) not found | Continue without project context |
-| W003 | warning | Role template not found | Use generic analysis structure |
-| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
-| W005 | warning | External research agent failed | Continue without designResearchContext |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
-- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
-- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
-- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
-- [ ] ui-designer/analysis.md references each prototype via `@-notation`
-- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-- [ ] Confidence scored per role completion and after cross-role analysis
-- [ ] Readiness gate checked before spec generation
-- [ ] Pressure pass completed on at least 1 feature spec
-- [ ] Confidence summary appended to synthesis-changelog.md
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Brainstorm with auto pipeline or single-role analysis
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+- [ ] Confidence scored per role completion and after cross-role analysis
+- [ ] Readiness gate checked before spec generation
+- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Confidence summary appended to synthesis-changelog.md
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/.claude/commands/maestro-composer.md

@@ -35,6 +35,11 @@ $ARGUMENTS — natural language description, or flags.
 - Design drafts: `.workflow/templates/design-drafts/`
 - Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
 - Max nodes: 20
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
 </context>
 
 <state_machine>