maestro-flow 0.4.21 → 0.4.23

package/.agents/skills/team-adversarial-swarm/scripts/aco.py

@@ -89,7 +89,7 @@ def cmd_init(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
     if not paths.config.exists():
         _fail(2, f"config not found: {paths.config}")
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
 
     paths.ensure_dirs()
 
@@ -107,7 +107,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         "start_nodes": config.get("task_space", {}).get("start_nodes", "any"),
         "edges": config.get("task_space", {}).get("edges", "complete"),
     }
-    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False))
+    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False), encoding="utf-8")
 
     # Initialize pheromone
     aco_cfg = config.get("aco", {})
@@ -148,9 +148,9 @@ def _pick_start_node(nodes: List[str], state: PheromoneState, mode: str) -> str:
 
 def cmd_select(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
 
     n_ants = config.get("swarm", {}).get("n_ants", 5)
     nodes = task_space["nodes"]
@@ -190,7 +190,7 @@ def _load_iteration_artifacts(paths: SessionPaths, iteration: int) -> List[dict]
     artifacts = []
     for f in files:
         try:
-            artifacts.append(json.loads(Path(f).read_text()))
+            artifacts.append(json.loads(Path(f).read_text(encoding="utf-8")))
         except json.JSONDecodeError as e:
             print(f"warning: skipped malformed artifact {f}: {e}", file=sys.stderr)
     return artifacts
@@ -213,9 +213,9 @@ def _validate_artifact(art: dict, valid_nodes: set) -> Optional[str]:
 
 def cmd_update(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
     valid_nodes = set(task_space["nodes"])
 
     artifacts = _load_iteration_artifacts(paths, args.iter)
@@ -266,7 +266,7 @@ def cmd_update(args: argparse.Namespace) -> None:
     # Elitist: re-load best history, deposit extra on best path
     best_data = None
     if paths.best.exists():
-        best_data = json.loads(paths.best.read_text())
+        best_data = json.loads(paths.best.read_text(encoding="utf-8"))
     current_best = max(scored, key=lambda x: x["score"]) if scored else None
     if current_best:
         best_art = next(a for a in artifacts if a["ant_id"] == current_best["ant_id"])
@@ -281,7 +281,7 @@ def cmd_update(args: argparse.Namespace) -> None:
                 "evidence": best_art.get("evidence", []),
                 "updated_at": time.time(),
             }
-            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False))
+            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False), encoding="utf-8")
         # Elite deposit
         state.deposit(best_data["path"], best_data["score"])
 
@@ -292,14 +292,14 @@ def cmd_update(args: argparse.Namespace) -> None:
 
     # Persist trails
     trails_file = paths.trails / f"{args.iter}.jsonl"
-    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log))
+    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log), encoding="utf-8")
 
     mean_score = sum(s["score"] for s in scored) / len(scored) if scored else 0.0
     best_score = best_data["score"] if best_data else 0.0
     prev_best = 0.0
     history_files = sorted(paths.pheromone_history.glob("*.json"))
     if len(history_files) >= 2:
-        prev = json.loads(history_files[-2].read_text())
+        prev = json.loads(history_files[-2].read_text(encoding="utf-8"))
         prev_best = prev.get("stats", {}).get("best_known", best_score)
     delta = best_score - prev_best
 
@@ -323,7 +323,7 @@ def cmd_update(args: argparse.Namespace) -> None:
 
 def cmd_converged(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     cv = config.get("convergence", {})
 
     state = PheromoneState.load(paths.pheromone_current)
@@ -339,7 +339,7 @@ def cmd_converged(args: argparse.Namespace) -> None:
     }
 
     if paths.best.exists():
-        metrics["best_score"] = json.loads(paths.best.read_text()).get("score", 0.0)
+        metrics["best_score"] = json.loads(paths.best.read_text(encoding="utf-8")).get("score", 0.0)
 
     # max_iterations
     max_iter = cv.get("max_iterations", 5)
@@ -397,7 +397,7 @@ def cmd_report(args: argparse.Namespace) -> None:
 
     best = None
     if paths.best.exists():
-        best = json.loads(paths.best.read_text())
+        best = json.loads(paths.best.read_text(encoding="utf-8"))
 
     # Top-K trails across all iterations
     all_trails = []
@@ -410,7 +410,7 @@ def cmd_report(args: argparse.Namespace) -> None:
     # Convergence curve
     curve = []
     for hf in sorted(paths.pheromone_history.glob("*.json"), key=lambda p: int(p.stem)):
-        snap = json.loads(hf.read_text())
+        snap = json.loads(hf.read_text(encoding="utf-8"))
         curve.append({
             "iteration": snap["iteration"],
             "entropy": snap["stats"]["entropy"],

package/.agents/skills/team-adversarial-swarm/scripts/pheromone.py

@@ -114,11 +114,11 @@ class PheromoneState:
 
     def save(self, path: Path) -> None:
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False))
+        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
 
     @classmethod
     def load(cls, path: Path) -> "PheromoneState":
-        return cls.from_dict(json.loads(path.read_text()))
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))
 
     def select_neighbors(
         self,

package/.agents/skills/team-adversarial-swarm/scripts/scoring.py

@@ -62,7 +62,7 @@ def load_verified_scores(scores_file: Path) -> Dict[str, float]:
     """Load pre-computed verified_scores from scorer role output (if exists)."""
     if not scores_file.exists():
         return {}
-    data = json.loads(scores_file.read_text())
+    data = json.loads(scores_file.read_text(encoding="utf-8"))
     return {
         ant_id: entry["verified_score"]
         for ant_id, entry in data.get("scores", {}).items()

package/.agents/skills/team-swarm/scripts/aco.py

@@ -89,7 +89,7 @@ def cmd_init(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
     if not paths.config.exists():
         _fail(2, f"config not found: {paths.config}")
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
 
     paths.ensure_dirs()
 
@@ -107,7 +107,7 @@ def cmd_init(args: argparse.Namespace) -> None:
         "start_nodes": config.get("task_space", {}).get("start_nodes", "any"),
         "edges": config.get("task_space", {}).get("edges", "complete"),
     }
-    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False))
+    paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False), encoding="utf-8")
 
     # Initialize pheromone
     aco_cfg = config.get("aco", {})
@@ -148,9 +148,9 @@ def _pick_start_node(nodes: List[str], state: PheromoneState, mode: str) -> str:
 
 def cmd_select(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
 
     n_ants = config.get("swarm", {}).get("n_ants", 5)
     nodes = task_space["nodes"]
@@ -190,7 +190,7 @@ def _load_iteration_artifacts(paths: SessionPaths, iteration: int) -> List[dict]
     artifacts = []
     for f in files:
         try:
-            artifacts.append(json.loads(Path(f).read_text()))
+            artifacts.append(json.loads(Path(f).read_text(encoding="utf-8")))
         except json.JSONDecodeError as e:
             print(f"warning: skipped malformed artifact {f}: {e}", file=sys.stderr)
     return artifacts
@@ -213,9 +213,9 @@ def _validate_artifact(art: dict, valid_nodes: set) -> Optional[str]:
 
 def cmd_update(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     state = PheromoneState.load(paths.pheromone_current)
-    task_space = json.loads(paths.task_space.read_text())
+    task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
     valid_nodes = set(task_space["nodes"])
 
     artifacts = _load_iteration_artifacts(paths, args.iter)
@@ -266,7 +266,7 @@ def cmd_update(args: argparse.Namespace) -> None:
     # Elitist: re-load best history, deposit extra on best path
     best_data = None
     if paths.best.exists():
-        best_data = json.loads(paths.best.read_text())
+        best_data = json.loads(paths.best.read_text(encoding="utf-8"))
     current_best = max(scored, key=lambda x: x["score"]) if scored else None
     if current_best:
         best_art = next(a for a in artifacts if a["ant_id"] == current_best["ant_id"])
@@ -281,7 +281,7 @@ def cmd_update(args: argparse.Namespace) -> None:
                 "evidence": best_art.get("evidence", []),
                 "updated_at": time.time(),
             }
-            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False))
+            paths.best.write_text(json.dumps(best_data, indent=2, ensure_ascii=False), encoding="utf-8")
         # Elite deposit
         state.deposit(best_data["path"], best_data["score"])
 
@@ -292,14 +292,14 @@ def cmd_update(args: argparse.Namespace) -> None:
 
     # Persist trails
     trails_file = paths.trails / f"{args.iter}.jsonl"
-    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log))
+    trails_file.write_text("\n".join(json.dumps(t, ensure_ascii=False) for t in trail_log), encoding="utf-8")
 
     mean_score = sum(s["score"] for s in scored) / len(scored) if scored else 0.0
     best_score = best_data["score"] if best_data else 0.0
     prev_best = 0.0
     history_files = sorted(paths.pheromone_history.glob("*.json"))
     if len(history_files) >= 2:
-        prev = json.loads(history_files[-2].read_text())
+        prev = json.loads(history_files[-2].read_text(encoding="utf-8"))
         prev_best = prev.get("stats", {}).get("best_known", best_score)
     delta = best_score - prev_best
 
@@ -323,7 +323,7 @@ def cmd_update(args: argparse.Namespace) -> None:
 
 def cmd_converged(args: argparse.Namespace) -> None:
     paths = SessionPaths(Path(args.session))
-    config = json.loads(paths.config.read_text())
+    config = json.loads(paths.config.read_text(encoding="utf-8"))
     cv = config.get("convergence", {})
 
     state = PheromoneState.load(paths.pheromone_current)
@@ -339,7 +339,7 @@ def cmd_converged(args: argparse.Namespace) -> None:
     }
 
     if paths.best.exists():
-        metrics["best_score"] = json.loads(paths.best.read_text()).get("score", 0.0)
+        metrics["best_score"] = json.loads(paths.best.read_text(encoding="utf-8")).get("score", 0.0)
 
     # max_iterations
     max_iter = cv.get("max_iterations", 5)
@@ -397,7 +397,7 @@ def cmd_report(args: argparse.Namespace) -> None:
 
     best = None
     if paths.best.exists():
-        best = json.loads(paths.best.read_text())
+        best = json.loads(paths.best.read_text(encoding="utf-8"))
 
     # Top-K trails across all iterations
     all_trails = []
@@ -410,7 +410,7 @@ def cmd_report(args: argparse.Namespace) -> None:
     # Convergence curve
     curve = []
     for hf in sorted(paths.pheromone_history.glob("*.json"), key=lambda p: int(p.stem)):
-        snap = json.loads(hf.read_text())
+        snap = json.loads(hf.read_text(encoding="utf-8"))
         curve.append({
             "iteration": snap["iteration"],
             "entropy": snap["stats"]["entropy"],

package/.agents/skills/team-swarm/scripts/pheromone.py

@@ -114,11 +114,11 @@ class PheromoneState:
 
     def save(self, path: Path) -> None:
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False))
+        path.write_text(json.dumps(self.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
 
     @classmethod
     def load(cls, path: Path) -> "PheromoneState":
-        return cls.from_dict(json.loads(path.read_text()))
+        return cls.from_dict(json.loads(path.read_text(encoding="utf-8")))
 
     def select_neighbors(
         self,

package/.agents/skills/team-swarm/scripts/scoring.py

@@ -62,7 +62,7 @@ def load_verified_scores(scores_file: Path) -> Dict[str, float]:
     """Load pre-computed verified_scores from scorer role output (if exists)."""
     if not scores_file.exists():
         return {}
-    data = json.loads(scores_file.read_text())
+    data = json.loads(scores_file.read_text(encoding="utf-8"))
     return {
         ant_id: entry["verified_score"]
         for ant_id, entry in data.get("scores", {}).items()

package/.agy/skills/maestro-analyze/SKILL.md

@@ -22,6 +22,8 @@ Combines structured 6-dimension scoring with iterative deepening and decision ex
 Use `-q` for quick decision extraction only (skip exploration + scoring).
 
 Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyze). Loads issues from issues.jsonl, performs CLI exploration against issue context/location, synthesizes root cause into issue.analysis, and outputs context.md for downstream `plan --gaps`.
+
+Pipeline position: downstream of maestro-grill, maestro-brainstorm, and maestro-blueprint (optional upstream enrichment); upstream of maestro-plan and maestro-roadmap (consumes analysis context).
 </purpose>
 
 <required_reading>
@@ -47,31 +49,47 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 - Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
-- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
-- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
-- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path)
-- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
-Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive scoping, use recommended defaults, auto-deepen | false |
+| `-c` / `--continue` | Resume from existing session (auto-detect session folder + discussion.md) | false |
+| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only) | false |
+| `--from <source>` | Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path) | — |
+| `--gaps [ISS-ID]` | Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl | — |
+
+**Scope routing:**
+| Input | Mode | Scope |
+|-------|------|-------|
+| Pure digits (e.g. `1`, `42`) | micro | Phase-level deep analysis |
+| Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
+| No positional arg + roadmap | micro | Milestone-wide |
+| No positional arg + no roadmap | macro | Fallback |
+| `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
+
+Output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Output Structure section).
+
+### Pre-load
+
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+3. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. All optional — proceed without if unavailable (log warning)
 
 ### Role Knowledge
 `maestro wiki list --category debug` → select relevant → `maestro wiki load`
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (explicit phase number or unambiguous topic).
-
-- One decision per turn via ask_question with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, Read, or — for open-ended multi-file scans — spawn `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately appended/updated in `discussion.md` (top table) and mirrored into `context.md` "Interview Decisions". Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
-- Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
-
-Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
-
-Exit: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/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
+**Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
+**Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
+**Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
+**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
+**Exit condition**: all decision points settled → finalize session metadata
 </interview_protocol>
 
 <execution>
@@ -108,23 +126,52 @@ Phase 4: Output context.md for downstream plan --gaps
 - `large` (3+ independent subsystems or hard serial dependencies) → suggest `/maestro-roadmap --from analyze:ANL-xxx`
 - `medium` (1-2 subsystems, parallelizable) → suggest `/maestro-plan --from analyze:ANL-xxx`
 - `small` (single-file or few-file change) → suggest `/maestro-plan --from analyze:ANL-xxx`
+</execution>
 
-**Next-step routing on completion:**
+<completion>
+### Standalone report
 
-Phase/Milestone scope (micro mode):
-- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
-- Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
-- No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
+```
+=== ANALYSIS READY ===
+Artifact: ANL-{id}
+Scope: {micro|macro|adhoc|gaps}
+Go/No-Go: {GO|NO-GO|CONDITIONAL}
+Confidence: {high|medium|low}
+Outputs: analysis.md, context.md, conclusions.json, discussion.md
+Session dir: {output_dir}
+===
+```
 
-Macro/Adhoc/Standalone scope:
-- scope_verdict = large → `/maestro-roadmap --from analyze:ANL-xxx`
-- scope_verdict = medium/small → `/maestro-plan --from analyze:ANL-xxx`
-- Need more exploration → `/maestro-analyze {topic} -c`
+### Ralph-invoked completion
 
-Gaps scope:
-- Issues analyzed → `/maestro-plan --gaps` (plan fix tasks linked to issues)
-- Need more context → `/maestro-analyze --gaps {ISS-ID}` (re-analyze specific issue)
-</execution>
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Phase/Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Phase/Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {phase}` |
+| Phase/Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
+| Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
+| Need more exploration | `/maestro-analyze {topic} -c` |
+| Gaps scope, issues analyzed | `/maestro-plan --gaps` |
+| Gaps scope, need more context | `/maestro-analyze --gaps {ISS-ID}` |
+
+### Session seal
+
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
@@ -168,6 +215,3 @@ Both modes (full + quick):
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>
 
-<on_complete>
-@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
-</on_complete>

package/.agy/skills/maestro-blueprint/SKILL.md

@@ -22,6 +22,8 @@ Parallel to `brainstorm` as an upstream origin command:
 - **blueprint** = convergent documentation (heavyweight, 6-phase formal spec chain)
 
 Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
+
+Pipeline position: downstream of maestro-brainstorm (optional). Upstream of maestro-analyze, maestro-roadmap, and maestro-plan.
 </purpose>
 
 <required_reading>
@@ -36,10 +38,13 @@ Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD,
 $ARGUMENTS -- idea text, @file reference, or upstream context source.
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint (reads blueprint-config.json)
-- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json
-- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint (reads blueprint-config.json) | false |
+| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
 
 **Input types:**
 - Direct text: `"Build a real-time collaboration platform with WebSocket"`
@@ -58,23 +63,22 @@ maestro-analyze → maestro-roadmap → maestro-plan
 
 **Output boundary**: ALL file writes MUST target `.workflow/blueprint/BLP-{slug}-{date}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
-2. Optional — proceed without if unavailable.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints for Phase 4 decisions
+2. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → prior knowledge context
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
-
-- Ask one question per turn via ask_question and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro spec load`, direct codebase exploration (Glob/Grep/Read), or — for open-ended multi-file scans — spawn `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
-- Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
-- Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.
-
-Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
-
-Exit: on consensus or explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) and proceed to Phase 1.
+Follows @~/.maestro/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
+**Scope guard**: only specification shape; do not pre-resolve roadmap phases or plan tasks
+**Writeback target**: blueprint-config.json (each decision persisted before next question)
+**Additional skip conditions**: none beyond standard (-y, -c)
+**Exit condition**: all decision points settled → finalize blueprint-config.json, proceed to Phase 1
 </interview_protocol>
 
 <execution>
@@ -88,15 +92,44 @@ P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief
 
 P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
 
-### Next-step routing on completion
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== BLUEPRINT READY ===
+Session: BLP-{slug}-{date}
+Phases completed: P0–P6
+Readiness score: {score}%
+Gate verdict: {Pass|Review|Fail}
+Output: .workflow/blueprint/BLP-{slug}-{date}/
+Key artifacts: product-brief.md, requirements/, architecture/, epics/, readiness-report.md
+===
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Need codebase analysis | /maestro-analyze {topic} --from blueprint:BLP-xxx |
-| Ready for roadmap | /maestro-roadmap --from blueprint:BLP-xxx |
-| Small scope, direct plan | /maestro-plan --from blueprint:BLP-xxx |
-| Need project setup | /maestro-init |
-</execution>
+| Need codebase analysis | `/maestro-analyze {topic} --from blueprint:BLP-xxx` |
+| Ready for roadmap | `/maestro-roadmap --from blueprint:BLP-xxx` |
+| Small scope, direct plan | `/maestro-plan --from blueprint:BLP-xxx` |
+| Need project setup | `/maestro-init` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |