maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/skill-tuning/templates/diagnosis-report.md

@@ -0,0 +1,153 @@
+# Diagnosis Report Template
+
+Template for individual diagnosis action reports.
+
+## Template
+
+```markdown
+# {{diagnosis_type}} Diagnosis Report
+
+**Target Skill**: {{skill_name}}
+**Diagnosis Type**: {{diagnosis_type}}
+**Executed At**: {{timestamp}}
+**Duration**: {{duration_ms}}ms
+
+---
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Issues Found | {{issues_found}} |
+| Severity | {{severity}} |
+| Patterns Checked | {{patterns_checked_count}} |
+| Patterns Matched | {{patterns_matched_count}} |
+
+---
+
+## Patterns Analyzed
+
+{{#each patterns_checked}}
+### {{pattern_name}}
+
+- **Status**: {{status}}
+- **Matches**: {{match_count}}
+- **Files Affected**: {{affected_files}}
+
+{{/each}}
+
+---
+
+## Issues Identified
+
+{{#if issues.length}}
+{{#each issues}}
+### {{id}}: {{description}}
+
+| Field | Value |
+|-------|-------|
+| Type | {{type}} |
+| Severity | {{severity}} |
+| Location | {{location}} |
+| Root Cause | {{root_cause}} |
+| Impact | {{impact}} |
+
+**Evidence**:
+{{#each evidence}}
+- `{{this}}`
+{{/each}}
+
+**Suggested Fix**: {{suggested_fix}}
+
+---
+{{/each}}
+{{else}}
+_No issues found in this diagnosis area._
+{{/if}}
+
+---
+
+## Recommendations
+
+{{#if recommendations.length}}
+{{#each recommendations}}
+{{@index}}. {{this}}
+{{/each}}
+{{else}}
+No specific recommendations - area appears healthy.
+{{/if}}
+
+---
+
+## Raw Data
+
+Full diagnosis data available at:
+`{{output_file}}`
+```
+
+## Variable Reference
+
+| Variable | Type | Source |
+|----------|------|--------|
+| `diagnosis_type` | string | 'context' \| 'memory' \| 'dataflow' \| 'agent' |
+| `skill_name` | string | state.target_skill.name |
+| `timestamp` | string | ISO timestamp |
+| `duration_ms` | number | Execution time |
+| `issues_found` | number | issues.length |
+| `severity` | string | Calculated severity |
+| `patterns_checked` | array | Patterns analyzed |
+| `patterns_matched` | array | Patterns with matches |
+| `issues` | array | Issue objects |
+| `recommendations` | array | String recommendations |
+| `output_file` | string | Path to JSON file |
+
+## Usage
+
+```javascript
+function renderDiagnosisReport(diagnosis, diagnosisType, skillName, outputFile) {
+  return `# ${diagnosisType} Diagnosis Report
+
+**Target Skill**: ${skillName}
+**Diagnosis Type**: ${diagnosisType}
+**Executed At**: ${new Date().toISOString()}
+**Duration**: ${diagnosis.execution_time_ms}ms
+
+---
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Issues Found | ${diagnosis.issues_found} |
+| Severity | ${diagnosis.severity} |
+| Patterns Checked | ${diagnosis.details.patterns_checked.length} |
+| Patterns Matched | ${diagnosis.details.patterns_matched.length} |
+
+---
+
+## Issues Identified
+
+${diagnosis.details.evidence.map((e, i) => `
+### Issue ${i + 1}
+
+- **File**: ${e.file}
+- **Pattern**: ${e.pattern}
+- **Severity**: ${e.severity}
+- **Context**: \`${e.context}\`
+`).join('\n')}
+
+---
+
+## Recommendations
+
+${diagnosis.details.recommendations.map((r, i) => `${i + 1}. ${r}`).join('\n')}
+
+---
+
+## Raw Data
+
+Full diagnosis data available at:
+\`${outputFile}\`
+`;
+}
+```

package/.agents/skills/skill-tuning/templates/fix-proposal.md

@@ -0,0 +1,204 @@
+# Fix Proposal Template
+
+Template for fix proposal documentation.
+
+## Template
+
+```markdown
+# Fix Proposal: {{fix_id}}
+
+**Strategy**: {{strategy}}
+**Risk Level**: {{risk}}
+**Issues Addressed**: {{issue_ids}}
+
+---
+
+## Description
+
+{{description}}
+
+## Rationale
+
+{{rationale}}
+
+---
+
+## Affected Files
+
+{{#each changes}}
+### {{file}}
+
+**Action**: {{action}}
+
+```diff
+{{diff}}
+```
+
+{{/each}}
+
+---
+
+## Implementation Steps
+
+{{#each implementation_steps}}
+{{@index}}. {{this}}
+{{/each}}
+
+---
+
+## Risk Assessment
+
+| Factor | Assessment |
+|--------|------------|
+| Complexity | {{complexity}} |
+| Reversibility | {{reversible ? 'Yes' : 'No'}} |
+| Breaking Changes | {{breaking_changes}} |
+| Test Coverage | {{test_coverage}} |
+
+**Overall Risk**: {{risk}}
+
+---
+
+## Verification Steps
+
+{{#each verification_steps}}
+- [ ] {{this}}
+{{/each}}
+
+---
+
+## Rollback Plan
+
+{{#if rollback_available}}
+To rollback this fix:
+
+```bash
+{{rollback_command}}
+```
+{{else}}
+_Rollback not available for this fix type._
+{{/if}}
+
+---
+
+## Estimated Impact
+
+{{estimated_impact}}
+```
+
+## Variable Reference
+
+| Variable | Type | Source |
+|----------|------|--------|
+| `fix_id` | string | Generated ID (FIX-001) |
+| `strategy` | string | Fix strategy name |
+| `risk` | string | 'low' \| 'medium' \| 'high' |
+| `issue_ids` | array | Related issue IDs |
+| `description` | string | Human-readable description |
+| `rationale` | string | Why this fix works |
+| `changes` | array | File change objects |
+| `implementation_steps` | array | Step-by-step guide |
+| `verification_steps` | array | How to verify fix worked |
+| `estimated_impact` | string | Expected improvement |
+
+## Usage
+
+```javascript
+function renderFixProposal(fix) {
+  return `# Fix Proposal: ${fix.id}
+
+**Strategy**: ${fix.strategy}
+**Risk Level**: ${fix.risk}
+**Issues Addressed**: ${fix.issue_ids.join(', ')}
+
+---
+
+## Description
+
+${fix.description}
+
+## Rationale
+
+${fix.rationale}
+
+---
+
+## Affected Files
+
+${fix.changes.map(change => `
+### ${change.file}
+
+**Action**: ${change.action}
+
+\`\`\`diff
+${change.diff || change.new_content?.slice(0, 200) || 'N/A'}
+\`\`\`
+`).join('\n')}
+
+---
+
+## Verification Steps
+
+${fix.verification_steps.map(step => `- [ ] ${step}`).join('\n')}
+
+---
+
+## Estimated Impact
+
+${fix.estimated_impact}
+`;
+}
+```
+
+## Fix Strategy Templates
+
+### sliding_window
+
+```markdown
+## Description
+Implement sliding window for conversation history to prevent unbounded growth.
+
+## Changes
+- Add MAX_HISTORY constant
+- Modify history update logic to slice array
+- Update state schema documentation
+
+## Verification
+- [ ] Run skill for 10+ iterations
+- [ ] Verify history.length <= MAX_HISTORY
+- [ ] Check no data loss for recent items
+```
+
+### constraint_injection
+
+```markdown
+## Description
+Add explicit constraint section to each phase prompt.
+
+## Changes
+- Add [CONSTRAINTS] section template
+- Reference state.original_requirements
+- Add reminder before output section
+
+## Verification
+- [ ] Check constraints visible in all phases
+- [ ] Test with specific constraint
+- [ ] Verify output respects constraint
+```
+
+### error_wrapping
+
+```markdown
+## Description
+Wrap all Task calls in try-catch with retry logic.
+
+## Changes
+- Create safeTask wrapper function
+- Replace direct Task calls
+- Add error logging to state
+
+## Verification
+- [ ] Simulate agent failure
+- [ ] Verify graceful error handling
+- [ ] Check retry logic
+```

package/.agents/skills/team-arch-opt/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: team-arch-opt
+description: Unified team skill for architecture optimization. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team arch-opt".
+allowed-tools: delegate_subagent, create_task, list_tasks, get_task, update_task, create_team, delete_team, send_message, ask_user, read_file, write_file, edit_file, shell, find_files, 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 Architecture Optimization
+
+Orchestrate multi-agent architecture optimization: analyze codebase → design refactoring plan → implement changes → validate improvements → review code quality.
+
+## Architecture
+
+```
+invoke_skill(skill="team-arch-opt", 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       v
+                 [analyzer][designer][refactorer][validator][reviewer]
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false |
+| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
+| refactorer | [roles/refactorer/role.md](roles/refactorer/role.md) | REFACTOR-*, FIX-* | true |
+| validator | [roles/validator/role.md](roles/validator/role.md) | VALIDATE-* | false |
+| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-* | false |
+
+
+## Pre-load (coordinator, before dispatch)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for module boundaries
+2. **Specs (arch)**: `maestro spec load --category arch` — load arch constraints as shared context
+3. **Specs (coding)**: `maestro spec load --category coding` — load coding constraints as shared context
+4. **Wiki knowledge**: `maestro search "architecture optimization refactor" --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**: `TAO`
+- **Session path**: `.workflow/.team/TAO-<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: "arch-opt",
+  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: arch-opt
+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).`
+})
+```
+
+**Inner Loop roles** (refactorer): Set `inner_loop` dynamically — `true` for single mode, `false` for fan-out/independent (parallel branches).
+**Single-task roles** (analyzer, designer, validator, reviewer): Set `inner_loop: false`.
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph (branch-grouped), no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task + cascade downstream |
+| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
+| `recheck` | Re-run quality check |
+| `improve [dimension]` | Auto-improve weakest dimension |
+
+## Session Directory
+
+```
+.workflow/.team/TAO-<slug>-<date>/
+├── session.json                    # Session metadata + status + parallel_mode
+├── task-analysis.json              # Coordinator analyze output
+├── artifacts/
+│   ├── architecture-baseline.json  # Analyzer: pre-refactoring metrics
+│   ├── architecture-report.md      # Analyzer: ranked structural issue findings
+│   ├── refactoring-plan.md         # Designer: prioritized refactoring plan
+│   ├── validation-results.json     # Validator: post-refactoring validation
+│   ├── review-report.md            # Reviewer: code review findings
+│   ├── aggregate-results.json      # Fan-out/independent: aggregated results
+│   ├── branches/                   # Fan-out mode branch artifacts
+│   │   └── B{NN}/
+│   │       ├── refactoring-detail.md
+│   │       ├── validation-results.json
+│   │       └── review-report.md
+│   └── pipelines/                  # Independent mode pipeline artifacts
+│       └── {P}/
+│           └── ...
+├── explorations/
+│   ├── cache-index.json            # Shared explore cache
+│   └── <hash>.md
+├── wisdom/
+│   └── patterns.md                 # Discovered patterns and conventions
+├── discussions/
+│   ├── DISCUSS-REFACTOR.md
+│   └── DISCUSS-REVIEW.md
+└── .msg/
+    ├── messages.jsonl              # Message bus log
+    └── meta.json                   # Session state + cross-role state
+```
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task registry, parallel modes
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| CLI tool fails | Worker fallback to direct implementation |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| consensus_blocked HIGH | Coordinator creates revision task or pauses pipeline |
+| Branch fix cycle >= 3 | Escalate only that branch to user, others continue |
+| max_branches exceeded | Coordinator truncates to top N at CP-2.5 |

package/.agents/skills/team-arch-opt/roles/analyzer/role.md

@@ -0,0 +1,88 @@
+---
+role: analyzer
+prefix: ANALYZE
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Architecture Analyzer
+
+Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type by scanning for framework markers:
+
+| Signal File | Project Type | Analysis Focus |
+|-------------|-------------|----------------|
+| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
+| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
+| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
+| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
+| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
+| No detection | Generic | All architecture dimensions |
+
+3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
+4. Detect available analysis tools (linters, dependency analyzers, build tools)
+
+## Phase 3: Architecture Analysis
+
+Execute analysis based on detected project type:
+
+**Dependency analysis**:
+- Build import/require graph across modules
+- Detect circular dependencies (direct and transitive cycles)
+- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
+- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
+
+**Structural analysis**:
+- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
+- Calculate coupling metrics (afferent/efferent coupling per module)
+- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
+- Detect code duplication (repeated logic blocks, copy-paste patterns)
+- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
+
+**API surface analysis**:
+- Count exported symbols per module (export bloat detection)
+- Identify dead exports (exported but never imported elsewhere)
+- Detect dead code (unreachable functions, unused variables, orphan files)
+- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
+
+**All project types**:
+- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
+- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
+- Record evidence: file paths, line numbers, measured values
+
+### Tech Profile Scan
+
+After analysis, scan findings for context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check dependency analysis → signals (`sql_detected`, `auth_detected`, `ml_detected`)
+2. Check structural analysis → risk signals (`perf_sensitive`, `legacy_patterns`, `scaling_concern`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## Phase 4: Report Generation
+
+1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
+   - Module count, dependency count, cycle count, average coupling, average cohesion
+   - God Class candidates with LOC and method count
+   - Dead code file count, dead export count
+   - Timestamp and project type details
+
+2. Write architecture report to `<session>/artifacts/architecture-report.md`:
+   - Ranked list of architecture issues with severity, location (file:line or module), measured impact
+   - Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
+   - Evidence summary per issue
+   - Detected project type and analysis methods used
+
+3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
+   - Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back

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

@@ -0,0 +1,57 @@
+# Analyze Task
+
+Parse user task -> detect architecture capabilities -> build dependency graph -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| analyze, scan, audit, map, identify | analyzer | ANALYZE |
+| design, plan, strategy, refactoring-plan | designer | DESIGN |
+| refactor, implement, fix, apply | refactorer | REFACTOR |
+| validate, build, test, verify, compile | validator | VALIDATE |
+| review, audit-code, quality, check-code | reviewer | REVIEW |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: analyzer (knowledge gathering -- no dependencies)
+- Tier 1: designer (requires analyzer output)
+- Tier 2: refactorer (requires designer output)
+- Tier 3: validator, reviewer (validation requires refactored artifacts, can run in parallel)
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Per capability | +1 |
+| Cross-domain refactoring | +2 |
+| Parallel branches requested | +1 per branch |
+| Serial depth > 3 | +1 |
+| Multiple targets (independent mode) | +2 |
+
+Results: 1-3 Low, 4-6 Medium, 7+ High
+
+## Role Minimization
+
+- Cap at 5 roles
+- Merge overlapping capabilities
+- Absorb trivial single-step roles
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<single|fan-out|independent|auto>",
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "parallel_mode": "<auto|single|fan-out|independent>",
+  "max_branches": 5
+}
+```