maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/team-testing/roles/generator/role.md

@@ -0,0 +1,100 @@
+---
+role: generator
+prefix: TESTGEN
+inner_loop: true
+message_types:
+  success: tests_generated
+  revision: tests_revised
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Test Generator
+
+Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Generator in the Generator-Critic loop. Supports revision mode for GC loop iterations.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Test strategy | <session>/strategy/test-strategy.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and layer from task description
+2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets
+3. Read test strategy:
+
+```
+read_file("<session>/strategy/test-strategy.md")
+```
+
+3. Read source files to test (from strategy priority_files, limit 20)
+4. Read .msg/meta.json for framework and scope context
+
+5. Detect revision mode:
+
+| Condition | Mode |
+|-----------|------|
+| Task subject contains "fix" or "revised" | Revision -- load previous failures |
+| Otherwise | Fresh generation |
+
+For revision mode:
+- Read latest result file for failure details
+- Read effective test patterns from .msg/meta.json
+
+6. Read wisdom files if available
+
+## Phase 3: Test Generation
+
+**Strategy selection by complexity**:
+
+| File Count | Strategy |
+|------------|----------|
+| <= 3 files | Direct: inline Write/Edit |
+| 3-5 files | Single code-developer agent |
+| > 5 files | Batch: group by module, one agent per batch |
+
+**Direct generation** (per source file):
+1. Generate test path: `<session>/tests/<layer>/<test-file>`
+2. Generate test code: happy path, edge cases, error handling
+3. Write test file
+
+**CLI delegation** (medium/high complexity):
+
+```
+shell({
+  command: `maestro delegate "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
+TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution
+MODE: write
+CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round>
+<if-revision: Previous failures: <failure-details>
+Effective patterns: <patterns-from-meta>>
+EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions
+CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions
+Source files to test:
+<file-list-with-content>" --tool gemini --mode write --cd <session>`,
+  run_in_background: false
+})
+```
+
+**Output verification**:
+
+```
+find_files("<session>/tests/<layer>/**/*")
+```
+
+## Phase 4: Self-Validation & State Update
+
+**Validation checks**:
+
+| Check | Method | Action on Fail |
+|-------|--------|----------------|
+| Syntax | `tsc --noEmit` or equivalent | Auto-fix imports/types |
+| File count | Count generated files | Report issue |
+| Import resolution | Check broken imports | Fix import paths |
+
+Update `<session>/wisdom/.msg/meta.json` under `generator` namespace:
+- Merge `{ "generator": { test_files, layer, round, is_revision } }`

package/.agents/skills/team-testing/roles/strategist/role.md

@@ -0,0 +1,85 @@
+---
+role: strategist
+prefix: STRATEGY
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Test Strategist
+
+Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
+
+## 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 scope from task description
+2. Get git diff for change analysis:
+
+```
+shell("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
+shell("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
+```
+
+3. Detect test framework from project files:
+
+| Signal File | Framework | Test Pattern |
+|-------------|-----------|-------------|
+| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
+| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
+| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
+| No detection | Default | Jest patterns |
+
+4. Scan existing test patterns:
+
+```
+find_files("**/*.test.*")
+find_files("**/*.spec.*")
+```
+
+5. Read .msg/meta.json if exists for session context
+
+## Phase 3: Strategy Formulation
+
+**Change analysis dimensions**:
+
+| Change Type | Analysis | Priority |
+|-------------|----------|----------|
+| New files | Need new tests | High |
+| Modified functions | Need updated tests | Medium |
+| Deleted files | Need test cleanup | Low |
+| Config changes | May need integration tests | Variable |
+
+**Strategy output structure**:
+
+1. **Change Analysis Table**: File, Change Type, Impact, Priority
+2. **Test Layer Recommendations**:
+   - L1 Unit: Scope, Coverage Target, Priority Files, Patterns
+   - L2 Integration: Scope, Coverage Target, Integration Points
+   - L3 E2E: Scope, Coverage Target, User Scenarios
+3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
+4. **Test Execution Order**: Prioritized sequence
+
+Write strategy to `<session>/strategy/test-strategy.md`
+
+**Self-validation**:
+
+| Check | Criteria | Fallback |
+|-------|----------|----------|
+| Has L1 scope | L1 scope not empty | Default to all changed files |
+| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
+| Has priority files | List not empty | Use all changed files |
+
+## Phase 4: Wisdom & State Update
+
+1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
+2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
+   - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back

package/.agents/skills/team-testing/specs/pipelines.md

@@ -0,0 +1,101 @@
+# Testing Pipelines
+
+Pipeline definitions and task registry for team-testing.
+
+## Pipeline Selection
+
+| Condition | Pipeline |
+|-----------|----------|
+| fileCount <= 3 AND moduleCount <= 1 | targeted |
+| fileCount <= 10 AND moduleCount <= 3 | standard |
+| Otherwise | comprehensive |
+
+## Pipeline Definitions
+
+### Targeted Pipeline (3 tasks, serial)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+
+### Standard Pipeline (6 tasks, progressive layers)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001 -> TESTGEN-002 -> TESTRUN-002 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+| TESTGEN-002 | generator | TESTRUN-001 | L2 | Generate L2 integration tests |
+| TESTRUN-002 | executor | TESTGEN-002 | L2 | Execute L2 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-002 | — | Defect pattern analysis, quality report |
+
+### Comprehensive Pipeline (8 tasks, parallel windows)
+
+```
+STRATEGY-001 -> [TESTGEN-001 || TESTGEN-002] -> [TESTRUN-001 || TESTRUN-002] -> TESTGEN-003 -> TESTRUN-003 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator-1 | STRATEGY-001 | L1 | Generate L1 unit tests (parallel) |
+| TESTGEN-002 | generator-2 | STRATEGY-001 | L2 | Generate L2 integration tests (parallel) |
+| TESTRUN-001 | executor-1 | TESTGEN-001 | L1 | Execute L1 tests (parallel) |
+| TESTRUN-002 | executor-2 | TESTGEN-002 | L2 | Execute L2 tests (parallel) |
+| TESTGEN-003 | generator | TESTRUN-001, TESTRUN-002 | L3 | Generate L3 E2E tests |
+| TESTRUN-003 | executor | TESTGEN-003 | L3 | Execute L3 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-003 | — | Defect pattern analysis, quality report |
+
+## GC Loop (Generator-Critic)
+
+Generator and executor iterate per test layer:
+
+```
+TESTGEN -> TESTRUN -> (if pass_rate < 0.95 OR coverage < target) -> TESTGEN-fix -> TESTRUN-fix
+                      (if pass_rate >= 0.95 AND coverage >= target) -> next layer or TESTANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current state with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Session Directory
+
+```
+.workflow/.team/TST-<slug>-<YYYY-MM-DD>/
+├── .msg/messages.jsonl          # Message bus log
+├── .msg/meta.json               # Session metadata
+├── wisdom/                     # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── strategy/                   # Strategist output
+│   └── test-strategy.md
+├── tests/                      # Generator output
+│   ├── L1-unit/
+│   ├── L2-integration/
+│   └── L3-e2e/
+├── results/                    # Executor output
+│   ├── run-001.json
+│   └── coverage-001.json
+└── analysis/                   # Analyst output
+    └── quality-report.md
+```

package/.agents/skills/team-testing/specs/team-config.json

@@ -0,0 +1,93 @@
+{
+  "team_name": "team-testing",
+  "team_display_name": "Team Testing",
+  "description": "Testing team with Generator-Critic loop, shared defect memory, and progressive test layers",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Change scope analysis, layer selection, quality gating",
+      "message_types": ["pipeline_selected", "gc_loop_trigger", "quality_gate", "task_unblocked", "error", "shutdown"]
+    },
+    "strategist": {
+      "task_prefix": "STRATEGY",
+      "responsibility": "Analyze git diff, determine test layers, define coverage targets",
+      "message_types": ["strategy_ready", "error"]
+    },
+    "generator": {
+      "task_prefix": "TESTGEN",
+      "responsibility": "Generate test cases by layer (unit/integration/E2E)",
+      "message_types": ["tests_generated", "tests_revised", "error"]
+    },
+    "executor": {
+      "task_prefix": "TESTRUN",
+      "responsibility": "Execute tests, collect coverage, auto-fix failures",
+      "message_types": ["tests_passed", "tests_failed", "coverage_report", "error"]
+    },
+    "analyst": {
+      "task_prefix": "TESTANA",
+      "responsibility": "Defect pattern analysis, coverage gap analysis, quality report",
+      "message_types": ["analysis_ready", "error"]
+    }
+  },
+
+  "pipelines": {
+    "targeted": {
+      "description": "Small scope: strategy → generate L1 → run",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001"],
+      "gc_loops": 0
+    },
+    "standard": {
+      "description": "Progressive: L1 → L2 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTRUN-001", "TESTGEN-002", "TESTRUN-002", "TESTANA-001"],
+      "gc_loops": 1
+    },
+    "comprehensive": {
+      "description": "Full coverage: parallel L1+L2, then L3 with analysis",
+      "task_chain": ["STRATEGY-001", "TESTGEN-001", "TESTGEN-002", "TESTRUN-001", "TESTRUN-002", "TESTGEN-003", "TESTRUN-003", "TESTANA-001"],
+      "gc_loops": 2,
+      "parallel_groups": [["TESTGEN-001", "TESTGEN-002"], ["TESTRUN-001", "TESTRUN-002"]]
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "generator",
+      "critic": "executor",
+      "max_rounds": 3,
+      "convergence_trigger": "coverage >= target && pass_rate >= 0.95"
+    },
+    "shared_memory": {
+      "file": "shared-memory.json",
+      "fields": {
+        "strategist": "test_strategy",
+        "generator": "generated_tests",
+        "executor": "execution_results",
+        "analyst": "analysis_report"
+      },
+      "persistent_fields": ["defect_patterns", "effective_test_patterns", "coverage_history"]
+    },
+    "dynamic_pipeline": {
+      "selector": "coordinator",
+      "criteria": "changed_file_count + module_count + change_type"
+    }
+  },
+
+  "test_layers": {
+    "L1": { "name": "Unit Tests", "coverage_target": 80, "description": "Function-level isolation tests" },
+    "L2": { "name": "Integration Tests", "coverage_target": 60, "description": "Module interaction tests" },
+    "L3": { "name": "E2E Tests", "coverage_target": 40, "description": "User scenario end-to-end tests" }
+  },
+
+  "collaboration_patterns": ["CP-1", "CP-3", "CP-5"],
+
+  "session_dirs": {
+    "base": ".workflow/.team/TST-{slug}-{YYYY-MM-DD}/",
+    "strategy": "strategy/",
+    "tests": "tests/",
+    "results": "results/",
+    "analysis": "analysis/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}

package/.agents/skills/wiki-connect/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: wiki-connect
+description: Find and link hidden connections in wiki graph
+argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<required_reading>
+@~/.maestro/workflows/wiki-connect.md
+</required_reading>
+
+<purpose>
+Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
+
+Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, health scoring) — no equivalent in gstack. Directly improves the quality of all downstream wiki consumers (search, digest, follow-along).
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, storage paths, and CLI commands defined in workflow wiki-connect.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
+
+**Next-step routing:**
+- Generate knowledge digest → `/wiki-digest <topic>`
+- Follow-along on orphan → `/learn-follow <wiki-id>`
+- View full graph → `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `/maestro-init` |
+| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
+| W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
+| W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |
+| W003 | warning | Health score unchanged after fix | Connections may not have improved the specific health metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with entry count and type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Connection candidates scored and ranked
+- [ ] Results filtered by --min-similarity and limited by --max
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated with new `related` links
+- [ ] If --fix: new health score computed and delta reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No unintended entry modifications (only `related` field changed)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.agents/skills/wiki-digest/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: wiki-digest
+description: Generate wiki digest with theme clustering and gap analysis
+argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Knowledge synthesis command that generates actionable digests from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage heatmap. Unique to maestro — leverages the wiki graph (BM25 search, backlinks, health) to surface trends and missing knowledge.
+
+Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-digest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
+
+**Next-step routing:**
+- Deep dive on a theme → `/learn-follow <wiki-id>`
+- Fix graph gaps → `/wiki-connect --fix`
+- Decompose code for missing patterns → `/learn-decompose <path>`
+- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
+- Triage gap issues → `/manage-issue list --source wiki-digest`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
+| E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
+| W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
+| W002 | warning | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow context |
+| W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope parsed and entries loaded
+- [ ] Baseline health score recorded
+- [ ] Entries clustered into 3-5 semantic themes
+- [ ] Per-theme analysis: summary, key entries, gaps, health
+- [ ] Cross-reference with specs/learnings.md completed
+- [ ] Coverage heatmap generated (type × theme matrix)
+- [ ] Knowledge gaps identified with suggested actions
+- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
+- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
+- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
+- [ ] Summary displayed with key findings and next-step routing
+</success_criteria>