Imported from databricks-solutions/vibe-coding-workshop-template (skills/vibecoding-state/SKILL.md). Install upstream with npx skills add databricks-solutions/vibe-coding-workshop-template --skill vibecoding-state. Copyright stays with the author.

name: vibecoding-state description: > Owns the end-to-end state, gating, pathway-applicability, and retrospective contract for the Instructions.md / example/<use_case>/WALKTHROUGH.md vibecoding workshops. Every workshop prompt invokes this skill at the top (enter) and bottom (exit) so the state file is read, gates are enforced, non-applicable steps are skipped, and the per-step log is appended — without each prompt repeating the contract as prose. Also owns the bootstrap initializer, the bootstrap → canonical migrate_canonical move, and the async retrospective.per_prompt / retrospective.rollup passes. Invoke BEFORE acting on any workshop prompt. license: Apache-2.0 compatibility: "Works with any workshop that follows the vibecoding state schema in references/state-template.md. Pathways A, B, C write the AppKit state to <app_root>/.vibecoding-state.md (= <artifact_root>/<app_name>/.vibecoding-state.md, the top-level app dir); the Track A custom-agent app (Pathways C/D) writes to <agent_app_root>/.vibecoding-state.md (= <artifact_root>/<agent_app_name>/.vibecoding-state.md, the top-level agent app dir)." clients: [ide_cli, genie_code] bundle_resource: none deploy_verb: none deploy_note: "Runtime state/gating/retrospective contract — not a deployable skill; no bundle resource and no deploy verb. It is the resolver: at enter (and, pre-bootstrap, via the lightweight resolve_root op) it resolves the active client and writes the client_context capability set (cli_channel, bundle_deploy.verb, page_context_required, state_file_root, artifact_root, skills_install_root, skill_ref_root, dp_bundle_root) that every downstream prompt and skill consumes, so it is client-agnostic by construction. On Genie Code the state file and artifacts live under the USER PROJECT root (state_file_root = artifact_root = /Workspace/Users/<email>/<repo>), which is a git clone of the workshop repo (a git working tree, so generated bundles are recognized); the skill tree is copied from there to skills_install_root (= /Workspace/Users/<email>/.assistant/skills/<repo>, the discovery + readSkillFile anchor, no git required); relative artifact paths resolve as <ARTIFACT_ROOT>/<relpath>, repo-relative skill paths load via readSkillFile under skill_ref_root (= skills/<clone-folder> = "skills/" + basename(skills_install_root)), the data-product bundle is authored under dp_bundle_root (= <artifact_root>/{user_schema_prefix}_<use_case_slug>_dab, the bundle deploy page-context root), and the AppKit app is authored under app_root (= <artifact_root>/<app_name>, the top-level app dir — same shape on both clients). See skills/genie-code-environment §8 for the resolved per-client deploy verbs, the artifact_root rule, the skill-load rule, and the dp_bundle_root rule." coverage: full metadata: last_verified: "2026-04-30" volatility: low upstream_sources: [] author: "prashanth-subrahmanyam" version: "2.1.0" domain: "genai-agents" role: "runtime-contract" operations: "bootstrap, resolve_root, resolve_spec, enter, migrate_canonical, exit, retrospective.per_prompt, retrospective.rollup, state_contract_audit, endpoint_guardrail_audit, llm_role_endpoint_probe, audit_debts, skill_helper_resolution" produces: "live_state_file, bootstrap_preflight, state_file_set, canonical_names, state_overrides, deferred_actions, mlflow_eval_known_quality_issues, gate_load_bearing_checks, productized_debts, preflight_check_registry, evaluation_runs_preflight, system_prompt_review, skill_helper_resolutions, resolved_variant, resolved_resources, resolved_ui, resolved_agent, resolved_governance, per_step_log_section, retrospective_entry" consumes: "Workshop Choices (PRD), PRD document at prd_path, Pathway Applicability Matrix, prior prompt gate" references: - "references/state-template.md" - "references/retrospective-template.md" - "references/spec-schema.md" - "references/resolver-prompt.md"

Vibecoding State — Workshop Runtime Contract

This skill is the single source of truth for how every prompt in the repo-root Instructions.md workshop and its worked instantiations (e.g. example/skyloyalty/WALKTHROUGH.md) interacts with the shared per-user state file and the async per-prompt retrospective file.

Prompts do not re-state the "Vibecoding state contract / Preamble / Postamble / Pathway Applicability guard / Retrospective contract" prose. They invoke this skill with typed parameters and this skill owns the behavior.

When to Use

Invoke this skill — always — when executing any vibecoding workshop prompt. Specifically:

• Every prompt in Instructions.md (Prompt 0.1 through 8.24).
• Every prompt in example/<use_case>/WALKTHROUGH.md (e.g. SkyLoyalty's 22 prompts).
• Every post-workshop per-prompt retro + the single session rollup.

Do not invoke for: one-off terminal commands, ad-hoc debugging, or anything outside the workshop flow.

Candidate future skills that this skill deliberately does not absorb (they stay inline in prompts for now): workspace-preflight (databricks compute-policies list, databricks current-user me), llm-endpoint-health (databricks serving-endpoints get <endpoint>), bundle-deploy (databricks bundle validate/deploy/run), derive-app-name (email + use_case_slug → APP_NAME), prd-reader. If you end up duplicating any of those across prompts, extract them next.

Operations

All thirteen operations take a typed parameter bag. The prompt invokes the operation by name (e.g. vibecoding-state.enter) and passes only the dynamic values. Everything else (file paths, log schema, gate rules, pathway matrix, resolved spec) is owned by this skill.

Operation: bootstrap

When: Once per workshop run, at Prompt 0.1 (Instructions.md) or Prompt 1 (WALKTHROUGH.md). Only runs if no live state file exists.

Inputs:

Behavior:

0. Detect environment & write the ## Environment Capabilities block (RULE_0 / RULE_1 enabling). Before any other step, resolve the active coding client and write the capability block (schema in references/state-template.md § Environment Capabilities) as section 0 of the state file. This is the block every prompt and the enter / exit operations read to resolve the deploy verb, CLI channel, and state-file root — so no skill or prompt body assumes a local IDE. Detection signal [inference — pending the live Genie Code probe]: if a Databricks-managed CLI channel is present in-session (the runDatabricksCli tool / Genie serverless markers), set client_context: genie_code, cli_channel: runDatabricksCli, bundle_deploy.page_context_required: true, both state_file_root and artifact_root to the user project workspace path (/Workspace/Users/<email>/<repo> — a git clone of the workshop repo, so it is a git working tree and generated bundles are recognized), and skills_install_root to the skills copy path (/Workspace/Users/<email>/.assistant/skills/<repo>, a copy of the tree for discovery, no git required); otherwise set client_context: ide_cli, cli_channel: local_shell, bundle_deploy.page_context_required: false, and state_file_root, artifact_root, and skills_install_root all to the local repo path. Ensure artifact_root (and thus state_file_root, which equals it) is a git-backed working tree — the kickstart git clones the workshop repo into it; if <artifact_root>/.git is absent, git clone <workshop remote> into it before writing the ## Environment Capabilities block (a bare mkdir leaves generated bundles unrecognized — TESTED; a Repos-managed Git folder is the documented fallback). On genie_code operate via the workspace path / executeCode, mindful of the FUSE create-then-validate gap (clone, then confirm os.path.exists(<artifact_root>/.git) before writing); a non-PRD-first flow may reach bootstrap before the clone exists. (artifact_root defaults equal to state_file_root; it is where relative artifact paths resolve as <ARTIFACT_ROOT>/<relpath> — see skills/genie-code-environment §8. skills_install_root is the read-side anchor: a copy of the clone on genie_code, the same repo on ide_cli.) Also set skill_ref_root — the prefix that makes a repo-relative skill path loadable: on genie_code it is the readSkillFile prefix "skills/" + basename(skills_install_root) (e.g. skills/vibe-coding-workshop, because the skills copy lives under .assistant/skills/<repo> and any file there loads as skills/{path-after-.assistant/skills/}); on ide_cli it is empty (repo-relative skill paths / @-mentions resolve as-is). See skills/genie-code-environment §8 for how prompts use it. Also set dp_bundle_root = <artifact_root>/{user_schema_prefix}_<use_case_slug>_dab (the use_case_slug bootstrap param is available here; {user_schema_prefix} is the SAME username-derived prefix used for the {user_schema_prefix}_bronze/_silver/_gold schemas — companion app on genie_code, authenticated-user derivation on ide_cli, e.g. jane_d) — the self-contained Databricks Asset Bundle project directory the whole data-product pipeline (bronze→silver→gold→semantic) writes its databricks.yml / src/ / resources/ into, and the bundle deploy page-context root on genie_code. The username prefix disambiguates concurrent users in a shared workspace; the bundle name: inside databricks.yml MUST match this prefixed folder name (bundle: { name: {user_schema_prefix}_<use_case_slug>_dab }). It is the same shape on both clients (a dedicated subdir of the repo/clone root, NOT the bare root and NOT inside a read-only framework dir); see skills/genie-code-environment §8. Also set app_root = <artifact_root>/<app_name> — the AppKit application track's analog of dp_bundle_root: a TOP-LEVEL sibling of <use_case_slug>_dab (NOT nested under apps_lakebase/) that holds the scaffolded app (app.yaml / databricks.yml / server/ / client/ + <app_root>/.vibecoding-state.md) on BOTH clients, so the app's root folder has parity regardless of client. It is the apps init --output-dir target on genie_code, deploys via apps deploy (no bundle page-context pin), and is <pending> until APP_NAME is resolved (Module 1 / prompt 04); n/a for Pathway D. Also set agent_app_root = <artifact_root>/<agent_app_name> — the Track A custom-agent track's analog of app_root: a TOP-LEVEL sibling of <app_name> and <use_case_slug>_dab (NOT nested under apps_lakebase/) that holds the cloned agent framework (app.yaml / pyproject.toml / databricks.yml / server/ + <agent_app_root>/.vibecoding-state.md) on BOTH clients, so the agent app's root folder has parity regardless of client. On genie_code it is the apps init --output-dir target and the uv/FastAPI server builds server-side via apps deploy (mode=SNAPSHOT) — there is no local uv run dev loop. It is <pending> until AGENT_APP_NAME is resolved (Track A clone / prompt 43); n/a for Pathways A/B. The remaining fields are client-invariant: bundle_deploy.verb is always bundle deploy --target dev, app_deploy is always { verb: "apps deploy", gated: true }, and destructive_ops is always confirm_required. Also seed genie_code_manifest_loaded (G3): n/a on ide_cli (the check is inert there), false on genie_code — on Genie Code the first deploy/divergent prompt's enter halts until the skills/genie-code-environment manifest is read in-thread and flips it true (see references/spec-schema.md § Genie Code manifest-load gate). Record the detection signal that fired in a trailing # detected_via: comment so a later live probe can confirm or correct it. For how the detected genie_code client actually behaves — the runDatabricksCli allow-list tiers, the bundle-deploy CWD pin and FUSE create-then-validate gap, the App-scaffold output-dir rule, and the deployed-app OAuth session pattern — see the genie-code-environment skill (this skill detects the client; that skill explains it).
1. Workspace URL normalization & placeholder refusal. Trim any trailing slash from workspace_url and normalize the scheme to https://. Refuse any literal placeholder — <your-workspace-url>, the empty string, or https://<...> — by halting with a remediation hint pointing the operator at Workshop Choices. Record the normalized value in bootstrap_preflight.workspace_url_normalized and the placeholder check in workspace_url_was_placeholder.
2. Profile selection & host match. Run databricks auth profiles and select the profile whose host equals the normalized workspace host. Store it in bootstrap_preflight.workspace_profile. If no profile matches, set workspace_host_auth_status: wrong_host and halt; if the matching profile fails databricks current-user me, set unauthenticated and halt; on success set authenticated.
3. CLI version preflight (client-branched — Gap-1). On ide_cli: capture databricks --version into bootstrap_preflight.databricks_cli_version, compare against bootstrap_preflight.databricks_cli_min_version (default 0.295.0, may be raised by workshop config), and halt with an upgrade hint if the installed version is older. On genie_code: databricks --version is hard-blocked (no local CLI binary — the managed runDatabricksCli channel does not expose a version string; CONFIRMED P1), so set bootstrap_preflight.databricks_cli_version: unknown_on_genie_code and skip the numeric comparison and the version halt entirely. Any later decision that would have keyed off the numeric version (the databricks_cli_min_version registry check, and skill_helper_resolution's CLI-version gate) falls back to the behavior probe — databricks bundle validate accepting the field/deploy without stripping — instead of a version number. The managed channel always tracks a current CLI, so the only real risk a version gate guards against (a stale local install) cannot occur on Genie Code.
4. Apps quota preflight. Before any databricks apps create happens (Pathways A/B/C), run databricks apps list --output json and record current_count, max_count, and free_slots in bootstrap_preflight.apps_quota. If free_slots < 1, halt with a clean-up hint listing the apps the operator can delete.
5. First state file path. Write the bootstrap live file to example/<use_case_slug>/.vibecoding-state.md (used in this repo's example/ examples) or workshops/<use_case_slug>/.vibecoding-state.md (used by external adopters that follow the workshops/ convention). Whichever path is chosen, record it verbatim in bootstrap_preflight.first_state_file_path so migrate_canonical knows exactly which file to move once $APP_NAME is resolved. Set bootstrap_preflight.app_name_known_at_bootstrap = false — $APP_NAME is resolved later by Module 1 / Prompt 2.
6. Copy the template. Copy references/state-template.md to bootstrap_preflight.first_state_file_path.
7. Replace <USE_CASE_SLUG> in the title and both <ISO timestamp> placeholders with the current ISO timestamp.
8. Write all Workshop Choices from the params above.
9. Run databricks auth profiles + databricks current-user me to capture PROFILE, Workspace host, User email into Global Variables. (PROFILE is the same value already stored as bootstrap_preflight.workspace_profile.)
10. Run the serverless-only preflight (databricks compute-policies list) and set workspace_serverless_only.
11. DAB dev-mode schema-prefix detection. If dabs_bundle_path is a real path (not n/a), shell out to databricks bundle validate --target dev --output json from that path and inspect every UC schema resource. If any resource has dev-mode prefixing applied (a name shaped like dev_${user}_<schema> instead of the unprefixed <schema>), set bootstrap_preflight.bundle_dev_mode_schema_prefix_detected = true. Every downstream prompt that passes agent_schema, ops_schema, or uc_schema into a job/notebook MUST read the resolved (prefixed) schema name from state — never the unprefixed variable name.
12. Verify-job summary semantics. Set bootstrap_preflight.verify_summary_semantics from the merged workshop config. Default pass_field/warn_field/fail_field are "pass", "warn", "fail" (matching 05_verify_infrastructure.py's notebook.exit payload). warning_policy defaults to allow_with_notes; set to block_if_load_bearing for use cases whose verify-job emits warnings that must block the gate. When warning_policy == block_if_load_bearing, any warning whose name matches an entry in the workshop's gate_load_bearing_checks[] list blocks the first verify gate (PASS only when fail == 0 AND no load-bearing warning is present).
13. Derive variant_id from pathway + track using the deterministic derivation table in references/resolver-prompt.md § Variant-ID Derivation Table.
14. Invoke resolve_spec (see below) to parse the PRD at prd_path and populate the six spec sections (## Variant, ## Resources, ## UI, ## Agent, ## Governance, ## Spec Provenance). This is a hard step: if resolve_spec halts, bootstrap halts.

Outputs: Path of the bootstrap state file (also stored as bootstrap_preflight.first_state_file_path), populated with ## Environment Capabilities (section 0), ## Bootstrap Preflight, Workshop Choices, Global Variables (partial), and fully resolved Variant / Resources / UI / Agent / Governance / Provenance spec sections (schema v2.0). The workshop continues with this path until migrate_canonical runs.

Errors: If the bootstrap path already exists, abort — do not overwrite. The operator must remove or migrate the stale file. Any of the four halt rules in references/spec-schema.md § Bootstrap Preflight (steps 1–4 above) abort before the template is copied. If resolve_spec fails validation twice, abort and surface the validation errors; the operator must fix the PRD before re-running.

DAB dev-mode schema-prefix rule (consumer-side). If Databricks Asset Bundle dev mode prefixes UC schema resource names, notebook/job parameters must receive the resolved prefixed schema name, not the unprefixed variable. Bootstrap captures bundle_dev_mode_schema_prefix_detected; any prompt that passes agent_schema, ops_schema, or uc_schema to a job reads the resolved value from state.

Operation: resolve_root

When: Any prompt that writes an artifact before bootstrap has run (e.g. the PRD-generation prompt produces docs/design_prd.md before the PRD exists to bootstrap from). It is the minimal, gate-free way to learn where relative artifact paths must land so a bare docs/… does not resolve against a page-dependent CWD on Genie Code. Idempotent — safe to call repeatedly; a later bootstrap supersedes it as the persistence owner.

Inputs: none required. (Optional state_file_path — if the caller already knows where a state file lives.)

Behavior:

1. Read-if-present. If a state file with a ## Environment Capabilities block (section 0) already exists (the live file, or the bootstrap path example/<use_case_slug>/.vibecoding-state.md / workshops/<use_case_slug>/.vibecoding-state.md), read client_context, artifact_root, skills_install_root, and skill_ref_root from it and return them. Do not re-detect or rewrite.
2. Else detect fresh (bootstrap step-0 detection ONLY). Run just the client/root detection from bootstrap step 0 — no URL/profile/CLI/quota preflights, no template copy, no resolve_spec, no gates: if a Databricks-managed CLI channel is present (runDatabricksCli / Genie serverless markers) ⇒ client_context: genie_code, artifact_root = the user project workspace path (e.g. /Workspace/Users/<email>/<repo>, a git clone of the workshop repo), skills_install_root = the skills copy path (e.g. /Workspace/Users/<email>/.assistant/skills/<repo>, a copy for discovery), skill_ref_root = "skills/" + basename(skills_install_root) (e.g. skills/vibe-coding-workshop); otherwise ⇒ client_context: ide_cli, artifact_root = skills_install_root = the local repo root, skill_ref_root = empty.
3. Ensure artifact_root is a git-backed working tree. The kickstart git clones the workshop repo into artifact_root; if <artifact_root>/.git is missing, git clone <workshop remote> into it so the caller's first relative write (e.g. the PRD at <ARTIFACT_ROOT>/docs/design_prd.md, produced before bootstrap) lands in a real, git-backed directory where generated bundles are recognized (a bare mkdir leaves them unrecognized — TESTED; a Repos-managed Git folder is the documented fallback). On genie_code operate via the workspace path / executeCode, mindful of the FUSE create-then-validate gap (clone, then confirm with os.path.exists(<artifact_root>/.git) before writing). This clone/check is the only filesystem side effect of resolve_root.
4. Echo, do not persist. Return client_context + artifact_root + skills_install_root + skill_ref_root for the caller to use immediately and to echo the project-root + skill-load rules to the operator. No state file is written — bootstrap step 0 remains the sole writer of section 0, so there is no "abort if path exists" conflict and no half-initialized state file.

Outputs: { client_context, artifact_root, skills_install_root, skill_ref_root } (ephemeral). The calling prompt resolves its relative artifact path as <ARTIFACT_ROOT>/<relpath>, loads any repo-relative skill path X/Y/SKILL.md as <skill_ref_root>/X/Y/SKILL.md via readSkillFile (§8), and echoes: "artifacts resolve under the workshop project root (artifact_root, the git-cloned user project on Genie Code — not the skills copy) and skills load under skill_ref_root (= skills/<clone-folder> = skills/ + basename of skills_install_root on Genie Code), never the page CWD."

Errors: None that halt — resolve_root is fail-soft. If detection is ambiguous, default to ide_cli / repo-root and note the assumption; the later bootstrap step 0 is authoritative.

Operation: resolve_spec

When: Called automatically as the final step of bootstrap. May also be re-invoked manually if the PRD changes mid-workshop (rare; prefer restarting from bootstrap).

Inputs:

Behavior:

1. Read the PRD contents from prd_path and compute prd_sha256.
2. Load the schema from references/spec-schema.md and the prompt from references/resolver-prompt.md.
3. Derive variant_id deterministically from Workshop Choices (pathway, track) per the resolver prompt's Variant-ID Derivation Table. Inject it into the user prompt.
4. Call llm_endpoint with the system + user prompts. Expect a single YAML document with exactly six top-level keys: variant_id, resources, ui, agent, governance, spec_provenance.
5. Run the deterministic guards listed in the resolver prompt's "Post-resolution Guards" section:
   • YAML parses cleanly into a dict with the expected top-level keys.
   • Every validation rule in references/spec-schema.md §"Validation Rules" passes.
   • Consumer cross-check: each agent.tools[].name of kind: function with language: python reconciles with the PRD Tools Table.
   • Placeholder guard: no resource-ID-shaped strings leaked through.
   • Variant-ID echo check: emitted variant_id equals the one passed in.
   • MCP ref resolution: every agent.tools[].mcp_server_ref (kind=mcp) maps to an agent.mcp_servers[].name.
6. If any guard fails, retry once with the validation errors appended to the user prompt. Second failure halts bootstrap.
7. Split the validated YAML by top-level key and write each block into its matching state-file section (## Variant, ## Resources, ## UI, ## Agent, ## Governance, ## Spec Provenance), replacing the <pending> placeholder body with a fenced ```yaml block containing the resolved content.
8. Stamp ## Spec Provenance with resolved_at, resolver_version: "2.0", schema_version: "2.0", prd_sha256, and llm_endpoint.

Outputs: No return value; mutates the live state file.

Errors: Validation failure (after one retry), missing PRD file, unreachable llm_endpoint, or any LLM response that is not parseable YAML with the six expected keys — all halt bootstrap.

Downstream contract: Every consuming skill declares which fields it reads via a machine-parseable fields_read: YAML list in its frontmatter (see § Field Consumer Contract below and references/spec-schema.md §"Field Consumer Contract"). Prompts in Instructions.md and WALKTHROUGH.md reference resolved content by dotted path (e.g. ui.user_journeys, agent.tools, governance.scorer_suite.guidelines) instead of inlining domain-specific content. This is what makes the workshops use-case-agnostic.

Operation: hydrate_from_files

When: Called once per workshop, before any prompt that reads state://AgentSpec, state://AppSpec, or state://DataSpec. The Agents Accelerator visible path calls it from prompt uc_resources_foundation (input_id 200, order 40), right after op enter succeeds and before any UC schema/volume creation.

Purpose: The Agents Accelerator design pair (docs/agent_spec.yaml from prompt 38, docs/agent_tool_plan.yaml from prompt 39) becomes the source of truth for the agent's intent. hydrate_from_files lifts those file values into the live state file so every downstream consumer (Track A build prompts, MLflow SDLC suite at prompts 50-56) keeps reading from state://AgentSpec, state://AppSpec, and state://Spec Provenance without an additional visible-path step. This is additive to resolve_spec: PRD-only LLM-driven workflows that never produce the docs/*.yaml files continue to work unchanged.

Inputs:

Behavior:

1. Read agent_spec_yaml. Copy scalar/list agent.* fields directly into the state file's ## Agent section as a fenced yaml block: model, capabilities, personas, system_prompt, benchmark_seeds, must_do, must_not_do. File values override any prior resolve_spec LLM output silently; the file is the source of truth.

   Tool projection rule (preserves the v2.0 fields_read: agent.tools contract without rewriting any consumer). The Agent Spec produced by step 38 follows the 00b schema (tool_recommendations, NOT agent.tools). Hydration MUST project tools into state://AgentSpec.agent.tools[] using these three sub-rules:

   a. Seed state://AgentSpec.agent.tools[] from docs/agent_spec.yaml.tool_recommendations.managed_databricks[] plus tool_recommendations.external[]. Map each entry to the v2.0 tool discriminated-union shape: populate kind (hosted | function | mcp), name, surface, io_contract, readonly, plus the kind-specific fields (hosted_type + resource_ref, or language, or mcp_server_ref). Carry selected_by_default forward to pre-mark entries. b. Overlay docs/agent_tool_plan.yaml.selected_tools[] on top. Any Tool Plan entry with the same name REPLACES the spec recommendation — binding selection wins over loose recommendation. Tool Plan entries with no matching spec recommendation are appended. c. Tool families absent from BOTH the spec and the Tool Plan are NOT written into agent.tools[]. Skipped families are recorded as skipped, not failed (consistent with step 44 semantics).

   The projection is the only legitimate way state://AgentSpec.agent.tools[] becomes populated on the Agents Accelerator visible path. Step 38 does NOT and MUST NOT write agent.tools[] directly into docs/agent_spec.yaml; downstream prompts that still cite agent.tools[] (e.g. step 44's prerequisite block before Pass 3.5) MUST be updated to read tool_recommendations (loose) plus selected_tools (binding) instead.

2. Read agent_tool_plan_yaml. Merge selected_tools[], selected_mcp_servers[], runtime_config.llm, and resource_grants into ## Agent under new keys selected_tools, selected_mcp_servers, runtime_config, and resource_grants. Tools selected by the user in the Tool Plan win over the Agent Spec's recommendations.

3. Read ui_design_md. Parse loose markdown headings into ## UI (pages[], personas[], user_journeys[]) on a best-effort basis. If the document is structured differently or only contains free-form prose, write the verbatim markdown into ## UI.raw_markdown and emit a non-fatal warning so downstream SDLC prompts can still find personas/journeys textually.

4. Stamp ## Spec Provenance. Compute prd_sha256 from prd_path and write resolved_at (current UTC ISO timestamp), resolver_version: "3.0" (new tag distinguishing file-based hydration from LLM resolve_spec's "2.0"), schema_version: "2.0", prd_sha256, and hydrated_from_files: true.

5. Optional ## Resources (DataSpec). If the PRD declares a Lakehouse/Resources section (Bronze tables, Genie Spaces, Vector Search indexes, etc.) and ## Resources is already populated by an earlier resolve_spec run, leave it untouched. Otherwise write ## Resources as optional: true with tables: [], mark_skipped: "no Lakehouse track", signalling downstream prompts that state://DataSpec.* lookups should fall back gracefully (e.g. KA branch C in prompt 42 reads from docs/design_prd.md + docs/agent_spec.yaml.agent.capabilities instead of state://DataSpec.glossary).

6. Idempotency. Re-running with the same inputs is a no-op: each section is regenerated from the file values, sha256 is stable, and the state file ends in the same byte sequence (modulo the resolved_at timestamp, which is allowed to drift). Re-running with newer docs/*.yaml files overwrites cleanly.

Outputs: { hydrated: true, sections_written: ["## Agent", "## UI", "## Resources", "## Spec Provenance"] }. The Agents Accelerator step 40 records hydrated_from_files: true and resolver_version: "3.0" in its op exit captured map.

Errors:

• Missing required input file → halt with an explicit pointer to the producing prompt: agent_spec_yaml → 38, agent_tool_plan_yaml → 39, ui_design_md → 04, prd_path → 03, state_path → bootstrap.
• agent_spec.yaml missing agent.model → halt with a pointer to prompt 38's model selection rule (Pass 1 / Pass 2 of the Agents Accelerator cleanup).
• agent_tool_plan.yaml.runtime_config.llm.endpoint equals the literal YAML-path string docs/agent_spec.yaml.agent.model → halt with the Pass 2 placeholder rule citation. This is defense-in-depth; prompt 39's generated prompt already forbids this.
• Any value at a documented Agent Spec / Tool Plan path is still wrapped in {...} (e.g. {agent_sql_catalog}) → halt with the Pass 2 placeholder-handling rule. The user must rerun prompt 39 with real values.

Downstream contract: After hydrate_from_files runs, every prompt that consumes state://AgentSpec.agent.*, state://AppSpec.ui.*, or state://Spec Provenance.* sees the file-derived values. state://DataSpec.* is <pending> or optional: true unless the Lakehouse track produced one. SDLC prompts (50-56) MUST handle the optional/pending DataSpec case gracefully — they already do (the Agents Accelerator visible path no longer requires Lakehouse outputs), but the optional: true flag makes the contract explicit.

LLM driver prompt: See references/hydrator-prompt.md for the actual prompt that an LLM-driven implementation runs to execute this operation. That file is to hydrate_from_files what references/resolver-prompt.md is to resolve_spec.

Operation: enter

When: At the top of every workshop prompt, before any domain skill or command runs.

Inputs:

Behavior:

1. Locate the live state file:

   • First, resolve state_file_root from the ## Environment Capabilities block (section 0). Every path below is relative to it — the local repo root for client_context: ide_cli, the git-folder workspace path for genie_code. On a pre-capability state file (no section 0), default state_file_root to the repo root and proceed without assuming a deploy channel.
   • If $APP_NAME is known (Pathways A/B/C), use <app_root>/.vibecoding-state.md (= <state_file_root>/<app_name>/.vibecoding-state.md, the TOP-LEVEL app dir — NOT apps_lakebase/<app_name>/).
   • Else if $AGENT_APP_NAME is known (Track A agent app, Pathways C/D), use <agent_app_root>/.vibecoding-state.md (= <state_file_root>/<agent_app_name>/.vibecoding-state.md, the TOP-LEVEL agent app dir — NOT apps_lakebase/<agent_app_name>/).
   • Else if dp_bundle_root is resolved (a data-product / lakehouse run with no app or agent app — e.g. the Gold-design→Bronze→Silver→Gold→semantic pipeline), use <dp_bundle_root>/.vibecoding-state.md (= <state_file_root>/{user_schema_prefix}_<use_case_slug>_dab/.vibecoding-state.md). This is the canonical DP-track live file — the data-product analog of <app_root> / <agent_app_root>. The FIRST data-product prompt to run (Gold design, step 09 — or Bronze, step 10, if design was skipped) bootstrap-creates it from references/state-template.md if absent (a real create, copying the template + filling Workshop Choices from the prior example/ bootstrap file if present — not just resolve_root); every later DP step appends to it. Do NOT leave data-product state in the temporary example/ bootstrap path — that path carries no durable record and was the root cause of "state survived only in chat summary."
   • Else fall back to the bootstrap path <state_file_root>/example/<use_case_slug>/.vibecoding-state.md (pre-bootstrap only — once dp_bundle_root/app_root/agent_app_root is known, migrate/bootstrap-create the canonical file above).
   • If none of these exists yet: for the dp_bundle_root/app_root/agent_app_root canonical paths, bootstrap-create the file from the template (this is the first prompt of that track); only stop and tell the operator to run bootstrap first if even use_case_slug/Workshop Choices are unknown.

2. Schema v2.0 gate (hard fail). Parse the ## Spec Provenance YAML block. If schema_version != "2.0", halt with:

   State file uses schema v<X> — this repo is strictly v2.0.
   Run: python scripts/migrate-spec-v1-to-v2.py <path-to-state-file>
   Then re-run this prompt.
   

   No best-effort reads against older shapes.

3. Read end-to-end. Treat Workshop Choices, Global Variables, and Captured Resource IDs as authoritative. Never ask the operator for a value that already exists in state.

4. Multi-file resolution via state_file_set. Parse the ## State File Set block.

   • If state_file_set.secondary.path is <pending> or null, treat the located file as the only source — done.
   • If secondary is declared and prompt_id is in secondary.required_for_prompts, read the secondary file too. Halt if it does not exist (remediation: run bootstrap for the missing side or correct secondary.path).
   • Walk both files following lookup_order (e.g. ["primary", "secondary"]). For each canonical field requested by the prompt, the first hit wins.
   • For any canonical field present in both files with different values: halt unless conflict_policy: primary_wins is set explicitly. With primary_wins, use the primary value and append the conflict to ## State Contract Audit (fields_read_but_never_produced / captured_fields_with_no_consumer are unaffected; conflicts get their own audit row).

5. Apply canonical_names aliasing on read. Parse the ## Canonical Names block. Whenever the prompt reads an env var, HTTP header, jq path, or state field listed as a legacy/incorrect spelling on the left of a canonical_names map, resolve to the canonical name on the right. If the map's value is null (e.g. http_headers.x-forwarded-user-info: null), the name does not exist; halt and surface a hint pointing at the canonical alternatives. state_contract_audit performs the same checks at audit time.

6. Enforce the prior gate if require_prior_gate is set. On mismatch, halt unless a matching entry exists in state_overrides[] (see step 7). Mismatches that are NOT covered by an override stop the workshop.

7. Apply state_overrides[] (fail-closed escape hatch). Parse ## State Overrides. An override entry covers a failing gate when ALL of the following hold: prompt_id matches the current prompt; gate_type matches the failing gate (require_prior_gate for step 6, hard_assert / preflight_check for step 9 below, pathway_applicability for step 8); and expires_at is in the future relative to the current ISO timestamp. A covered failure is treated as satisfied and the override is logged in the prompt's Resolved issues / workarounds Per-Step Log entry. Expired or missing entries DO NOT cover the failure — enter halts. Cross-session continuity (e.g. resuming from a previous run's state file) is recorded as a state_override whose reason cites the earlier run's evidence; it is NOT a prose exception.

8. Consult the Pathway Applicability Matrix (below). If the prompt does not apply for this pathway/track and no state_override with gate_type: pathway_applicability covers it, synthesize a ## Prompt <prompt_id> — Skipped (N/A for pathway <X>) section with Gate: Skipped — N/A for pathway <X>, append it, and return a skipped: true signal so the prompt body short-circuits. With a covering override, proceed (the override reason is logged in the prompt's Per-Step Log entry).

9. Enforce deferred_actions[]. Parse ## Deferred Actions. Halt if the current prompt's role is in any open deferred_action's target_prompt_roles[] and its divergence_check evaluates to false (or fails to parse under the divergence-check grammar in references/spec-schema.md § Deferred Actions). Halt is suppressed only when a state_override with gate_type: hard_assert (or preflight_check) on the current prompt_id exists AND its references[] contains "deferred_action:<id>" matching the action's id. If divergence_check returns true, flip status to resolved and proceed. Entries with status: waived are skipped without evaluation.

10. Enforce mlflow_eval_known_quality_issues[]. Parse ## MLflow Eval Known Quality Issues. If the current prompt's role appears in any open issue's target_prompt_roles_blocked[], halt with a remediation hint citing id, source_prompt_role, and error_signature — unless a state_override exists on the current prompt_id whose references[] contains "known_issue:<id>" matching the issue's id. The issue's error_signature SHOULD be a name from gate_load_bearing_checks[] so audits and verify summaries align, but enter halts purely on target_prompt_roles_blocked[] membership and status: open — it does NOT consult gate_load_bearing_checks[] directly (that list drives state_contract_audit and the verify-job warning_policy: block_if_load_bearing rule per § Gate Load Bearing Checks in references/spec-schema.md).

11. Enforce preflight_check_registry. Parse ## Preflight Check Registry. For each registry entry, if the current prompt's role appears in blocks_prompt_roles[], evaluate the matching state field per the State-field mapping table in references/spec-schema.md § Preflight Check Registry. If the pass condition is not met (the field is <pending>, missing, or fails the predicate), halt with a remediation hint pointing at owner. The halt is suppressed only when a matching state_override with gate_type: preflight_check exists on the current prompt_id whose affected_state_field matches the check's state field. For reflection_lm_large_context_probe, the check is treated as passing only when a synchronous ≥80000-character probe has been run against the currently bound llm_role_endpoints.reflection_lm.endpoint and endpoint_guardrail_audit[<reflection_lm.endpoint>].long_context_ok == true AND accepted_min_context_chars >= 80000 — the generic bootstrap endpoint guardrail pass is NOT sufficient on its own. The owning skill (instruction_iteration) MUST invoke the probe synchronously before any 08b diff-summary helper or iteration helper call. For genie_code_manifest_loaded (G3, the one client-conditional check), evaluate it only when environment_capabilities.client_context == 'genie_code' — it is inert on ide_cli — and on Genie Code halt the deploy roles until environment_capabilities.genie_code_manifest_loaded == true (the agent has read skills/genie-code-environment in-thread); see references/spec-schema.md § Genie Code manifest-load gate.

12. Resolve variables. Return the subset of state the prompt body needs (it is declared in the prompt's enter invocation — e.g. APP_NAME, PROFILE, warehouse_id). Always also return the environment-capability set so any deploy/run instruction the prompt emits uses the resolved verb + channel instead of assuming a local IDE: bundle_deploy.verb (always bundle deploy --target dev), app_deploy.verb (apps deploy), cli_channel (local_shell for ide_cli, runDatabricksCli for genie_code), artifact_root + skill_ref_root, and — for data-product prompts — dp_bundle_root (so the bundle is written and deployed under <artifact_root>/{user_schema_prefix}_<use_case_slug>_dab, not the bare clone root), and — for AppKit app-track prompts — app_root (so the app is scaffolded, wired, and deployed under <artifact_root>/<app_name>, the top-level app dir, on both clients), and — for Track A custom-agent prompts — agent_app_root (so the agent app is cloned, wired, and deployed under <artifact_root>/<agent_app_name>, the top-level agent app dir, on both clients). When bundle_deploy.page_context_required: true, also return the page-context note (Genie Code must run the deploy from the dp_bundle_root page). The body never hardcodes a bare-shell databricks call.

Recovery reconcile (on resume / after a context reset — do BEFORE re-authoring anything). When enter runs in a thread that did not author the work itself (a resumed or compacted session), the live state file — not the chat summary — is the source of truth. (a) For any prompt whose Per-Step Log entry shows Gate: …PASSED (or the prompt's success gate), treat that step as DONE: do NOT re-run it or overwrite its files, regardless of what a summary says ("NOT DONE"/"IN PROGRESS" in a stale summary is the known drift failure). (b) Before writing files for an in-flight step, reconcile what is already on disk: list the target dirs with os.listdir(...) (NOT listFiles, which lags FUSE writes — see genie-code-environment §10) and compare against the paths the state file captured, so you resume the partial step instead of recreating files that already exist.

Outputs: {skipped: bool, resolved: {<key>: <value>}, capabilities: {client_context, cli_channel, bundle_deploy, app_deploy, state_file_root}}.

Errors:

• step 6 — prior-gate mismatch with no covering override.
• step 7 — invalid override (expired / missing fields / fails any of the four override-coverage clauses).
• step 8 — pathway-applicability mismatch with no pathway_applicability override.
• step 9 — open deferred_action whose divergence_check evaluates to false (or fails to parse) and no state_override references it.
• step 10 — open mlflow_eval_known_quality_issue whose target_prompt_roles_blocked[] includes the current prompt and no state_override references it.
• step 11 — preflight_check_registry entry whose blocks_prompt_roles[] includes the current prompt's role and whose state-field pass condition is not met (and no state_override with gate_type: preflight_check covers it). For reflection_lm_large_context_probe, the synchronous large-context probe MUST have been run against the currently bound reflection-LM endpoint with accepted_min_context_chars >= 80000.
• step 7 corollary — expired state_overrides[] entries do NOT cover failures.

Other halt conditions (not numbered above): missing state file, unresolved <pending> value the prompt requires, missing required secondary state file when prompt_id is in state_file_set.secondary.required_for_prompts, conflicting canonical fields across primary/secondary without conflict_policy: primary_wins, and read on a header/env-var/jq-path/state-field whose canonical_names entry is null.

Operation: migrate_canonical

When: Exactly once, at the prompt that first resolves $APP_NAME (Pathways A/B/C, usually Prompt 1.1 / Prompt 2 of the walkthrough) or $AGENT_NAME (Pathway D, usually Prompt 4.0).

Inputs:

Behavior:

1. Move example/<use_case_slug>/.vibecoding-state.md to <app_root>/.vibecoding-state.md (= <artifact_root>/<app_name>/.vibecoding-state.md, A/B/C) or <agent_app_root>/.vibecoding-state.md (= <artifact_root>/<agent_app_name>/.vibecoding-state.md, Track A agent app for C/D).
2. Update Global Variables.APP_NAME (or AGENT_NAME).
3. Pin MLflow experiment paths to the user-and-use-case identity. At the same prompt that first resolves $APP_NAME / $AGENT_NAME, also resolve any <pending> MLflow experiment paths in Captured Resource IDs so downstream skills (F2, SDLC 04c, 08-appkit-feedback) consume the value from state instead of constructing their own — generic leaves like Tracing, traces, or my-app-feedback are forbidden:
   • mlflow_experiment_path → /Users/<user_email>/mlflow/<APP_NAME>-agent (Pathway C) or /Users/<user_email>/mlflow/<AGENT_NAME>-agent (Pathway D). n/a for Pathways A and B.
   • mlflow_feedback_experiment_path → /Users/<user_email>/mlflow/<APP_NAME>-feedback (Pathway C only). n/a for A, B, D.
   • The leaf MUST carry the same ${FIRSTNAME}-${LASTINITIAL}-${use_case_slug} shape that backs APP_NAME so concurrent workshop attendees on a shared workspace cannot collide on a single MLflow experiment.
4. All subsequent enter calls resolve to the canonical path automatically.

Outputs: Path of the canonical state file.

Errors: If the canonical path already exists, abort — the operator has collided with an earlier run.

Operation: exit

When: At the bottom of every workshop prompt, after all verification checks have passed.

Inputs:

Behavior:

1. Run the prompt's verification checks (caller supplies verification if declared). When a check involves a deploy/run, use the verb + CLI channel resolved by enter from ## Environment Capabilities (never a bare-shell databricks call).
2. Write the ## Prompt <prompt_id> — <title> section to the live state file (located under environment_capabilities.state_file_root, same resolution as enter step 1) using the Per-Step Log template in references/state-template.md. Idempotent by prompt_id (hard): first scan the file for an existing ## Prompt <prompt_id> — … heading. If one exists, replace that section in place (update its Gate, captured vars, and bullets); only append a NEW section when no entry for this prompt_id is present. Never append a second section for a prompt_id that is already logged — a re-run after a retry or context reset must update the existing entry, not create a duplicate (duplicate silver_layer_sdp entries were a live regression).
3. Update Captured Resource IDs at the top — replace <pending> entries for every key in captured. Mark pathway-irrelevant IDs <n/a>.
4. Bump Last updated in the header.
5. Gate rule (hard): if the prompt is a build/modify prompt, gate MUST be Local testing passed. If it is anything else, exit stops and the next deployment-oriented prompt's enter will reject on the prior-gate check.
6. Verify the write (load-bearing — not advisory): after appending, re-read the live state file and confirm the new ## Prompt <prompt_id> section, the updated Captured Resource IDs, and the bumped Last updated are actually present. If the re-read does not show the appended section, the exit did NOT persist — retry the write (on Genie Code, fall back to executeCode open(path,"a") when workspaceUpdateFile silently no-ops on an existing file). The prompt is NOT complete until this re-read confirms the write. The chat summary is NOT the state store.
7. Print a 3-line summary to chat: what was created, what values were captured, what the next prompt will consume.

Handoff invariant (every summary / context-compaction / thread handoff): carry state_file_path, last_completed_prompt, last_gate, environment_capabilities, and state file updated: yes/no verbatim (see references/retrospective-template.md § Handoff invariant). A handoff that omits these is non-conformant; the next thread must re-open the live file rather than trust the prose. Generate the summary FROM the live state file's Per-Step Log — never from in-memory recollection — and the state file always supersedes the summary: if the summary and the state file disagree about whether a step is done, the state file wins (a step logged with its gate PASSED is DONE even if the summary says "NOT DONE" / "IN PROGRESS"; a summary mid-execution snapshot must NOT trigger re-running a completed, gated step).

Outputs: The new log section's path inside the state file.

Errors: Verification check failure, gate-rule violation — halt without marking complete.

Operation: retrospective.per_prompt

When: Async, after the whole workshop completes. Run once per executed prompt. Do not interleave with active prompts.

Inputs:

Behavior:

1. Load references/retrospective-template.md.
2. Fill in the per-prompt block exactly as specified (fixed headings, no additions or renames).
3. Append to example/<use_case_slug>/retrospective.md.
4. Print back to chat: Friction score, Outcome, Pathway/track applicability verdict, Top 3 improvements. Nothing else.

Errors: If the state file has no matching ## Prompt <prompt_id> section, halt — there is nothing to retro.

Operation: retrospective.rollup

When: After every per-prompt retro is in retrospective.md. Run exactly once.

Inputs: None.

Behavior: Follow the Session Rollup Prompt in references/retrospective-template.md. Produce example/<use_case_slug>/retrospective-rollup.md with the seven fixed sections (Instructions.md edits, Skill edits, State-file schema edits, Pathway Applicability Matrix edits, Top disambiguation gaps, Gate violations, Spec drift).

Before producing the backlog, run the Spec Drift checks from the rollup template in this order:

1. PRD drift. Compute sha256 of the file at ## Workshop Choices → prd_path and compare with ## Spec Provenance → prd_sha256. Mismatch → halt with a hard error instructing the operator to re-run resolve_spec (or accept drift by updating prd_sha256 explicitly).
2. Schema drift. Read ## Spec Provenance → schema_version. If it differs from the Schema Version in references/spec-schema.md (currently "2.0"), halt with a hard error: either run the migrator for that schema bump or re-run resolve_spec on the current schema.
3. Producer-consumer contract (fields_read: drift check). Load every known consumer skill's frontmatter and parse its fields_read: YAML list. Parse the live state file's ## Resources, ## UI, ## Agent, ## Governance YAML blocks and enumerate every dotted-path leaf. Compute consumed = union(fields_read:) (expand parent paths like ui.* to their leaves). Compute produced = leaves_of(state file). Halt with a hard error if:
   • produced − consumed ≠ ∅ → resolver emitted a field nothing reads (stale or missing consumer).
   • consumed − produced ≠ ∅ → consumer declares a read on a field the resolver did not emit (schema drift or typo).

Only if all three pass does the rollup proceed to enumerate the four non-blocking sub-checks (unused resolved fields, hardcoded leaks), merge them into the backlog as section 7 (Spec drift), and write the rollup file.

Surface state_contract_audit.productized_debts_status in the rollup as a one-line debt-lift summary (e.g. "Productized debts: 5 total / 1 lifted / 0 parse errors").

Outputs: Path of the rollup file. On halt, path of a short error report at example/<use_case_slug>/retrospective-rollup.ERROR.md explaining which check failed and how to recover.

Operation: state_contract_audit

When: Run before retrospective.rollup, before any workshop release, and after modifying prompt/skill state fields.

Inputs:

Behavior:

1. Parse every prompt's declared captured fields from docs/02_seed_section_input_prompts.sql.
2. Parse every skill frontmatter fields_read: and produces: list.
3. Parse references/spec-schema.md and references/state-template.md.
4. Emit four lists:
   • fields_read_but_never_produced
   • fields_produced_but_not_in_schema
   • schema_fields_missing_from_template
   • captured_fields_with_no_consumer
5. Canonical-names extension. Parse the live state file's ## Canonical Names block and grep prompt sources + skill bodies for legacy/incorrect spellings of env vars, HTTP headers, jq paths, MLflow Prompt Registry URI schemes, and eval-dataset column names. Add any non-canonical reads to fields_read_but_never_produced (with the legacy name as the field) so the same fail-list flushes them. Reads on null-valued canonical entries (e.g. x-forwarded-user-info) are always reported regardless of mode.
6. Preflight-registry extension. Parse the live state file's ## Preflight Check Registry block. For each entry, verify (a) owner resolves to either a real skill path under skill_root or a known prompt id in the workshop's prompt registry, and (b) every check name referenced from a prompt body or skill fields_read: list exists as a key in the registry. Unresolved owners and unknown referenced check names are added to fields_read_but_never_produced so the same fail-list flushes them. Until forward-referenced owners (Phase 2.2's instruction_iteration, Phase 4.4's lakebase_memory, etc.) land, those entries

Truncated - read the full file at https://github.com/databricks-solutions/vibe-coding-workshop-template/blob/9b4eb111831fbcad37f883859a715ff81bbc6b0e/skills/vibecoding-state/SKILL.md.