mk:workflow-orchestrator

<!-- Split for progressive disclosure (checklist #11, #14): 463 → ~75 lines -->

Workflow Orchestrator

Priority: CRITICAL — Use for complex feature implementations.

Only activates on session start for complex-feature intent. If /mk:cook was explicitly invoked in this session, do not activate — mk:cook owns the pipeline. See .claude/rules/orchestration-rules.md"Orchestrator Entry Point Rule".

Plan-First Gate

Orchestrator enforces the plan-first pattern for all workflows:

1. On task received → check for existing approved plan
2. If no plan and task is non-trivial → route to mk:plan-creator first
3. After Gate 1 approval → select workflow model and execute phases

Skip: Fasttrack mode with pre-approved spec.

When to Use

USE for: New features, complex implementations, tasks >2 hours, multi-file changes, tasks requiring TDD.

DON'T use for: Bug fixes → mk:fix, quick refactors → direct edit, config changes → direct edit, simple questions → just answer.

Pre-Execution Checklist

1. agent-detector → Select lead agent (MANDATORY)
2. Load context → Read .claude/memory/fixes.md + .claude/memory/architecture-decisions.json (Phase 0 Orient)
3. Show agent banner at start of response
4. Verify task complexity — if simple, suggest lighter approach
5. Challenge requirements → Ask clarifying questions before Phase 1

Process

See .claude/rules/phase-contracts.md for input/output expectations per phase. (Loaded by mk:agent-detector Step 0b at session start.)

1. Run pre-execution checklist — select lead agent, load memory, show agent banner, verify complexity, challenge requirements.

1. Detect workflow mode — check for fasttrack: prefix or Agent Teams trigger; if present load references/fasttrack-and-teams.md. Otherwise proceed with standard 7-phase flow.

1. Execute phases sequentially — load references/workflow-phases.md then run:
2. Phase 0: Orient — model tier, execution mode, TDD mode detection, read memory. Auto-continue.
3. Phase 1: Plan → GATE 1 (human approval required)
4. Phase 2: Test — in TDD mode (--tdd / MEOWKIT_TDD=1), write failing tests; in default mode, optional / on-request only. Auto-continue.
5. Phase 3: Build — implement per the plan. In TDD mode, code must make failing tests pass. Auto-continue.
6. Phase 3.5: Simplify — run mk:simplify after build (after tests pass in TDD mode). MANDATORY before Phase 4. Auto-continue.
7. Phase 4: Review — quality/security audit → GATE 2 (human approval required, NO EXCEPTIONS)
8. Phase 5: Ship — commit, PR, deploy. Auto-continue.
9. Phase 6: Reflect — memory capture, docs sync. Auto-complete.

1. At each phase boundary — check token budget (warn at 75%, handoff at 90%). Show what comes next before continuing. Save state via workflow:handoff if context is near limit. Also delegate to project-manager after each phase transition per .claude/rules/post-phase-delegation.md Rule 1 (background, non-blocking — include "Run in the background" in the prompt). Skipped when MEOWKIT_PM_AUTO=off.

Only 2 approval gates: Phase 1 (Plan) and Phase 4 (Review). Everything else auto-continues.

References

| Reference | When to load | Content | | ----------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- | | [workflow-phases.md](./references/workflow-phases.md) | Steps 2-6 — executing phases | Phase details, transition rules, approval gates, token budgets, TDD rules | | [fasttrack-and-teams.md](./references/fasttrack-and-teams.md) | Only if fasttrack trigger or Agent Teams enabled | Fast-track mode, spec validation, Agent Teams composition, state management |

Key Rules

• TDD is OPT-IN (post-migration): default mode skips Phase 2 RED gate; enable with --tdd or MEOWKIT_TDD=1. In TDD mode the cycle is RED → GREEN → REFACTOR.
• KISS: Simple over complex, standard patterns over custom
• Token budget: Target ≤30K for full workflow. Warn at 75%, handoff at 90%.
• State: workflow:handoff saves, workflow:resume <id> continues
• ALWAYS show what's next after each phase

Related Rules

• .claude/rules/gate-rules.md — Gate 1 (Plan) and Gate 2 (Review) hard-stop conditions enforced by this orchestrator
• .claude/rules/injection-rules.md — DATA vs INSTRUCTIONS boundary; applies to all file/tool output processed during orchestration

Gotchas

• Parallel agents editing same file: Two subagents modify the same source file simultaneously → Define exclusive file ownership before spawning parallel agents
• Token budget exceeded mid-workflow: Complex 7-phase workflow runs out of context → Check remaining context at each phase boundary; escalate if < 20% remaining