maestro-flow 0.3.47 → 0.3.48

package/.codex/skills/maestro/SKILL.md

@@ -16,10 +16,6 @@ Entry points:
 - **`$maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/maestro.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
-</required_reading>
-
 <deferred_reading>
 - [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
 </deferred_reading>
@@ -51,7 +47,7 @@ $ARGUMENTS — user intent text, or special flags.
 <states>
 S_PARSE         — 解析参数、检测 flags              PERSIST: —
 S_CONTINUE      — 加载已有 session，定位 resume 点   PERSIST: session (loaded)
-S_CLASSIFY      — 意图分类、解析 chain               PERSIST: —
+S_CLASSIFY      — 意图分类、解析 chain (A_CLASSIFY)   PERSIST: —
 S_CREATE        — 创建 session + status.json         PERSIST: session.status, session.steps[]
 S_DRY_RUN       — 显示 chain 后结束                  PERSIST: —
 S_CONFIRM       — 用户确认（auto_mode 跳过）          PERSIST: —
@@ -73,7 +69,7 @@ S_CONTINUE:
   → S_FALLBACK    WHEN: no session found
 
 S_CLASSIFY:
-  → S_CREATE      WHEN: chain resolved (keyword match or maestro.codex.md lookup)
+  → S_CREATE      WHEN: chain resolved                      DO: A_CLASSIFY
   → S_FALLBACK    WHEN: no match AND auto_mode
   → S_CLASSIFY    WHEN: no match AND not auto_mode          DO: A_CLARIFY_INTENT
                    GUARD: max 1 clarification attempt → S_FALLBACK
@@ -113,7 +109,7 @@ S_FALLBACK:
 ### A_CREATE_SESSION
 
 1. Read `.workflow/state.json` for project context (current phase, milestone, workflow_name)
-2. Resolve chain's skill list from chain_map or maestro.codex.md
+2. Resolve chain's skill list from Chain Map (see appendix)
 3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
    ```json
    { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
@@ -132,6 +128,85 @@ S_FALLBACK:
 2. Find first pending step → set as resume point
 3. Rebuild `update_plan` from status.json (completed→"completed", current→"in_progress", rest→"open")
 
+### A_CLASSIFY
+
+**Layer 1: Exact-match (fast path)**
+- `--chain <name>` flag → validate against chainMap, use directly (E002 if not found)
+- `continue`/`next`/`go`/`继续`/`下一步` → `state_continue`
+- `status`/`状态`/`dashboard` → `status`
+
+If matched, skip to chain resolution.
+
+**Layer 2: Structured intent extraction**
+
+Extract tuple from intent using LLM semantic understanding:
+```json
+{
+  "action":    "<create|fix|analyze|plan|execute|verify|review|test|debug|refactor|explore|manage|transition|continue|sync|learn|retrospect>",
+  "object":    "<feature|bug|issue|code|test|spec|phase|milestone|doc|performance|security|ui|memory|codebase|config>",
+  "scope":     "<module/file/area or null>",
+  "issue_id":  "<ISS-XXXXXXXX-NNN or null>",
+  "phase_ref": "<integer or null>",
+  "urgency":   "<low|normal|high>"
+}
+```
+
+Disambiguation: "问题"/"issue"/"problem" as broken → `object: "bug"` (→ debug); as tracked item (with ISS-ID or management context) → `object: "issue"` (→ issue management). When ambiguous, prefer `"bug"`.
+
+**Layer 3: action × object routing matrix**
+
+If `issue_id` present → issue pipeline directly.
+
+| action | object-specific overrides | default |
+|--------|--------------------------|---------|
+| fix | bug/code/perf/security→`debug`, issue→`issue` | `debug` |
+| create | feature→`quick`, issue→`issue`, test→`test_gen`, spec→`spec_generate`, ui→`ui_design`, config→`init` | `quick` |
+| analyze | bug/code→`analyze`, issue→`issue_analyze`, codebase→`spec_map` | `analyze` |
+| explore | issue→`issue_discover`, feature/ui→`brainstorm`/`ui_design` | `brainstorm` |
+| plan | issue→`issue_plan`, spec→`spec_generate` | `plan` |
+| execute | issue→`issue_execute` | `execute` |
+| manage | issue→`issue`, milestone→`milestone_audit`, phase→`phase_transition`, memory/doc/codebase→`memory`/`sync`/`codebase_refresh` | `status` |
+| transition | phase→`phase_transition`, milestone→`milestone_complete` | `phase_transition` |
+| verify, review, test, debug, refactor, continue, sync, learn, retrospect, release, amend, compose | — | self-named |
+
+**Clarity scoring**: 3=action+object+scope, 2=action+object, 1=action only, 0=empty.
+If `clarity < 2` and not `auto_mode` → transition to A_CLARIFY_INTENT.
+
+**Layer 4: State-based routing** (when `taskType === 'state_continue'`)
+
+Read `.workflow/state.json` and route by condition:
+
+| Condition | Chain |
+|-----------|-------|
+| Not initialized | `init` |
+| No phases, no roadmap, has accumulated_context | `next-milestone` |
+| No phases | `brainstorm-driven` |
+| pending + has context | `plan` |
+| pending, no context | `analyze` |
+| exploring/planning + has plan | `execute-verify` |
+| exploring/planning, no plan | `plan` |
+| executing, all tasks done | `verify` |
+| executing, tasks remain | `execute` |
+| verifying, passed + no review | `review` |
+| verifying, passed + BLOCK | `review-fix` |
+| verifying, passed + UAT pending | `test` |
+| verifying, passed + UAT passed | `milestone-close` |
+| verifying, passed + UAT failed | `debug` |
+| verifying, not passed | `quality-loop-partial` |
+| testing, UAT passed | `milestone-close` |
+| testing, UAT not passed | `debug` |
+| completed | `milestone-close` |
+| blocked | `debug` |
+| fallback | `status` |
+
+**Chain resolution order:**
+1. `forceChain` → `chainMap[forceChain]` (E002 if not found)
+2. `state_continue` → Layer 4 state routing → `{ chain, argsOverride? }`
+3. `taskToChain[taskType]` → alias lookup (see Chain Aliases below)
+4. `chainMap[taskType]` → direct lookup
+
+**Phase resolution**: structured extraction `phase_ref` → fallback regex (`phase N` or bare number) → `projectState.current_phase`.
+
 ### A_CLARIFY_INTENT
 
 1. `AskUserQuestion` with available chain types
@@ -177,23 +252,90 @@ S_FALLBACK:
 
 <appendix>
 
-### Chain Map (Quick Reference)
-
-| Intent keywords | Chain | Steps |
-|----------------|-------|-------|
-| fix, bug, error, broken | `quality-fix` | analyze --gaps → plan --gaps → execute → verify |
-| test, spec, coverage | `quality-test` | quality-test |
-| refactor, cleanup, debt | `quality-refactor` | quality-refactor |
-| feature, implement, add | `feature` | plan → execute → verify |
-| review, check, audit | `quality-review` | quality-review |
-| deploy, release, ship | `deploy` | verify → milestone-release |
-| brainstorm, explore, ideate | `brainstorm-driven` | brainstorm → plan → execute → verify |
-| plan, design, architect | `plan` | plan |
-| debug, diagnose | `debug` | quality-debug |
-| continue, next | `state_continue` | (from project state) |
-| status, dashboard | `status` | manage-status |
-
-Full chain map (40+ chains): `@~/.maestro/workflows/maestro.codex.md` §3c
+### Chain Map (Full)
+
+**Single-step chains:**
+
+| Chain | Command + Args |
+|-------|---------------|
+| `status` | `manage-status` |
+| `init` | `maestro-init` |
+| `analyze` | `maestro-analyze {phase}` |
+| `ui_design` | `maestro-ui-design {phase}` |
+| `plan` | `maestro-plan {phase}` |
+| `execute` | `maestro-execute {phase}` |
+| `verify` | `maestro-verify {phase}` |
+| `test_gen` | `quality-auto-test {phase}` |
+| `auto_test` | `quality-auto-test {phase}` |
+| `test` | `quality-test {phase}` |
+| `debug` | `quality-debug "{description}"` |
+| `integration_test` | `quality-auto-test {phase}` |
+| `refactor` | `quality-refactor "{description}"` |
+| `review` | `quality-review {phase}` |
+| `retrospective` | `quality-retrospective {phase}` |
+| `learn` | `maestro-learn "{description}"` |
+| `sync` | `quality-sync` |
+| `milestone_audit` | `maestro-milestone-audit` |
+| `milestone_complete` | `maestro-milestone-complete` |
+| `codebase_rebuild` | `manage-codebase-rebuild` |
+| `codebase_refresh` | `manage-codebase-refresh` |
+| `spec_setup` | `spec-setup` |
+| `spec_add` | `spec-add "{description}"` |
+| `spec_load` | `spec-load` |
+| `spec_map` | `manage-codebase-rebuild` |
+| `spec_remove` | `spec-remove "{description}"` |
+| `knowhow_capture` | `manage-knowhow-capture "{description}"` |
+| `knowhow` | `manage-knowhow "{description}"` |
+| `issue` | `manage-issue "{description}"` |
+| `issue_discover` | `manage-issue-discover "{description}"` |
+| `issue_analyze` | `maestro-analyze --gaps "{description}"` |
+| `issue_plan` | `maestro-plan --gaps` |
+| `issue_execute` | `maestro-execute` |
+| `quick` | `maestro-quick "{description}"` |
+| `harvest` | `manage-harvest "{description}"` |
+| `wiki` | `manage-wiki` |
+| `wiki_connect` | `wiki-connect` |
+| `wiki_digest` | `wiki-digest` |
+| `business_test` | `quality-auto-test {phase}` |
+| `amend` | `maestro-amend "{description}"` |
+| `release` | `maestro-milestone-release` |
+| `compose` | `maestro-composer "{description}"` |
+| `play` | `maestro-player "{description}"` |
+| `update` | `maestro-update` |
+| `overlay` | `maestro-overlay "{description}"` |
+| `link_coordinate` | `maestro-link-coordinate "{description}"` |
+
+**Multi-step chains:**
+
+| Chain | Steps (→ = sequential, [B] = barrier) |
+|-------|---------------------------------------|
+| `feature` | [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
+| `deploy` | maestro-verify → maestro-milestone-release |
+| `spec-driven` | maestro-init → [B] maestro-roadmap --mode full → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `ui-design-driven` | maestro-ui-design → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → maestro-verify → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
+| `execute-verify` | [B] maestro-execute → maestro-verify |
+| `analyze-plan-execute` | [B] maestro-analyze -q → [B] maestro-plan --dir {scratch_dir} → [B] maestro-execute --dir {scratch_dir} |
+| `quality-loop` | maestro-verify → quality-review → quality-test → quality-debug --from-uat → [B] maestro-plan --gaps → [B] maestro-execute |
+| `quality-loop-partial` | [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
+| `review-fix` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
+| `milestone-close` | maestro-milestone-audit → maestro-milestone-complete |
+| `milestone-release` | maestro-milestone-audit → maestro-milestone-release |
+| `phase_transition` | maestro-milestone-audit → maestro-milestone-complete |
+| `issue-full` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
+| `issue-quick` | [B] maestro-plan --gaps → [B] maestro-execute → manage-issue close |
+
+**Chain Aliases** (taskType → chain):
+
+| taskType | Chain |
+|----------|-------|
+| `spec_generate` | `spec-driven` |
+| `brainstorm` | `brainstorm-driven` |
+| `issue_execute` | `issue-full` |
 
 ### Auto-Yes Flag Map
 

package/.codex/skills/maestro-ralph/SKILL.md

@@ -156,17 +156,28 @@ S_FALLBACK -> S_PARSE_ROUTE WHEN: user input | -> END WHEN: cancel
 | Has .workflow/ but no state.json | init |
 | Has state.json | artifact-based inference |
 
-**Artifact-based**: filter by current_milestone + target phase. Latest artifact type: none->analyze, analyze->plan, plan->execute, execute->verify, verify->refine from result files:
+**Artifact-based inference:** Filter by current_milestone + target phase:
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] non-empty | verify-failed |
-| passed==true, no review.json, has auto-test report | review |
-| passed==true, no review.json, no auto-test report | business-test (full) / review (standard/quick) |
-| review.json: verdict=="BLOCK" | review-failed |
-| review.json: verdict!="BLOCK" | test |
-| uat.md: all passed | milestone-audit |
-| uat.md: has failures | test-failed |
+| no milestones defined or no roadmap.md | `roadmap` |
+| no artifacts for target phase | `analyze` |
+| latest artifact = analyze | `plan` |
+| latest artifact = plan | `execute` |
+| latest artifact = execute | `verify` |
+| latest artifact = verify | → refine from result files |
+
+**Refine from verify results:**
+
+| Condition | Position |
+|-----------|----------|
+| verification.json: passed==false or gaps[] non-empty | `verify-failed` |
+| passed==true, no review.json, has auto-test report | `review` |
+| passed==true, no review.json, no auto-test report | `business-test` (full) / `review` (standard/quick) |
+| review.json: verdict=="BLOCK" | `review-failed` |
+| review.json: verdict!="BLOCK" | `test` |
+| uat.md: all passed | `milestone-audit` |
+| uat.md: has failures | `test-failed` |
 
 ### A_RESOLVE_PHASE
 
@@ -182,23 +193,32 @@ Priority: regex from intent `phase\s*(\d+)` -> latest in-progress artifact's pha
 
 ### A_BUILD_STEPS
 
-Lifecycle stages (start from position, skip completed, filter by quality_mode):
-
-| Stage | Skill | Barrier | Decision after |
-|-------|-------|---------|----------------|
-| brainstorm | maestro-brainstorm | yes | -- |
-| init | maestro-init | no | -- |
-| roadmap | maestro-roadmap | yes | -- |
-| analyze | maestro-analyze | yes | -- |
-| plan | maestro-plan | yes | -- |
-| execute | maestro-execute | yes | -- |
-| verify | maestro-verify | no | post-verify |
-| business-test | quality-auto-test | no | post-business-test (full) |
-| review | quality-review | no | post-review |
-| test-gen | quality-auto-test | no | -- (full; standard if coverage<80%) |
-| test | quality-test | no | post-test |
-| milestone-audit | maestro-milestone-audit | no | -- |
-| milestone-complete | maestro-milestone-complete | no | post-milestone |
+**Lifecycle stages:**
+
+| Stage | Skill | Barrier | Quality Mode | Decision after |
+|-------|-------|---------|-------------|----------------|
+| brainstorm | maestro-brainstorm "{intent}" | yes | all | — |
+| init | maestro-init | no | all | — |
+| roadmap | maestro-roadmap "{intent}" | yes | all | — |
+| analyze | maestro-analyze {phase} | yes | all | — |
+| plan | maestro-plan {phase} | yes | all | — |
+| execute | maestro-execute {phase} | yes | all | — |
+| verify | maestro-verify {phase} | no | all | post-verify |
+| business-test | quality-auto-test {phase} | no | full only | post-business-test |
+| review | quality-review {phase} | no | all (quick: --tier quick) | post-review |
+| test-gen | quality-auto-test {phase} | no | full; standard if coverage<80% | — |
+| test | quality-test {phase} | no | full, standard | post-test |
+| milestone-audit | maestro-milestone-audit | no | all | — |
+| milestone-complete | maestro-milestone-complete | no | all | post-milestone |
+
+**Build rules:**
+1. Start from `lifecycle_position`, end at `milestone-complete`
+2. Skip stages with existing completed artifacts (check state.json)
+3. Filter stages by `quality_mode` — skip non-applicable stages (see Quality Mode column)
+4. Quick mode: `review` appends `--tier quick`; skips `business-test`, `test-gen`, `test`
+5. Insert decision node after each stage with non-empty Decision column: `{ type: "decision", decision: "<gate>", retry_count: 0, max_retries: 2 }`
+6. Args use placeholders `{phase}`, `{intent}`, `{dirs}` — resolved at wave execution time
+7. Append `-y` to all skill args when `auto_mode` is true (see -y propagation table in context)
 
 ### A_BUILD_AND_SPAWN_WAVE
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.47",
+  "version": "0.3.48",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {