maestro-flow 0.3.30 → 0.3.32

package/workflows/maestro.md

@@ -1,8 +1,8 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Dual execution engines: **Skill()** (in-process, synchronous) and **CLI delegate** (via `maestro delegate`, async with role-based tool selection).
-Default `auto` mode selects engine based on chain complexity.
+Two step types: **Skill** (in-process, synchronous) and **CLI** (via `maestro delegate`, async with role-based tool selection).
+Default `auto` mode selects type based on step complexity. All execution dispatched to unified executor (`maestro-ralph-execute`).
 
 **Prerequisites:**
 - None for initial invocation (can bootstrap)
@@ -226,18 +226,18 @@ When executing issue chains, replace `{issue_id}` in step args with resolved ID.
 **If not `autoYes`:** Confirm with user — show numbered steps, offer: Execute / Execute from step N / Cancel.
 If user chooses "Execute from step N": set `$START_STEP = N` (used in 3f to set `current_step`).
 
-### 3e: Step-level engine selection
+### 3e: Step-level type selection
 
-Engine is selected **per step**, not per chain. Pre-compute and write to each step's `engine` field in status.json (execution workflow reads this, does not re-compute).
+Step type is selected **per step**, not per chain. Pre-compute and write to each step's `type` field in status.json (executor reads this, does not re-compute).
 
 ```
-If execMode is 'cli' or 'internal' → force that engine for all steps.
+If execMode is 'cli' or 'internal' → force that type for all steps ("cli" or "skill").
 In 'auto' mode, select per step:
-  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-roadmap, maestro-ui-design, quality-refactor
-  Internal steps (everything else): current-session Skill() call — verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc.
+  CLI steps (heavy, context-isolated): maestro-plan, maestro-execute, maestro-analyze, maestro-brainstorm, maestro-roadmap, maestro-ui-design, quality-refactor → type: "cli"
+  Skill steps (everything else): current-session Skill() call — verify, review, test, debug, milestone-*, manage-*, spec-*, quick, etc. → type: "skill"
 ```
 
-**Trade-off:** CLI = context isolation + template prompts + gemini analysis. Internal = current-session Skill() call, direct visibility + synchronous + user can intervene.
+**Trade-off:** CLI = context isolation + template prompts. Skill = current-session Skill() call, direct visibility + synchronous + user can intervene.
 
 ### 3f: Low-complexity fast path (before session creation)
 
@@ -262,17 +262,22 @@ Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and wri
   "auto_mode": "{autoYes}",
   "exec_mode": "{execMode}",
   "cli_tool": "{cliTool}",
-  "gemini_session_id": null,
-  "step_analyses": [],
   "context": {
-    "current_phase": "{resolved_phase}",
-    "user_intent": "{original_intent}",
     "issue_id": "{resolved_issue_id or null}",
     "milestone_num": "{current_milestone_num or null}",
     "spec_session_id": null,
-    "scratch_dir": null
+    "scratch_dir": null,
+    "plan_dir": null,
+    "analysis_dir": null,
+    "brainstorm_dir": null
   },
-  "steps": [{ "index": 0, "skill": "{chainMap[].cmd}", "args": "{chainMap[].args}", "engine": "{cli|internal from 3e}", "status": "pending", "started_at": null, "completed_at": null }],
+  "source": "maestro",
+  "updated_at": "{ISO timestamp}",
+  "milestone": null,
+  "lifecycle_position": null,
+  "target": null,
+  "waves": [],
+  "steps": [{ "index": 0, "skill": "{chainMap[].cmd}", "args": "{chainMap[].args}", "type": "{cli|skill from 3e}", "status": "pending", "started_at": null, "completed_at": null, "error": null }],
   "current_step": "{$START_STEP or 0}",
   "status": "running"
 }
@@ -290,12 +295,15 @@ const todos = steps.map((step, i) => ({
 TodoWrite({ todos });
 ```
 
-## Step 4: Dispatch to execution workflow
+## Step 4: Dispatch to unified executor
 
 status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 
-1. Read `~/.maestro/workflows/maestro-chain-execute.md`
-2. Follow it with `$SESSION_PATH` = session directory from Step 3g
+```
+Skill({ skill: "maestro-ralph-execute" })
+```
+
+The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps sequentially. For maestro sessions (source: "maestro"), there are no decision nodes — execution is purely sequential.
 
 ---
 
@@ -484,8 +492,8 @@ detectNextAction(state):
 1. **Semantic Routing** — LLM-native `action × object` extraction; disambiguates "问题" by context
 2. **State-Aware** — Reads `.workflow/state.json` before routing
 3. **Quality Gates** — Issue chains auto-include review; `issue-full` is default for issue execution
-4. **Per-Step Engine** — Each step independently selects internal or CLI. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (verify, review, test, debug, manage-*) → internal (current-session Skill()) for direct visibility. `--exec cli|internal` forces all steps.
-5. **CLI Analysis Chain** — Gemini evaluates each CLI step's output, generates `next_step_hints` via `{{ANALYSIS_HINTS}}`. Internal steps skip analysis (output already visible). Sessions chained via `--resume`
+4. **Per-Step Type** — Each step independently typed as `"skill"` or `"cli"`. Heavy steps (plan, execute, analyze, brainstorm) → CLI for context isolation. Observable steps (verify, review, test, debug, manage-*) → Skill (current-session) for direct visibility. `--exec cli|internal` forces all steps.
+5. **Unified Executor** — All execution dispatched to `maestro-ralph-execute`, which handles both maestro (static chain) and ralph (adaptive chain with decision nodes) sessions.
 6. **Phase Propagation** — Auto-detects and passes phase numbers to downstream commands
 7. **Auto Mode** — `-y` propagates through chain, skipping all confirmations
 8. **Resumable** — Session state in `.workflow/.maestro/` enables `-c` resume

package/workflows/plan.md

@@ -70,7 +70,7 @@ default             → Create Mode: P1 → P2 → P3 → P4 → P4.5 → P5
    - Read `${CONTEXT_DIR}/context.md` if exists, else warn (no upstream analyze)
 
 2. **Load spec reference** (if `--spec` flag or index.json has spec_ref)
-   - Read from `.workflow/task-specs/${spec_ref}/`: spec-summary.md, requirements/_index.md, epics/_index.md
+   - Read from `.workflow/.spec/${spec_ref}/`: spec-summary.md, requirements/_index.md, epics/_index.md
 
 3. **Load project specs**
    ```

package/workflows/verify.md

@@ -42,7 +42,7 @@ Milestone mode creates output dir: .workflow/scratch/verify-{milestone_slug}-{da
 ## V0: Load Project Specs
 
 ```
-specs_content = maestro spec load --category validation
+specs_content = maestro spec load --category quality
 ```
 
 Pass specs_content to verifier agent as quality standards context.

package/dist/src/hooks/context-monitor.d.ts

@@ -1,33 +0,0 @@
-/**
- * Maestro Context Monitor — PostToolUse Hook
- *
- * Reads bridge file written by statusline hook, injects warnings
- * into agent context when usage is high.
- *
- * Bridge file: /tmp/maestro-ctx-{session_id}.json
- *
- * Thresholds:
- *   WARNING  (remaining <= 35%) — wrap up current task
- *   CRITICAL (remaining <= 25%) — stop and inform user
- *
- * Debounce: 5 tool calls between warnings; severity escalation bypasses it.
- */
-interface MonitorInput {
-    session_id?: string;
-    cwd?: string;
-}
-interface HookOutput {
-    hookSpecificOutput: {
-        hookEventName: string;
-        additionalContext: string;
-    };
-}
-/**
- * Evaluate context metrics and return a warning if thresholds are crossed.
- * Returns null if no warning needed.
- */
-export declare function evaluateContext(data: MonitorInput): HookOutput | null;
-/** Entry point — reads stdin JSON, writes hook output to stdout */
-export declare function runContextMonitor(): void;
-export {};
-//# sourceMappingURL=context-monitor.d.ts.map

package/dist/src/hooks/context-monitor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-monitor.d.ts","sourceRoot":"","sources":["../../../src/hooks/context-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAcD,UAAU,UAAU;IAClB,kBAAkB,EAAE;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAiCD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CA8DrE;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,IAAI,IAAI,CAmBxC"}

package/dist/src/hooks/context-monitor.js

@@ -1,128 +0,0 @@
-/**
- * Maestro Context Monitor — PostToolUse Hook
- *
- * Reads bridge file written by statusline hook, injects warnings
- * into agent context when usage is high.
- *
- * Bridge file: /tmp/maestro-ctx-{session_id}.json
- *
- * Thresholds:
- *   WARNING  (remaining <= 35%) — wrap up current task
- *   CRITICAL (remaining <= 25%) — stop and inform user
- *
- * Debounce: 5 tool calls between warnings; severity escalation bypasses it.
- */
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { WARNING_THRESHOLD, CRITICAL_THRESHOLD, STALE_SECONDS, DEBOUNCE_CALLS, BRIDGE_PREFIX, } from './constants.js';
-import { resolveWorkspace } from './workspace.js';
-import { isAutoMode } from './auto-mode.js';
-/** Build the warning message based on severity, workflow presence, and auto mode */
-function buildMessage(usedPct, remaining, isCritical, hasWorkflow, autoMode) {
-    // Auto mode (-y): never instruct the model to stop — let the chain finish
-    if (autoMode) {
-        return isCritical
-            ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-                'Finish current chain step. Progress tracked in status.json. ' +
-                'Chain can resume with /maestro -c in a new session.'
-            : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-                'Finish current chain step, then stop chain. Resume with /maestro -c.';
-    }
-    if (isCritical) {
-        return hasWorkflow
-            ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-                'Context is nearly exhausted. Do NOT start new complex work. ' +
-                'State is tracked in .workflow/state.json. Inform the user so they can ' +
-                'decide how to proceed (e.g. /maestro -c or pause).'
-            : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-                'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
-                'want to proceed. Do NOT autonomously save state or write handoff files unless asked.';
-    }
-    return hasWorkflow
-        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-            'Context is getting limited. Avoid starting new complex work. ' +
-            'If between plan steps, inform the user so they can prepare to pause.'
-        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
-            'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
-            'starting new complex work.';
-}
-/**
- * Evaluate context metrics and return a warning if thresholds are crossed.
- * Returns null if no warning needed.
- */
-export function evaluateContext(data) {
-    const sessionId = data.session_id;
-    if (!sessionId)
-        return null;
-    const tmp = tmpdir();
-    const metricsPath = join(tmp, `${BRIDGE_PREFIX}${sessionId}.json`);
-    if (!existsSync(metricsPath))
-        return null;
-    const metrics = JSON.parse(readFileSync(metricsPath, 'utf8'));
-    const now = Math.floor(Date.now() / 1000);
-    // Stale check
-    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS)
-        return null;
-    const { remaining_percentage: remaining, used_pct: usedPct } = metrics;
-    // Below threshold — no warning
-    if (remaining > WARNING_THRESHOLD)
-        return null;
-    // --- Debounce ---
-    const warnPath = join(tmp, `${BRIDGE_PREFIX}${sessionId}-warned.json`);
-    let warnData = { callsSinceWarn: 0, lastLevel: null };
-    let firstWarn = true;
-    if (existsSync(warnPath)) {
-        try {
-            warnData = JSON.parse(readFileSync(warnPath, 'utf8'));
-            firstWarn = false;
-        }
-        catch {
-            // Corrupted — reset
-        }
-    }
-    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
-    const currentLevel = isCritical ? 'critical' : 'warning';
-    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
-    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-        writeFileSync(warnPath, JSON.stringify(warnData));
-        return null;
-    }
-    // Reset debounce
-    warnData.callsSinceWarn = 0;
-    warnData.lastLevel = currentLevel;
-    writeFileSync(warnPath, JSON.stringify(warnData));
-    // Detect maestro workflow state via workspace resolver
-    const hasWorkflow = resolveWorkspace(data) !== null;
-    const autoMode = hasWorkflow && isAutoMode(data);
-    const message = buildMessage(usedPct, remaining, isCritical, hasWorkflow, autoMode);
-    return {
-        hookSpecificOutput: {
-            hookEventName: 'PostToolUse',
-            additionalContext: message,
-        },
-    };
-}
-/** Entry point — reads stdin JSON, writes hook output to stdout */
-export function runContextMonitor() {
-    let input = '';
-    const timeout = setTimeout(() => process.exit(0), 3000);
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (chunk) => (input += chunk));
-    process.stdin.on('end', () => {
-        clearTimeout(timeout);
-        try {
-            const data = JSON.parse(input);
-            const result = evaluateContext(data);
-            if (result) {
-                process.stdout.write(JSON.stringify(result));
-            }
-        }
-        catch {
-            // Silent fail — never block tool execution
-            process.exit(0);
-        }
-    });
-}
-//# sourceMappingURL=context-monitor.js.map

package/dist/src/hooks/context-monitor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"context-monitor.js","sourceRoot":"","sources":["../../../src/hooks/context-monitor.ts"],"names":[],"mappings":"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"}