maestro-flow 0.5.35 → 0.5.37

package/workflows/analyze.md

@@ -163,11 +163,13 @@ Parse $ARGUMENTS to determine mode and flags:
    - `constraints[status=open]` → prioritize for analysis
    - `open_questions[]` → seed discussion topics
 6. Load project specs: `specs_content = maestro spec load --category arch`
+7. Load domain glossary: read `.workflow/domain/glossary.yaml`（如存在）— 分析过程中使用 canonical term names 保持术语一致性；新发现的术语候选记入 `context-package.json#domain.terminology[]`
 
 **Load prior context** (adhoc/standalone scope):
 1. Read `.workflow/project.md` (if exists) — project vision, Validated requirements, Active requirements, Key Decisions
 2. Read `.workflow/state.json` (if exists) → `accumulated_context` (key_decisions, deferred, blockers)
 3. Load project specs: `specs_content = maestro spec load --category arch`
+4. Load domain glossary: read `.workflow/domain/glossary.yaml`（如存在）
 
 **Quick mode routing**: If QUICK_MODE, skip to Step 8 (Decision Extraction) after loading context.
 
@@ -525,8 +527,6 @@ Implementer's choice. Research suggests: {relevant finding from researchContext}
 (e.g., "Standard Stack recommends React Query for server state. Common pitfall: avoid mixing with Redux for async.")
 ```
 
-This makes research findings visible to the planner through context.md without imposing hard constraints.
-
 **8.5: Write context.md**
 
 Write to `OUTPUT_DIR/context.md`:

package/workflows/boundary-grill.md

@@ -0,0 +1,50 @@
+# Boundary Grill — Embedded Mini-Review Protocol
+
+
+## Conflict Types
+
+| ID | Signal | Example |
+|----|--------|---------|
+| `RSC` | Decision outside command's scope guard | analyze outputs task-level details (plan scope) |
+| `MOD` | Changes cross 2+ module boundaries | task touches `commands/` and `hooks/` without declaring cross-module |
+| `DEC` | Upstream locked decision contradicts code | locked "use EventEmitter" but code uses Subject at `file:line` |
+
+## Trigger
+
+Run boundary grill when ANY of:
+- **RSC**: produced decision matches another command's scope guard keywords
+- **MOD**: `ARCHITECTURE.md` exists AND changes touch 2+ top-level modules
+- **DEC**: upstream Locked decisions AND code grep shows contradicting patterns
+
+Priority when >3 conflicts: DEC > RSC > MOD.
+
+## Protocol
+
+Per conflict (max 3 conflicts × 3 questions = 9 total):
+1. State the conflict with `file:line` evidence
+2. Ask 2-3 adversarial questions via AskUserQuestion — challenge with code reality
+3. Resolve: RESOLVED (evidence-based) / DEFERRED (needs escalation) / ACCEPTED_RISK
+
+**Auto mode (`-y`)**: skip questions, resolve via code evidence weighting:
+- RSC → defer to target scope
+- MOD → follow existing cross-module pattern (or flag as risk)
+- DEC → code wins (current code = ground truth)
+
+## Output
+
+Append to calling command's primary output:
+
+```markdown
+## Boundary Grill Results
+
+| # | Type | Conflict | Resolution | Evidence |
+|---|------|----------|------------|----------|
+```
+
+Feed into `context.md`: resolved DEC → amend Locked; unresolved → Deferred with `boundary_grill: true`.
+
+## Constraints
+
+- Non-blocking — warnings + resolutions, never hard stops
+- Evidence MUST include `file:line` — generic assertions invalid
+- Results visible in command output — no silent swallowing

package/workflows/brainstorm.md

@@ -1,7 +1,5 @@
 # Workflow: Brainstorm
 
-Dual-mode brainstorming: auto pipeline (full multi-role analysis) or single role analysis.
-
 ## Architecture
 
 ```
@@ -202,9 +200,12 @@ Pass into Steps 2 and 3.
 
 ### Step 2: Terminology & Boundary Definition (Auto Mode)
 
-1. Extract 5-10 core domain terms (merge upstream locked terms if available)
-2. AskUserQuestion for Non-Goals (multiSelect, include "其他" option)
-3. Store terminology + non_goals to session
+1. Load existing domain terms: read `.workflow/domain/glossary.yaml` 中已注册术语，避免重复定义
+2. Extract 5-10 core domain terms (merge upstream locked terms + existing glossary terms)
+3. AskUserQuestion for Non-Goals (multiSelect, include "其他" option)
+4. Store terminology + non_goals to session
+
+新候选术语仅存入 `context-package.json#domain.terminology[]`，不直接写 glossary.yaml。由 chain 末尾 `manage-harvest --auto` 触发 finish-work Step 3.5 统一提升为正式术语。
 
 **Skip if**: `--yes` (auto-generate terms, empty non-goals)
 

package/workflows/claude-instructions.md

@@ -5,45 +5,75 @@
 ## Delegate & CLI
 
 - **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.
+
 ## Knowledge System
 
-**Gate rule: On any coding/modification/debugging task, run `maestro search` BEFORE reading code or editing files. Use targeted queries — multiple short searches beat one long one.**
+**Gate rule: On any coding/modification/debugging task, run `maestro search` + `maestro load` BEFORE reading code or editing files.**
 
-### Required search (every task, no exceptions)
+### Required (every task, no exceptions)
 
 ```bash
-maestro search "<1-3 word topic phrase>"
+# 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"` then `maestro search "DetailedTopologySVG" --code`
-- Run multiple targeted searches rather than one broad query
+- 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 (5+ unrelated terms → diluted BM25 scores)
+# ❌ Bad: keyword dump
 maestro search "topology display frontend DetailedTopologySVG elk"
 
-# ✅ Good: targeted multi-search
+# ✅ Good: targeted multi-search + spec load
 maestro search "topology layout"
 maestro search "DetailedTopologySVG" --code
-maestro search "elk layout" --type knowhow
+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]
 ```
 
-Then add follow-up searches based on results:
-- Specific symbol/function → `maestro kg search <symbol>` or `maestro kg context <node>`
-- Architecture/testing → `maestro search --type spec --category arch|test`
-- Call chains → `maestro kg callers <fn>` / `maestro kg callees <fn>`
-- Domain rules → `maestro spec load --category <cat> [--keyword <kw>]`
+**`--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
 
-- **Spec** → `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"`
-- **Knowhow** → `/manage-knowhow-capture` (use `--spec-category <cat>` to bridge into agent injection)
+| 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`.
 
@@ -52,12 +82,12 @@ Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`l
 When search results conflict with current context, **mark the entry**:
 
 ```bash
-maestro spec conflict mark <file> <line> --note "<conflict reason>"
-maestro spec conflict list                    # view all marked entries
+maestro spec conflict mark <file> <line> --note "<reason>"
+maestro spec conflict list
 ```
 
-Confidence levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
+Levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
 
-- `contested` → 注入时排末尾，`[CONTESTED]` 标记 + 冲突说明
-- `low` → `[LOW CONFIDENCE]` 标记
-- 消除由 `/manage-knowledge-audit` 审查命令专门处理
+- `contested` → sorted last during injection, labeled `[CONTESTED]` with conflict note
+- `low` → labeled `[LOW CONFIDENCE]`
+- Resolution handled by `/manage-knowledge-audit`

package/workflows/codebase-rebuild.md

@@ -204,7 +204,6 @@ Uses the native `maestro kg index` command (`src/graph/analyzers/fs-analyzer.ts`
 maestro kg index --src "$PROJECT_ROOT/src"
 ```
 
-This single command performs:
   - File system scan and code entity extraction (nodes, edges)
   - Import/call graph analysis and test pairing (tested_by edges)
   - Layer classification and topological tour generation

package/workflows/codex-instructions.md

@@ -2,10 +2,15 @@
 
 
 - **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
@@ -79,39 +84,64 @@ Before implementation, always:
 
 ## Knowledge System
 
-**Gate rule: On any coding/modification/debugging task, run `maestro search` BEFORE reading code or editing files. Use targeted queries — multiple short searches beat one long one.**
+**Gate rule: On any coding/modification/debugging task, run `maestro search` + `maestro load` BEFORE reading code or editing files.**
 
-### Required search (every task, no exceptions)
+### Required (every task, no exceptions)
 
 ```bash
-maestro search "<1-3 word topic phrase>"
+# 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"` then `maestro search "DetailedTopologySVG" --code`
-- Run multiple targeted searches rather than one broad query
+- 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 (5+ unrelated terms → diluted BM25 scores)
+# ❌ Bad: keyword dump
 maestro search "topology display frontend DetailedTopologySVG elk"
 
-# ✅ Good: targeted multi-search
+# ✅ Good: targeted multi-search + spec load
 maestro search "topology layout"
 maestro search "DetailedTopologySVG" --code
-maestro search "elk layout" --type knowhow
+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]
 ```
 
-Then add follow-up searches based on results:
-- Specific symbol/function → `maestro kg search <symbol>` or `maestro kg context <node>`
-- Architecture/testing → `maestro search --type spec --category arch|test`
-- Call chains → `maestro kg callers <fn>` / `maestro kg callees <fn>`
-- Domain rules → `maestro spec load --category <cat> [--keyword <kw>]`
+**`--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
 
-- **Spec** → `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"`
-- **Knowhow** → persist non-obvious knowledge (deviations, root causes, constraints)
+| What | Command |
+|------|---------|
+| Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
+| Knowhow | Persist non-obvious knowledge (deviations, root causes, constraints) |
 
 Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
 
@@ -120,12 +150,12 @@ Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`l
 When search results conflict with current context, **mark the entry**:
 
 ```bash
-maestro spec conflict mark <file> <line> --note "<conflict reason>"
-maestro spec conflict list                    # view all marked entries
+maestro spec conflict mark <file> <line> --note "<reason>"
+maestro spec conflict list
 ```
 
-Confidence levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
+Levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
 
-- `contested` → 注入时排末尾，`[CONTESTED]` 标记 + 冲突说明
-- `low` → `[LOW CONFIDENCE]` 标记
-- 消除由 `/manage-knowledge-audit` 审查命令专门处理
+- `contested` → sorted last during injection, labeled `[CONTESTED]` with conflict note
+- `low` → labeled `[LOW CONFIDENCE]`
+- Resolution handled by `/manage-knowledge-audit`

package/workflows/debug.md

@@ -1,9 +1,5 @@
 # Debug Workflow
 
-Scientific method debugging with subagent isolation. Three modes: **Standalone** (user describes issue), **From UAT** (`--from-uat`, pre-filled symptoms), **Parallel** (`--parallel`, concurrent agents per gap cluster).
-
-Output: `understanding.md` + `evidence.ndjson` per investigation.
-
 ---
 
 ## Iron Law

package/workflows/domain-add.md

@@ -0,0 +1,115 @@
+---
+name: domain-add
+alias: domain-add
+---
+
+# Workflow: domain-add
+
+Register a domain term into `.workflow/domain/glossary.yaml`.
+
+## Arguments
+
+```
+$ARGUMENTS: "<canonical> <definition>"
+
+canonical -- kebab-case term name (e.g. "auth-token", "event-bus")
+definition -- one-line definition (≤200 chars)
+```
+
+## Prerequisites
+
+- `.workflow/domain/` directory must exist (run `maestro domain init` if missing)
+
+## Execution Steps
+
+### Step 1: Parse Arguments
+
+```
+Parse $ARGUMENTS:
+  1. canonical = first token (kebab-case, e.g. "auth-token")
+  2. definition = remaining text
+Validate:
+  - canonical is non-empty, kebab-case (lowercase, hyphens only)
+  - definition is non-empty, ≤200 chars
+On failure: show usage `domain-add <canonical> "<definition>"`, exit
+```
+
+### Step 2: Check Glossary State
+
+Verify `.workflow/domain/glossary.yaml` exists. If not, create via `maestro domain init`.
+
+Read existing glossary and check for:
+- **Exact duplicate**: same canonical name already registered → report existing entry, exit
+- **Near match**: Levenshtein distance ≤ 2 or alias overlap → warn, ask to confirm or merge
+
+### Step 3: Extract Metadata
+
+Auto-derive from the definition and codebase context:
+
+- **aliases** (1-3): common abbreviations, Chinese translations, or alternate forms the term is known by
+- **keywords** (3-5): search terms for discovery
+- **tier**: `core` (fundamental project concept) | `extended` (secondary) | `peripheral` (rarely referenced)
+- **relationships**: scan existing glossary for related terms (semantic overlap or dependency)
+
+### Step 4: Register Term
+
+Write via `maestro domain add`:
+
+```bash
+maestro domain add "<canonical>" "<definition>" --tier <tier>
+```
+
+If aliases or relationships identified, update immediately:
+
+```bash
+maestro domain update "<canonical>" --aliases "alias1,alias2" --keywords "kw1,kw2,kw3" --relationships "related-term-1,related-term-2"
+```
+
+Records `source.kind = 'manual'`, `source.registered_at = now`.
+
+### Step 5: Verify Injection
+
+Confirm the term is injectable by checking:
+
+```bash
+maestro domain show "<canonical>"
+```
+
+Display: canonical name, definition, aliases, tier, relationships, and verify command:
+```
+maestro domain list
+```
+
+### Step 6: Report
+
+```
+=== DOMAIN TERM REGISTERED ===
+Term:      {canonical}
+Definition: {definition}
+Aliases:   {alias1, alias2}
+Tier:      {tier}
+Related:   {rel1, rel2}
+Injection: domain-compact (always) + domain-expanded (on keyword match)
+Next:      maestro domain list | maestro domain discover (find more candidates)
+```
+
+## Auto-Discovery Alternative
+
+For batch registration from codebase scanning:
+
+```bash
+maestro domain discover    # scan codebase for term candidates
+maestro domain import      # batch import from external source
+```
+
+## Domain Term Lifecycle
+
+```
+discover/manual → register → active → (optional) deprecated → removed
+                                ↑
+                          update aliases/keywords/relationships
+```
+
+## Output
+
+One domain term entry added to `.workflow/domain/glossary.yaml`.

package/workflows/execute.md

@@ -589,6 +589,13 @@ Append unique entries to .workflow/specs/learnings.md using <spec-entry> closed-
   category="learning", keywords (3-5 terms), date, source="execute"
 
 Mark artifact.harvested = true; write state.json (atomic)
+
+// Domain knowledge note:
+// E5 仅提取 incremental learnings (spec category=learning)。
+// 完整的知识提取（constraints → spec, decisions → knowhow, terminology → domain glossary）
+// 由 chain 末尾的 manage-harvest --auto 触发 finish-work 统一处理。
+// Domain compact/expanded 注入是 hook 自动行为，execute 期间无需手动加载——
+// 已注册术语通过 keyword-spec-injector 自动注入到 agent context 中。
 ```
 
 ---

package/workflows/explore-usage.md

@@ -0,0 +1,133 @@
+# Explore Usage
+
+```bash
+maestro explore "<PROMPT>" [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.
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-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.
+
+## 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]
+```
+
+Only `FIND` required. Plain text (no `FIND:` prefix) also works.
+
+| 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` |
+
+## Execution Model
+
+**Serial within endpoint, parallel across endpoints.**
+
+Same API → jobs queue and run one-by-one (avoids rate limits).
+Different APIs → queues run concurrently.
+
+```
+Endpoint A:  [job1] → [job2] → [job3]    (serial)
+Endpoint B:  [job4] → [job5]              (serial)
+                                           ↑ parallel ↑
+```
+
+Raise per-endpoint parallelism with `--ep-concurrency 2` when the API allows it.
+
+## Multi-Prompt Input
+
+**Inline**: `maestro explore "prompt1" "prompt2" "prompt3"`
+
+**JSON file** (`-f prompts.json`):
+
+```json
+[
+  "simple string prompt",
+  { "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> --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**:
+
+```
+Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
+```
+
+Single quick lookup — foreground is fine:
+
+```
+Bash({ command: "maestro explore \"Where is X defined?\"" })
+```

package/workflows/finish-work.md

@@ -1,7 +1,5 @@
 # Workflow: finish-work
 
-Last step of session commands. Inline-extracts spec/knowhow from this single session, then writes `archive.json` so the session enters `wiki search` (strategy 2: only sealed/archived sessions are indexed).
-
 ## Inputs
 
 Caller passes: `SESSION_DIR`, `SESSION_TYPE` (grill | brainstorm | analyze | blueprint | plan | execute | verify), `SESSION_ID`, `LINKED_MILESTONE` (optional).
@@ -78,10 +76,10 @@ Source priority:
 
 Process:
   1. 从 session 产物中收集术语候选
-  2. 过滤已注册的 `glossary.json` terms
+  2. 过滤已注册的 `glossary.yaml` terms
   3. 0 个新候选 → 跳过（静默）
   4. ≥ 1 个新候选 → 交互确认（domain 注册始终需要用户确认，`-y` 对 domain 无效）
-  5. 确认的术语写入 `glossary.json` via `maestro domain add`
+  5. 确认的术语写入 `glossary.yaml` via `maestro domain add`
   6. 记录到 `archive.json` 的 `extraction.domain_ids[]`
 
 Skip conditions:
@@ -130,8 +128,6 @@ Next: /maestro-milestone-complete will flip lifecycle.status → archived and pr
 
 ## Idempotency
 
-Re-running on same session: archive.json overwritten with fresh timestamps. Steps 2-3 skipped when existing `archive.json.extraction.harvested == true` (avoids duplicate spec/knowhow). Force re-extract: delete `archive.json` first.
-
 ## Boundary
 
 - Does NOT flip `archived_at` or move files — that is milestone-complete Step 2.3.

package/workflows/fork.md

@@ -1,9 +1,5 @@
 # Workflow: fork
 
-Create a git worktree for an entire milestone, enabling inter-milestone parallel development. Copies `.workflow/` context into the worktree since `.workflow/` is gitignored.
-
-Worktrees operate at the **milestone level** — all phases within a milestone are owned by one worktree and executed sequentially inside it. Per-phase parallelism within a milestone is not supported.
-
 ---
 
 ## Step 1: Parse Arguments and Flags