pi-maestro-flow 0.3.0 → 0.4.0

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.4.0",
   "description": "Pi extension for Maestro workflow orchestration — explore, delegate, MOA tools, 113 skills, 82 workflow docs, and 28 agent definitions",
   "type": "module",
   "keywords": [
@@ -33,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "pi-maestro-teammate": "^0.1.0",
+    "pi-maestro-teammate": "^0.2.0",
     "@earendil-works/pi-tui": "0.74.0",
     "typebox": "1.1.24"
   },
@@ -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.