maestro-flow 0.5.41 → 0.5.43

package/workflows/agy-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/claude-instructions.md

@@ -5,89 +5,141 @@
 ## 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
+## 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.
 
-## Knowledge System
+```bash
+maestro explore "FIND: <target + condition>\nSCOPE: <paths>" [more prompts...] [options]
+```
 
-**Gate rule: On any coding/modification/debugging task, run `maestro search` + `maestro load` BEFORE reading code or editing files.**
+Lightweight read-only codebase search. 1 prompt = 1 agent. Not for write-mode/long sessions — use `delegate`.
 
-### Required (every task, no exceptions)
+| 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 |
 
-```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
 ```
+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
 
-**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)
+对重要搜索，用 2-3 个不同角度的 prompt 并发，结果由 Claude 交叉验证。
+
+**按角度拆分，不按关键词拆分：**
+
+| 角度 | Prompt A | Prompt B |
+|------|----------|----------|
+| 定义 vs 调用 | 找函数定义 | 找调用点 |
+| 正例 vs 反例 | 找正确用法 | 找遗漏用法 |
+| 入口 vs 实现 | 找 export/路由 | 找内部逻辑 |
+| 按文件类型 | .ts 中的用法 | .vue 中的用法 |
 
 ```bash
-# ❌ Bad: keyword dump
-maestro search "topology display frontend DetailedTopologySVG elk"
+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：
 
-# ✅ Good: targeted multi-search + spec load
-maestro search "topology layout"
-maestro search "DetailedTopologySVG" --code
-maestro load --type spec --category coding
 ```
+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>`
 
-### Load & Search reference
+## 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>]
-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**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
+**--category** (spec only): `coding`, `arch`, `debug`, `test`, `review`, `learning`, `ui`
 
-**`--type` values**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
+### Query Rules
 
-| 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` |
+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>` to bridge into agent injection) |
+| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` for 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**:
+### Conflict Marking
 
 ```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`
+Levels: `high` → `medium` (default) → `low` (`[LOW CONFIDENCE]`) → `contested` (`[CONTESTED]`).
+Resolution: `/manage-knowledge-audit`