aidp-fusion-autopilot

aidp-fusion-autopilot — one goal, driven A-to-Z

Turns "I want a CFO dashboard of supplier spend vs GL balance, by currency" into a finished workbook by conducting the existing skill family — it does not re-implement any step. Its only jobs are: detect where the user already is, drive the next incomplete step via the right skill, and stop at the decisions a human must make.

This is the single entry point so the user never has to know which of the seven skills to invoke, or in what order.

When to use

• The user states a goal and wants it taken end-to-end ("take me from nothing to a dashboard", "set up Fusion analytics for X", "autopilot this").
• Resuming a half-done journey ("finish setting up my supplier dashboard").

When NOT to use

• A single known step → call that skill directly (/aidp-fusion-seed, /oac-dataset-advisor, /mart-author, /workbook-authoring, …). Autopilot is overhead when the user already knows the one thing they want.

Operating principles

1. Compose, never reimplement. Each step delegates to a sibling skill or a CLI command. Autopilot owns only sequencing + state.
2. State-first — don't redo finished work. Detect each step's status before acting (a tenant with gold already seeded skips straight to advise).
3. Inherit the sub-skills' guards. The seed destructive guard, the advisor's live-evidence rule, bootstrap's variation-freeze surfacing — autopilot never weakens them. It auto-advances only on a clean result.
4. Pause at human decisions (see gates). Auto-advance otherwise. Always show the journey state + what it's about to do before a state-changing step.

---

The journey (step state machine)

#	Step	Done when (detect)	Drive with	PAUSE before if
1	Config	bundle.yaml + aidp.config.yaml exist; coords non-placeholder	aidp-fusion-bundle init (scaffold if absent — fresh install) → /aidp-fusion-config for coords	missing fusion: connectivity (human-only)
1b	OAC MCP connect (front-loaded prerequisite — see §below)	oac-mcp-server tools answer a live search_catalog ping	project-scoped dashboard mcp-setup, then restart/reconnect Claude Code	always when dead — staging the connector needs a Claude Code restart before its tools work; write the resume checkpoint, then PAUSE for the restart
2	Bootstrap	profiles/<tenant>.yaml present + fingerprint pinned	/aidp-fusion-bootstrap	multi-match variation needs a human pick (never --non-interactive); surface frozen picks
3	Seed	live gold has the needed tables (probe)	/aidp-fusion-seed	always confirm the destructive guard's CONFIRM outcome
4	Advise	— (always run for the goal)	/oac-dataset-advisor	—
5	Author mart (only on advisor GAP)	the gap node exists live after seed	/mart-author → use-pack → back to Step 3	confirm the authored change before seeding it
6	OAC dataset	a dataset over the recommended table(s) exists (OAC MCP)	/oac-dataset-setup	always — dataset creation is an OAC UI action today (MCP can't create datasets); hand the exact spec to the user
7	Workbook	a workbook on that dataset exists/renders	/workbook-authoring	confirm overwrite if replacing an existing workbook
8	End-user MCP chat (optional deliverable)	least-privilege OAC user handed the connect steps	docs/oac_mcp_setup.md hand-off	confirm the end-user OAC account is least-privilege (v1.4 exposes write/delete/ACL tools)

Steps 6–7 read OAC through the oac-mcp-server tools (autopilot's own detectors and /workbook-authoring's required tools). That connection is Step 1b, a prerequisite — not Step 8. Step 8 is a different thing: enabling end users to chat with their own clients. Don't conflate them.

Step 1b — OAC MCP connectivity (front-loaded prerequisite)

Why front-loaded (not Step 8). /workbook-authoring and autopilot's own step-6/7 detectors consume the oac-mcp-server tools (search_catalog, describe_data, save-validation). They are a prerequisite for the OAC half of the journey. And establishing the connector (dashboard mcp-setup) requires a Claude Code restart/reconnect before the tools come alive (docs/oac_mcp_setup.md — MCP servers bind at session start; a mid-flow setup can't transparently light them up). So the connection is set up early, once, before the minutes-long Bootstrap/Seed — by the time those finish the OAC tools are live and phases 6–7 flow with no further interruption.

Run it as early as OAC coords exist. It needs the OAC instance + creds, which come from Config — so on a fresh install Step 1b falls right after Step 1, before Bootstrap. On an already-configured tenant, probe it first thing.

The gate:

1. Probe liveness — a cheap oracle_analytics-search_catalog ping (or claude mcp list → expect oac-mcp-server ✔ Connected).
2. Live → continue to Bootstrap; record [✓] mcp connect.
3. Dead → set up + restart. From the customer project directory, run:

   env -u OAC_URL -u OAC_MCP_USER -u OAC_MCP_PASSWORD -u OAC_ADMIN_USER -u OAC_ADMIN_PASSWORD \
   aidp-fusion-bundle dashboard mcp-setup \
     --connector-js <path-to-oac-mcp-connect.js>
   

   This stages the connector, writes the 0600 connector config, and wires the project .mcp.json. The env -u ... wrapper prevents a global shell OAC profile from overriding the project .env. Before stopping, write .aidp/autopilot/resume.md with the user's goal and next step. Then PAUSE with an explicit handoff: "OAC MCP staged — restart/reconnect Claude Code (/mcp → reconnect oac-mcp-server, or relaunch), then paste: Resume the Fusion dashboard workflow from .aidp/autopilot/resume.md." Autopilot is state-first, and the checkpoint preserves the goal if chat context is lost. Do not try to proceed into phases 6–7 on a dead connection.

Persistent resume checkpoint

Before any pause that may cross a Claude Code restart/reconnect or a long manual UI step, write a non-secret checkpoint at:

.aidp/autopilot/resume.md

Use the helper from this skill directory:

python3 skills/aidp-fusion-autopilot/write_resume_checkpoint.py \
  --workdir . \
  --goal "<dashboard or workflow goal>" \
  --phase "Step 1b OAC MCP connect" \
  --next-step "Reconnect Claude Code, verify oac-mcp-server, then re-run /aidp-fusion-autopilot" \
  --completed "bundle.yaml and aidp.config.yaml exist" \
  --pending "OAC MCP liveness check" \
  --evidence "OAC URL configured" \
  --note "No secrets recorded"

Resolve the script path relative to the active skill directory when the user is running from a separate customer bundle. Do not put passwords, private keys, tokens, full OCIDs, or connection payloads in the checkpoint. On resume, read the checkpoint first, then re-probe live state; the file is context, not proof.

First run (fresh install)

If bundle.yaml / aidp.config.yaml don't exist yet (brand-new install), Step 1 starts from zero.

First, make sure the CLI exists. On a plugin-only install, the user may have downloaded the Claude Code plugin but not manually run pip install -e. Do not send them back to a setup guide for that. Check command -v aidp-fusion-bundle; if it is missing, install the CLI from the plugin root that contains this skill directory, then continue. The plugin root is two directories above this file (skills/aidp-fusion-autopilot/../..). Use the active Python, create or reuse the plugin repo's .venv only when needed, and keep the customer bundle directory separate.

Then run aidp-fusion-bundle init from the clean customer bundle directory to scaffold bundle.yaml, aidp.config.yaml, and .env, then /aidp-fusion-config to resolve the AIDP coords from names. Capture the user's goal first (even a rough one) so the rest of the journey has a target; if they have no goal yet, scaffold + configure and stop there with "what dashboard do you want?". Don't ask for OCIDs by hand — that's what init + /aidp-fusion-config are for.

Returning user (re-entry fast-path — don't redo built work)

The loop is state-first, so a returning user with a specific goal is just a journey that starts mid-way. Concretely, for "autopilot — I want a dashboard of dim_supplier":

1. Map the goal to its table(s) via /oac-dataset-advisor (it resolves "supplier" → the gold/dim table(s) that answer it).
2. Detect that entity's state, in order, and jump to the first gap:
   • No live gold table for it → start at Step 3 (seed) (Bootstrap first if no profile).
   • Seeded, but no OAC dataset over it → Step 6 (/oac-dataset-setup hands the dataset spec to the user for the OAC UI and verifies it after).
   • Dataset exists, no workbook → skip straight to Step 7 (/workbook-authoring) — this is the common "already built upstream, just need the dashboard" case.
   • Workbook already exists → report it + its viewUrl; offer to refresh/open it or author a new one. Don't silently re-author.
3. Step 1b (OAC MCP connect) still gates anything that reads OAC — probe it before the dataset/workbook detection, since that detection uses the MCP tools (a dead connection ≠ "nothing exists").

So the answer to "if supplier already exists, go to workbook authoring; if not, seed first" is the loop's normal behavior — this section just makes the entity- scoped routing explicit.

The loop

1. Capture the goal — restate the dashboard the user wants (metrics, dimensions, grain). Keep it; every phase serves it.
2. Assess state — run the cheap detectors (below) to find the first incomplete step for the goal's entity (see re-entry fast-path above). Report the full journey status (✓ done / ▶ next / ⏸ pause).
3. Drive that step via its skill/command.
4. On clean success → advance to the next step and repeat. On a pause gate → stop, present the decision, wait for the user.
5. Stop when Step 7 (workbook) is done — and offer Step 8 (end-user MCP chat) if the user wants downstream clients to query OAC directly.

The one hard ordering rule: never enter phases 6–7 with a dead oac-mcp-server. If the Step 1b probe fails, set up, write the resume checkpoint, hand off the restart, and stop there. Re-running autopilot after the restart reads the checkpoint and resumes the journey.

State detection (reuse the family's helpers — no new probes)

• Config / profile / cluster: python3 skills/aidp-fusion-seed/preconditions.py --bundle bundle.yaml --config aidp.config.yaml --env <env> → {ok, missing[], config_placeholders[], cluster_state}.
• Live gold (what's seeded): the advisor's live-catalog probe (tests/live/aidp_catalog_probe_live.py → skills/oac-dataset-advisor/catalog_inventory.py). Live AIDP catalog is the evidence — never pack YAMLs.
• What the pack could build (seed-vs-gap routing): python3 skills/oac-dataset-advisor/pack_capability.py.
• OAC MCP liveness (Step 1b gate): a cheap oracle_analytics-search_catalog ping, or claude mcp list (expect oac-mcp-server ✔ Connected). A failure / auth error means route to Step 1b setup + restart — it does not mean the catalog is empty.
• Existing OAC datasets / workbooks: OAC MCP search_catalog / find_matching_datasources / describe_data. Only trust these once Step 1b is green — a dead connection returning nothing must never be read as "no dataset/workbook exists" (false negative → autopilot would wrongly try to re-author).

Pause gates (never auto-do these)

• Destructive seed — honour /aidp-fusion-seed's fail-closed guard; if it says CONFIRM, surface the affected tables and wait.
• Bootstrap variation freeze — surface the resolved column-alias / semantic-variant picks; on a multi-match, let a human choose.
• Mart authoring — show /mart-author's chosen change (rung, blast radius) before authoring/seeding it.
• OAC dataset creation — delegate to /oac-dataset-setup; it presents the exact spec (tables, columns, join key), pauses for the OAC UI action, then verifies the saved dataset with MCP.
• OAC MCP not connected (Step 1b) — stage it with dashboard mcp-setup, write .aidp/autopilot/resume.md, then stop for the operator to restart/reconnect Claude Code; the tools can't activate inside the current session. Resume from the checkpoint on re-run.
• Missing fusion: connectivity / non-least-privilege MCP user — stop and ask.
• Anything overwriting populated data or external state.

Output

A compact journey ledger each turn — e.g.:

goal: supplier spend vs GL closing balance, by currency
[✓] config   [✓] mcp connect   [✓] bootstrap   [✓] seed (gl_balance, supplier_spend live)
[✓] advise → COVERED: dataset over gl_balance + supplier_spend on currency_code
[⏸] OAC dataset → create in OAC UI (spec below), then I continue
[ ] workbook   [ ] end-user mcp chat (optional)

On a pause, state exactly what you need from the user and which step resumes.

Skill family (what autopilot conducts)

/aidp-fusion-config · /aidp-fusion-bootstrap / medallion-author · /aidp-fusion-seed · /aidp-fusion-status · /oac-dataset-advisor · /oac-dataset-setup · /mart-author (+ use-pack) · /workbook-authoring · /aidpf-error-triage · dashboard mcp-setup. Day-2: /aidp-fusion-incremental (deltas) with /fusion-drift-doctor as its drift precheck. On known drift gates (AIDPF-2072/4070/4071/2012/4040 — schema/PVO drift, plan-hash), route directly to /fusion-drift-doctor, which diagnoses and hands to bootstrap --refresh / /medallion-author / re-seed. On any other AIDPF-* code or ambiguous failure, route first to /aidpf-error-triage. Autopilot adds no mechanism — it sequences these and holds the user's goal across them.

Safety invariants (do not regress)

• Never weaken a sub-skill's guard to "keep moving."
• Never claim a phase is done without its detector confirming it (live evidence for seed/gold; OAC MCP for dataset/workbook).
• Never enter phases 6–7 with a dead oac-mcp-server, and never read a dead/ unauthenticated MCP connection as an empty catalog — set up Step 1b + restart first.
• Never guess recovery from an unfamiliar AIDPF-* code; route to /aidpf-error-triage.
• Never create the OAC dataset or seed populated data without the gate.
• Surface every irreversible/external action before doing it.