pi-maestro-flow 0.3.0 → 0.3.1

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 @~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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
-@~/.pi/agent/packages/pi-maestro-flow/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,6 +1,6 @@
 {
   "name": "pi-maestro-flow",
-  "version": "0.3.0",
+  "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": [
@@ -61,7 +61,12 @@
   "maestro": {
     "required": true,
     "minVersion": "1.0.0",
-    "features": ["search", "load", "delegate", "explore"],
+    "features": [
+      "search",
+      "load",
+      "delegate",
+      "explore"
+    ],
     "installUrl": "https://github.com/catlog22/maestro2"
   }
 }

package/skills/domain-add/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read Write Bash Glob Grep maestro
 Register a domain term into `.workflow/domain/glossary.yaml`. Domain terms are automatically injected into agent context via hooks (domain-compact for all prompts, domain-expanded on keyword match).
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/domain-add.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/domain-add.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- expects `<canonical> "<definition>"`

package/skills/maestro/SKILL.md

@@ -9,9 +9,10 @@ Orchestrate all maestro commands: classify intent → select chain → create se
 Session: `.workflow/.maestro/{session_id}/status.json`.
 </purpose>
 
-> **Reference files** (read when needed):
-> - [maestro.md](~/.pi/agent/packages/pi-maestro-flow/workflows/maestro.md) — read at execution start for intent analysis + chain selection
-> - [maestro-super.md](~/.pi/agent/packages/pi-maestro-flow/workflows/maestro-super.md) — read when `--super` flag active
+<deferred_reading>
+- [maestro.md](~/.pi/agent/packages/pi-maestro-flow/workflows/maestro.md) — read at execution start for intent analysis + chain selection
+- [maestro-super.md](~/.pi/agent/packages/pi-maestro-flow/workflows/maestro-super.md) — read when `--super` flag active
+</deferred_reading>
 
 <context>
 $ARGUMENTS — user intent text, or special keywords.

package/skills/maestro-amend/SKILL.md

@@ -9,8 +9,8 @@ Signal-driven overlay generator — collect workflow deficiency signals from mul
 </purpose>
 
 <required_reading>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/overlays.md`.
-@~/.maestro/cli-tools.json
+~/.pi/agent/packages/pi-maestro-flow/workflows/overlays.md
+~/.maestro/cli-tools.json
 </required_reading>
 
 <context>

package/skills/maestro-analyze/SKILL.md

@@ -8,12 +8,15 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Multi-dimensional analysis of a proposal, decision, or architecture choice via CLI-assisted exploration and interactive discussion. Produces analysis.md (6-dimension scoring), context.md (Locked/Free/Deferred decisions), conclusions.json, and discussion.md with Go/No-Go recommendation. Use `--gaps` for issue root cause analysis feeding `plan --gaps`.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/analyze.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/analyze.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
-> - [issue-gaps-analyze.md](~/.pi/agent/packages/pi-maestro-flow/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
-> - [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
+<deferred_reading>
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+- [issue-gaps-analyze.md](~/.pi/agent/packages/pi-maestro-flow/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+- [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- milestone number for micro mode, topic text for macro/adhoc mode, no args for current milestone.
@@ -61,7 +64,7 @@ Output directory format, artifact registration schema, and output artifact listi
 </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): scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold
@@ -122,7 +125,7 @@ Status verdicts:
 
 ### Session seal
 
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md`. — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
 </completion>
 
 <error_codes>

package/skills/maestro-blueprint/SKILL.md

@@ -10,10 +10,13 @@ allowed-tools: Read Write Edit Bash Glob Grep teammate maestro
 Pipeline: brainstorm (optional) → **blueprint** → analyze / roadmap / plan.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/blueprint.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/blueprint.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [blueprint-config.json](~/.pi/agent/packages/pi-maestro-flow/templates/blueprint-config.json) — read when initializing blueprint configuration
+<deferred_reading>
+- [blueprint-config.json](~/.pi/agent/packages/pi-maestro-flow/templates/blueprint-config.json) — read when initializing blueprint configuration
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- idea text, @file reference, or upstream context source.
@@ -43,7 +46,7 @@ $ARGUMENTS -- idea 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, depth-first
 **Decision tree** (strict depth-first): scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration → requirement priorities
@@ -152,5 +155,5 @@ Status verdicts:
 </success_criteria>
 
 <on_complete>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md`. — SESSION_DIR={session_dir}, SESSION_TYPE=blueprint, SESSION_ID={session_id}, LINKED_MILESTONE=null
+~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md — SESSION_DIR={session_dir}, SESSION_TYPE=blueprint, SESSION_ID={session_id}, LINKED_MILESTONE=null
 </on_complete>

package/skills/maestro-brainstorm/SKILL.md

@@ -10,13 +10,16 @@ Multi-role brainstorming with cross-role conflict resolution. Auto mode: guidanc
 Pipeline: grill (optional) → **brainstorm** → roadmap / analyze / blueprint.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/brainstorm.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/brainstorm.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [scratch-index.json](~/.pi/agent/packages/pi-maestro-flow/templates/scratch-index.json) — read when operating in scratch mode
-> - [index.json](~/.pi/agent/packages/pi-maestro-flow/templates/index.json) — read when operating in phase mode
-> - [brainstorm-visualize.md](~/.pi/agent/packages/pi-maestro-flow/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
-> - [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (in cross-role review)
+<deferred_reading>
+- [scratch-index.json](~/.pi/agent/packages/pi-maestro-flow/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.pi/agent/packages/pi-maestro-flow/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.pi/agent/packages/pi-maestro-flow/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+- [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (in cross-role review)
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
@@ -54,7 +57,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 </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** (flexible order — user may jump between branches): mode (auto / single-role / review-only) → role selection and --count → --from upstream source (grill:ID, blueprint:ID, @file, path) → whether to enable design-research and DESIGN.md sub-pipeline
@@ -186,5 +189,5 @@ Status verdicts:
 </success_criteria>
 
 <on_complete>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md`. — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

package/skills/maestro-composer/SKILL.md

@@ -9,9 +9,10 @@ Interactive workflow template composer: natural language to DAG template.
 Three modes: new design (default), resume (`--resume`), edit (`--edit <path>`).
 </purpose>
 
-> **Reference files** (read when needed):
-> - [node-catalog](~/.pi/agent/packages/pi-maestro-flow/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
-> - [template-schema](~/.pi/agent/packages/pi-maestro-flow/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
+<deferred_reading>
+- [node-catalog](~/.pi/agent/packages/pi-maestro-flow/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
+- [template-schema](~/.pi/agent/packages/pi-maestro-flow/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
+</deferred_reading>
 
 <context>
 $ARGUMENTS — natural language description, or flags.

package/skills/maestro-execute/SKILL.md

@@ -9,11 +9,14 @@ Execute confirmed plan tasks via wave-based parallel dispatch.
 Consumes plan from maestro-plan; registers EXC artifact in state.json.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/execute.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - [task.json](~/.pi/agent/packages/pi-maestro-flow/templates/task.json) — read when reading task definitions
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.pi/agent/packages/pi-maestro-flow/templates/task.json) — read when reading task definitions
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+</deferred_reading>
 
 <context>
 $ARGUMENTS — milestone number, or no args for current milestone, with optional flags.

package/skills/maestro-fork/SKILL.md

@@ -9,11 +9,14 @@ Create or sync a milestone-level git worktree for parallel development.
 Supports `--sync` mode to pull latest main changes into an active worktree.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/fork.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - [worktrees.json](~/.pi/agent/packages/pi-maestro-flow/templates/worktrees.json) — read when updating registry
-> - [worktree-scope.json](~/.pi/agent/packages/pi-maestro-flow/templates/worktree-scope.json) — read when writing scope marker
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/fork.md
+</required_reading>
+
+<deferred_reading>
+- [worktrees.json](~/.pi/agent/packages/pi-maestro-flow/templates/worktrees.json) — read when updating registry
+- [worktree-scope.json](~/.pi/agent/packages/pi-maestro-flow/templates/worktree-scope.json) — read when writing scope marker
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- milestone number and optional flags.

package/skills/maestro-grill/SKILL.md

@@ -10,10 +10,13 @@ Socratic stress-testing of plans/ideas against codebase reality. Produces grill-
 Pipeline position: BEFORE brainstorm (stress-test → then elaborate).
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/grill.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/grill.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+<deferred_reading>
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+</deferred_reading>
 
 <context>
 $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstream input.
@@ -44,7 +47,7 @@ $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstrea
 </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 override**: adversarial Socratic — NOT menu-driven
 **Question style**:
@@ -144,5 +147,5 @@ Status verdicts:
 </success_criteria>
 
 <on_complete>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md`. — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+~/.pi/agent/packages/pi-maestro-flow/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

package/skills/maestro-init/SKILL.md

@@ -9,12 +9,15 @@ Initialize project: detect state, create `.workflow/` with project.md, state.jso
 Entry point; downstream: maestro-roadmap or maestro-brainstorm.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/init.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/init.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [project.md](~/.pi/agent/packages/pi-maestro-flow/templates/project.md) — read when generating project description
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when creating initial state
-> - [config.json](~/.pi/agent/packages/pi-maestro-flow/templates/config.json) — read when creating workflow configuration
+<deferred_reading>
+- [project.md](~/.pi/agent/packages/pi-maestro-flow/templates/project.md) — read when generating project description
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when creating initial state
+- [config.json](~/.pi/agent/packages/pi-maestro-flow/templates/config.json) — read when creating workflow configuration
+</deferred_reading>
 
 <context>
 $ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for auto mode.
@@ -41,7 +44,7 @@ Check for `.workflow/state.json` -- loads context if project already initialized
 </invariants>
 
 <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): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap)

package/skills/maestro-merge/SKILL.md

@@ -9,7 +9,9 @@ Merge a milestone worktree branch back into main, sync scratch artifacts, and re
 Two-phase: git merge first, artifact sync second (only after git succeeds).
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/merge.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/merge.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- milestone number and optional flags.

package/skills/maestro-milestone-audit/SKILL.md

@@ -9,7 +9,9 @@ Audit milestone for phase coverage, execution completeness, and integration gaps
 Produces audit-report.md with PASS/FAIL verdict.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-audit.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-audit.md
+</required_reading>
 
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).

package/skills/maestro-milestone-complete/SKILL.md

@@ -9,10 +9,13 @@ Archive passed milestone: validate, archive artifacts, extract knowhow, advance
 Requires audit PASS; produces milestone archive and learnings.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-complete.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-complete.md
+</required_reading>
 
-> **Reference files** (read when needed):
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when updating milestone_history and advancing state
+<deferred_reading>
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when updating milestone_history and advancing state
+</deferred_reading>
 
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).

package/skills/maestro-milestone-release/SKILL.md

@@ -10,7 +10,9 @@ Package a completed milestone into a releasable version: version bump → change
 Pipeline position: downstream of `/maestro-milestone-complete`. Terminal command.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-release.md` before proceeding.
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/milestone-release.md
+</required_reading>
 
 <context>
 $ARGUMENTS -- optional explicit version string and flags.
@@ -38,7 +40,7 @@ $ARGUMENTS -- optional explicit version string and flags.
 </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.
 
 **Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
 **Scope guard**: only release decisions; do not prejudge next milestone scope

package/skills/maestro-overlay/SKILL.md

@@ -10,8 +10,8 @@ Turn natural-language instructions into command overlays — JSON patch files th
 </purpose>
 
 <required_reading>
-Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/overlays.md`.
-@~/.maestro/cli-tools.json
+~/.pi/agent/packages/pi-maestro-flow/workflows/overlays.md
+~/.maestro/cli-tools.json
 </required_reading>
 
 <context>
@@ -22,7 +22,7 @@ Read and follow `~/.pi/agent/packages/pi-maestro-flow/workflows/overlays.md`.
 
 **Where overlays live**
 - User overlays: `~/.maestro/overlays/*.json` — created by this skill
-- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
+- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `~/.maestro/overlays/docs/*.md` inside patch content
 - Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit
 
 **Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
@@ -111,7 +111,7 @@ Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestr
 **Content guidelines**
 - Lead the injected block with a heading that includes `(overlay)` so readers see it's machine-injected
 - Keep content concise — overlays should add a step, not rewrite the command
-- `@~/.maestro/...` references are encouraged for pointing at docs
+- `~/.maestro/...` references are encouraged for pointing at docs
 - Escape `\n` in JSON strings; use a HEREDOC via Bash if content is long
 
 **Skill chain content** — if a chain was configured in Step 2.5, append a Skill Handoff block at the end of the patch `content`. The handoff uses user prompt so the user controls whether to proceed:

package/skills/maestro-plan/SKILL.md

@@ -9,13 +9,16 @@ Create, revise, or verify execution plans (5-stage pipeline).
 Produces plan.json + TASK files; registers PLN artifact in state.json.
 </purpose>
 
-> **Required**: Read `~/.pi/agent/packages/pi-maestro-flow/workflows/plan.md` before proceeding.
-
-> **Reference files** (read when needed):
-> - [plan.json](~/.pi/agent/packages/pi-maestro-flow/templates/plan.json) — read when generating plan output
-> - [task.json](~/.pi/agent/packages/pi-maestro-flow/templates/task.json) — read when generating task files
-> - [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
-> - [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
+<required_reading>
+~/.pi/agent/packages/pi-maestro-flow/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.pi/agent/packages/pi-maestro-flow/templates/plan.json) — read when generating plan output
+- [task.json](~/.pi/agent/packages/pi-maestro-flow/templates/task.json) — read when generating task files
+- [state.json](~/.pi/agent/packages/pi-maestro-flow/templates/state.json) — read when registering artifact
+- [boundary-grill.md](~/.pi/agent/packages/pi-maestro-flow/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
+</deferred_reading>
 
 <context>
 $ARGUMENTS — milestone number, or no args for current milestone, with optional flags.

package/skills/maestro-quick/SKILL.md

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

package/skills/maestro-ralph/SKILL.md

@@ -9,8 +9,9 @@ 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>
 
-> **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
+<deferred_reading>
+- [ralph-amend-goal.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
+</deferred_reading>
 
 <context>
 $ARGUMENTS — intent text, flags, or keywords.

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

@@ -10,8 +10,9 @@ Adaptive lifecycle orchestrator: locate step → resolve args → load context
 Session: `.workflow/.maestro/ralph-v2-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
 
-> **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
+<deferred_reading>
+- [ralph-amend-goal.md](~/.pi/agent/packages/pi-maestro-flow/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
+</deferred_reading>
 
 <context>
 $ARGUMENTS — intent text, flags, or keywords.

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)