pi-maestro-flow 0.2.0 → 0.3.0

package/skills/maestro-quick/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-quick
 description: "Quick task execution, skip optional agents Arguments: [description] [--full] [--discuss] [-y]"
-allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -10,9 +10,7 @@ Flags --discuss and --full enable additional pipeline stages.
 **Implicit write**: state.json scratch task entry is written automatically as part of workflow tracking (no confirmation gate).
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/quick.md
-</required_reading>
+> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/quick.md` before proceeding.
 
 <context>
 $ARGUMENTS
@@ -40,7 +38,7 @@ Parse for:
 2. **Evidence-based summaries** — task summaries MUST include concrete evidence (files changed, tests run, commands executed); NEVER accept "task completed successfully" as a summary
 3. **Plan before execute** — plan.json MUST be written before any task execution begins; NEVER skip planning even for single-task workflows
 4. **Scratch isolation** — all workflow artifacts MUST live under `.workflow/scratch/{task-dir}/`; NEVER write workflow metadata outside this directory
-5. **Commit confirmation** — staged files and commit message MUST be shown via AskUserQuestion before committing (unless `-y`); NEVER auto-commit without user awareness
+5. **Commit confirmation** — staged files and commit message MUST be shown via user prompt before committing (unless `-y`); NEVER auto-commit without user awareness
 </invariants>
 
 <execution>
@@ -63,7 +61,7 @@ Parse for:
 - REQUIRED: --full verification passed (if flag set).
 - BLOCKED if: any task summary missing or lacking evidence.
 
-Follow '~/.maestro/workflows/quick.md' completely.
+Follow '~/.pi/agent/packages/pi-maestro-flow/workflows/quick.md' completely.
 
 ### Artifact Verification (before completion)
 
@@ -113,5 +111,5 @@ maestro ralph complete <idx> --status {DONE|DONE_WITH_CONCERNS|NEEDS_RETRY|BLOCK
 - [ ] plan.json written with task definitions
 - [ ] All tasks executed with summaries written
 - [ ] state.json updated with scratch task entry (implicit — part of workflow tracking, no confirmation needed)
-- [ ] Commit created with task changes: stage ONLY files modified by the task (from `.summaries/TASK-*-summary.md` "Files modified" list); confirm with `AskUserQuestion` showing staged files and proposed commit message — unless `-y` is active, in which case auto-commit
+- [ ] Commit created with task changes: stage ONLY files modified by the task (from `.summaries/TASK-*-summary.md` "Files modified" list); confirm with `user prompt` showing staged files and proposed commit message — unless `-y` is active, in which case auto-commit
 </success_criteria>

package/skills/maestro-ralph/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph
 description: "[LEGACY — prefer maestro-ralph-v2] Inline lifecycle orchestrator — state-based determination with main-session execution Arguments: <intent> [-y] | status | continue | --amend [change]"
-allowed-tools: Read Write Edit Bash Glob Grep Skill AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep maestro
 ---
 
 <purpose>
@@ -9,9 +9,8 @@ Closed-loop decision engine: read project state → infer position → build ada
 Ralph builds/evaluates; ralph-execute runs steps. Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`.
 </purpose>
 
-<deferred_reading>
-- [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
-</deferred_reading>
+> **Reference files** (read when needed):
+> - [ralph-amend-goal.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
 
 <context>
 $ARGUMENTS — intent text, flags, or keywords.
@@ -46,7 +45,7 @@ Remaining     → intent (amend_mode 时为 change_request)
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作。不得以 "效率" 或 "意图明确" 为由绕过。特别是 invariant 1（ralph 不执行 step）和 invariant 6（completion_confirmed 由 CLI 写入）不可隐性违反。
 13. **Delegate fallback 必须标记** — A_DELEGATE_EVALUATE 解析 verdict 失败时 fallback 为 "fix"，但 MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`，后续 step 继承 LOW CONFIDENCE 标记。
 14. **auto_confirm 单一来源** — `auto_confirm` 仅由用户 `-y` 标志设定；ralph 不得内部推断。`session.auto_mode` 仅反映用户输入。
-15. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有（`source=="ralph"` → `decomposition_owner="ralph"`；`source=="maestro"` → `"maestro"`）。contract 已存在时，后续 S_DECOMPOSE MUST 跳过 AskUserQuestion，仅做 shape 校验 + 缺省补齐；goal-audit 只更新 `task_decomposition[*].status/completion_confirmed/completed_at`，禁止改 `goal/done_when/boundary`。
+15. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有（`source=="ralph"` → `decomposition_owner="ralph"`；`source=="maestro"` → `"maestro"`）。contract 已存在时，后续 S_DECOMPOSE MUST 跳过 user prompt，仅做 shape 校验 + 缺省补齐；goal-audit 只更新 `task_decomposition[*].status/completion_confirmed/completed_at`，禁止改 `goal/done_when/boundary`。
 16. **控制权优先级（范式治理）** — FSM 独占 session 生命周期 + step 排序 + retry/fix/escalate + cross-step decision 节点；Pipeline 命令只拥有自身 artifact GATE（GATE 失败 → `maestro ralph complete <idx> --status BLOCKED|NEEDS_RETRY`，自身 GATE 全过 → DONE）；Router 命令不得出现在 FSM step 内。
 </invariants>
 
@@ -129,7 +128,7 @@ S_CONFIRM:
   → END             WHEN: user selects "Cancel"
 
 S_DISPATCH:
-  → END             DO: Skill({ skill: "maestro-ralph-execute" })
+  → END             DO: invoke /skill: "maestro-ralph-execute" })
 
 S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取自该字段)
   → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test, post-frontend-verify)
@@ -162,16 +161,16 @@ S_APPLY_VERDICT:
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
-  GUARD: not auto_confirm → AskUserQuestion with override options
+  GUARD: not auto_confirm → user prompt with override options
   GUARD: post-reground + drifted + confidence_score >= 60 → A_REGROUND_HALT（漂移熔断为安全门，auto_confirm 不跳过）
 
 S_AMEND_GOAL:
   → S_DISPATCH      WHEN: change applied + user confirmed    DO: A_AMEND_GOAL
   → END             WHEN: user cancels
-  GUARD: RISK_LEVEL=high → auto_confirm 无效，必须 AskUserQuestion
+  GUARD: RISK_LEVEL=high → auto_confirm 无效，必须 user prompt
 
 S_FALLBACK:
-  → S_PARSE_ROUTE   WHEN: user provides input               DO: AskUserQuestion
+  → S_PARSE_ROUTE   WHEN: user provides input               DO: user prompt
   → END             WHEN: user cancels
 
 </transitions>
@@ -203,7 +202,7 @@ S_FALLBACK:
 | 3 | 未派生 → 取最新 in-progress artifact 的 phase | false |
 | 4 | 仍无 → state.json 首个 incomplete phase | false |
 | 5 | position 将是 brainstorm/blueprint/init/roadmap/analyze-macro → phase = null | n/a |
-| 6 | 仍模糊 → `AskUserQuestion` | 由用户回答确定 |
+| 6 | 仍模糊 → `user prompt` | 由用户回答确定 |
 
 **D-007 Phase→Milestone 反查**（数字 phase 已解析时）：
 ```
@@ -317,9 +316,9 @@ wants_roadmap = (--roadmap flag)
 | intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
 | milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
 | milestone 含多个 phase + `auto_confirm` | `unified` | 自动模式倾向高效 |
-| milestone 含多个 phase + 非 `auto_confirm` | → AskUserQuestion | 征询用户选择 |
+| milestone 含多个 phase + 非 `auto_confirm` | → user prompt | 征询用户选择 |
 
-**AskUserQuestion** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
+**user prompt** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
 
 ```
 question: "当前里程碑含 {N} 个 phase，选择规划模式？"
@@ -346,7 +345,7 @@ Runs once before chain build; additive to status.json. 设 `session.decompositio
 | named single file/function/bug, "fix X", "add Y to Z" | narrow | skip — auto-derive |
 | otherwise | medium | clarify unless auto_confirm |
 
-**2. Clarify boundary** (broad/medium) — `AskUserQuestion`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
+**2. Clarify boundary** (broad/medium) — `user prompt`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
 
 | Round | Question | Drives |
 |-------|----------|--------|
@@ -632,7 +631,7 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
    - 把下一个未完成的 `plan` step 改为 `maestro-plan --from analyze:{analyze_macro_id}`，去掉 `{phase}`，`source_artifact_ref = analyze:{analyze_macro_id}`
    - 后续 `execute` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
 4. 路径 C（`unknown`）：
-   - 非 auto_confirm → AskUserQuestion 二选一（roadmap 多发布 / 单一计划）；auto_confirm → 默认路径 B（单一计划，不引入 roadmap）
+   - 非 auto_confirm → user prompt 二选一（roadmap 多发布 / 单一计划）；auto_confirm → 默认路径 B（单一计划，不引入 roadmap）
 5. Reindex steps，标 decision completed，write status.json
 6. Display: ◆ Scope verdict: {verdict} → {kept|collapsed to standalone via analyze:{ANL_ID}}
 
@@ -668,12 +667,12 @@ GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
 | Phase | 行为 | 产出 |
 |-------|------|------|
 | 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
-| 2. 解析 | `change_request` 非空 → 直接用；为空 → AskUserQuestion（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 2. 解析 | `change_request` 非空 → 直接用；为空 → user prompt（修改/新增/移除/调整边界） | `change_type` + `change_request` |
 | 3. Mini Grill | `maestro delegate --to {session.cli_tool} --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
-| 4. 确认 | AskUserQuestion：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 4. 确认 | user prompt：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff ralph-execute |
 
-GUARD: `RISK_LEVEL == high` → AskUserQuestion 不跳过（auto_confirm 无效）
+GUARD: `RISK_LEVEL == high` → user prompt 不跳过（auto_confirm 无效）
 GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 
 </actions>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph-cli
 description: "[LEGACY — prefer maestro-ralph-v2] CLI-delegated lifecycle orchestrator — compose, delegate, analyze, decide in one loop Arguments: <intent> [-y] [--to <tool>] [--amend [change]] [--roadmap] | status | continue"
-allowed-tools: Read Write Edit Bash Glob Grep Skill AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep maestro
 ---
 
 <purpose>
@@ -191,7 +191,7 @@ S_APPLY_VERDICT:
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
-  GUARD: not auto_confirm → AskUserQuestion with override options
+  GUARD: not auto_confirm → user prompt with override options
   GUARD: post-reground + drifted + confidence >= 60 → A_REGROUND_HALT（auto_confirm 不跳过）
 
 S_HANDLE_FAIL:
@@ -221,7 +221,7 @@ S_SESSION_DONE:
 | 3 | 未派生 → 取最新 in-progress artifact 的 phase | false |
 | 4 | 仍无 → state.json 首个 incomplete phase | false |
 | 5 | position 将是 brainstorm/blueprint/init/roadmap/analyze-macro → phase = null | n/a |
-| 6 | 仍模糊 → `AskUserQuestion` | 由用户回答确定 |
+| 6 | 仍模糊 → `user prompt` | 由用户回答确定 |
 
 **D-007 Phase→Milestone 反查**（数字 phase 已解析时）：
 ```
@@ -335,9 +335,9 @@ wants_roadmap = (--roadmap flag)
 | intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
 | milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
 | milestone 含多个 phase + `auto_confirm` | `unified` | 自动模式倾向高效 |
-| milestone 含多个 phase + 非 `auto_confirm` | → AskUserQuestion | 征询用户选择 |
+| milestone 含多个 phase + 非 `auto_confirm` | → user prompt | 征询用户选择 |
 
-**AskUserQuestion** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
+**user prompt** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
 
 ```
 question: "当前里程碑含 {N} 个 phase，选择规划模式？"
@@ -364,7 +364,7 @@ Runs once before chain build; additive to status.json. 设 `session.decompositio
 | named single file/function/bug, "fix X", "add Y to Z" | narrow | skip — auto-derive |
 | otherwise | medium | clarify unless auto_confirm |
 
-**2. Clarify boundary** (broad/medium) — `AskUserQuestion`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
+**2. Clarify boundary** (broad/medium) — `user prompt`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
 
 | Round | Question | Drives |
 |-------|----------|--------|

package/skills/maestro-ralph-cli-execute/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph-cli-execute
 description: "Skill execution wrapper for delegate — execute skill, return structured result Arguments: --session <id> | <skill-name> [args...]"
-allowed-tools: Read Write Edit Bash Glob Grep Skill AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep maestro
 ---
 
 <purpose>
@@ -73,7 +73,7 @@ S_OUTPUT → END         DO: A_OUTPUT_RESULT
    - Exit 1 → required_reading 缺失或 schema 错误 → set `status = "BLOCKED"`, skip to S_OUTPUT, SUMMARY 引用 CLI stderr
    - Exit 2 → 无 pending step（已全部完成）→ set `status = "DONE"`, SUMMARY = "所有 step 已完成", skip to S_OUTPUT
    - Exit 3 → active_step_index 冲突（另一进程占用）→ set `status = "BLOCKED"`, SUMMARY = "并发冲突", skip to S_OUTPUT
-2. If no session → `Skill({ skill: skill_name, args: skill_args })` — direct skill call
+2. If no session → `invoke /skill: skill_name, args: skill_args })` — direct skill call
 3. **Goal context**: `ralph next` CLI 输出的 session_anchor 已含 goal context（`ralph_protocol_version >= "2"`），无需额外注入
 4. **Deferred reading**: `ralph next` 将 `<deferred_reading>` 路径记录到 `step.load.deferred_files`，执行阶段按需 Read
 5. **Inline execution** — 按 stdout 内容执行 skill 逻辑；执行完成后进入 S_SCAN

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph-execute
 description: "Execute next pending step in ralph session Arguments: [-y] [session-id]"
-allowed-tools: Read Write Edit Bash Glob Grep Skill
+allowed-tools: Read Write Edit Bash Glob Grep maestro
 ---
 
 <purpose>
@@ -31,7 +31,7 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 HARD RULES:
 - 执行 step：**统一通过 `maestro ralph next` CLI 加载**。CLI 负责读 command_path、解析 `<required_reading>` + `<deferred_reading>`、拼接 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`。不要再在会话里手动 Read + 解析 required_reading
-- decision step：A_EXEC_DECISION 通过 `Skill({ skill: "maestro-ralph" })` handoff 给 ralph 评估（不走 CLI）
+- decision step：A_EXEC_DECISION 通过 `invoke /skill: "maestro-ralph" })` handoff 给 ralph 评估（不走 CLI）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（缺失 → ralph next 返回 E006/E007 并拒绝执行）
 - 每个 step 结束必须调用 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`。STATUS 仅 4 个合法值：`DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`（**`NEEDS_CONTEXT` 已废除**，context 容量由 harness 自动压缩处理）
 </context>
@@ -203,7 +203,7 @@ Write enriched args + source_artifact_ref back to status.json.
 
 1. Mark step running, write status.json
 2. Display: `[{index}/{total}] ◆ {step.decision} Retry: {retry}/{max}`
-3. `Skill({ skill: "maestro-ralph" })` — ralph 评估 + handoff
+3. `invoke /skill: "maestro-ralph" })` — ralph 评估 + handoff
 4. 执行在此结束
 
 ### A_EXEC_STEP
@@ -271,7 +271,7 @@ Write enriched args + source_artifact_ref back to status.json.
 
 6. **Propagate context signals** — 按 4c checklist 将关键信号写入 `status.json.context`
 
-完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
+完成后 S_LOCATE 触发 `invoke /skill: "maestro-ralph-execute" })` 自调用。
 
 ### A_POST_ANALYZE_DRIFT
 

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph-v2
 description: "[RECOMMENDED] Adaptive lifecycle orchestrator — compose, dispatch ralph-executor agent, evaluate decision, loop Arguments: <intent> [-y] [--amend [change]] [--roadmap] | status | continue"
-allowed-tools: Read Write Edit Bash Glob Grep Skill AskUserQuestion Agent SendMessage
+allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -10,9 +10,8 @@ Adaptive lifecycle orchestrator: locate step → resolve args → load context
 Session: `.workflow/.maestro/ralph-v2-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
 
-<deferred_reading>
-- [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
-</deferred_reading>
+> **Reference files** (read when needed):
+> - [ralph-amend-goal.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
 
 <context>
 $ARGUMENTS — intent text, flags, or keywords.
@@ -180,7 +179,7 @@ S_APPLY_VERDICT:
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
-  GUARD: not auto_confirm → AskUserQuestion with override options
+  GUARD: not auto_confirm → user prompt with override options
   GUARD: post-reground + drifted + confidence >= 60 → A_REGROUND_HALT（auto_confirm 不跳过）
 
 S_HANDLE_FAIL:
@@ -210,7 +209,7 @@ S_SESSION_DONE:
 | 3 | 未派生 → 取最新 in-progress artifact 的 phase | false |
 | 4 | 仍无 → state.json 首个 incomplete phase | false |
 | 5 | position 将是 brainstorm/blueprint/init/roadmap/analyze-macro → phase = null | n/a |
-| 6 | 仍模糊 → `AskUserQuestion` | 由用户回答确定 |
+| 6 | 仍模糊 → `user prompt` | 由用户回答确定 |
 
 **D-007 Phase→Milestone 反查**（数字 phase 已解析时）：
 ```
@@ -324,9 +323,9 @@ wants_roadmap = (--roadmap flag)
 | intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
 | milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
 | milestone 含多个 phase + `auto_confirm` | `unified` | 自动模式倾向高效 |
-| milestone 含多个 phase + 非 `auto_confirm` | → AskUserQuestion | 征询用户选择 |
+| milestone 含多个 phase + 非 `auto_confirm` | → user prompt | 征询用户选择 |
 
-**AskUserQuestion** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
+**user prompt** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
 
 ```
 question: "当前里程碑含 {N} 个 phase，选择规划模式？"
@@ -353,7 +352,7 @@ Runs once before chain build; additive to status.json. 设 `session.decompositio
 | named single file/function/bug, "fix X", "add Y to Z" | narrow | skip — auto-derive |
 | otherwise | medium | clarify unless auto_confirm |
 
-**2. Clarify boundary** (broad/medium) — `AskUserQuestion`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
+**2. Clarify boundary** (broad/medium) — `user prompt`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
 
 | Round | Question | Drives |
 |-------|----------|--------|
@@ -571,7 +570,7 @@ Execution criteria: {session.execution_criteria joined by '; '}
 > 执行 Agent 不传 name，结果通过 task-notification `<result>` 自动回传主流程。executor 内部编排也用 unnamed Agent（子结果自动回流 executor，嵌套套娃模型）。
 
 ```
-Agent({
+teammate({
   subagent_type: "ralph-executor",
   description: "执行 step {index}: {step.skill} [{resolved_agent_name}]",
   prompt: `Session: {session_id}
@@ -739,7 +738,7 @@ Agent({
 **Mode: `agent`（默认）** — 同步 Agent 评估：
 
 ```
-Agent({
+teammate({
   description: "评估 {decision} 质量门（同步评估 Agent，不传 name）",
   prompt: "PURPOSE: 评估 {decision} 质量门结果
 TASK: 读取以下结果文件 | 分析状态 | 评估严重性 | 给出建议
@@ -803,7 +802,7 @@ Bash({
 1. Read `session.task_decomposition` from status.json
 2. Dispatch audit（按 `evaluate_via` 模式，默认 `agent`）:
    ```
-   Agent({
+   teammate({
      description: "审计子目标完成情况（同步评估 Agent，不传 name）",
      prompt: "PURPOSE: 审计未完成子目标，判定 met / unmet
    TASK:
@@ -839,7 +838,7 @@ Bash({
 1. Read status.json：intent, boundary_contract, completed steps, done goals
 2. Dispatch reground（按 `evaluate_via` 模式，默认 `agent`）:
    ```
-   Agent({
+   teammate({
      description: "意图保真检查（同步评估 Agent，不传 name）",
      prompt: "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
    TASK:
@@ -905,7 +904,7 @@ Bash({
 
 1. 路径 A（`large` 且 `wants_roadmap`）：保持 roadmap+analyze，`plan` 选 phase 列
 2. 路径 B（`medium`/`small`，或 `large` 非 `wants_roadmap`）：删除未完成的 `roadmap` + `analyze` step，`plan` 改为 `--from analyze:{ANL_ID}`
-3. 路径 C（`unknown`）：非 auto_confirm → AskUserQuestion；auto_confirm → 默认路径 B
+3. 路径 C（`unknown`）：非 auto_confirm → user prompt；auto_confirm → 默认路径 B
 4. Reindex steps，标 decision completed
 
 ### A_APPLY_GOAL_FIX / A_APPLY_GOAL_DONE
@@ -931,14 +930,14 @@ Bash({
 | Phase | 行为 | 产出 |
 |-------|------|------|
 | 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
-| 2. 解析 | `change_request` 非空 → 直接用；为空 → AskUserQuestion（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 2. 解析 | `change_request` 非空 → 直接用；为空 → user prompt（修改/新增/移除/调整边界） | `change_type` + `change_request` |
 | 3. Mini Grill | Agent 评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
-| 4. 确认 | AskUserQuestion：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 4. 确认 | user prompt：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | re-dispatch |
 
 **Phase 3 Agent prompt:**
 ```
-Agent({
+teammate({
   description: "Amend impact analysis（同步评估 Agent，不传 name）",
   prompt: "PURPOSE: 评估目标修改对 running session 的影响
 TASK:
@@ -962,7 +961,7 @@ CONSTRAINTS: 只评估不修改文件"
 })
 ```
 
-GUARD: `RISK_LEVEL == high` → AskUserQuestion 不跳过（auto_confirm 无效）
+GUARD: `RISK_LEVEL == high` → user prompt 不跳过（auto_confirm 无效）
 GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 旧目标标 `superseded`（`superseded_by` + `superseded_at`），新目标标 `origin: "CHG-xxx"`。`goal_changelog` 含完整 `before/after` + `impact_assessment`。
 
@@ -1163,7 +1162,7 @@ E001–E006, W001–W004 适用。Agent 新增：
 ### Success Criteria
 
 - [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → wait task-notification → extract → drift → complete → next
-- [ ] One agent per step — `Agent({ subagent_type: "ralph-executor" })` 每步派发一个 unnamed executor
+- [ ] One agent per step — `teammate({ subagent_type: "ralph-executor" })` 每步派发一个 unnamed executor
 - [ ] Executor 内调 `maestro ralph next` 获取 skill prompt 并执行，内部编排用 unnamed Agent（子结果回流 executor）
 - [ ] Executor 结果通过 task-notification `<result>` 自动回传主流程
 - [ ] 主流程调 `maestro ralph complete` 上报（非 agent 上报）

package/skills/maestro-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
 description: "Generate roadmap with milestone/phase structure from requirements or upstream context Arguments: <requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
-allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -11,13 +11,12 @@ Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {milestone}
 </purpose>
 
 <required_reading>
-@~/.maestro/workflows/roadmap-common.md
-@~/.maestro/templates/roadmap.md
+Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap-common.md`.
+@~/.pi/agent/packages/pi-maestro-flow/templates/roadmap.md
 </required_reading>
 
-<deferred_reading>
-- [roadmap.md](~/.maestro/workflows/roadmap.md) — read for roadmap generation workflow
-</deferred_reading>
+> **Reference files** (read when needed):
+> - [roadmap.md](~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap.md) — read for roadmap generation workflow
 
 <context>
 $ARGUMENTS -- requirement text, @file reference, or upstream context source.
@@ -48,7 +47,7 @@ $ARGUMENTS -- requirement text, @file reference, or upstream context source.
 </context>
 
 <interview_protocol>
-Follows @~/.maestro/workflows/interview-mechanics.md standard.
+Follows `~/.pi/agent/packages/pi-maestro-flow/workflows/interview-mechanics.md` standard.
 
 **Interaction mode**: convergent menu-driven
 **Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
@@ -60,8 +59,8 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 <execution>
 
-1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
-2. Read `@~/.maestro/workflows/roadmap.md`, follow its process
+1. Read `@~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap-common.md` (always — shared logic)
+2. Read `@~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap.md`, follow its process
 
 Sub-modes:
 - **Create** (default): Build roadmap from requirements or upstream context

package/skills/maestro-swarm-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-swarm-workflow
 description: "Parallel workflow accelerator — route intent to fixed Workflow scripts for multi-agent concurrent execution Arguments: <intent> [--script <name>] [--dims <d1,d2>] [--roles <r1,r2>] [--count N] [--tier quick|standard] [--resume <runId>]"
-allowed-tools: Read Write Edit Bash Glob Grep Workflow AskUserQuestion
+allowed-tools: Read Write Edit Bash Glob Grep Workflow maestro
 ---
 
 <purpose>
@@ -23,7 +23,7 @@ $ARGUMENTS — intent text with optional flags.
 Remaining        → intent
 ```
 
-**Script inventory** (`~/.maestro/workflows/swarm/`):
+**Script inventory** (`~/.pi/agent/packages/pi-maestro-flow/workflows/swarm/`):
 
 | Script | args 接口 |
 |--------|-----------|
@@ -36,7 +36,7 @@ Remaining        → intent
 | `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
 | `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
 
-**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.pi/agent/packages/pi-maestro-flow/workflows/swarm/`), or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -58,7 +58,7 @@ S_PARSE:
 
 S_ROUTE:
   → S_CONTEXT   WHEN: script resolved              DO: A_ROUTE_SCRIPT
-  → S_FALLBACK  WHEN: ambiguous intent              DO: AskUserQuestion
+  → S_FALLBACK  WHEN: ambiguous intent              DO: user prompt
 
 S_CONTEXT:
   → S_DISPATCH  DO: A_ASSEMBLE_CONTEXT
@@ -101,7 +101,7 @@ Intent-to-script routing（按关键词匹配，--script 优先级最高）。
 | 7 | 头脑风暴 / brainstorm / 方案 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
 | 8 | 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
 
-**Disambiguation**: 多命中（同一优先级内多个关键词匹配不同脚本）→ AskUserQuestion 让用户选择。跨优先级命中取高优先级。
+**Disambiguation**: 多命中（同一优先级内多个关键词匹配不同脚本）→ user prompt 让用户选择。跨优先级命中取高优先级。
 
 ### A_ASSEMBLE_CONTEXT
 
@@ -134,7 +134,7 @@ Intent-to-script routing（按关键词匹配，--script 优先级最高）。
 
 ### A_DISPATCH_WORKFLOW
 
-1. 确定 scriptPath = `~/.maestro/workflows/swarm/{script}.js`（展开为绝对路径）
+1. 确定 scriptPath = `~/.pi/agent/packages/pi-maestro-flow/workflows/swarm/{script}.js`（展开为绝对路径）
 2. 构建 Workflow 调用：
    ```
    Workflow({
@@ -186,7 +186,7 @@ Workflow 返回 JSON 后：
 2. **args 预编译** — 所有 FS 读取在 A_ASSEMBLE_CONTEXT 完成，脚本内 agent 通过工具自行读取补充
 3. **产出格式兼容** — 写入的 artifact 格式必须与对应命令（analyze/brainstorm/review/verify）的产出一致
 4. **resume 透传** — resumeFromRunId 直接透传给 Workflow 工具，利用内置缓存机制
-5. **脚本只读** — 路由命令不修改 `~/.maestro/workflows/swarm/wf-*.js` 脚本文件
+5. **脚本只读** — 路由命令不修改 `~/.pi/agent/packages/pi-maestro-flow/workflows/swarm/wf-*.js` 脚本文件
 6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
 </invariants>
 
@@ -204,7 +204,7 @@ Workflow 返回 JSON 后：
 
 **GATE 3: Context → Dispatch**
 - REQUIRED: Args payload assembled with all required fields for target script.
-- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- REQUIRED: Script file exists at `~/.pi/agent/packages/pi-maestro-flow/workflows/swarm/{script}.js`.
 - BLOCKED if: script file not found (E003) or required args missing.
 
 **GATE 4: Dispatch → Ingest**
@@ -264,7 +264,7 @@ ralph-execute 正常通过 `maestro ralph next` 加载并执行，swarm-workflow
 | Code | Description | Recovery |
 |------|-------------|----------|
 | E001 | No intent and no --script | Prompt for intent |
-| E002 | Ambiguous routing | AskUserQuestion |
+| E002 | Ambiguous routing | user prompt |
 | E003 | Script file not found | Check .claude/workflows/ |
 | E004 | Workflow execution failed | Show error, suggest --resume |
 | E005 | Result ingestion failed | Write raw JSON to scratch |

package/skills/maestro-tools-execute/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-tools-execute
 description: "Load and execute tool specs by category or name Arguments: [<tool-name> | --category <category>] [--list]"
-allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion Agent
+allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -9,9 +9,7 @@ Load registered tool documents and execute them step-by-step.
 Direct (by name) or category-based (list + select) invocation.
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/tools-spec.md
-</required_reading>
+> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md` before proceeding.
 
 <context>
 $ARGUMENTS — Tool name, keyword, or --category filter
@@ -28,7 +26,7 @@ Empty arguments enters interactive mode: list all tools for user selection.
 </context>
 
 <invariants>
-1. **Confirmation before execution** — MUST AskUserQuestion before executing tool steps; NEVER auto-execute without user consent
+1. **Confirmation before execution** — MUST user prompt before executing tool steps; NEVER auto-execute without user consent
 2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
 3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
 4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
@@ -73,7 +71,7 @@ maestro load --type spec --category <category>
 Extract tool entries from the "Available Tools" section in output.
 
 **Empty args**:
-Load all categories, collect tool entries, present to user with AskUserQuestion for selection.
+Load all categories, collect tool entries, present to user with user prompt for selection.
 
 ### Step 2: Display Tool
 
@@ -104,7 +102,7 @@ Follow the tool definition steps in order:
 
 **Blocker handling**:
 - Step fails → report error, ask user: retry / skip / abort
-- Needs user input → AskUserQuestion for parameters
+- Needs user input → user prompt for parameters
 - Prerequisites unmet → show missing items, ask how to proceed
 
 ### Step 5: Report Results

package/skills/maestro-tools-register/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-tools-register
 description: "Register tool specs - extract, generate, or optimize Arguments: [<description>] [--extract <path>] [--optimize <name>]"
-allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion Agent
+allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -9,9 +9,7 @@ Codify reusable business processes as knowhow documents with `tool: true` in `.w
 Four modes: Extract, Generate, Optimize, Promote. Short processes inline; long use ref mode.
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/tools-spec.md
-</required_reading>
+> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md` before proceeding.
 
 <context>
 $ARGUMENTS — Intent description
@@ -31,7 +29,7 @@ $ARGUMENTS — Intent description
 1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords`, and `summary` in YAML frontmatter; missing fields → reject write
 2. **No duplicate names** — tool title MUST be unique within its category; duplicate detection → E002 warning with overwrite/optimize confirmation
 3. **Category required** — every tool MUST declare exactly one category from: coding, test, review, arch, debug; empty category → E003
-4. **Confirmation gate** — MUST AskUserQuestion before writing knowhow document and spec ref entry; NEVER persist without user confirmation
+4. **Confirmation gate** — MUST user prompt before writing knowhow document and spec ref entry; NEVER persist without user confirmation
 5. **Promote is in-place** — promote mode MUST update existing knowhow frontmatter via `maestro wiki update`; NEVER recreate the document
 6. **Output boundary** — ALL file writes MUST target .workflow/knowhow/ (tool documents) and .workflow/specs/ (ref entries via maestro spec add) only. NEVER modify source code or files outside these paths
 7. **Description format** — first line after `### Title` MUST state "Use when ..." (usage timing); this is critical for ref entry summary visibility in spec-load
@@ -44,7 +42,7 @@ $ARGUMENTS — Intent description
 **GATE 1: Parse → Gather**
 - REQUIRED: Mode determined (extract/generate/optimize/promote) from argument parsing.
 - REQUIRED: For optimize/promote modes, target tool/document exists and is loadable.
-- BLOCKED if: empty args without user response to AskUserQuestion.
+- BLOCKED if: empty args without user response to user prompt.
 
 **GATE 2: Gather → Write**
 - REQUIRED: Tool name, category, and usage timing confirmed.
@@ -65,7 +63,7 @@ Parse $ARGUMENTS to determine mode:
 - Contains "optimize/improve" → optimize mode
 - Contains "promote" or references existing knowhow doc (path/ID) → promote mode
 - Other → generate mode
-- Empty → ask user with AskUserQuestion
+- Empty → ask user with user prompt
 
 ### Step 2: Gather Information
 
@@ -75,7 +73,7 @@ Parse $ARGUMENTS to determine mode:
 
 **Generate mode**:
 - Confirm tool name, applicable roles, target scenario
-- If unclear, ask user with AskUserQuestion
+- If unclear, ask user with user prompt
 
 **Optimize mode**:
 - Load existing tool: `maestro search "<name>" --type knowhow` → `maestro load --type knowhow --id <id>`
@@ -121,7 +119,7 @@ Use when {timing/trigger condition}.
 1. Step one ...
 ```
 
-**Confirm before writing** — Use `AskUserQuestion` to show the user the planned knowhow document (title, category, keywords, summary, step count) and spec ref entry before persisting:
+**Confirm before writing** — Use `user prompt` to show the user the planned knowhow document (title, category, keywords, summary, step count) and spec ref entry before persisting:
 
 ```
 question: "确认写入以下 knowhow 工具文档？"