maestro-flow 0.5.40 → 0.5.42

package/workflows/codex-instructions.md

@@ -1,161 +1,147 @@
-# Codex Code Guidelines
-
-
-- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
-- **Explore Usage**: @~/.maestro/workflows/explore-usage.md
-- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
-
-**Strictly follow the cli-tools.json configuration**
-
-## Explore Priority
-
-`maestro explore` takes priority over Glob, Grep, and Read. When locating files or searching code patterns, call `maestro explore` first and stop to wait for results.
-
-# Coding Philosophy
-
-## Core Beliefs
-
-- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
-- **Embrace extreme simplicity** - Complexity is the root of all evil
-- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
-- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
-- **Never break backward compatibility** - Existing functionality is sacred and inviolable
-- **Incremental progress over big bangs** - Small changes that compile and pass tests
-- **Learning from existing code** - Study and plan before implementing
-- **Clear intent over clever code** - Be boring and obvious
-- **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
-- **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
-- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
-
-## Simplicity Means
-
-- Single responsibility per function/class
-- Avoid premature abstractions
-- No clever tricks - choose the boring solution
-- If you need to explain it, it's too complex
-
-## Fix, Don't Hide
-
-**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
-
-**NEVER**:
-- Make assumptions - verify with existing code
-- Generate reports, summaries, or documentation files without explicit user request
-- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause
-
-**ALWAYS**:
-- Plan complex tasks thoroughly before implementation
-- Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
-- Track progress using TODO checklists for complex tasks
-- Validate planning documents before starting development
-- Commit working code incrementally
-- Update plan documentation and progress tracking as you go
-- Learn from existing implementations
-- Stop after 3 failed attempts and reassess
-- **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
-
-## Learning the Codebase
-
-- Find 3 similar features/components
-- Identify common patterns and conventions
-- Use same libraries/utilities when possible
-- Follow existing test patterns
-
-## Tooling
-
-- Use project's existing build system
-- Use project's test framework
-- Use project's formatter/linter settings
-- Don't introduce new tools without strong justification
-
-## Content Uniqueness Rules
-
-- **Each layer owns its abstraction level** - no content sharing between layers
-- **Reference, don't duplicate** - point to other layers, never copy content
-- **Maintain perspective** - each layer sees the system at its appropriate scale
-- **Avoid implementation creep** - higher layers stay architectural
-
-# Context Requirements
-
-Before implementation, always:
-- Identify 3+ existing similar patterns
-- Map dependencies and integration points
-- Understand testing framework and coding conventions
-
-## Knowledge System
-
-**Gate rule: On any coding/modification/debugging task, run `maestro search` + `maestro load` BEFORE reading code or editing files.**
-
-### Required (every task, no exceptions)
-
-```bash
-# Search relevant knowledge (1-3 keywords, multiple short queries beat one long one)
-maestro search "<topic phrase>"
-
-# Load specs for the task type
-maestro load --type spec --category coding    # coding tasks
-maestro load --type spec --category arch      # architecture decisions
-maestro load --type spec --category test      # test writing
-maestro load --type spec --category ui        # UI work
-```
-
-**Query rules:**
-- Use **1-3 core keywords** per query — never dump all context into one search
-- Separate concepts from symbols: `maestro search "topology layout"` + `maestro search "DetailedTopologySVG" --code`
-- Add as needed: `maestro search "query" --kg` (KG full-source), `maestro kg callers <fn>` (call chain), `maestro kg context <node>` (node context)
-
-```bash
-# ❌ Bad: keyword dump
-maestro search "topology display frontend DetailedTopologySVG elk"
-
-# ✅ Good: targeted multi-search + spec load
-maestro search "topology layout"
-maestro search "DetailedTopologySVG" --code
-maestro load --type spec --category coding
-```
-
-### Load & Search reference
-
-```bash
-maestro load --type <type> [--list] [--category <cat>] [--keyword <word>] [--id <id>]
-maestro search "<query>" [--type <type>] [--category <cat>] [--code] [--kg] [--json]
-```
-
-**`--category` values** (for `--type spec`): `coding`, `arch`, `debug`, `test`, `review`, `learning`, `ui`
-**`--keyword`**: free-text filter on title/body/tags — use to narrow within a category
-
-**`--type` values**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
-
-| Action | Command |
-|--------|---------|
-| Load coding specs | `maestro load --type spec --category coding` |
-| Load arch specs with keyword | `maestro load --type spec --category arch --keyword auth` |
-| List sessions | `maestro load --type session --list` |
-| Load specific knowhow | `maestro load --type knowhow --id <id>` |
-| Search sessions | `maestro search "query" --type session` |
-| Code graph search | `maestro search "symbol" --code` |
-| KG full-source search | `maestro search "query" --kg` |
-
-### Record
-
-| What | Command |
-|------|---------|
-| Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
-| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` to bridge into agent injection) |
-
-Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
-
-### Confidence & Conflict Marking
-
-When search results conflict with current context, **mark the entry**:
-
-```bash
-maestro spec conflict mark <file> <line> --note "<reason>"
-maestro spec conflict list
-```
-
-Levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
-
-- `contested` → sorted last during injection, labeled `[CONTESTED]` with conflict note
-- `low` → labeled `[LOW CONFIDENCE]`
-- Resolution handled by `/manage-knowledge-audit`
+# Maestro
+
+- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
+
+## Delegate & CLI
+
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+`maestro delegate "<PROMPT>" --to <tool> --mode analysis|write` — dispatch tasks to external CLI tools (gemini, codex, claude, opencode).
+Always `run_in_background: true`. Full guide: `cat ~/.maestro/workflows/delegate-usage.md`
+
+**Strictly follow the cli-tools.json configuration**
+
+## Explore
+
+`maestro explore` takes priority over Glob, Grep, and Read. When locating files or searching code patterns, call `maestro explore` first and stop to wait for results.
+
+```bash
+maestro explore "FIND: <target + condition>\nSCOPE: <paths>" [more prompts...] [options]
+```
+
+Lightweight read-only codebase search. 1 prompt = 1 agent. Not for write-mode/long sessions — use `delegate`.
+
+| Option | Description |
+|--------|-------------|
+| `-e, --endpoint <names>` | Endpoint name(s), comma-separated |
+| `--all` | Fan out each prompt to all endpoints |
+| `--max-turns <n>` | Max agent turns per job |
+| `-f, --file <path>` | Load prompts from JSON or text file |
+| `--cd <dir>` | Working directory |
+| `--json` | Output results as JSON |
+
+### Context Injection
+
+Explore agent 无项目认知，调用前注入上下文：
+
+| 注入项 | 写入字段 | 内容 |
+|--------|----------|------|
+| 结构 | SCOPE | 相关目录的具体路径（非通配泛扫） |
+| 领域 | SCOPE | `maestro search` 已返回的关键文件路径 |
+| 约束 | ATTENTION | 框架、语言、命名惯例 |
+
+```
+FIND: authentication middleware that validates JWT tokens
+SCOPE: src/middleware/, src/auth/, src/api/routes/
+ATTENTION: Express.js, middleware files named *.middleware.ts
+```
+
+### Prompt Structure
+
+**FIND + SCOPE 为最低标准。** 每个字段一句陈述句，禁止嵌套条件。
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `FIND` | **Yes** | 可判定的具体目标（什么 + 判定条件） |
+| `SCOPE` | **Yes** | 明确路径或 glob，禁止 `**/*` 泛扫 |
+| `EXCLUDE` | No | 要跳过的文件类型或目录 |
+| `ATTENTION` | No | 框架、命名惯例、已知陷阱 |
+| `EXPECTED` | Recommended | 输出格式：`file:line` 列表 / 摘要 / JSON |
+
+```
+FIND: Functions that call db.query() with string concatenation instead of $1/$2
+SCOPE: src/db/**/*.ts, src/api/**/*.ts
+EXCLUDE: **/*.test.ts
+EXPECTED: file:line list with the SQL string
+```
+
+### Cross-Search
+
+对重要搜索，用 2-3 个不同角度的 prompt 并发，结果由 Claude 交叉验证。
+
+**按角度拆分，不按关键词拆分：**
+
+| 角度 | Prompt A | Prompt B |
+|------|----------|----------|
+| 定义 vs 调用 | 找函数定义 | 找调用点 |
+| 正例 vs 反例 | 找正确用法 | 找遗漏用法 |
+| 入口 vs 实现 | 找 export/路由 | 找内部逻辑 |
+| 按文件类型 | .ts 中的用法 | .vue 中的用法 |
+
+```bash
+maestro explore \
+  "FIND: All functions exported from auth module\nSCOPE: src/auth/\nEXPECTED: function name + file:line" \
+  "FIND: All imports from auth module\nSCOPE: src/**/*.ts\nEXCLUDE: src/auth/\nEXPECTED: import path + file:line" \
+  --json
+```
+
+**结果置信度：**
+- 双命中 → 高置信，直接使用
+- 单命中 → 用 Grep/Read 二次确认
+- 零命中 → 换角度重搜或目标不存在
+
+### Execution
+
+Multi-prompt — background；single lookup — foreground：
+
+```
+Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
+Bash({ command: "maestro explore \"FIND: ...\nSCOPE: ...\"" })
+```
+
+Session: `maestro explore show` / `maestro explore output <id>`
+
+## Knowledge System
+
+**Gate rule**: run `maestro search` + `maestro load` BEFORE reading code or editing files.
+
+```bash
+maestro search "<query>" [--type <type>] [--category <cat>] [--code] [--kg]
+maestro load --type <type> [--list] [--category <cat>] [--keyword <word>] [--id <id>]
+```
+
+**--type**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
+**--category** (spec only): `coding`, `arch`, `debug`, `test`, `review`, `learning`, `ui`
+
+### Query Rules
+
+1-3 core keywords per query — multiple short queries beat one long one.
+Separate concepts from symbols. Add `--code` for symbols, `--kg` for full-source.
+
+```bash
+# ❌ keyword dump
+maestro search "topology display frontend DetailedTopologySVG elk"
+
+# ✅ targeted
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro load --type spec --category coding
+```
+
+### Record
+
+| What | Command |
+|------|---------|
+| Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
+| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` for agent injection) |
+
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
+
+### Conflict Marking
+
+```bash
+maestro spec conflict mark <file> <line> --note "<reason>"
+```
+
+Levels: `high` → `medium` (default) → `low` (`[LOW CONFIDENCE]`) → `contested` (`[CONTESTED]`).
+Resolution: `/manage-knowledge-audit`

package/workflows/execute.md

@@ -43,7 +43,7 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 | `--executor <tool>` | Default CLI tool: gemini\|codex\|qwen\|opencode\|claude (default: first enabled in cli-tools.json) |
 | `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
 | `--skip-verify` | Skip E2.7 verification gate (trust execution output) |
-| `-y` | Auto-approve execution options (skip confirmation prompt) |
+| `-y` | Auto mode — skip ALL interactive questions (E0.5 options, inter-wave confirmations, blocked-task prompts) |
 
 ---
 
@@ -51,7 +51,7 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 
 ### Skip conditions
 
-- `-y` flag → use resolved defaults, skip prompt
+- `-y` flag → use resolved defaults, skip prompt (applies to ALL interactive questions throughout execution, not just E0.5)
 - `executionContext.executionMethod` already set → skip (confirmed in /maestro-plan)
 
 ### Pre-step: Load tool config
@@ -301,7 +301,8 @@ For each wave in execution_queue (sequential):
     Clear state.json.current_task_id
 
   Wait for all wave tasks; update index.json (tasks_completed, commits)
-  If any blocked: prompt user to continue or stop
+  If any blocked AND NOT -y flag: prompt user to continue or stop
+  Else: continue to next wave automatically (NEVER ask for confirmation between waves)
 ```
 
 ### Parallel Dispatch Rules

package/workflows/explore-usage.md

@@ -1,19 +1,11 @@
 # Explore Usage
 
 ```bash
-maestro explore "<PROMPT>" [more prompts...] [options]
+maestro explore "FIND: <target + condition>\nSCOPE: <paths>" [more prompts...] [options]
 ```
 
-## When to Use
-
-| Scenario | Example |
-|----------|---------|
-| Multi-angle codebase scan | 3 prompts scanning DB/API/error patterns in parallel |
-| Quick code lookup | Single prompt, foreground |
-| Per-prompt endpoint routing | JSON file with different endpoints per prompt |
-| Lightweight read-only analysis | Where delegate is overkill (no session, no history) |
-
-**Not for**: write-mode tasks, long sessions, interactive follow-ups — use `delegate` instead.
+Lightweight read-only codebase search. 1 prompt = 1 agent.
+**Not for**: write-mode, long sessions, follow-ups — use `delegate`.
 
 ## Options
 
@@ -21,103 +13,71 @@ maestro explore "<PROMPT>" [more prompts...] [options]
 |--------|-------------|---------|
 | `-e, --endpoint <names>` | Endpoint name(s), comma-separated | First available |
 | `--all` | Fan out each prompt to all endpoints | — |
-| `--parallel <n>` | Max concurrent endpoint queues | Config or `4` |
-| `--ep-concurrency <n>` | Max concurrent jobs per endpoint | `1` (serial) |
 | `--max-turns <n>` | Max agent turns per job | Config or `6` |
 | `-f, --file <path>` | Load prompts from JSON or text file | — |
 | `--cd <dir>` | Working directory | Current |
-| `-o, --output-dir <dir>` | Custom session save directory | `.workflow/explore/` |
-| `--no-save` | Skip session save | — |
 | `--json` | Output results as JSON | — |
 
-> **API Format**: Each endpoint supports `"format": "openai"` (default) or `"format": "anthropic"`. OpenAI-compatible endpoints (vLLM, Ollama, SiliconFlow, DeepSeek) use `openai`; Anthropic Messages API uses `anthropic`.
-
-**1 prompt = 1 agent**. Endpoint resolution: `--endpoint` > `--all` > first available.
+Endpoint resolution: `--endpoint` > `--all` > first available.
 
-## Prompt Template
-
-```
-FIND: [what to search for — the core query]
-SCOPE: [file patterns, directories, or modules]
-EXCLUDE: [what to skip — files, patterns, false positives]
-ATTENTION: [caveats, edge cases, things to watch for]
-EXPECTED: [output format — evidence list, summary, JSON]
-```
+## Prompt Rules
 
-Only `FIND` required. Plain text (no `FIND:` prefix) also works.
+**FIND + SCOPE is minimum standard.** Bare FIND produces unfocused results.
 
-| Field | Role | Example |
-|-------|------|---------|
-| `FIND` | What to search for | `All database query patterns that could cause N+1` |
-| `SCOPE` | Where to look | `src/db/**/*.ts`, `src/api/` |
-| `EXCLUDE` | What to skip | `test files, generated code, node_modules` |
-| `ATTENTION` | What to watch for | `ORM lazy-loading traps, raw SQL in service layer` |
-| `EXPECTED` | Output format | `file:line evidence list with severity` |
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `FIND` | **Yes** | Precise target — what exactly + condition |
+| `SCOPE` | **Yes** | File patterns or directories to search |
+| `EXCLUDE` | No | What to skip |
+| `ATTENTION` | No | Edge cases to watch |
+| `EXPECTED` | Recommended | Output format (`file:line` list, summary, JSON) |
 
-## Execution Model
+### Bad vs Good
 
-**Serial within endpoint, parallel across endpoints.**
+```
+# ❌ Vague — no actionable target
+FIND: database patterns
+FIND: error handling
 
-Same API → jobs queue and run one-by-one (avoids rate limits).
-Different APIs → queues run concurrently.
+# ✅ Specific target + condition + scope
+FIND: Functions that execute SQL queries without parameterized inputs
+SCOPE: src/db/**/*.ts, src/api/**/*.ts
 
-```
-Endpoint A:  [job1] → [job2] → [job3]    (serial)
-Endpoint B:  [job4] → [job5]              (serial)
-                                           ↑ parallel ↑
+FIND: catch blocks that swallow errors silently (empty catch or catch-and-log-only)
+SCOPE: src/services/
+EXPECTED: file:line list with severity
 ```
 
-Raise per-endpoint parallelism with `--ep-concurrency 2` when the API rate limit permits (verify via test request).
+### Multi-Prompt
 
-## Multi-Prompt Input
+**Decompose by angle, not by keyword.** Each prompt gets one focused question + scope.
 
-**Inline**: `maestro explore "prompt1" "prompt2" "prompt3"`
+```
+# ❌ Keyword dump in one prompt
+"database error handling auth patterns"
+
+# ✅ One angle per prompt
+maestro explore \
+  "FIND: N+1 query patterns\nSCOPE: src/db/" \
+  "FIND: Unparameterized SQL\nSCOPE: src/db/, src/api/" \
+  "FIND: Missing error propagation\nSCOPE: src/services/"
+```
 
-**JSON file** (`-f prompts.json`):
+Input formats: inline strings, JSON file (`-f`), text file (`-f`), or mixed.
+JSON supports per-prompt endpoint override:
 
 ```json
-[
-  "simple string prompt",
-  { "prompt": "FIND: auth bypass\nSCOPE: src/api/", "endpoint": "deepseek" }
-]
+[{ "prompt": "FIND: auth bypass\nSCOPE: src/api/", "endpoint": "deepseek" }]
 ```
 
-Per-prompt `endpoint` overrides global `--endpoint`.
-
-**Text file** (`-f prompts.txt`): paragraphs separated by blank lines.
-
-**Mixed**: `maestro explore "inline" -f file.json`
-
 ## Session
 
-Results auto-save to `.workflow/explore/{session-id}.json` per workspace.
-
 ```bash
 maestro explore show                  # list sessions
-maestro explore output <id>           # view session results
+maestro explore output <id>           # view results
 maestro explore output <id> --json    # JSON output
 ```
 
-## Endpoint Config
-
-File: `~/.maestro/api-explore.json`
-
-```json
-{
-  "endpoints": {
-    "qwen": { "baseUrl": "https://...", "apiKey": "sk-xxx", "model": "Qwen/Qwen3-8B" },
-    "deepseek": { "baseUrl": "https://...", "apiKey": "sk-yyy", "model": "deepseek-chat" },
-    "sonnet": { "baseUrl": "https://api.anthropic.com", "apiKey": "sk-ant-...", "model": "claude-sonnet-4-20250514", "format": "anthropic" }
-  },
-  "maxTurns": 6,
-  "concurrency": 4
-}
-```
-
-`format` per endpoint: `"openai"` (default) for OpenAI-compatible APIs, `"anthropic"` for Anthropic Messages API.
-
-Proxy auto-inherited from `~/.maestro/cli-tools.json`. Legacy single-endpoint and env vars also supported.
-
 ## Execution Rules
 
 Multi-prompt — **background**:
@@ -126,7 +86,7 @@ Multi-prompt — **background**:
 Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
 ```
 
-Single quick lookup — run in foreground:
+Single quick lookup — foreground:
 
 ```
 Bash({ command: "maestro explore \"Where is X defined?\"" })

package/workflows/grill.md

@@ -428,6 +428,17 @@ Write `{output_dir}/context-package.json`:
 
 ---
 
+## Step 6.5: Artifact Verification (before completion)
+
+Verify all required artifacts exist before proceeding to artifact registration:
+- `grill-report.md` — Branch Log + Q&A entries + synthesis
+- `terminology.md` — ≥5 terms with code refs
+- `context-package.json` — schema "context-package/1.0"
+
+If any missing: produce the missing artifact before Step 7. Do NOT register completion without all artifacts present.
+
+---
+
 ## Step 7: Register Artifact
 
 ### 7.1: Register in state.json

package/workflows/milestone-audit.md

@@ -107,6 +107,14 @@ CONSTRAINTS: Only check cross-phase boundaries | Ignore intra-phase issues
 
 ---
 
+## Step 5.9: Artifact & Evidence Verification
+
+Before proceeding to verdict:
+- Verify `audit-report.md` exists at `.workflow/milestones/{milestone}/audit-report.md`. If missing: re-run Step 5.
+- Every audit check result MUST cite what was examined and what was found (e.g., "Phase 1 chain complete: ANL-001 → PLN-001 → EXC-001" or "Phase 2 missing EXC artifact"). Do NOT mark checks as PASS without verifying the actual artifact exists.
+
+---
+
 ## Step 6: Audit Report & Verdict
 
 1. Read the audit report generated by the integration checker