pi-maestro-flow 0.3.0 → 0.4.0

package/skills/maestro-roadmap/SKILL.md

@@ -11,12 +11,13 @@ Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {milestone}
 </purpose>
 
 <required_reading>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap-common.md`.
-@~/.pi/agent/packages/pi-maestro-flow/templates/roadmap.md
+~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap-common.md
+~/.pi/agent/packages/pi-maestro-flow/templates/roadmap.md
 </required_reading>
 
-> **Reference files** (read when needed):
-> - [roadmap.md](~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap.md) — read for roadmap generation workflow
+<deferred_reading>
+- [roadmap.md](~/.pi/agent/packages/pi-maestro-flow/workflows/roadmap.md) — read for roadmap generation workflow
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- requirement text, @file reference, or upstream context source.
@@ -47,7 +48,7 @@ $ARGUMENTS -- requirement text, @file reference, or upstream context source.
 </context>
 
 <interview_protocol>
-Follows `~/.pi/agent/packages/pi-maestro-flow/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
@@ -59,8 +60,8 @@ Follows `~/.pi/agent/packages/pi-maestro-flow/workflows/interview-mechanics.md`
 
 <execution>
 
-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
+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-tools-execute/SKILL.md

@@ -9,7 +9,9 @@ Load registered tool documents and execute them step-by-step.
 Direct (by name) or category-based (list + select) invocation.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md
+</required_reading>
 
 <context>
 $ARGUMENTS — Tool name, keyword, or --category filter

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

@@ -9,7 +9,9 @@ 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**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/tools-spec.md
+</required_reading>
 
 <context>
 $ARGUMENTS — Intent description

package/skills/maestro-ui-codify/SKILL.md

@@ -9,11 +9,12 @@ Extract design system from source code into tokens, reference package, and knowl
 4-phase pipeline: validate → extract → package → knowhow.
 </purpose>
 
-> **Reference files** (read when needed):
-> - [ui-codify.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify.md) — read always (main workflow orchestrator)
-> - [ui-codify-extract.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-extract.md) — read when Phase 2 starts (style extraction with 3 agents)
-> - [ui-codify-package.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-package.md) — read when Phase 3 starts (reference package generation)
-> - [ui-codify-knowhow.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-knowhow.md) — read when Phase 4 starts (knowledge asset generation)
+<deferred_reading>
+- [ui-codify.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify.md) — read always (main workflow orchestrator)
+- [ui-codify-extract.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-extract.md) — read when Phase 2 starts (style extraction with 3 agents)
+- [ui-codify-package.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-package.md) — read when Phase 3 starts (reference package generation)
+- [ui-codify-knowhow.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ui-codify-knowhow.md) — read when Phase 4 starts (knowledge asset generation)
+</deferred_reading>
 
 <context>
 $ARGUMENTS — source path (required) with optional flags.

package/skills/manage-codebase-rebuild/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Full rebuild of `.workflow/codebase/` docs: 4 parallel mapper agents → tech-stack, architecture, features, concerns. Destructive — overwrites existing docs.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/codebase-rebuild.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/codebase-rebuild.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- optional flags.

package/skills/manage-drift-realign/SKILL.md

@@ -8,12 +8,15 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 检测代码重构/增量变更后，代码现实与 .workflow/ 文档之间的漂移。互补于 `manage-knowledge-audit`（检测知识存储内部矛盾）。本命令通过 git 时间线 + session 历史检测 code↔document 漂移。
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/drift-realign.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - ~/.pi/agent/packages/pi-maestro-flow/workflows/knowledge-audit.md (交叉引用已有审计发现)
-> - ~/.pi/agent/packages/pi-maestro-flow/workflows/sync.md (codebase 文档严重漂移时自动触发)
-> - ~/.pi/agent/packages/pi-maestro-flow/workflows/codebase-rebuild.md (sync 不足时的回退方案)
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/drift-realign.md
+</required_reading>
+
+<deferred_reading>
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/knowledge-audit.md (交叉引用已有审计发现)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/sync.md (codebase 文档严重漂移时自动触发)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/codebase-rebuild.md (sync 不足时的回退方案)
+</deferred_reading>
 
 <context>
 Arguments: $ARGUMENTS

package/skills/manage-harvest/SKILL.md

@@ -8,11 +8,14 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Extract knowledge from workflow artifacts → route to wiki/spec/issue stores. Works on any artifact (vs retrospective which is phase-scoped).
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/harvest.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md` (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md` (spec entry format — read when routing to spec in Stage 6b)
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
 
 <context>
 Arguments: $ARGUMENTS

package/skills/manage-issue/SKILL.md

@@ -8,10 +8,13 @@ allowed-tools: Read Write Edit Bash Glob Grep maestro
 Issue lifecycle management: create, list, status, update, close, link. Stored in `.workflow/issues/issues.jsonl`. For automated discovery, use `/manage-issue-discover`.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [issue.json template](~/.pi/agent/packages/pi-maestro-flow/templates/issue.json) — read when creating or updating issue records (create, update, close)
+<deferred_reading>
+- [issue.json template](~/.pi/agent/packages/pi-maestro-flow/templates/issue.json) — read when creating or updating issue records (create, update, close)
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- subcommand + options. Parse first token as subcommand.

package/skills/manage-issue-discover/SKILL.md

@@ -8,11 +8,14 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Automated issue discovery: multi-perspective (8 perspectives) or prompt-driven. Deduplicates and records to `issues.jsonl`. For CRUD operations, use `/manage-issue`.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/issue-discover.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - [issue.json template](~/.pi/agent/packages/pi-maestro-flow/templates/issue.json) — read when creating issue records from findings (Step 6/11)
-> - [search-tools](~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md) — search tool priority, passed to agents via workflow
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/issue-discover.md
+</required_reading>
+
+<deferred_reading>
+- [issue.json template](~/.pi/agent/packages/pi-maestro-flow/templates/issue.json) — read when creating issue records from findings (Step 6/11)
+- [search-tools](~/.pi/agent/packages/pi-maestro-flow/templates/search-tools.md) — search tool priority, passed to agents via workflow
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- optional. Parse first token to determine mode.

package/skills/manage-knowhow/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep maestro
 Manage knowhow across two stores: workflow (`.workflow/knowhow/`) and system memory (`~/.claude/projects/*/memory/`). Operations: list, search, view, edit, delete, prune.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/knowhow.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/knowhow.md
+</required_reading>
 
 <context>
 Arguments: $ARGUMENTS

package/skills/manage-knowhow-capture/SKILL.md

@@ -9,7 +9,9 @@ Capture reusable knowledge into `.workflow/knowhow/` with type-specific structur
 Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/knowhow.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/knowhow.md
+</required_reading>
 
 <context>
 $ARGUMENTS — type token + description + optional flags.

package/skills/manage-knowledge-audit/SKILL.md

@@ -8,11 +8,14 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 审查 spec/knowhow/artifact 存储，识别矛盾/失效/孤儿，通过 keep/deprecate/delete 三态清理。对称于 `manage-harvest`（写入入口）。
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/knowledge-audit.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/harvest.md` (audit 检测的 artifact 是 harvest 的产物源)
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md` (deprecate 操作所需的 `<spec-entry>` 变形)
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/knowledge-audit.md
+</required_reading>
+
+<deferred_reading>
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/harvest.md (audit 检测的 artifact 是 harvest 的产物源)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md (deprecate 操作所需的 `<spec-entry>` 变形)
+</deferred_reading>
 
 <context>
 Arguments: $ARGUMENTS

package/skills/manage-status/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Bash Glob Grep maestro
 Project dashboard: artifact progress, task counts, active work, next-step suggestions.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/status.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/status.md
+</required_reading>
 
 <context>
 $ARGUMENTS (no arguments required)

package/skills/manage-wiki/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep maestro
 Wiki graph management: health, search, cleanup, stats, connect, digest.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/wiki-manage.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/wiki-manage.md
+</required_reading>
 
 <context>
 $ARGUMENTS — subcommand and optional flags.

package/skills/odyssey-debug/SKILL.md

@@ -4,7 +4,7 @@ description: "Long-running debug cycle — archaeology, diagnosis, fix, confirma
 allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
-<base>`~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>`
+<base>~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>
 
 <purpose>
 archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.

package/skills/odyssey-improve/SKILL.md

@@ -4,7 +4,7 @@ description: "Long-running codebase improvement cycle — multi-dimensional audi
 allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
-<base>`~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>`
+<base>~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>
 
 <purpose>
 survey → 6-dimension audit → diagnose → fix → verify → generalize → discover → persist.

package/skills/odyssey-planex/SKILL.md

@@ -4,7 +4,7 @@ description: "Requirement-driven iterative cycle — plan, execute, strict verif
 allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
-<base>`~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>`
+<base>~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>
 
 <purpose>
 Requirement-to-delivery closed loop: parse requirement → define acceptance criteria →

package/skills/odyssey-review-test-fix/SKILL.md

@@ -4,7 +4,7 @@ description: "Deep review + fix cycle — archaeology, exploration, multi-dimens
 allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
-<base>`~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>`
+<base>~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>
 
 <purpose>
 archaeology → explore → multi-dimensional review → fix ALL findings → confirm → generalize → discover → persist. Zero-residual: every finding gets an action.

package/skills/odyssey-ui/SKILL.md

@@ -4,7 +4,7 @@ description: "Long-running UI optimization cycle — visual survey, multi-dimens
 allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 ---
 
-<base>`~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>`
+<base>~/.pi/agent/packages/pi-maestro-flow/workflows/odyssey-base.md</base>
 
 <purpose>
 survey → 6-dimension audit → divergent exploration → fix → verify → generalize → discover → persist.

package/skills/quality-auto-test/SKILL.md

@@ -10,7 +10,9 @@ Unified automated testing via CSV layer pipeline. Auto-selects scenario source f
 Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-iter 1` = single-pass; default = full iterative cycle.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/auto-test.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/auto-test.md
+</required_reading>
 
 <context>
 Phase or task: $ARGUMENTS (required — phase number)

package/skills/quality-debug/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/debug.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/debug.md
+</required_reading>
 
 <context>
 User's issue: $ARGUMENTS

package/skills/quality-refactor/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Targeted refactoring with safety guarantees: plan → confirm → execute with test verification per change → reflection-log.md.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/refactor.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/refactor.md
+</required_reading>
 
 <context>
 Scope: $ARGUMENTS (required)

package/skills/quality-retrospective/SKILL.md

@@ -8,13 +8,16 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Post-execution retrospective (复盘): four parallel lenses (technical/process/quality/decision) → distill insights → route to spec/knowhow/issue stores.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/retrospective.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md` (issues.jsonl schema for auto-creation)
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/learn.md` (tip routing via manage-knowhow-capture tip)
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/verify.md` (verification.json schema for quality lens parsing)
-> - `~/.pi/agent/packages/pi-maestro-flow/workflows/review.md` (review.json schema for quality lens parsing)
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/retrospective.md
+</required_reading>
+
+<deferred_reading>
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/issue.md (issues.jsonl schema for auto-creation)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/learn.md (tip routing via manage-knowhow-capture tip)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/verify.md (verification.json schema for quality lens parsing)
+- ~/.pi/agent/packages/pi-maestro-flow/workflows/review.md (review.json schema for quality lens parsing)
+</deferred_reading>
 
 <context>
 Arguments: $ARGUMENTS

package/skills/quality-review/SKILL.md

@@ -8,10 +8,13 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Multi-dimensional code review on a phase's changed files. Three levels (quick/standard/deep), auto-detected from file count. Level and dimension details in workflow review.md.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/review.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/review.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [index.json](~/.pi/agent/packages/pi-maestro-flow/templates/index.json) — read when updating phase index after review
+<deferred_reading>
+- [index.json](~/.pi/agent/packages/pi-maestro-flow/templates/index.json) — read when updating phase index after review
+</deferred_reading>
 
 <context>
 Phase: $ARGUMENTS (required — phase number or slug)

package/skills/quality-sync/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Sync codebase docs after code changes: git diff → trace impact via doc-index.json → refresh `.workflow/codebase/` docs.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/sync.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/sync.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- optional flags:

package/skills/quality-test/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 UAT-style conversational testing for a completed phase. Interactive scenario walk-through with severity inference. Issues trigger parallel debug agents and optional gap-fix loop (--auto-fix).
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/test.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/test.md
+</required_reading>
 
 <context>
 Phase or task: $ARGUMENTS (optional)

package/skills/security-audit/SKILL.md

@@ -9,7 +9,9 @@ Systematic security audit covering OWASP Top 10, dependency supply chain, secret
 CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/review.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/review.md
+</required_reading>
 
 <context>
 $ARGUMENTS — Parse tier and scope:

package/skills/spec-add/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Bash Glob Grep maestro
 Add `<spec-entry>` to specs by category. 4 scopes: project (default), global, team, personal.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/specs-add.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`

package/skills/spec-load/SKILL.md

@@ -10,7 +10,9 @@ Category-based loading: loads the category's primary doc in full + matching entr
 By default, loads from both global (~/.maestro/specs/) and project (.workflow/specs/) layers.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-load.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/specs-load.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- optional flags and keyword

package/skills/spec-remove/SKILL.md

@@ -9,7 +9,9 @@ Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
 Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-remove.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/specs-remove.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)

package/skills/spec-setup/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Bash Glob Grep maestro
 Initialize `.workflow/specs/` by scanning codebase for conventions. Core files always created; optional files created when signals detected. Also generates recipe knowhow for detected workflows.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/specs-setup.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/specs-setup.md
+</required_reading>
 
 <context>
 $ARGUMENTS (no arguments expected)

package/src/providers/provider-registry.ts

@@ -20,7 +20,7 @@ function mapToolToProviderConfig(
   name: string,
   config: CliToolConfig,
 ): {
-  apiType: string;
+  api: string;
   envVar: string;
   baseUrl?: string;
 } {
@@ -28,46 +28,51 @@ function mapToolToProviderConfig(
   switch (name) {
     case "claude":
       return {
-        apiType: "anthropic-messages",
+        api: "anthropic-messages",
         envVar: "ANTHROPIC_API_KEY",
+        baseUrl: "https://api.anthropic.com",
       };
 
     case "gemini":
       return {
-        apiType: "google-genai",
+        api: "google-genai",
         envVar: "GOOGLE_API_KEY",
+        baseUrl: "https://generativelanguage.googleapis.com",
       };
 
     case "codex":
       return {
-        apiType: "openai-completions",
+        api: "openai-completions",
         envVar: "OPENAI_API_KEY",
+        baseUrl: "https://api.openai.com/v1",
       };
 
     case "opencode":
       return {
-        apiType: "openai-compatible",
+        api: "openai-compatible",
         envVar: "OPENAI_API_KEY",
         baseUrl: "https://api.openai.com/v1",
       };
 
     case "agy":
       return {
-        apiType: "openai-compatible",
+        api: "openai-compatible",
         envVar: "AGY_API_KEY",
+        baseUrl: "https://api.openai.com/v1",
       };
 
     case "api-explore":
       return {
-        apiType: "openai-compatible",
+        api: "openai-compatible",
         envVar: "API_EXPLORE_KEY",
+        baseUrl: "https://api.openai.com/v1",
       };
 
     default:
-      // Generic OpenAI-compatible fallback
       return {
-        apiType: "openai-compatible",
+        api: "openai-compatible",
         envVar: `${name.toUpperCase()}_API_KEY`,
+        baseUrl: "https://api.openai.com/v1",
       };
   }
 }
@@ -102,7 +107,7 @@ export function registerMaestroProviders(pi: ExtensionAPI): void {
       // pi-agent-core version.
       if (typeof pi.registerProvider === "function") {
         pi.registerProvider(name, {
-          apiType: providerMapping.apiType,
+          api: providerMapping.api,
           apiKey: `$${providerMapping.envVar}`,
           ...(providerMapping.baseUrl
             ? { baseUrl: providerMapping.baseUrl }

package/src/tools/delegate.ts

@@ -8,7 +8,7 @@
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { runTeammate } from "@pi-maestro/teammate/src/runs/execution.ts";
+import { runTeammate } from "../../../pi-teammate/src/runs/execution.ts";
 
 export interface DelegateParams {
   prompt?: string;

package/src/tools/explore.ts

@@ -8,8 +8,8 @@
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { runTeammate } from "@pi-maestro/teammate/src/runs/execution.ts";
-import type { SingleResult } from "@pi-maestro/teammate/src/shared/types.ts";
+import { runTeammate } from "../../../pi-teammate/src/runs/execution.ts";
+import type { SingleResult } from "../../../pi-teammate/src/shared/types.ts";
 
 export interface ExploreParams {
   prompts?: string[];

package/src/tools/moa.ts

@@ -9,8 +9,8 @@
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { runTeammate } from "@pi-maestro/teammate/src/runs/execution.ts";
-import type { SingleResult } from "@pi-maestro/teammate/src/shared/types.ts";
+import { runTeammate } from "../../../pi-teammate/src/runs/execution.ts";
+import type { SingleResult } from "../../../pi-teammate/src/shared/types.ts";
 
 export interface MoaParams {
   prompts?: string[];