catlog22 Two execution modes:
- Router (default): Analyze intent -> match chain template -> create session -> step execution
- Direct (
--cmd <name> <args>): Load and execute a specific command inline
Execution uses maestro-flow next/done CLI for step lifecycle management.
Commands loaded via maestro-flow resolve + Read() for inline execution.
External steps delegated via maestro delegate --to claude "/maestro-flow --cmd ...".
Session path: .workflow/.maestro/flow-{YYYYMMDD-HHmmss}/status.json
Skill directory structure (relative to this SKILL.md):
maestro-flow/
SKILL.md <- this file (router)
executor.md <- step execution loop (deferred read)
commands/
lifecycle/ <- 17 commands: init, analyze, plan, execute, verify, ...
quality/ <- 7 commands: debug, review, test, auto-test, ...
manage/ <- 10 commands: status, issue, wiki, harvest, ...
learn/ <- 5 commands: decompose, follow, investigate, ...
milestone/ <- 3 commands: audit, complete, release
spec/ <- 4 commands: add, load, remove, setup
wiki/ <- 2 commands: connect, digest
chains/
templates.json <- 14 chain templates + decision types
State files:
.workflow/state.json-- project artifact registry (optional).workflow/.maestro/flow-*/status.json-- flow session state
CLI prerequisite: maestro-flow command must be globally available (npm install -g maestro-flow-one)
Step 1: Parse & Route
Parse $ARGUMENTS:
--cmd <name> <remaining-args>
-> Step 1a: Direct Command Execution
-> End.
list
-> Bash: maestro-flow list
-> End.
status [session-id]
-> Bash: maestro-flow status [session-id]
-> End.
chains
-> Bash: maestro-flow chains
-> End.
execute | continue
-> Read executor.md from deferred_reading
-> Follow executor.md completely
-> End.
--chain <name> [-y] <remaining>
-> Force chain selection, go to Step 4
-y / --yes
-> auto_confirm = true
Other text
-> intent = remaining text -> Step 2
Step 1a: Direct Command Execution (--cmd)
1. Bash: maestro-flow resolve <name>
-> Returns absolute path to command .md file
2. If NOT_FOUND -> Error. End.
3. Read() the command .md file
4. Set $ARGUMENTS = <remaining-args>
5. Follow the command's <execution> section completely
End.
Step 2: Read Project State (optional)
If .workflow/state.json exists:
Read -> extract: current_milestone, milestones, artifacts
If not: state_summary = "Project not initialized"
Step 3: Intent Analysis & Chain Matching
Bash: maestro-flow suggest "{intent}"
Display top 3 chain options
AskUserQuestion: select chain / single command / Cancel
If auto_confirm: pick highest scoring chain
If single command: --cmd -> Step 1a
If chain selected: -> Step 4
Step 3.5: Task Decomposition (broad lifecycle intents)
Shares the decomposition contract with maestro-ralph A_DECOMPOSE_TASKS — reference that spec; do not duplicate.
Classify intent breadth:
broad = 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp
narrow = single file/function/bug, "fix X", "add Y to Z"
other = medium
Skip decomposition (-> Step 4 directly) WHEN:
narrow intent OR single-command chain OR chain ∈ {status, init, quick}
Else (broad MUST clarify even if auto_confirm; medium clarify unless auto_confirm):
AskUserQuestion ≤3 rounds (options pre-filled from intent + quick Glob/Grep of target module):
1. Scope -> in_scope / out_of_scope
2. Constraints -> constraints + execution_criteria (compat/API/perf/test bar)
3. Done -> definition_of_done
Derive:
execution_criteria = 3-6 imperative rules every step obeys
task_decomposition = outcome sub-goals; each:
{ id:"G1", goal, boundary, done_when, evidence, lifecycle:[...], status:"pending" }
RULE: done_when objectively verifiable, mapped to a ralph evidence artifact
(verification.json | review.json | uat.md | <test path>)
Write {session_dir}/goal-checklist.md (template below) with ALL_GOALS_DONE sentinel.
Stage additive block + goal_checklist_path for Step 4.
Emit the /goal bind prompt:
📋 任务分解完成。复制下面一行设定目标(推荐)：
/goal 当 {session_dir}/goal-checklist.md 子目标全 [x] 且含 ALL_GOALS_DONE 时达成；
否则按执行准则继续推进且不越边界契约
goal-checklist.md template:
# Flow Goal Checklist — {session_id}
> Intent: {intent}
## 执行准则 / Execution Criteria
- {criterion}
## 边界契约 / Boundary Contract
- In scope / Out of scope / Constraints / Definition of Done
## 子目标 / Sub-goals
- [ ] G1: {goal} — done when: {done_when} (evidence: {evidence})
<!-- executor flips [ ]→[x] when evidence confirms; appends ALL_GOALS_DONE when all [x] -->
Step 4: Build Session
4.1: Create session from template
session_id = "flow-{YYYYMMDD-HHmmss}"
session_dir = .workflow/.maestro/{session_id}/
Build steps[] from selected chain template.
If Step 3.5 produced a decomposition:
- Add additive block to status.json (OPTIONAL keys; absent = old behavior;
never remove/rename existing fields — status JSON is schema-additive + step-dynamic):
boundary_contract, execution_criteria, task_decomposition, goal_checklist_path
- Each step gains optional "goal_ref": null
- Append a decision step
{ "cmd":"decision:post-goal-audit", "type":"decision",
"decision":"post-goal-audit", "retry_count":0, "max_retries":2 }
as the FINAL node — after the last evidence-producing step (verify/review/test),
before a milestone-complete/close-out step if the chain ends with one
(audit needs evidence artifacts to exist)
Write status.json.
Display chain steps (+ Sub-goals: {n} if decomposed), confirm (or auto if -y).
Fall through to Phase 2.
Phase 2: Step Execution Loop
Read executor.md from deferred_reading and follow it completely.
Executor loop: maestro-flow next -> route by type -> execute -> maestro-flow done -> Skill({ skill: "maestro-flow", args: "execute" }) until SESSION_COMPLETE.