maestro-flow 0.5.3 → 0.5.31

package/workflows/claude-instructions.md

@@ -1,7 +1,5 @@
 # Maestro
 
-Workflow orchestration CLI with MCP endpoint support and extensible architecture.
-
 - **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
 
 ## Delegate & CLI
@@ -11,64 +9,38 @@ Workflow orchestration CLI with MCP endpoint support and extensible architecture
 
 **Strictly follow the cli-tools.json configuration**
 
-Available CLI endpoints are dynamically defined by the config file
-
-## Code Diagnostics
-
-- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation
-
 ## Knowledge System
 
-### Design Principles
-
-- **Single search entry** — `maestro search` is the only user-facing search command
-- **Silent-skip-is-bug** — if knowledge exists but search misses it, that is a defect
-- **Layer 2 auto-injection** — agents receive specs via hooks, rarely need manual `spec load`
-
-### Search — Three-Layer Architecture
-
-**Before planning or implementing, search first.** Load the right knowledge at the right time.
-
-| Layer | Command | When to Use |
-|-------|---------|-------------|
-| **1. Unified** | `maestro search "<query>" [--type spec\|knowhow\|issue] [--category <cat>]` | Daily search — BM25 full-text across all knowledge types |
-| **2. Agent injection** | `maestro spec load --category <cat> [--keyword <kw>]` | Domain rules for implementation (auto-injected by hooks) |
-| **3. Code structure** | `maestro kg search <symbol>` / `maestro kg context <node>` | Tracing dependencies, call chains, module boundaries |
-
-**Deprecated** (do not use): `spec search`, `knowhow search`, `wiki search` — all replaced by Layer 1.
-
-KG stays fresh via hooks (`kg-sync` on UserPromptSubmit, `kg-context-injector` on Agent spawn). Manual `maestro kg index --sqlite` only needed on initial setup.
+**ALWAYS search before acting.** Never assume context is pre-loaded.
 
-### Proactive Search — Mandatory Triggers
+### Search Commands
 
-Search is **not optional**. Execute these commands before acting in the corresponding scenarios:
+| 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 |
 
-| Trigger Condition | Command | Purpose |
-|---|---|---|
-| Starting any implementation task | `maestro search "<feature/module keywords>"` | Load relevant specs, knowhow, existing issues |
-| Encountering unknown symbol/module | `maestro kg search "<symbol>"` | Understand code structure and dependencies |
-| Understanding module boundaries | `maestro kg context <file-or-symbol>` | Get callers, callees, related code |
-| Making architecture decisions | `maestro search --type spec --category arch` | Load architecture constraints |
-| Debugging unfamiliar code | `maestro kg callers <function>` / `maestro kg callees <function>` | Trace call chains |
-| Before writing tests | `maestro search --type spec --category test "<module>"` | Load test patterns and requirements |
-| Before refactoring | `maestro kg search "<module>" --code` | Map impact radius before changes |
+Do not use deprecated commands: `spec search`, `knowhow search`, `wiki search`.
 
-### Fallback — When Hooks Are Not Firing
+### Proactive Search — ALWAYS Execute
 
-If automatic injection seems absent (no `<maestro-context>` blocks appearing):
+**L0 — Every task, no exceptions:**
+- `maestro search "<feature/module keywords>"`
 
-1. Check hook status: `maestro hooks status`
-2. Sync graph manually: `maestro kg sync`
-3. Search directly: `maestro search "<query>"` or `maestro kg search "<symbol>"`
-4. Reinstall hooks if needed: `maestro hooks install --level standard`
+**L1 — Unfamiliar code:**
+- `maestro kg search "<symbol>"`
+- `maestro kg context <file-or-symbol>`
 
-### Record — Capture Knowledge
+**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`
 
-When execution surfaces non-obvious knowledge, persist it:
+### Record
 
-- **Spec entry** (short rule/constraint) → `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"`
-- **Knowhow document** (detailed recipe/template/decision) → `/manage-knowhow-capture`
-  - Use `--spec-category <cat>` to bridge knowhow into agent injection
-  - Files use `{PREFIX}-{YYYYMMDD}-{slug}.md` naming for readable filenames
+- **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`, test strategy→`test`.
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.

package/workflows/codex-instructions.md

@@ -6,99 +6,49 @@
 
 **Strictly follow the cli-tools.json configuration**
 
-Available CLI endpoints are dynamically defined by the config file
-
-## Code Quality Standards
-
-### Code Quality
-- Follow project's existing patterns
-- Match import style and naming conventions
-- Single responsibility per function/class
-- DRY (Don't Repeat Yourself)
-- YAGNI (You Aren't Gonna Need It)
-
-### Testing
-- Test all public functions
-- Test edge cases and error conditions
-- Mock external dependencies
-- Target 80%+ coverage
-
-### Error Handling
-- Proper try-catch blocks
-- Clear error messages
-- Graceful degradation
-- Don't expose sensitive info
-
 ## Core Principles
 
-**Incremental Progress**:
-- Small, testable changes
-- Commit working code frequently
-- Build on previous work (subtasks)
-
-**Evidence-Based**:
+- Follow project's existing patterns and conventions
+- Single responsibility, DRY, YAGNI
+- Small testable changes, commit frequently
 - Study 3+ similar patterns before implementing
-- Match project style exactly
-- Verify with existing code
-
-**Pragmatic**:
 - Boring solutions over clever code
-- Simple over complex
-- Adapt to project reality
-
-**Context Continuity** (Multi-Task):
-- Leverage resume for consistency
-- Maintain established patterns
-- Test integration between subtasks
 
-**Git Operations** (Parallel Task Safety):
-- Only stage/commit files directly produced by current task
-- Never touch unrelated changes or other task outputs
+**Git Operations:**
+- Only stage/commit files produced by current task
 - Use `git add <specific-files>` instead of `git add .`
-- Verify staged files before commit to avoid cross-task conflicts
-
-**Multi-CLI Coexistence** (CRITICAL):
-- If your task conflicts with existing uncommitted changes, **STOP and report the conflict** instead of overwriting
-- Treat all pre-existing uncommitted changes as intentional work-in-progress by other tools
 
+**Multi-CLI Coexistence (CRITICAL):**
+- Conflicts with uncommitted changes → **STOP and report**, never overwrite
 
 ## Knowledge System
 
-### Search — Query Before Acting
-
-**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
-
-- `maestro search "<query>" [--type spec|knowhow|issue] [--category <cat>]` — BM25 full-text across all knowledge types
-- `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
-- `maestro spec load --keyword <kw>` — cross-category keyword match
-### Proactive Search — Mandatory Triggers
+**ALWAYS search before acting.** Never assume context is pre-loaded.
 
-Search is **not optional**. Execute these commands before acting in the corresponding scenarios:
+### Search Commands
 
-| Trigger Condition | Command | Purpose |
-|---|---|---|
-| Starting any implementation task | `maestro search "<feature/module keywords>"` | Load relevant specs, knowhow, existing issues |
-| Encountering unknown symbol/module | `maestro kg search "<symbol>"` | Understand code structure and dependencies |
-| Understanding module boundaries | `maestro kg context <file-or-symbol>` | Get callers, callees, related code |
-| Making architecture decisions | `maestro search --type spec --category arch` | Load architecture constraints |
-| Debugging unfamiliar code | `maestro kg callers <function>` / `maestro kg callees <function>` | Trace call chains |
-| Before writing tests | `maestro search --type spec --category test "<module>"` | Load test patterns and requirements |
-| Before refactoring | `maestro kg search "<module>" --code` | Map impact radius before changes |
+- `maestro search "<query>" [--type spec|knowhow|issue] [--category <cat>]`
+- `maestro spec load --category <cat>` / `--keyword <kw>`
+- `maestro kg search <symbol>` / `maestro kg context <node>`
 
-### Fallback — When Hooks Are Not Firing
+### Proactive Search — ALWAYS Execute
 
-If automatic injection seems absent (no `<maestro-context>` blocks appearing):
+**L0 — Every task, no exceptions:**
+- `maestro search "<feature/module keywords>"`
 
-1. Check hook status: `maestro hooks status`
-2. Sync graph manually: `maestro kg sync`
-3. Search directly: `maestro search "<query>"` or `maestro kg search "<symbol>"`
-4. Reinstall hooks if needed: `maestro hooks install --level standard`
+**L1 — Unfamiliar code:**
+- `maestro kg search "<symbol>"`
+- `maestro kg context <file-or-symbol>`
 
-### Knowledge Capture
+**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`
 
-- **Spec writes** → always `<spec-entry>` closed-tag format with `title`, `description`, `category`, `keywords`, `date`, `source`. Never raw Markdown. Route through `spec-add` when possible.
-- **Capture signal** → when execution surfaces non-obvious knowledge (plan deviation, retry pattern, root cause, constraint violation), ask user once whether to persist it. Match category to content: decisions→`arch`, pitfalls→`debug`/`learning`, patterns→`coding`, rules→`quality`.
-- **Promotion** → at milestone close, scan learnings for repeated keywords (≥2 entries) and offer to graduate them into formal conventions.
-- **Traceability** → every entry needs a source anchor: `file:line`, `INS-{id}`, commit, or phase path.
+### Record
 
+- **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`.

package/workflows/coding-philosophy.md

@@ -1,70 +1,70 @@
-# 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
+# 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