maestro-flow 0.3.38 → 0.3.40

package/.codex/skills/team-tech-debt/SKILL.md

@@ -1,143 +1,144 @@
----
-name: team-tech-debt
-description: Unified team skill for tech debt identification and remediation. Scans codebase for tech debt, assesses severity, plans and executes fixes with validation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team tech debt".
-allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__maestro-tools__read_file(*), mcp__maestro-tools__write_file(*), mcp__maestro-tools__edit_file(*), mcp__maestro-tools__team_msg(*)
----
-
-<purpose>
-Systematic tech debt governance: scan -> assess -> plan -> fix -> validate. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
-
-```
-Skill(skill="team-tech-debt", 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
-           [team-worker agents, each loads roles/<role>/role.md]
-          scanner  assessor  planner  executor  validator
-```
-</purpose>
-
-<context>
-$ARGUMENTS — task description and optional flags.
-
-**Role Router:**
-- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → `roles/coordinator/role.md`, execute entry router
-
-**Role Registry:**
-| Role | Path | Prefix | Inner Loop |
-|------|------|--------|------------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
-| scanner | [roles/scanner/role.md](roles/scanner/role.md) | TDSCAN-* | false |
-| assessor | [roles/assessor/role.md](roles/assessor/role.md) | TDEVAL-* | false |
-| planner | [roles/planner/role.md](roles/planner/role.md) | TDPLAN-* | false |
-| executor | [roles/executor/role.md](roles/executor/role.md) | TDFIX-* | true |
-| validator | [roles/validator/role.md](roles/validator/role.md) | TDVAL-* | false |
-
-**User Commands:**
-| Command | Action |
-|---------|--------|
-| `check` / `status` | View execution status graph |
-| `resume` / `continue` | Advance to next step |
-| `--mode=scan` | Scan-only pipeline (TDSCAN + TDEVAL) |
-| `--mode=targeted` | Targeted pipeline (TDPLAN + TDFIX + TDVAL) |
-| `--mode=remediate` | Full pipeline (default) |
-| `-y` / `--yes` | Skip confirmations |
-
-**Delegation Lock — Coordinator is PURE ORCHESTRATOR:**
-| Tool Call | Verdict | Reason |
-|-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
-| `list_agents`, `request_user_input`, `mcp__maestro-tools__team_msg` | ALLOWED | Coordination |
-| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
-| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading instructions |
-| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
-| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
-| `Bash` running build/test/lint | BLOCKED | Delegate to worker |
-
-**No exceptions.** Even single-file tasks MUST go through spawn_agent.
-
-**Shared Constants:**
-- Session prefix: `TD`
-- Session path: `.workflow/.team/TD-<slug>-<date>/`
-- CLI tools: `maestro delegate --mode analysis|write`
-- Max GC rounds: 3
-
-**Specs:** [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
-
-**Session Directory:**
-```
-.workflow/.team/TD-<slug>-<date>/
-├── .msg/            # Team message bus
-├── scan/            # Scanner output
-├── assessment/      # Assessor output
-├── plan/            # Planner output
-├── fixes/           # Executor output
-├── validation/      # Validator output
-└── wisdom/          # Cross-task knowledge
-```
-</context>
-
-<invariants>
-1. **Coordinator never executes domain work** — only orchestrates via spawn_agent
-2. **Scanner results inform downstream** — each stage narrows and refines
-3. **Pipeline flow**: TDSCAN → TDEVAL → TDPLAN → TDFIX → TDVAL
-</invariants>
-
-<execution>
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent. Message includes: role, role_spec path, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> close.
-
-### Model Selection Guide
-
-| Role | reasoning_effort |
-|------|-------------------|
-| scanner | medium |
-| assessor | high |
-| planner | high |
-| executor | high |
-| validator | medium |
-
-### v4 Agent Coordination
-
-**Message Semantics**: `send_message` for supplementary info to downstream. `followup_task` to assign fixes from planner output. `list_agents` for health checks.
-
-**Agent Health Check**: Reconcile `meta.json` active tasks with `list_agents({})`. Reset orphaned tasks to pending.
-
-**Named Targeting**: `send_message({ target: "TDSCAN-001" })`, `followup_task({ target: "TDFIX-001" })`, `close_agent({ target: "TDVAL-001" })`.
-</execution>
-
-<error_codes>
-| Scenario | Resolution |
-|----------|------------|
-| Unknown command | Error with available command list |
-| Role not found | Error with role registry |
-| Session corruption | Attempt recovery, fallback to manual |
-| Fast-advance conflict | Coordinator reconciles on next callback |
-| Completion action fails | Default to Keep Active |
-| Scanner finds no debt | Report clean codebase, skip to summary |
-</error_codes>
-
-<success_criteria>
-- [ ] Role routing correct (coordinator vs worker)
-- [ ] Delegation lock enforced (coordinator never executes domain work)
-- [ ] Pipeline stages execute in order (scan → assess → plan → fix → validate)
-- [ ] Worker spawn uses correct template with role-spec paths
-- [ ] Timeout handling applied (STATUS_CHECK → FINALIZE → close)
-- [ ] Scanner results flow through downstream stages
-- [ ] Session directory structure maintained
-- [ ] Completion action presented to user
-</success_criteria>
+---
+name: team-tech-debt
+description: Team tech debt identification and remediation
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__maestro-tools__read_file(*), mcp__maestro-tools__write_file(*), mcp__maestro-tools__edit_file(*), mcp__maestro-tools__team_msg(*)
+---
+
+<purpose>
+Systematic tech debt governance: scan -> assess -> plan -> fix -> validate. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
+
+```
+Skill(skill="team-tech-debt", 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
+           [team-worker agents, each loads roles/<role>/role.md]
+          scanner  assessor  planner  executor  validator
+```
+
+</purpose>
+
+<context>
+$ARGUMENTS — task description and optional flags.
+
+**Role Router:**
+- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` → `roles/coordinator/role.md`, execute entry router
+
+**Role Registry:**
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| scanner | [roles/scanner/role.md](roles/scanner/role.md) | TDSCAN-* | false |
+| assessor | [roles/assessor/role.md](roles/assessor/role.md) | TDEVAL-* | false |
+| planner | [roles/planner/role.md](roles/planner/role.md) | TDPLAN-* | false |
+| executor | [roles/executor/role.md](roles/executor/role.md) | TDFIX-* | true |
+| validator | [roles/validator/role.md](roles/validator/role.md) | TDVAL-* | false |
+
+**User Commands:**
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `--mode=scan` | Scan-only pipeline (TDSCAN + TDEVAL) |
+| `--mode=targeted` | Targeted pipeline (TDPLAN + TDFIX + TDVAL) |
+| `--mode=remediate` | Full pipeline (default) |
+| `-y` / `--yes` | Skip confirmations |
+
+**Delegation Lock — Coordinator is PURE ORCHESTRATOR:**
+| Tool Call | Verdict | Reason |
+|-----------|---------|--------|
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
+| `list_agents`, `request_user_input`, `mcp__maestro-tools__team_msg` | ALLOWED | Coordination |
+| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
+| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading instructions |
+| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
+| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
+| `Bash` running build/test/lint | BLOCKED | Delegate to worker |
+
+**No exceptions.** Even single-file tasks MUST go through spawn_agent.
+
+**Shared Constants:**
+- Session prefix: `TD`
+- Session path: `.workflow/.team/TD-<slug>-<date>/`
+- CLI tools: `maestro delegate --mode analysis|write`
+- Max GC rounds: 3
+
+**Specs:** [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+**Session Directory:**
+```
+.workflow/.team/TD-<slug>-<date>/
+├── .msg/            # Team message bus
+├── scan/            # Scanner output
+├── assessment/      # Assessor output
+├── plan/            # Planner output
+├── fixes/           # Executor output
+├── validation/      # Validator output
+└── wisdom/          # Cross-task knowledge
+```
+</context>
+
+<invariants>
+1. **Coordinator never executes domain work** — only orchestrates via spawn_agent
+2. **Scanner results inform downstream** — each stage narrows and refines
+3. **Pipeline flow**: TDSCAN → TDEVAL → TDPLAN → TDFIX → TDVAL
+</invariants>
+
+<execution>
+
+### Worker Spawn Template
+
+Spawn via `team-worker` agent. Message includes: role, role_spec path, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> close.
+
+### Model Selection Guide
+
+| Role | reasoning_effort |
+|------|-------------------|
+| scanner | medium |
+| assessor | high |
+| planner | high |
+| executor | high |
+| validator | medium |
+
+### v4 Agent Coordination
+
+**Message Semantics**: `send_message` for supplementary info to downstream. `followup_task` to assign fixes from planner output. `list_agents` for health checks.
+
+**Agent Health Check**: Reconcile `meta.json` active tasks with `list_agents({})`. Reset orphaned tasks to pending.
+
+**Named Targeting**: `send_message({ target: "TDSCAN-001" })`, `followup_task({ target: "TDFIX-001" })`, `close_agent({ target: "TDVAL-001" })`.
+</execution>
+
+<error_codes>
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| Scanner finds no debt | Report clean codebase, skip to summary |
+</error_codes>
+
+<success_criteria>
+- [ ] Role routing correct (coordinator vs worker)
+- [ ] Delegation lock enforced (coordinator never executes domain work)
+- [ ] Pipeline stages execute in order (scan → assess → plan → fix → validate)
+- [ ] Worker spawn uses correct template with role-spec paths
+- [ ] Timeout handling applied (STATUS_CHECK → FINALIZE → close)
+- [ ] Scanner results flow through downstream stages
+- [ ] Session directory structure maintained
+- [ ] Completion action presented to user
+</success_criteria>

package/.codex/skills/team-tech-debt/roles/executor/role.md

@@ -36,19 +36,23 @@ For each batch, use CLI tool for implementation:
 
 **Per-batch delegation**:
 
-```bash
-maestro delegate "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
+```
+exec_command({
+  cmd: `maestro delegate "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
 TASK: <batch-type-specific-tasks>
 MODE: write
 CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
 EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
 CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
 Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
-Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
+Items: <list-of-items-with-file-paths-and-descriptions>" --role implement --mode write --cd "<worktree-path>"`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — must wait for batch fix to complete before next batch or validation
 ```
 
-Wait for CLI completion before proceeding to next batch.
-
 **Fix Results Tracking**:
 
 | Field | Description |

package/.codex/skills/team-tech-debt/roles/scanner/role.md

@@ -61,6 +61,16 @@ Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, arch
 - Fan-out C (High only): Multi-perspective analysis (security, performance, code-quality, architecture) via `--role analyze`
 - Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
 
+**Delegate execution protocol** (applies to ALL fan-out CLI calls):
+```
+exec_command({
+  cmd: `maestro delegate "<prompt>" --role <role> --mode analysis`,
+  yield_time_ms: 30000, max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — each fan-out result is required for fan-in merge
+```
+
 **Standardize each finding**:
 
 | Field | Description |

package/.codex/skills/team-tech-debt/roles/validator/role.md

@@ -58,12 +58,18 @@ Execute 4-layer validation (all commands in worktree):
 **Auto-fix attempt** (when total_regressions <= 3):
 - Use CLI tool to fix regressions in worktree:
   ```
-  Bash(`cd "${worktreePath}" && maestro delegate "PURPOSE: Fix regressions found in validation
+  exec_command({
+    cmd: `cd "${worktreePath}" && maestro delegate "PURPOSE: Fix regressions found in validation
   TASK: ${regressionDetails}
   MODE: write
   CONTEXT: @${modifiedFiles.join(' @')}
   EXPECTED: Fixed regressions
-  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`)
+  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --role implement --mode write`,
+    yield_time_ms: 30000,
+    max_output_tokens: 6000
+  })
+  // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+  // NEVER skip — must wait for fix before re-running validation
   ```
 - Re-run validation checks after fix attempt
 

package/.codex/skills/team-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: team-testing
-description: Unified team skill for testing team. Progressive test coverage through Generator-Critic loops, shared memory, and dynamic layer selection. Triggers on "team testing".
+description: Team testing with progressive coverage and generator-critic loops
 allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
 ---
 
@@ -26,6 +26,7 @@ Skill(skill="team-testing", args="task description")
                 [strat] [gen]  [exec]  [analyst]
                 team-worker agents, each loads roles/<role>/role.md
 ```
+
 </purpose>
 
 <context>

package/.codex/skills/team-testing/roles/executor/role.md

@@ -61,14 +61,20 @@ Bash("<test-command> 2>&1 || true")
 **Auto-fix delegation** (on failure):
 
 ```
-Bash(`maestro delegate "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
+exec_command({
+  cmd: `maestro delegate "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
 TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent
 MODE: write
 CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3
 EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage
 CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes
 Test failures:
-<test-output>" --tool gemini --mode write --cd <session>`)
+<test-output>" --role implement --mode write --cd <session>`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — must wait for fix to complete before re-running tests
 ```
 
 **Save results**: `<session>/results/run-<N>.json`

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

@@ -63,7 +63,8 @@ For revision mode:
 **CLI delegation** (medium/high complexity):
 
 ```
-Bash(`maestro delegate "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
+exec_command({
+  cmd: `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>
@@ -72,7 +73,12 @@ 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>`)
+<file-list-with-content>" --role implement --mode write --cd <session>`,
+  yield_time_ms: 30000,
+  max_output_tokens: 6000
+})
+// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+// NEVER skip — must wait for test files to be generated before verification
 ```
 
 **Output verification**:

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

@@ -1,73 +1,73 @@
----
-name: wiki-connect
-description: Wiki knowledge graph link discovery and health improvement. Finds orphaned entries, missing connections, transitive gaps. Scores candidates and optionally auto-applies new related links via --fix.
-argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Knowledge graph link discovery. Analyzes wiki index to find orphaned entries, missing
-bidirectional links, and transitive closure gaps. Scores connection candidates and
-optionally auto-applies new `related` links to improve graph connectivity.
-</purpose>
-
-<context>
-$ARGUMENTS — optional flags.
-
-**Flags:**
-- `--scope <type>` — Limit to wiki type (spec, knowhow, note, lesson, issue). Default: all.
-- `--min-similarity N` — Threshold 0.0-1.0 (default: 0.3)
-- `--fix` — Auto-apply top suggestions
-- `--max N` — Max suggestions (default: 20)
-
-**Output**: `.workflow/learning/wiki-connections-{date}.md`
-</context>
-
-<execution>
-
-### Stage 1: Load Wiki State
-Parallel `maestro wiki` commands: `list --json`, `health`, `orphans`, `hubs --top 10`.
-
-### Stage 2: Identify Connection Candidates
-- **Orphan rescue**: BM25 search by title, tag overlap, same category/parent
-- **Missing bidirectional**: A→B exists but B→A missing
-- **Transitive closure**: A→B and B→C but no A→C (with shared tags/category)
-- **Type bridge**: Different types referencing same concept but unlinked
-- **Parent cluster**: Entries sharing the same parent but not linked to each other
-
-### Stage 3: Score Candidates
-Score = 0.4 x tag_overlap + 0.3 x title_bm25 + 0.2 x same_category + 0.1 x type_bridge. Filter by `--min-similarity`, rank desc, limit by `--max`.
-
-### Stage 4: Present Suggestions
-Display ranked suggestions with scores, reasons, projected health delta.
-If not `--fix`: display and exit.
-
-### Stage 5: Apply (--fix only)
-For each suggestion: get entry → append target to `related` → update via `maestro wiki update`.
-Re-run `maestro wiki health` for delta.
-
-### Stage 6: Persist
-Write `wiki-connections-{date}.md`. Append graph insights to `lessons.jsonl` (source: "wiki-connect").
-
-**Next steps:** `/wiki-digest <topic>`, `/manage-wiki health`, `/learn-follow <wiki-id>`, `maestro wiki graph`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No wiki entries found | Initialize wiki content |
-| W001 | warning | No candidates above threshold | Lower --min-similarity |
-| W002 | warning | Some wiki updates failed during --fix | Retry manually |
-| W003 | warning | Health score unchanged after fix | Connections may not affect specific metrics |
-</error_codes>
-
-<success_criteria>
-- [ ] Wiki index loaded with type distribution
-- [ ] Baseline health score recorded
-- [ ] Orphans identified and rescue candidates generated
-- [ ] Candidates scored and ranked
-- [ ] Suggestions displayed with scores and reasons
-- [ ] If --fix: entries updated, new health score reported
-- [ ] Report written to `wiki-connections-{date}.md`
-- [ ] Graph insights appended to `lessons.jsonl`
-</success_criteria>
+---
+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, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Knowledge graph link discovery. Analyzes wiki index to find orphaned entries, missing
+bidirectional links, and transitive closure gaps. Scores connection candidates and
+optionally auto-applies new `related` links to improve graph connectivity.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--scope <type>` — Limit to wiki type (spec, knowhow, note, lesson, issue). Default: all.
+- `--min-similarity N` — Threshold 0.0-1.0 (default: 0.3)
+- `--fix` — Auto-apply top suggestions
+- `--max N` — Max suggestions (default: 20)
+
+**Output**: `.workflow/learning/wiki-connections-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Load Wiki State
+Parallel `maestro wiki` commands: `list --json`, `health`, `orphans`, `hubs --top 10`.
+
+### Stage 2: Identify Connection Candidates
+- **Orphan rescue**: BM25 search by title, tag overlap, same category/parent
+- **Missing bidirectional**: A→B exists but B→A missing
+- **Transitive closure**: A→B and B→C but no A→C (with shared tags/category)
+- **Type bridge**: Different types referencing same concept but unlinked
+- **Parent cluster**: Entries sharing the same parent but not linked to each other
+
+### Stage 3: Score Candidates
+Score = 0.4 x tag_overlap + 0.3 x title_bm25 + 0.2 x same_category + 0.1 x type_bridge. Filter by `--min-similarity`, rank desc, limit by `--max`.
+
+### Stage 4: Present Suggestions
+Display ranked suggestions with scores, reasons, projected health delta.
+If not `--fix`: display and exit.
+
+### Stage 5: Apply (--fix only)
+For each suggestion: get entry → append target to `related` → update via `maestro wiki update`.
+Re-run `maestro wiki health` for delta.
+
+### Stage 6: Persist
+Write `wiki-connections-{date}.md`. Append graph insights to `lessons.jsonl` (source: "wiki-connect").
+
+**Next steps:** `/wiki-digest <topic>`, `/manage-wiki health`, `/learn-follow <wiki-id>`, `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found | Initialize wiki content |
+| W001 | warning | No candidates above threshold | Lower --min-similarity |
+| W002 | warning | Some wiki updates failed during --fix | Retry manually |
+| W003 | warning | Health score unchanged after fix | Connections may not affect specific metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Candidates scored and ranked
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated, new health score reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `lessons.jsonl`
+</success_criteria>