Master orchestrator

master-orchestrator

Why This Skill Exists

The five former orch-* skills (orch-build-mvp, orch-add-feature, orch-change-feature, orch-fix-defect, orch-refine-code) shared an identical underlying pipeline — Research → Plan → TDD → Deliver — and differed only in three settings: size floor, phase mask, and TDD first move. Per the Three-Principle Framework in the refactor spec:

• Each skill's unique input (user intent) was the sole output of an implicit intent-classifier with no other consumer → sequential workflow → MERGE.
• Combined token budget stays well under 5 K, so no Needle-in-a-Haystack risk.

session-state, ck, and handoff remain independent (cross-cutting, shared-state, never-merge zone).

---

Intent Router (State Machine)

Read the user's request and classify it through this decision tree before doing anything else.

User request
    │
    ▼
Does a spec/SDD/PRD document exist as input?
    ├── YES → Mode: BUILD_MVP
    └── NO
         │
         ▼
    Does the capability exist in the codebase yet?
         ├── NO  → Mode: ADD_FEATURE
         └── YES
              │
              ▼
         Is it currently broken / producing wrong output?
              ├── YES → Mode: FIX_DEFECT
              └── NO
                   │
                   ▼
              Does the desired behavior change?
                   ├── YES → Mode: CHANGE_FEATURE
                   └── NO  → Mode: REFINE_CODE

Signals by mode:

Mode	Trigger phrases
BUILD_MVP	"build from this SDD/PRD/spec", "bootstrap the project", "start from this doc"
ADD_FEATURE	"add", "implement", "build X" (X doesn't exist)
FIX_DEFECT	"broken", "crash", "wrong output", "regression", "error", "bug"
CHANGE_FEATURE	"change X to Y", "make it do Y instead", "adjust", "alter"
REFINE_CODE	"refactor", "clean up", "extract", "simplify", "remove duplication"

If the intent is ambiguous, ask one clarifying question before proceeding.

---

Mode Settings

Once the mode is identified, apply these settings to the shared pipeline below:

Setting	BUILD_MVP	ADD_FEATURE	FIX_DEFECT	CHANGE_FEATURE	REFINE_CODE
Size floor	large	standard	small	small	standard
Phase mask	0→1→2→3→4→5→6	0→1→2→4→5→6	0→(2?)→4→5→6	0→(1?)→2→4→5→6	0→2→4→5→6
TDD first move	GAN framework from spec	Write new failing tests	Write regression test reproducing the bug	Update existing tests to new spec, then implement	Confirm existing tests green; add characterization tests if coverage thin
Commit prefix	feat: (per slice)	feat:	fix:	feat:	refactor:
Phase 3 (Scaffold)?	✅ required	❌ skip	❌ skip	❌ skip	❌ skip
Research (Phase 1)?	✅ always	✅ default on	❌ usually skip	conditional	❌ skip

Phases at a glance:

0 → Ingest (read spec / explore code)
1 → Research (external docs, libs, prior art)
2 → Plan (task_list / restructure plan)  ← GATE 1: user approves
3 → Scaffold (MVP only: stand up first vertical slice)
4 → TDD (red → green, per mode's first move)
5 → Code Review (+ security-reviewer if security trigger)
6 → Commit  ← GATE 2: user confirms

---

Shared Pipeline Execution

Phase 0 — Ingest

• BUILD_MVP: Read the spec document at the given path. Extract: scope, locked decisions, feature list. Order into thin vertical slices (one end-to-end path first, not all-models-then-all-views).
• All other modes: Run code-explorer to map the relevant module/file set.

Phase 1 — Research (conditional, see table)

• Delegate to documentation-lookup or deep-research agent.
• Skip if mode is FIX_DEFECT (root cause is in the code, not docs) or REFINE_CODE (no new behavior).

Phase 2 — Plan

Produce a task_list (ordered subtasks, each implementable in one TDD cycle). For BUILD_MVP, phase 2 is heavy: translate the ingested SDD into gan-FRM/spec.md + gan-FRM/eval-rubric.md.

GATE 1: Present the plan to the user. Do not proceed until approved. For FIX_DEFECT where root cause is obvious, Gate 1 may be skipped.

Phase 3 — Scaffold (BUILD_MVP only)

Stand up the first vertical slice using the GAN framework:

/gan-build "<one-line brief>" --skip-planner

Defaults: --max-iterations 15, --pass-threshold 7.0, --eval-mode playwright (use --eval-mode code-only for non-UI slices). Commit the scaffold as a separate feat: commit before iterating.

Phase 4 — TDD

Apply the mode-specific first move (see Mode Settings table), then run the RED → GREEN → REFACTOR cycle per task in the task_list. Each task is one atomic TDD cycle.

Phase 5 — Code Review

Run code-review agent on the diff. Auto-add security-reviewer if any of these triggers appear: auth, permissions, cryptography, external data ingestion, payment processing, PII.

Phase 6 — Commit

GATE 2: Show the user: diff summary, test results, review findings. Commit only after explicit confirmation.

git add -p   # stage selectively
git commit -m "<prefix>: <concise description>"

---

Size Classifier

When the size floor is standard or large, classify the request first. Apply phase collapse for smaller work:

Size	Rule of thumb	Phase behaviour
trivial	< 5 lines, single function	Skip 1 and 2; go straight 0→4→5→6
small	single file or isolated module	Floor for FIX_DEFECT and CHANGE_FEATURE
standard	multi-file, clear boundary	Default floor; full 2-phase plan
large	cross-cutting or multi-slice	Floor for BUILD_MVP; heavy phase 2

---

Examples

# BUILD_MVP
master-orchestrator: civicpulse/docs/SDD-v0.6.md
→ read SDD → slice list (vertical) → scaffold slice 1  [GATE 1]
→ /gan-build --skip-planner (generator → evaluator loop) → review
→ commit feat:  [GATE 2] → next slice

# ADD_FEATURE
master-orchestrator: add OAuth2 login to nws-poller
→ research auth libs → task_list  [GATE 1]
→ new failing tests → implement to green → code-review (+ security-reviewer)
→ commit feat:  [GATE 2]

# FIX_DEFECT
master-orchestrator: poller crashes on empty NWS response
→ regression test reproducing crash → fix to green
→ code-review → commit fix:  [GATE 2]

# CHANGE_FEATURE
master-orchestrator: alert at 2 warnings instead of 3
→ update threshold tests to new spec → change impl to green
→ code-review → commit feat:  [GATE 2]

# REFINE_CODE
master-orchestrator: extract the NWS HTTP client out of poller.py
→ confirm tests green → restructure plan  [GATE 1]
→ move in small steps (tests green throughout) → code-review
→ commit refactor:  [GATE 2]

---

Migration Notes

Deprecated skill	Replaced by	Mode
orch-build-mvp	master-orchestrator	BUILD_MVP
orch-add-feature	master-orchestrator	ADD_FEATURE
orch-fix-defect	master-orchestrator	FIX_DEFECT
orch-change-feature	master-orchestrator	CHANGE_FEATURE
orch-refine-code	master-orchestrator	REFINE_CODE

The underlying orch-pipeline engine is unchanged; only the five thin-wrapper files are retired.