maestro-flow 0.5.33 → 0.5.35

package/workflows/claude-instructions.md

@@ -1,45 +1,63 @@
-# Maestro
-
-- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
-
-## Delegate & CLI
-
-- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
-- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
-
-**Strictly follow the cli-tools.json configuration**
-
-## Knowledge System
-
-**ALWAYS search before acting.** Never assume context is pre-loaded.
-
-### Search Commands
-
-| Layer | Command | Purpose |
-|-------|---------|---------|
-| **1. Unified** | `maestro search "<query>" [--type spec\|knowhow\|issue] [--category <cat>]` | All knowledge types |
-| **2. Domain rules** | `maestro spec load --category <cat> [--keyword <kw>]` | Load rules before coding |
-| **3. Code structure** | `maestro kg search <symbol>` / `maestro kg context <node>` | Dependencies, call chains |
-
-
-### Proactive Search — ALWAYS Execute
-
-**L0 — Every task, no exceptions:**
-- `maestro search "<feature/module keywords>"`
-
-**L1 — Unfamiliar code:**
-- `maestro kg search "<symbol>"`
-- `maestro kg context <file-or-symbol>`
-
-**L2 — Architecture / debugging / refactoring / tests:**
-- `maestro search --type spec --category arch`
-- `maestro kg callers <fn>` / `maestro kg callees <fn>` (注意: `--json` 返回 `{node, callers/callees: [...]}` 对象，非数组)
-- `maestro search --type spec --category test "<module>"`
-- `maestro kg search "<module>" --code`
-
-### 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)
-
-Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
+# Maestro
+
+- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
+
+## Delegate & CLI
+
+- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+**Strictly follow the cli-tools.json configuration**
+
+## 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.**
+
+### Required search (every task, no exceptions)
+
+```bash
+maestro search "<1-3 word topic phrase>"
+```
+
+**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
+
+```bash
+# ❌ Bad: keyword dump (5+ unrelated terms → diluted BM25 scores)
+maestro search "topology display frontend DetailedTopologySVG elk"
+
+# ✅ Good: targeted multi-search
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro search "elk layout" --type knowhow
+```
+
+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>]`
+
+### 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)
+
+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 "<conflict reason>"
+maestro spec conflict list                    # view all marked entries
+```
+
+Confidence levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
+
+- `contested` → 注入时排末尾，`[CONTESTED]` 标记 + 冲突说明
+- `low` → `[LOW CONFIDENCE]` 标记
+- 消除由 `/manage-knowledge-audit` 审查命令专门处理

package/workflows/codex-instructions.md

@@ -1,50 +1,112 @@
 # Codex Code Guidelines
-## Delegate & CLI
+
 
 - **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
 - **CLI Endpoints Config**: @~/.maestro/cli-tools.json
 
 **Strictly follow the cli-tools.json configuration**
 
-## Core Principles
+# 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
 
-- Follow project's existing patterns and conventions
-- Single responsibility, DRY, YAGNI
-- Small testable changes, commit frequently
-- Study 3+ similar patterns before implementing
-- Boring solutions over clever code
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
 
-**Git Operations:**
-- Only stage/commit files produced by current task
-- Use `git add <specific-files>` instead of `git add .`
+## Tooling
 
-**Multi-CLI Coexistence (CRITICAL):**
-- Conflicts with uncommitted changes → **STOP and report**, never overwrite
+- 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
 
-**ALWAYS search before acting.** Never assume context is pre-loaded.
+**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.**
 
-### Search Commands
+### Required search (every task, no exceptions)
 
-- `maestro search "<query>" [--type spec|knowhow|issue] [--category <cat>]`
-- `maestro spec load --category <cat>` / `--keyword <kw>`
-- `maestro kg search <symbol>` / `maestro kg context <node>`
+```bash
+maestro search "<1-3 word topic phrase>"
+```
 
-### Proactive Search — ALWAYS Execute
+**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
 
-**L0 — Every task, no exceptions:**
-- `maestro search "<feature/module keywords>"`
+```bash
+# ❌ Bad: keyword dump (5+ unrelated terms → diluted BM25 scores)
+maestro search "topology display frontend DetailedTopologySVG elk"
 
-**L1 — Unfamiliar code:**
-- `maestro kg search "<symbol>"`
-- `maestro kg context <file-or-symbol>`
+# ✅ Good: targeted multi-search
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro search "elk layout" --type knowhow
+```
 
-**L2 — Architecture / debugging / refactoring / tests:**
-- `maestro search --type spec --category arch`
-- `maestro kg callers <fn>` / `maestro kg callees <fn>` 
-- `maestro search --type spec --category test "<module>"`
-- `maestro kg search "<module>" --code`
+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>]`
 
 ### Record
 
@@ -52,3 +114,18 @@
 - **Knowhow** → persist non-obvious knowledge (deviations, root causes, constraints)
 
 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 "<conflict reason>"
+maestro spec conflict list                    # view all marked entries
+```
+
+Confidence levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
+
+- `contested` → 注入时排末尾，`[CONTESTED]` 标记 + 冲突说明
+- `low` → `[LOW CONFIDENCE]` 标记
+- 消除由 `/manage-knowledge-audit` 审查命令专门处理

package/workflows/command-authoring.md

@@ -526,7 +526,7 @@ The two styles are complementary: FSM orchestrators invoke pipeline commands; pi
 | Style | Commands |
 |-------|----------|
 | **Pipeline** | init, analyze, plan, execute, verify, brainstorm, grill, blueprint, roadmap, milestone-audit, milestone-complete, milestone-release |
-| **FSM** | ralph, ralph-execute, ralph-beta |
+| **FSM** | ralph, ralph-execute |
 | **Needs evaluation** | coordinate (multi-role handoff may need FSM) |
 
 ---

package/workflows/plan.md

@@ -261,6 +261,7 @@ Output: `plan.json` (summary, approach, task_ids[], task_count, complexity, wave
 - Group simple unrelated changes into a batch task to minimize agent spawns
 - depends_on only for genuine output dependencies; most tasks should be parallel
 - Each task must be substantial (15-60 min); sub-5-min changes must be merged
+- **Vertical slice for UI**: a user-facing feature is ONE end-to-end task/wave (backend endpoint + frontend wiring + integration); never split into backend-only/frontend-only. Each UI delivery wave needs ≥1 task carrying a `[UI-observable]` convergence criterion (verifiable user flow; runtime-checked by ralph frontend-verify gate)
 
 ### Deep Work Rules (MANDATORY for all modes)
 
@@ -322,7 +323,7 @@ Bidirectional linking (main flow, post-planner): update matching issues in `.wor
 
 1. **Spawn workflow-plan-checker agent**
    - Input: plan.json + all .task/TASK-*.json + index.json (success_criteria)
-   - Check dimensions: requirements coverage, feasibility, dependency correctness (no circular deps), convergence criteria quality (grep-verifiable, no subjective language), read_first completeness, action concreteness (no vague references), wave structure (no conflicting files), completeness (no orphan tasks)
+   - Check dimensions: requirements coverage, feasibility, dependency correctness (no circular deps), convergence criteria quality (grep-verifiable, no subjective language), read_first completeness, action concreteness (no vague references), wave structure (no conflicting files), completeness (no orphan tasks), UI-observable coverage (when plan touches UI: each delivery wave has ≥1 `[UI-observable]` criterion)
 
 2. **Revision loop** (max 3 rounds)
    - Critical issues → re-spawn planner with issues, revise, re-check