maestro-flow 0.5.3 → 0.5.31

package/workflows/wiki-manage.md

@@ -1,109 +1,109 @@
-# Wiki Manage Workflow
-
-Unified wiki knowledge graph management — health monitoring, interactive search, orphan cleanup, and graph statistics.
-
-Complements `wiki-connect.md` (link discovery) and `wiki-digest.md` (synthesis) with day-to-day operational tooling.
-
----
-
-## Prerequisites
-
-- `.workflow/` initialized
-- Wiki entries exist
-- `maestro wiki` CLI available
-
----
-
-## Argument Shape
-
-```
-/manage-wiki                                   → health dashboard (default)
-/manage-wiki health                            → health dashboard
-/manage-wiki search auth                       → search for "auth" with follow-up actions
-/manage-wiki cleanup                           → find orphans, broken links, stale entries
-/manage-wiki cleanup --fix                     → auto-fix issues
-/manage-wiki stats                             → graph statistics
-/manage-wiki stats --type spec                 → spec-only statistics
-```
-
-| Flag | Effect |
-|------|--------|
-| `--type <type>` | Filter: spec, knowhow, note, issue |
-| `--fix` | Auto-fix issues during cleanup |
-| `--json` | JSON output |
-
----
-
-## Subcommand: health (default)
-
-### Step 1: Gather Data
-
-Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`.
-
-### Step 2: Render Dashboard
-
-Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
-
-> **Scope split (complementary, not conflicting):** `/wiki-connect --fix` repairs/augments `related` links between existing entries (no deletion). `/manage-wiki cleanup --fix` deletes/flags orphans and removes broken-link entries from frontmatter. Run `wiki-connect` first to maximize link recovery, then `cleanup` to handle the true residual orphans.
-
----
-
-## Subcommand: search <query>
-
-### Step 1: Execute Search
-
-```bash
-maestro wiki search "<query>" --json
-```
-
-### Step 2: Display Results
-
-Show table of results (ID, type, title, tags) with action hints: `maestro wiki get <id>`, `backlinks <id>`, `/learn-follow <id>`, `/wiki-connect --scope <type>`.
-
-### Step 3: Interactive Follow-up
-
-If not `--json`: offer to view an entry by number selection.
-
----
-
-## Subcommand: cleanup
-
-### Step 1: Scan Issues
-
-Gather baseline via `maestro wiki health`, `orphans --json`, `graph`.
-
-### Step 2: Categorize Issues
-
-| Issue Type | Detection | Auto-fix Action |
-|-----------|-----------|----------------|
-| Broken links | Forward link target doesn't exist | Remove broken link from frontmatter |
-| Orphans | No in/out links | Suggest connections via BM25 title match |
-| Stale entries | No updates in 90+ days, status=draft | Flag for review |
-| Empty body | Entry exists but body is empty/placeholder | Flag for review |
-
-### Step 3: Display Issues
-
-Show baseline health, issue counts by type, and entry-level details.
-
-### Step 4: Apply Fixes (--fix only)
-
-Broken links: remove from frontmatter via `maestro wiki update`. Orphans: mini wiki-connect (BM25 + tag match). Stale/empty: flag only (no auto-delete).
-
-Report: fixed count, remaining count, health delta.
-
----
-
-## Subcommand: stats
-
-### Step 1: Gather Data
-
-```bash
-maestro wiki list --json
-```
-
-### Step 2: Compute & Display Statistics
-
-Compute: type distribution (count/%), top 20 tags, category distribution (specs), connectivity (avg in/out-degree, max hub), growth (entries/week).
-
-Display as bar charts and summary tables.
-
+# Wiki Manage Workflow
+
+Unified wiki knowledge graph management — health monitoring, interactive search, orphan cleanup, and graph statistics.
+
+Complements `wiki-connect.md` (link discovery) and `wiki-digest.md` (synthesis) with day-to-day operational tooling.
+
+---
+
+## Prerequisites
+
+- `.workflow/` initialized
+- Wiki entries exist
+- `maestro wiki` CLI available
+
+---
+
+## Argument Shape
+
+```
+/manage-wiki                                   → health dashboard (default)
+/manage-wiki health                            → health dashboard
+/manage-wiki search auth                       → search for "auth" with follow-up actions
+/manage-wiki cleanup                           → find orphans, broken links, stale entries
+/manage-wiki cleanup --fix                     → auto-fix issues
+/manage-wiki stats                             → graph statistics
+/manage-wiki stats --type spec                 → spec-only statistics
+```
+
+| Flag | Effect |
+|------|--------|
+| `--type <type>` | Filter: spec, knowhow, note, issue |
+| `--fix` | Auto-fix issues during cleanup |
+| `--json` | JSON output |
+
+---
+
+## Subcommand: health (default)
+
+### Step 1: Gather Data
+
+Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`.
+
+### Step 2: Render Dashboard
+
+Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
+
+> **Scope split (complementary, not conflicting):** `/wiki-connect --fix` repairs/augments `related` links between existing entries (no deletion). `/manage-wiki cleanup --fix` deletes/flags orphans and removes broken-link entries from frontmatter. Run `wiki-connect` first to maximize link recovery, then `cleanup` to handle the true residual orphans.
+
+---
+
+## Subcommand: search <query>
+
+### Step 1: Execute Search
+
+```bash
+maestro wiki search "<query>" --json
+```
+
+### Step 2: Display Results
+
+Show table of results (ID, type, title, tags) with action hints: `maestro wiki get <id>`, `backlinks <id>`, `/learn-follow <id>`, `/wiki-connect --scope <type>`.
+
+### Step 3: Interactive Follow-up
+
+If not `--json`: offer to view an entry by number selection.
+
+---
+
+## Subcommand: cleanup
+
+### Step 1: Scan Issues
+
+Gather baseline via `maestro wiki health`, `orphans --json`, `graph`.
+
+### Step 2: Categorize Issues
+
+| Issue Type | Detection | Auto-fix Action |
+|-----------|-----------|----------------|
+| Broken links | Forward link target doesn't exist | Remove broken link from frontmatter |
+| Orphans | No in/out links | Suggest connections via BM25 title match |
+| Stale entries | No updates in 90+ days, status=draft | Flag for review |
+| Empty body | Entry exists but body is empty/placeholder | Flag for review |
+
+### Step 3: Display Issues
+
+Show baseline health, issue counts by type, and entry-level details.
+
+### Step 4: Apply Fixes (--fix only)
+
+Broken links: remove from frontmatter via `maestro wiki update`. Orphans: mini wiki-connect (BM25 + tag match). Stale/empty: flag only (no auto-delete).
+
+Report: fixed count, remaining count, health delta.
+
+---
+
+## Subcommand: stats
+
+### Step 1: Gather Data
+
+```bash
+maestro wiki list --json
+```
+
+### Step 2: Compute & Display Statistics
+
+Compute: type distribution (count/%), top 20 tags, category distribution (specs), connectivity (avg in/out-degree, max hub), growth (entries/week).
+
+Display as bar charts and summary tables.
+

package/workflows/cli-tools-usage.md

@@ -1,252 +0,0 @@
-# Delegate Execution Specification
-
-<purpose>
-Unified reference for `maestro delegate` — synchronous task delegation with broker-managed lifecycle, message injection, and MCP notifications.
-</purpose>
-
-**References**: `~/.maestro/cli-tools.json` (tool config), `~/.maestro/templates/cli/` (protocol + prompt templates)
-
----
-
-## 1. Quick Reference
-
-<context>
-
-### Command Syntax
-
-```bash
-maestro delegate "<PROMPT>" [options]
-```
-
-### Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--to <tool>` | Explicit tool: gemini, qwen, codex, claude, opencode | First enabled in config |
-| `--role <role>` | Capability role: analyze, explore, review, implement, plan, brainstorm, research | — (resolves via config) |
-| `--mode <mode>` | `analysis` (read-only) or `write` (create/modify/delete) | `analysis` |
-| `--model <model>` | Model override | Tool's `primaryModel` |
-| `--cd <dir>` | Working directory | Current directory |
-| `--includeDirs <dirs>` | Additional directories (comma-separated) | — |
-| `--rule <template>` | Load protocol + prompt template | — (optional) |
-| `--id <id>` | Execution ID | Auto: `{prefix}-{HHmmss}-{rand4}` |
-| `--resume [id]` | Resume session (last if no id, comma-separated for merge) | — |
-| `--backend <type>` | Adapter backend: `direct` or `terminal` (tmux/wezterm) | `direct` |
-
-### Tool Resolution Priority
-
-1. `--to <tool>` — explicit tool selection (highest priority)
-2. `--role <role>` — capability-based auto-selection via config
-3. No flag — first enabled tool in config
-
-### Caller Decision Rule
-
-- **User names a tool** (e.g. "用 gemini 分析", "ask codex") → **must use `--to <tool>`**
-- **User names a capability** (e.g. "分析一下", "review this") → use `--role <role>` or omit
-- **Never use `--role` when user has explicitly named a tool** — `--role` may route to a different tool
-
-### Role-Based Tool Selection
-
-Roles map to tools via `cli-tools.json` configuration:
-- User-defined roles in `roles` section override built-in defaults
-- Workspace `.maestro/cli-tools.json` overrides global `~/.maestro/cli-tools.json`
-- Built-in roles: `analyze`, `explore`, `review`, `implement`, `plan`, `brainstorm`, `research`
-
-### Mode Definition (Authoritative)
-
-| Mode | Permission | Auto-Invoke Safe | Use For |
-|------|-----------|------------------|---------|
-| `analysis` | Read-only | Yes | Review, exploration, diagnosis, architecture analysis |
-| `write` | Create/Modify/Delete | No — requires explicit intent | Implementation, bug fixes, refactoring |
-
-> `--mode` is the **authoritative** permission control. The `MODE:` field inside prompt text is a hint for the agent — both should be consistent, but `--mode` governs actual behavior.
-</context>
-
----
-
-## 2. Configuration
-
-<context>
-
-### Config File: `~/.maestro/cli-tools.json`
-
-| Field | Description |
-|-------|-------------|
-| `enabled` | Tool availability |
-| `primaryModel` | Default model |
-| `secondaryModel` | Fallback model |
-| `tags` | Capability tags (for caller-side routing) |
-| `type` | `builtin` / `cli-wrapper` / `api-endpoint` |
-
-> `api-endpoint` tools support **analysis only** — no file write capability.
-
-### Supported Tools
-
-| Tool | Agent Type | Adapter |
-|------|-----------|---------|
-| `gemini` | gemini | StreamJsonAdapter |
-| `qwen` | qwen | StreamJsonAdapter |
-| `codex` | codex | CodexCliAdapter |
-| `claude` | claude-code | ClaudeCodeAdapter |
-| `opencode` | opencode | OpenCodeAdapter |
-
-### Tool Selection
-
-1. Explicit `--to` specified → use it (validate enabled)
-2. No `--to` → first enabled tool in config order
-
-### Fallback Chain
-
-Primary model fails → `secondaryModel` → next enabled tool → first enabled (default).
-</context>
-
----
-
-## 3. Prompt Construction
-
-<context>
-
-### Assembly Order
-
-`maestro delegate` builds the final prompt as:
-
-1. **Mode protocol** — `~/.maestro/templates/cli/protocols/{mode}-protocol.md`
-2. **User prompt** — the positional `"<PROMPT>"` value
-3. **Rule template** — `~/.maestro/templates/cli/prompts/{rule}.txt` (if `--rule` specified)
-
-### Prompt Template (6 Fields)
-
-```
-PURPOSE: [goal] + [why] + [success criteria]
-TASK: [step 1] | [step 2] | [step 3]
-MODE: analysis|write
-CONTEXT: @[file patterns] | Memory: [prior work context]
-EXPECTED: [output format] + [quality criteria]
-CONSTRAINTS: [scope limits] | [special requirements]
-```
-
-- **PURPOSE**: What + Why + Success. Not "Analyze code" but "Identify auth vulnerabilities; success = OWASP Top 10 covered"
-- **TASK**: Specific verbs. Not "Review code" but "Scan for SQL injection | Check XSS | Verify CSRF"
-- **MODE**: Must match `--mode` flag
-- **CONTEXT**: File scope + memory from prior work
-- **EXPECTED**: Deliverable format, not just "Report"
-- **CONSTRAINTS**: Task-specific limits (vs `--rule` which loads generic templates)
-
-### CONTEXT: File Patterns + Directory
-
-- `@**/*` — all files in working directory (default)
-- `@src/**/*.ts` — scoped pattern
-- `@../shared/**/*` — sibling directory (**requires `--includeDirs`**)
-
-**Rule**: If CONTEXT uses `@../dir/**/*`, must add `--includeDirs ../dir`.
-
-```bash
-# Cross-directory example
-maestro delegate "CONTEXT: @**/* @../shared/**/*" --to gemini --mode analysis \
-  --cd "src/auth" --includeDirs "../shared"
-```
-
-### CONTEXT: Memory
-
-Include when building on previous work:
-
-```
-Memory: Building on auth refactoring (commit abc123), implementing refresh tokens
-Memory: Integration with auth module, using shared error patterns
-```
-
-### --rule Templates
-
-**Universal**: `universal-rigorous-style`, `universal-creative-style`
-
-**Analysis**: `analysis-trace-code-execution`, `analysis-diagnose-bug-root-cause`, `analysis-analyze-code-patterns`, `analysis-analyze-technical-document`, `analysis-review-architecture`, `analysis-review-code-quality`, `analysis-analyze-performance`, `analysis-assess-security-risks`
-
-**Planning**: `planning-plan-architecture-design`, `planning-breakdown-task-steps`, `planning-design-component-spec`, `planning-plan-migration-strategy`
-
-**Development**: `development-implement-feature`, `development-refactor-codebase`, `development-generate-tests`, `development-implement-component-ui`, `development-debug-runtime-issues`
-
-### Complete Example
-
-```bash
-maestro delegate "PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module; success = all critical/high documented with remediation
-TASK: Scan for injection flaws | Check auth bypass vectors | Evaluate session management | Assess data exposure
-MODE: analysis
-CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt + JWT
-EXPECTED: Severity matrix, file:line references, remediation snippets, priority ranking
-CONSTRAINTS: Focus on authentication | Ignore test files
-" --to gemini --mode analysis --rule analysis-assess-security-risks --cd "src/auth"
-```
-</context>
-
----
-
-## 4. Execution
-
-<execution>
-
-### Calling Convention
-
-`maestro delegate` runs synchronously. Status summary and output are **auto-appended** on completion — no manual `output` or `status` commands needed.
-
-**Always** use `run_in_background: true` and **end your response immediately**:
-
-```
-Bash({ command: "maestro delegate \"...\" --to gemini --mode analysis", run_in_background: true })
-```
-
-When the background callback arrives, the result is already included:
-```
-[MAESTRO_EXEC_ID=gem-143022-a7f2]        , at start
-[DELEGATE COMPLETED] gem-143022-a7f2 gemini/analysis   ← status, on completion
---- Output ---
-<actual output content>                   ← output, on completion
-```
-
-**Rules:**
-- NEVER use foreground Bash for delegate calls
-- NEVER output text or tool calls after the `run_in_background` Bash call
-- When the callback arrives, output is already included — directly use it
-
-### Execution ID
-
-ID prefix: gemini→`gem`, qwen→`qwn`, codex→`cdx`, claude→`cld`, opencode→`opc`
-
-```bash
-maestro delegate "<PROMPT>" --to gemini --mode analysis    # auto-ID: gem-143022-a7f2
-maestro delegate "<PROMPT>" --to gemini --mode write --id my-task-1  # custom ID
-```
-
-### Session Resume
-
-```bash
-maestro delegate "<PROMPT>" --to gemini --resume              # last session
-maestro delegate "<PROMPT>" --to gemini --mode write --resume <id>  # specific
-maestro delegate "<PROMPT>" --to gemini --resume <id1>,<id2>     # merge multiple
-```
-
-Resume auto-assembles previous conversation context. Warning emitted when context exceeds 32KB.
-</execution>
-
----
-
-## 5. Auto-Invoke Triggers
-
-<execution>
-
-Proactively invoke `maestro delegate` when these conditions are met — no user confirmation needed for `analysis` mode:
-
-| Trigger | Suggested Rule |
-|---------|---------------|
-| Self-repair fails (1+ attempts) | `analysis-diagnose-bug-root-cause` |
-| Ambiguous requirements | `planning-breakdown-task-steps` |
-| Architecture decisions needed | `planning-plan-architecture-design` |
-| Pattern uncertainty | `analysis-analyze-code-patterns` |
-| Critical/security code paths | `analysis-assess-security-risks` |
-
-### Principles
-
-- Default `--mode analysis` (safe, read-only)
-- Wait for results before next action
-- User named a tool → `--to <tool>`; user didn't → `--role` or omit (see Caller Decision Rule)
-- Rule suggestions are guidelines — choose the best fit
-</execution>

package/workflows/delegate-protocol.codex.md

@@ -1,65 +0,0 @@
-# Maestro Delegate Execution Protocol (Codex)
-
-`maestro delegate` is a long-running shell command (30s–5min+). All Codex agents MUST follow this polling protocol when executing delegate calls.
-
-## Execution Steps
-
-### Step 1: Start Delegate
-
-```
-exec_command({
-  cmd: `maestro delegate "<PROMPT>" [options]`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-```
-
-- `yield_time_ms: 30000` — wait up to 30s for initial output
-- If the command completes within yield time → result is final, proceed to Step 3
-
-### Step 2: Poll Loop (if session_id returned)
-
-If `exec_command` returns `{ session_id: N, ... }` (command still running), enter poll loop:
-
-```
-poll_interval = 15000   // start at 15s
-
-LOOP:
-  result = write_stdin({
-    session_id: <session_id>,
-    chars: "",
-    yield_time_ms: poll_interval,
-    max_output_tokens: 6000
-  })
-
-  IF result indicates command completed → BREAK, proceed to Step 3
-  IF result indicates command still running:
-    poll_interval = min(poll_interval * 2, 60000)   // backoff: 15s → 30s → 60s cap
-    GOTO LOOP
-```
-
-### Step 3: Parse Result
-
-Extract the delegate output (assistant response) from the final result. Parse according to the caller's expected format (JSON, structured text, etc.).
-
-## Invariants
-
-| Rule | Description |
-|------|-------------|
-| **NEVER skip polling** | Delegate output is required for workflow continuation. If session_id is returned, you MUST poll until completion. |
-| **NEVER abandon session** | Do not move to next workflow step while delegate is still running. |
-| **NEVER fire-and-forget** | Every delegate call must be awaited and its result consumed. |
-| **Increasing backoff** | Poll intervals: 15s → 30s → 60s (capped). Prevents unnecessary load. |
-| **Error still completes** | If output contains error/failed, still finish reading the full output before handling the error. |
-| **Timeout escalation** | If polling exceeds 5 minutes total, report as blocker but do NOT abandon — continue polling. |
-
-## Quick Reference
-
-```
-// Compact pattern for inline use:
-//
-// 1. exec_command({ cmd: `maestro delegate "..."`, yield_time_ms: 30000 })
-// 2. If session_id → poll write_stdin({ session_id, chars: "", yield_time_ms: 15000→60000 })
-// 3. Parse result after completion
-// ⚠️ MUST poll until completion — NEVER skip
-```