pi-maestro-flow 0.2.0 → 0.3.1

package/README.md

@@ -1,99 +1,68 @@
 # pi-maestro-flow
 
-> Maestro workflow orchestration for [Pi](https://github.com/earendil-works/pi) — tools, skills, and agent definitions
+> Maestro workflow orchestration for [Pi](https://github.com/earendil-works/pi) — tools, skills, workflows, and agent definitions
 
-Pi extension providing Maestro's full workflow toolkit: explore/delegate/MOA tools, 113 skills (converted from maestro commands + skills), and 28 agent definitions. Built on [pi-teammate](../pi-teammate/) for the execution engine.
+Pi extension providing Maestro's full workflow toolkit. Built on [pi-teammate](../pi-teammate/) for the execution engine.
 
-## Features
+## Contents
 
-### Tools
+| Resource | Count | Description |
+|----------|-------|-------------|
+| **Extension tools** | 3 | `maestro`, `maestro-wait`, `maestro-status` |
+| **Skills** | 113 | All maestro commands + skills as `/skill:name` |
+| **Agent definitions** | 28 | For teammate dispatch |
+| **Workflow docs** | 82 | Bundled reference documentation |
+| **Templates** | 23 | Bundled template files |
 
-| Tool | Purpose |
-|------|---------|
-| `maestro` | Main dispatch — `action: explore \| delegate \| moa` |
-| `maestro-wait` | Block until background runs finish |
-| `maestro-status` | Inspect running/completed teammate fleet |
+## Prerequisites
 
-### Skills (113)
+- **Pi coding agent** — the host runtime
+- **Maestro CLI** — `maestro search`, `maestro load`, `maestro delegate`, `maestro explore`
+- **pi-maestro-teammate** — installed automatically as dependency
 
-All maestro commands and skills converted to Pi skill format. Available as `/skill:name` slash commands.
+## Install
 
-**Workflow orchestration:**
-- `maestro-analyze` — Multi-dimensional analysis with scoring
-- `maestro-plan` — Execution planning with task decomposition
-- `maestro-execute` — Task execution with verification
-- `maestro-ralph-v2` — Adaptive lifecycle orchestrator
-- `maestro-roadmap` — Project roadmap generation
+```bash
+# From npm (installs pi-maestro-teammate automatically)
+pi install npm:pi-maestro-flow
 
-**Quality & review:**
-- `quality-review` — Code quality review
-- `quality-test` — Test generation and execution
-- `quality-refactor` — Refactoring with behavior preservation
-- `security-audit` — Security vulnerability analysis
+# Or from local path
+pi install ./flow
+```
 
-**Odyssey workflows:**
-- `odyssey-planex` — Requirement-to-delivery closed loop
-- `odyssey-debug` — Hypothesis-driven debugging
-- `odyssey-review-test-fix` — Review + test + fix cycle
-- `odyssey-ui` — UI optimization workflow
+After installation:
+- 3 tools available: `maestro`, `maestro-wait`, `maestro-status`
+- 113 skills available as `/skill:name` slash commands
+- 28 agent definitions for teammate dispatch
+- 82 workflow docs bundled at `~/.pi/agent/packages/pi-maestro-flow/workflows/`
 
-**Team orchestration:**
-- `team-coordinator` — Multi-role team pipeline
-- `team-executor` — Session execution
-- `team-frontend` — Frontend development team
-- `team-quality-assurance` — QA pipeline
+## Skills Categories
 
-**Knowledge management:**
-- `spec-add` / `spec-load` / `spec-remove` — Spec CRUD
-- `manage-knowhow-capture` — Knowledge extraction
-- `manage-knowledge-audit` — Knowledge health check
+**Workflow orchestration:** `maestro-analyze`, `maestro-plan`, `maestro-execute`, `maestro-ralph-v2`, `maestro-roadmap`
 
-### Agent Definitions (28)
+**Quality & review:** `quality-review`, `quality-test`, `quality-refactor`, `security-audit`
 
-| Agent | Role |
-|-------|------|
-| `explorer` | Read-only codebase exploration |
-| `delegate` | General-purpose task execution |
-| `workflow-executor` | Atomic task implementation |
-| `workflow-planner` | Execution plan creation |
-| `workflow-reviewer` | Multi-dimensional code review |
-| `workflow-verifier` | Goal-backward verification |
-| `team-worker` | Role-specific pipeline execution |
-| `team-supervisor` | Pipeline health monitoring |
-| ... and 20 more |
+**Odyssey workflows:** `odyssey-planex`, `odyssey-debug`, `odyssey-review-test-fix`, `odyssey-ui`
 
-### Dynamic Provider Registration
+**Team orchestration:** `team-coordinator`, `team-executor`, `team-frontend`, `team-quality-assurance`
 
-On startup, reads `~/.maestro/cli-tools.json` and registers each enabled tool as a Pi provider via `pi.registerProvider()`.
+**Knowledge management:** `spec-add`, `spec-load`, `manage-knowhow-capture`, `manage-knowledge-audit`
 
-## Install
+**Academic writing:** `scholar-writing`, `scholar-review`, `scholar-experiment`, `scholar-thesis-docx`
 
-```bash
-pi install npm:pi-maestro-flow
-# or from local path
-pi install ./flow
-```
-
-Requires `pi-maestro-teammate` as a dependency (installed automatically).
-
-After installation, all 113 skills become available as `/skill:name` slash commands.
-
-## Actions
+## Tool Actions
 
 ### Explore
-
 ```
 { action: "explore", prompts: ["Find authentication middleware"], maxTurns: 6 }
 ```
 
 ### Delegate
-
 ```
 { action: "delegate", prompt: "Fix the login bug", tool: "claude", mode: "write" }
 ```
 
 ### MOA (Mixture-of-Agents)
-
 ```
 { action: "moa", prompts: ["Best approach for caching layer?"] }
 ```
@@ -104,18 +73,21 @@ After installation, all 113 skills become available as `/skill:name` slash comma
 ┌──────────────────────────────────────────┐
 │  pi-maestro-flow                         │
 │                                          │
-│  Extension (tools):                      │
-│    maestro, maestro-wait, maestro-status  │
+│  Extension:                              │
+│    maestro / maestro-wait / maestro-status│
 │                                          │
 │  Skills (113):                           │
-│    maestro-*, odyssey-*, quality-*,       │
-│    team-*, manage-*, spec-*, learn-*      │
+│    maestro-* / odyssey-* / quality-*     │
+│    team-* / manage-* / spec-* / learn-*  │
+│    scholar-* / skill-*                   │
 │                                          │
 │  Agents (28):                            │
-│    workflow-*, team-*, role-*             │
+│    workflow-* / team-* / role-*          │
+│                                          │
+│  Workflows (82) + Templates (23):        │
+│    Bundled reference docs                │
 │                                          │
-│  All dispatch via ──► pi-teammate        │
-│  (spawn pi subprocess)                   │
+│  Dispatch via ──► pi-maestro-teammate    │
 └──────────────────────────────────────────┘
 ```
 

package/agents/cross-role-reviewer.md

@@ -9,7 +9,7 @@ tools:
 
 # Cross-Role Reviewer
 
-You read N role analysis index files from a brainstorm session and report cross-role issues. You do NOT write files. You produce structured text that the orchestrator consumes to drive AskUserQuestion and subsequent file edits.
+You read N role analysis index files from a brainstorm session and report cross-role issues. You do NOT write files. You produce structured text that the orchestrator consumes to drive user prompt and subsequent file edits.
 
 ## Inputs (parsed from your prompt)
 

package/agents/impeccable-agent.md

@@ -64,7 +64,7 @@ These commands ask questions only "if unclear from codebase". When PRODUCT.md an
 
 1. **Load context**: Run `maestro impeccable load-context` to load PRODUCT.md and DESIGN.md
 2. **Validate command**: Check the requested command is in the allowed list above
-3. **Execute**: Read `~/.maestro/workflows/impeccable/{command}.md` → follow workflow instructions
+3. **Execute**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/impeccable/{command}.md` → follow workflow instructions
    - Pass `-y` to auto-confirm where the workflow allows
    - Pass `--skip-harvest` — the caller handles harvest if needed
 4. **Report**: Return the command output (scores, changes made, findings)

package/agents/ralph-executor.md

@@ -43,7 +43,7 @@ Single-step skill executor with multi-agent orchestration capability. Call `maes
 ### Worker Dispatch Template
 
 ```
-Agent({
+teammate({
   description: "执行子任务: {task_description}",
   prompt: "执行以下任务：\n{task_content}\n\n返回执行结果摘要 + 产物路径。"
 })

package/agents/team-worker.md

@@ -77,7 +77,7 @@ Before executing role-specific logic, load available cross-role context:
 Follow the instructions loaded from the role_spec body. This contains the domain-specific execution phases for the role. Key rules:
 
 - Team workers cannot call Agent() to spawn other agents
-- Use CLI tools (`maestro delegate`) or direct tools (Read, Grep, Glob) for analysis — see @~/.maestro/templates/search-tools.md for tool selection
+- Use CLI tools (`maestro delegate`) or direct tools (Read, Grep, Glob) for analysis — see ~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md for tool selection
 - If agent delegation is needed, send a request to the coordinator via SendMessage
 
 ### Context-Aware Signal Emission (Optional)

package/agents/workflow-analyzer.md

@@ -17,7 +17,7 @@ tools:
 You perform structured multi-dimensional analysis of technical topics, proposals, or decisions. You evaluate across six standard dimensions, score each with evidence, and produce actionable recommendations. You are invoked when a decision needs rigorous evaluation before proceeding.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-codebase-mapper.md

@@ -15,7 +15,7 @@ tools:
 You analyze an existing codebase from a specific focus area (tech, arch, features, or concerns). You are typically spawned 4 times in parallel, each mapping a different dimension of the codebase. Your output feeds into planning and execution agents.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-collab-planner.md

@@ -14,7 +14,7 @@ tools:
 You are a collaborative planner that works within a pre-allocated task ID range. Multiple collab-planners run in parallel, each responsible for planning a subset of the work. You coordinate through a shared plan-note.md file and produce task definitions within your assigned ID range.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md
 
 ## Process
 

package/agents/workflow-debugger.md

@@ -16,7 +16,7 @@ tools:
 You perform hypothesis-driven debugging of issues identified by verification or testing. You form hypotheses, design experiments, execute them, and log structured evidence. You iterate until the root cause is found and a fix is implemented, or you reach a checkpoint requiring user input. Maximum 5 hypothesis cycles before checkpoint.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-executor.md

@@ -16,7 +16,7 @@ tools:
 You implement a single task from the execution plan. Each task is executed atomically: you make the code changes, verify the convergence criteria are met, run test commands if defined, create an atomic git commit, and write a completion summary. You never modify code outside the task's scope.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-integration-checker.md

@@ -14,7 +14,7 @@ tools:
 You validate cross-phase integration at milestone boundaries. You check that shared interfaces match across phases, data contracts are honored, and no cross-phase dependencies are broken. You are invoked during milestone audits to ensure phases compose correctly.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Schema Reference
 N/A -- reads code artifacts, not task JSON.

package/agents/workflow-nyquist-auditor.md

@@ -15,7 +15,7 @@ tools:
 You audit test coverage by mapping requirements to test files, calculating coverage metrics, identifying gaps, and generating test stubs for missing coverage. Named after the Nyquist theorem -- you ensure the testing "sample rate" is sufficient to capture the signal of correctness.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Schema Reference
 - `@templates/validation.json` -- defines the validation artifact schema for coverage data and gap reporting

package/agents/workflow-phase-researcher.md

@@ -16,7 +16,7 @@ tools:
 You research the implementation approach for a specific phase of the roadmap. You investigate libraries, patterns, and potential pitfalls relevant to that phase's goals, producing a research document that the planner consumes when creating tasks.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md
 
 ## Process
 

package/agents/workflow-planner.md

@@ -15,7 +15,7 @@ tools:
 You create structured execution plans from context, research, and specifications. You group work into feature-level tasks, assign them to parallel waves, set dependencies only when truly needed, and define verifiable convergence criteria. You support both full planning (detailed) and quick mode (one task per feature, minimal waves).
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-project-researcher.md

@@ -16,7 +16,7 @@ tools:
 You are a domain researcher for project initialization. You explore a specific angle of the project domain (tech stack, architecture, features, or concerns) and produce a focused research document. You are typically spawned 4 times in parallel, each with a different focus angle.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md
 
 ## Schema Reference
 N/A -- produces markdown research documents, not task JSON artifacts.

package/agents/workflow-reviewer.md

@@ -14,7 +14,7 @@ tools:
 You perform focused code review for a single dimension (e.g., security, performance, architecture). You analyze changed files, identify issues with evidence, classify severity, and produce structured findings. You are read-only and never modify project files.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/agents/workflow-verifier.md

@@ -14,7 +14,7 @@ tools:
 You perform goal-backward verification of completed work using a three-layer checking approach. You verify that artifacts exist, contain real substance, and are properly connected to the rest of the system. You also validate each task's convergence criteria individually. You are read-only and never modify project files.
 
 ## Search Tools
-@~/.maestro/templates/search-tools.md — Follow search tool priority and selection patterns.
+~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md — Follow search tool priority and selection patterns.
 
 ## Process
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-maestro-flow",
-  "version": "0.2.0",
-  "description": "Pi extension for Maestro workflow orchestration — explore, delegate, MOA tools, 113 skills, and 28 agent definitions",
+  "version": "0.3.1",
+  "description": "Pi extension for Maestro workflow orchestration — explore, delegate, MOA tools, 113 skills, 82 workflow docs, and 28 agent definitions",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -13,12 +13,15 @@
     "delegate",
     "moa",
     "workflow",
-    "orchestration"
+    "orchestration",
+    "skills"
   ],
   "files": [
     "src/**/*.ts",
     "agents/",
     "skills/",
+    "workflows/",
+    "templates/",
     "README.md"
   ],
   "pi": {
@@ -30,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "pi-maestro-teammate": "0.1.0",
+    "pi-maestro-teammate": "^0.1.0",
     "@earendil-works/pi-tui": "0.74.0",
     "typebox": "1.1.24"
   },
@@ -54,5 +57,16 @@
     "@earendil-works/pi-agent-core": "0.74.0",
     "@earendil-works/pi-ai": "0.74.0",
     "@earendil-works/pi-coding-agent": "0.74.0"
+  },
+  "maestro": {
+    "required": true,
+    "minVersion": "1.0.0",
+    "features": [
+      "search",
+      "load",
+      "delegate",
+      "explore"
+    ],
+    "installUrl": "https://github.com/catlog22/maestro2"
   }
 }

package/skills/codify-to-knowhow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: codify-to-knowhow
 description: "Manifest-driven knowledge asset generator — converts any structured package into maestro knowhow + spec entries with ref linking. Triggers on \"codify-to-knowhow\", \"style to knowhow\", \"知识固化\"."
-allowed-tools: Read Write Edit Bash Glob Grep TodoWrite
+allowed-tools: Read Write Edit Bash Glob Grep maestro
 auto-continue: true
 ---
 

package/skills/delegation-check/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: delegation-check
 description: "Check workflow delegation prompts against agent role definitions for content separation violations. Detects conflicts, duplication, boundary leaks, and missing contracts. Triggers on \"check delegation\", \"delegation conflict\", \"prompt vs role check\"."
-allowed-tools: Read Glob Grep Bash AskUserQuestion
+allowed-tools: Read Glob Grep Bash maestro
 ---
 
 <purpose>

package/skills/domain-add/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: domain-add
 description: "Register a domain term into project glossary Arguments: <canonical> \\\"<definition>\\\""
-allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+allowed-tools: Read Write Bash Glob Grep maestro
 ---
 
 <purpose>
@@ -9,7 +9,7 @@ Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are a
 </purpose>
 
 <required_reading>
-@~/.maestro/workflows/domain-add.md
+~/.pi/agent/packages/pi-maestro-flow/workflows/domain-add.md
 </required_reading>
 
 <context>
@@ -35,15 +35,15 @@ Domain term lifecycle: discover/manual → register → active → (optional) de
 1. **Single-term atomic operation** — each invocation registers exactly ONE term; NEVER batch-write multiple terms in a single execution
 2. **Glossary append-only** — existing terms in `glossary.yaml` SHALL NOT be modified or removed; only new entries are appended
 3. **Duplicate guard** — MUST check for exact canonical name match AND near-matches before writing; NEVER create duplicate entries
-4. **Confirmation mandatory** — MUST present term details (canonical, definition, aliases, tier, path) via AskUserQuestion before any glossary write; NEVER write without user confirmation
+4. **Confirmation mandatory** — MUST present term details (canonical, definition, aliases, tier, path) via user prompt before any glossary write; NEVER write without user confirmation
 5. **Schema compliance** — every term entry MUST include canonical name, definition, tier, and at least one alias/keyword; incomplete entries SHALL NOT be persisted
 6. **Domain directory prerequisite** — `.workflow/domain/` MUST exist before writing; NEVER auto-create the directory (E002 if missing)
 </invariants>
 
 <execution>
-Follow '~/.maestro/workflows/domain-add.md' completely.
+Follow '~/.pi/agent/packages/pi-maestro-flow/workflows/domain-add.md' completely.
 
-**Confirmation gate**: Before writing to glossary.yaml, AskUserQuestion showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
+**Confirmation gate**: Before writing to glossary.yaml, user prompt showing the term canonical name, definition, extracted aliases/keywords, tier, and target file path. Proceed only on user confirm.
 </execution>
 
 <error_codes>

package/skills/insight-challenge/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: insight-challenge
 description: "Adversarial review of code quality findings. Challenges insights with counter-evidence, verifies claims against source code, and produces structured verdicts. Triggers on 'insight-challenge', 'challenge finding', '审查发现'."
-allowed-tools: Read Glob Grep Bash Write
+allowed-tools: Read Glob Grep Bash Write maestro
 ---
 
 # Insight Challenge

package/skills/learn-decompose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-decompose
 description: "Extract design patterns from code into specs and wiki Arguments: <path|module> [--patterns <list>] [--save-spec] [--save-wiki] [-y]"
-allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -30,7 +30,7 @@ $ARGUMENTS — target path/module and optional flags.
 2. **Evidence-anchored findings** — every pattern MUST include at least one `file:line` anchor from source; unanchored patterns SHALL NOT be persisted
 3. **Dedup before persist** — MUST cross-reference against existing `learnings.md` and `coding-conventions.md` before writing; duplicate entries SHALL NOT be appended
 4. **Parallel agent isolation** — each dimension agent operates independently; NEVER share state between agents during analysis
-5. **Confirmation gate** — unless `-y` is set, MUST present all findings and target files via AskUserQuestion before any writes
+5. **Confirmation gate** — unless `-y` is set, MUST present all findings and target files via user prompt before any writes
 6. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
 </invariants>
 
@@ -49,7 +49,7 @@ S_PERSIST    — 写文件 + 可选 spec-add/wiki create         PERSIST: knowho
 
 S_RESOLVE:
   → S_DEDUP       WHEN: file list resolved
-  → S_RESOLVE     WHEN: unresolvable                     DO: AskUserQuestion
+  → S_RESOLVE     WHEN: unresolvable                     DO: user prompt
 
 S_DEDUP:
   → S_ANALYZE     DO: read coding-conventions.md + .workflow/specs/learnings.md → build known pattern set
@@ -64,7 +64,7 @@ S_CATALOG:
   → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
 
 S_PERSIST:
-  → END           GATE: unless -y, AskUserQuestion showing files to write and patterns to persist — proceed only on confirm
+  → END           GATE: unless -y, user prompt showing files to write and patterns to persist — proceed only on confirm
                   DO: append .workflow/specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
 
 </transitions>

package/skills/learn-follow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-follow
 description: "Guided reading of code or wiki to extract patterns Arguments: <path|wiki-id|topic> [--depth shallow|deep] [--save-wiki] [-y]"
-allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -36,7 +36,7 @@ $ARGUMENTS — target and optional flags.
 3. **Anchor requirement** — every extracted pattern MUST include a `file:line` anchor; unanchored patterns SHALL NOT be persisted to learnings.md
 4. **Convention cross-ref** — MUST check every finding against `coding-conventions.md` and mark status (documented/candidate); NEVER persist without status tag
 5. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
-6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via AskUserQuestion before any writes
+6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via user prompt before any writes
 7. **Depth contract** — `--depth shallow` MUST NOT descend into function bodies; `--depth deep` MUST cover every branch and sub-expression
 </invariants>
 
@@ -59,7 +59,7 @@ $ARGUMENTS — target and optional flags.
 - BLOCKED if: unanchored patterns remain in extraction results.
 
 **GATE 4: Persistence → Completion** (S_PERSIST → END)
-- REQUIRED: Unless `-y`, AskUserQuestion showing files to write and spec-entries to append — user must confirm.
+- REQUIRED: Unless `-y`, user prompt showing files to write and spec-entries to append — user must confirm.
 - REQUIRED: KNW-follow-{slug}-{date}.md written with understanding map.
 - REQUIRED: learnings.md appended (not overwritten) with new spec-entry blocks.
 - BLOCKED if: user declines confirmation — offer to adjust findings before retry.
@@ -81,7 +81,7 @@ S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowh
 
 S_RESOLVE:
   → S_CONTEXT     WHEN: target resolved
-  → S_RESOLVE     WHEN: unresolvable                       DO: AskUserQuestion with suggestions
+  → S_RESOLVE     WHEN: unresolvable                       DO: user prompt with suggestions
 
 S_CONTEXT:
   → S_ORDER       DO: A_BUILD_CONTEXT_WEB
@@ -96,7 +96,7 @@ S_EXTRACT:
   → S_PERSIST     DO: A_EXTRACT_PATTERNS
 
 S_PERSIST:
-  → END           GATE: unless -y, AskUserQuestion showing files to write and spec-entries to append — proceed only on confirm
+  → END           GATE: unless -y, user prompt showing files to write and spec-entries to append — proceed only on confirm
                   DO: write KNW-follow + append .workflow/specs/learnings.md [+ wiki note if --save-wiki]
 
 </transitions>

package/skills/learn-investigate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-investigate
 description: "Investigate questions with hypothesis testing and evidence logging Arguments: <question> [--scope <path>] [--max-hypotheses N] [-y]"
-allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -34,8 +34,8 @@ $ARGUMENTS — question text and optional flags.
 3. **Scope lock** — once `--scope` is resolved in S_FRAME, NEVER expand search scope without explicit user confirmation via S_ESCALATE
 4. **Hypothesis cap** — MUST NOT generate more than `--max-hypotheses` (default 3) before triggering escalation; NEVER silently exceed the cap
 5. **Structured evidence format** — every evidence entry MUST include `{ts, type, source, relevance, content, note}`; incomplete entries SHALL NOT be appended
-6. **3-strike escalation** — after all hypotheses fail, MUST escalate to user via AskUserQuestion; NEVER silently conclude as INCONCLUSIVE without user interaction
-7. **Confirmation gate** — unless `-y` is set, MUST present report.md path and spec-entries via AskUserQuestion before final writes
+6. **3-strike escalation** — after all hypotheses fail, MUST escalate to user via user prompt; NEVER silently conclude as INCONCLUSIVE without user interaction
+7. **Confirmation gate** — unless `-y` is set, MUST present report.md path and spec-entries via user prompt before final writes
 </invariants>
 
 <state_machine>
@@ -75,11 +75,11 @@ S_TEST:
   → S_ESCALATE    WHEN: max_hypotheses all failed              DO: A_TEST_HYPOTHESIS
 
 S_ESCALATE:
-  → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis   DO: AskUserQuestion
+  → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis   DO: user prompt
   → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
 
 S_REPORT:
-  → END           GATE: unless -y, AskUserQuestion showing report.md path and spec-entries to append — proceed only on confirm
+  → END           GATE: unless -y, user prompt showing report.md path and spec-entries to append — proceed only on confirm
                   DO: A_SYNTHESIZE_REPORT
 
 </transitions>

package/skills/learn-second-opinion/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: learn-second-opinion
 description: "Get alternative perspectives — review, challenge, or consult Arguments: <target> [--mode review|challenge|consult] [-y]"
-allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+allowed-tools: Read Write Bash Glob Grep teammate maestro
 ---
 
 <purpose>
@@ -37,7 +37,7 @@ $ARGUMENTS — target and optional mode flag.
 3. **Evidence-backed verdicts** — every finding MUST include a `location` reference (file:line or section); ungrounded opinions SHALL NOT appear in the report
 4. **Mode contract** — MUST execute exactly the mode specified (review/challenge/consult); NEVER mix mode behaviors within a single execution
 5. **Append-only learnings** — `.workflow/specs/learnings.md` MUST be appended, NEVER overwritten or truncated
-6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via AskUserQuestion before any writes
+6. **Confirmation gate** — unless `-y` is set, MUST present findings and target files via user prompt before any writes
 </invariants>
 
 <state_machine>
@@ -54,7 +54,7 @@ S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: k
 
 S_RESOLVE:
   → S_CONTEXT     WHEN: target resolved                DO: read target content
-  → S_RESOLVE     WHEN: unresolvable                   DO: AskUserQuestion for clarification
+  → S_RESOLVE     WHEN: unresolvable                   DO: user prompt for clarification
 
 S_CONTEXT:
   → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
@@ -68,7 +68,7 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           GATE: unless -y, AskUserQuestion showing files to write and spec-entries to append — proceed only on confirm
+  → END           GATE: unless -y, user prompt showing files to write and spec-entries to append — proceed only on confirm
                   DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
@@ -98,7 +98,7 @@ Spawn 1 adversarial Agent:
 Interactive loop:
 1. Agent studies target
 2. Display "Target loaded. What would you like to know?"
-3. AskUserQuestion → Agent answers with code refs → repeat until "done"
+3. user prompt → Agent answers with code refs → repeat until "done"
 4. Compile Q&A into report
 
 </actions>