maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-frontend/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: team-frontend
+description: Unified team skill for frontend development. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
+allowed-tools: agent(*), task_create(*), task_list(*), task_get(*), task_update(*), team_create(*), team_delete(*), send_message(*), ask_user_question(*), read(*), write(*), edit(*), bash(*), glob(*), grep(*), web_fetch(*), web_search(*), mcp__maestro__team_msg(*)
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team Frontend Development
+
+Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from role.md specs.
+
+## Architecture
+
+```
+invoke_skill(skill="team-frontend", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+
+                    v       v       v       v
+               [analyst] [architect] [developer] [qa]
+              (team-worker agents, each loads roles/<role>/role.md)
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | false |
+| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | false |
+| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | true |
+| qa | [roles/qa/role.md](roles/qa/role.md) | QA-* | false |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (coding)**: `maestro spec load --category coding` — load coding constraints as shared context
+3. **Specs (ui)**: `maestro spec load --category ui` — load ui constraints as shared context
+4. **Wiki knowledge**: `maestro search "frontend component UI" --json` — top 5 entries as prior context
+5. All optional — proceed without if unavailable
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `FE`
+- **Session path**: `.workflow/.team/FE-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__maestro__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "frontend",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: frontend
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final send_message.
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Session Directory
+
+```
+.workflow/.team/FE-<slug>-<YYYY-MM-DD>/
+├── .msg/
+│   ├── messages.jsonl          # Message bus log
+│   └── meta.json               # Session state + cross-role state
+├── task-analysis.json          # Coordinator analyze output
+├── wisdom/                     # Cross-task knowledge
+├── analysis/                   # Analyst output
+│   ├── design-intelligence.json
+│   └── requirements.md
+├── architecture/               # Architect output
+│   ├── design-tokens.json
+│   ├── component-specs/
+│   └── project-structure.md
+├── qa/                         # QA output
+│   └── audit-<NNN>.md
+└── build/                      # Developer output
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| QA score < 6 over 2 GC rounds | Escalate to user |
+| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |
+| Worker no response | Report waiting task, suggest user `resume` |
+| Pipeline deadlock | Check blockedBy chain, report blocking point |

package/.agents/skills/team-frontend/roles/analyst/role.md

@@ -0,0 +1,102 @@
+---
+role: analyst
+prefix: ANALYZE
+inner_loop: false
+message_types:
+  success: analyze_ready
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Requirements Analyst
+
+Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Industry context | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path, industry type, and tech stack from task description
+2. Detect existing design system:
+
+| Signal | Detection Method |
+|--------|-----------------|
+| Token files | Glob `**/*token*.*` |
+| CSS files | Glob `**/*.css` |
+| Package.json | Read for framework dependencies |
+
+3. Detect tech stack from package.json:
+
+| Dependency | Stack |
+|------------|-------|
+| `next` | nextjs |
+| `react` | react |
+| `vue` | vue |
+| `svelte` | svelte |
+| `@shadcn/ui` | shadcn |
+| (none) | html-tailwind |
+
+4. Load .msg/meta.json for shared state
+
+## Phase 3: Design Intelligence Retrieval
+
+Retrieve design intelligence via ui-ux-pro-max skill integration.
+
+**Step 1: Invoke ui-ux-pro-max** (primary path):
+
+| Action | Invocation |
+|--------|------------|
+| Full design system | `invoke_skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
+| UX guidelines | `invoke_skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
+| Tech stack guide | `invoke_skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
+
+**Step 2: Fallback** (if skill unavailable):
+- Generate design recommendations from LLM general knowledge
+- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
+
+**Step 3: Analyze existing codebase** (if token/CSS files found):
+- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
+
+**Step 4: Competitive reference** (optional, if industry is not "Other"):
+- `web_search({ query: "<industry> web design trends best practices" })`
+
+**Step 5: Compile design-intelligence.json**:
+
+| Field | Source |
+|-------|--------|
+| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
+| `industry` | Task description |
+| `detected_stack` | Phase 2 detection |
+| `design_system` | Skill output (colors, typography, effects) |
+| `ux_guidelines` | Skill UX domain output |
+| `stack_guidelines` | Skill stack output |
+| `recommendations` | Synthesized: style, anti-patterns, must-have |
+
+**Output files**:
+- `<session>/analysis/design-intelligence.json`
+- `<session>/analysis/requirements.md`
+
+### Tech Profile Scan
+
+After analysis, scan findings for context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check detected_stack and dependencies → framework signals (`frontend_framework`, `api_surface`)
+2. Check codebase patterns → risk signals (`perf_sensitive`, `test_gap`, `legacy_patterns`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-intelligence.json | No parse errors |
+| Required fields | Check _source, industry, design_system | All present |
+| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
+| Requirements doc exists | File check | requirements.md written |
+
+Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.

package/.agents/skills/team-frontend/roles/architect/role.md

@@ -0,0 +1,88 @@
+---
+role: architect
+prefix: ARCH
+inner_loop: false
+message_types:
+  success: arch_ready
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Frontend Architect
+
+Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
+| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Load design intelligence from analyst output
+3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
+4. Detect existing project structure via Glob `src/**/*`
+
+**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
+
+## Phase 3: Architecture Design
+
+**Scope selection**:
+
+| Scope | Output |
+|-------|--------|
+| `tokens` | Design token system only |
+| `components` | Component specs only |
+| `full` | Both tokens and components + project structure |
+
+**Step 1: Design Token System** (scope: tokens or full):
+
+Generate `<session>/architecture/design-tokens.json` with categories:
+
+| Category | Content | Source |
+|----------|---------|--------|
+| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
+| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
+| `spacing` | xs through 2xl | Standard scale |
+| `border-radius` | sm, md, lg, full | Standard scale |
+| `shadow` | sm, md, lg | Standard elevation |
+| `transition` | fast, normal, slow | Standard durations |
+
+Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
+
+**Step 2: Component Architecture** (scope: components or full):
+
+Generate component specs in `<session>/architecture/component-specs/`:
+- Design reference (style, stack)
+- Props table (name, type, default, description)
+- Variants table
+- Accessibility requirements (role, keyboard, ARIA, contrast)
+- Anti-patterns to avoid (from design intelligence)
+
+**Step 3: Project Structure** (scope: full):
+
+Generate `<session>/architecture/project-structure.md` with stack-specific layout:
+
+| Stack | Key Directories |
+|-------|----------------|
+| react | src/components/, src/pages/, src/hooks/, src/styles/ |
+| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
+| vue | src/components/, src/views/, src/composables/, src/styles/ |
+| html-tailwind | src/components/, src/pages/, src/styles/ |
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-tokens.json | No errors |
+| Required categories | Check color, typography, spacing | All present |
+| Anti-pattern compliance | Token values vs anti-patterns | No violations |
+| Component specs complete | Each has props + accessibility | All complete |
+| File existence | Verify all planned files | All present |
+
+Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.

package/.agents/skills/team-frontend/roles/coordinator/commands/analyze.md

@@ -0,0 +1,52 @@
+# Analyze Task
+
+Parse frontend task -> detect capabilities -> assess pipeline complexity -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Role |
+|----------|------------|------|
+| analyze, requirements, design intelligence | analyst | analyst |
+| design tokens, component architecture, design system | architect | architect |
+| implement, build, code, develop, page, component | developer | developer |
+| review, audit, quality, test, accessibility | qa | qa |
+
+## Pipeline Selection
+
+| Scope Signal | Pipeline |
+|--------------|----------|
+| single page, landing, simple | page (4-beat) |
+| feature, multi-component, complex | feature (5-beat with arch review gate) |
+| full system, design system, multiple pages | system (7-beat dual-track) |
+
+Default to `feature` if ambiguous.
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| ui-ux-pro-max integration needed | +1 |
+| Existing design system detected | +1 |
+| Accessibility strict mode (healthcare/finance) | +2 |
+| Multiple tech stacks | +2 |
+| Dark mode required | +1 |
+
+Results: 1-2 page, 3-4 feature, 5+ system
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<page|feature|system>",
+  "capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "industry": "<industry>",
+  "constraints": [],
+  "needs_ui_ux_pro_max": true
+}
+```

package/.agents/skills/team-frontend/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,197 @@
+# Command: Dispatch
+
+Create the frontend development task chain with correct dependencies and structured task descriptions. Supports page, feature, and system pipeline modes.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| User requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline mode | From session.json `pipeline_mode` | Yes |
+| Industry | From session.json `industry` | Yes |
+| Constraints | From session.json `constraints` | No |
+
+1. Load user requirement and scope from session.json
+2. Load pipeline mode (page / feature / system) from session.json
+3. Load industry and constraints for task descriptions
+
+## Phase 3: Task Chain Creation
+
+### Task Description Template
+
+Every task description uses structured format:
+
+```
+create_task({
+  subject: "<TASK-ID>",
+  description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
+TASK:
+  - <step 1: specific action>
+  - <step 2: specific action>
+  - <step 3: specific action>
+CONTEXT:
+  - Session: <session-folder>
+  - Industry: <industry>
+  - Scope: <scope>
+  - Upstream artifacts: <artifact-1>, <artifact-2>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <deliverable path> + <quality criteria>
+CONSTRAINTS: <scope limits, focus areas>"
+})
+update_task({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })
+```
+
+### Mode Router
+
+| Mode | Task Chain |
+|------|------------|
+| `page` | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 |
+| `feature` | ANALYZE-001 -> ARCH-001 -> QA-001 -> DEV-001 -> QA-002 |
+| `system` | ANALYZE-001 -> ARCH-001 -> QA-001 -> [ARCH-002 &#124;&#124; DEV-001] -> QA-002 -> DEV-002 -> QA-003 |
+
+---
+
+### Page Mode Task Chain (4 tasks)
+
+**ANALYZE-001** (analyst):
+```
+create_task({
+  subject: "ANALYZE-001",
+  description: "PURPOSE: Analyze frontend requirements and retrieve design intelligence | Success: design-intelligence.json produced with industry-specific recommendations
+TASK:
+  - Detect tech stack and existing design system
+  - Retrieve design intelligence via ui-ux-pro-max (or LLM fallback)
+  - Analyze existing codebase patterns
+  - Compile design-intelligence.json and requirements.md
+CONTEXT:
+  - Session: <session-folder>
+  - Industry: <industry>
+  - Scope: <scope>
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/analysis/design-intelligence.json + requirements.md | Structured design data
+CONSTRAINTS: Read-only analysis | No code modifications"
+})
+update_task({ taskId: "ANALYZE-001", owner: "analyst" })
+```
+
+**ARCH-001** (architect):
+```
+create_task({
+  subject: "ARCH-001",
+  description: "PURPOSE: Define design token system and component architecture | Success: design-tokens.json + component specs produced
+TASK:
+  - Load design intelligence from analyst output
+  - Generate design token system (colors, typography, spacing, shadows)
+  - Define component architecture and specs
+  - Generate project structure
+CONTEXT:
+  - Session: <session-folder>
+  - Industry: <industry>
+  - Scope: full
+  - Upstream artifacts: design-intelligence.json, requirements.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/architecture/design-tokens.json + component-specs/ + project-structure.md
+CONSTRAINTS: Use ui-ux-pro-max recommendations for token values | Support light/dark mode"
+})
+update_task({ taskId: "ARCH-001", addBlockedBy: ["ANALYZE-001"], owner: "architect" })
+```
+
+**DEV-001** (developer):
+```
+create_task({
+  subject: "DEV-001",
+  description: "PURPOSE: Implement frontend page/components from architecture artifacts | Success: All planned files implemented with design token usage
+TASK:
+  - Load design tokens, component specs, project structure
+  - Generate CSS custom properties from design tokens
+  - Implement components following specs and coding standards
+  - Self-validate: no hardcoded colors, cursor-pointer, focus styles, responsive
+CONTEXT:
+  - Session: <session-folder>
+  - Industry: <industry>
+  - Scope: full
+  - Upstream artifacts: design-tokens.json, component-specs/, project-structure.md
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: src/styles/tokens.css + component files | Design-token compliant code
+CONSTRAINTS: Use CSS variables from tokens | Mobile-first responsive | WCAG AA"
+})
+update_task({ taskId: "DEV-001", addBlockedBy: ["ARCH-001"], owner: "developer" })
+```
+
+**QA-001** (qa):
+```
+create_task({
+  subject: "QA-001",
+  description: "PURPOSE: Execute 5-dimension quality audit on implementation | Success: Score >= 8 with 0 critical issues
+TASK:
+  - Load design intelligence and tokens for compliance checks
+  - Execute 5-dimension audit (code quality, accessibility, design compliance, UX, pre-delivery)
+  - Calculate weighted score and determine verdict
+  - Write audit report
+CONTEXT:
+  - Session: <session-folder>
+  - Industry: <industry>
+  - Review type: code-review
+  - Upstream artifacts: design-intelligence.json, design-tokens.json, src/**
+  - Shared memory: <session>/.msg/meta.json
+EXPECTED: <session>/qa/audit-001.md | Weighted score + verdict + categorized issues
+CONSTRAINTS: Read-only review | No code modifications"
+})
+update_task({ taskId: "QA-001", addBlockedBy: ["DEV-001"], owner: "qa" })
+```
+
+---
+
+### Feature Mode Task Chain (5 tasks)
+
+Create ANALYZE-001 and ARCH-001 as page mode above, then:
+
+**QA-001** (qa, architecture review):
+- blockedBy: ["ARCH-001"]
+- Review type: architecture-review
+- Reviews architecture artifacts before developer starts
+
+**DEV-001** (developer):
+- blockedBy: ["QA-001"] (waits for arch review to pass)
+
+**QA-002** (qa, code review):
+- blockedBy: ["DEV-001"]
+- Review type: code-review
+
+---
+
+### System Mode Task Chain (7 tasks)
+
+Create ANALYZE-001, ARCH-001, QA-001 as feature mode above, then:
+
+**ARCH-002** (architect, parallel with DEV-001):
+- blockedBy: ["QA-001"]
+- Scope: components (refined specs after QA feedback)
+
+**DEV-001** (developer, parallel with ARCH-002):
+- blockedBy: ["QA-001"]
+- Scope: tokens (CSS generation)
+
+**QA-002** (qa):
+- blockedBy: ["ARCH-002"]
+- Review type: component-review
+
+**DEV-002** (developer):
+- blockedBy: ["QA-002"]
+- Scope: components
+
+**QA-003** (qa, final review):
+- blockedBy: ["DEV-002"]
+- Review type: final
+
+## Phase 4: Validation
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | list_tasks count | page: 4, feature: 5, system: 7 |
+| Dependencies correct | Trace dependency graph | Acyclic, correct blockedBy |
+| Structured descriptions | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
+| Owner assignments correct | Role matches task prefix | ANALYZE->analyst, ARCH->architect, DEV->developer, QA->qa |
+
+If validation fails, fix the specific task and re-validate.