guided

name

guided

description

Outcome-driven Alvera platform provisioning. The user describes a business goal ("send review SMS after appointments", "onboard patient data from CSV", "create an AI agent for claim triage") and the skill derives the full dependency chain, checks what already exists, and provisions everything in the correct order — bottom-up execution, top-down design. Handles all resource types: datalakes, data sources, tools, generic tables (with compliance gate and column profiling), AI agents, agentic workflows (with templates and dry-run testing), connected apps, interop contracts, data activation clients, file ingestion (anti-pattern detection, Liquid template generation, sandbox testing), and PostgREST explorer scaffolding. Drives the `alvera` CLI from `@alvera-ai/platform-sdk`. Auth is session-based — the user runs `alvera login` themselves. Emits an `alvera-<tenant-slug>.yaml` receipt. Use when the user says anything about setting up, provisioning, onboarding, creating, or configuring Alvera platform resources.

Alvera AI — Guided Setup

Outcome-driven provisioning. The user describes what they want to achieve; the skill derives what's needed, checks what exists, and builds in order.

Top-down design, bottom-up execution:

• User: "I want to send review SMS after appointments"
• Skill: derives → datalake → data source → SMS tool → workflow
• Skill: checks → datalake exists, data source exists, tool missing, workflow missing
• Skill: provisions in order → tool → workflow → done

Workflow

Step 1: Planning (outcome elicitation)

Ask the user what they want to achieve — not what resource to create.

"What are you trying to set up? Describe the goal — e.g. 'send review SMS after appointments', 'onboard patient data from a CSV', 'create an AI agent for triage', 'build an appointment reminder workflow', 'push data from a file'. Or name a specific resource if you know what you need."

Match the outcome to a dependency chain using references/outcomes.md.

If the outcome maps to a known chain, derive the plan. If the user names a specific resource directly, treat it as a single-resource outcome (minimal chain). If the outcome is ambiguous, ask one clarifying question and proceed.

Step 2: Bootstrap

Auto-detect first, ask only what's missing. Returning users should not re-answer questions the CLI already knows.

Bootstrap sequence (run silently, no questions):

1. CLI resolution — alvera --version or npx -p @alvera-ai/platform-sdk alvera --version. If both fail, hand the user npm install -g @alvera-ai/platform-sdk and stop. See references/cli-cheatsheet.md.
2. Auth check — alvera whoami. Three outcomes:
   • Valid session → present it and proceed:

     "Session active: profile default, tenant acme-health, [e-mail]. Proceeding."

   • Not authenticated / expired → single instruction:

     "Please run alvera login and let me know when done." Then stop and wait. Don't investigate WHY auth failed.

   • No profile configured → ask for tenant slug and base URL (default https://admin.alvera.ai), run alvera configure, then ask user to login.
3. Tool not set up — if the user hasn't set up their Alvera platform account yet, direct them to https://alvera.ai and stop.
4. Pick datalake — alvera datalakes list. If one exists, use it (tell the user which). If multiple, ask which. If none, offer to create.

Receipt: always emit alvera-<tenant-slug>.yaml — don't ask.

Only ask questions the CLI can't answer. A returning user with a valid session and one datalake should reach Step 3 with zero prompts.

NEVER introspect the user's HOME directory. Don't read, write, cat, or ls ~/.alvera-ai/ or any auth/config files. Don't symlink anything. Don't run env | grep alvera. The CLI is the only interface to auth state. If alvera whoami fails, tell the user to login — don't investigate further.

Creating a datalake (when none exists)

Primary flow: alvera init infra-setup

1. Run alvera init infra-setup in the project directory (cwd). This generates .alvera.datalake.env with all required fields as blanks.
2. Tell the user: "Fill out .alvera.datalake.env and let me know when done." Or, if user provides values inline, fill them programmatically.
3. Read the .env file from cwd to build the create body.
4. Create via alvera datalakes create <tenant> --body-file /tmp/datalake.json.

Never manually construct the full datalake JSON from scratch. Use the .env as the schema source — it guarantees all required fields are present.

Never read or write ~/.alvera-ai/.alvera.datalake.env — only the copy in the project directory (cwd). The HOME copy is the user's business.

Alternative: Neon API — if NEON_API_KEY is set, use the Neon API to provision Postgres and get connection details in one call. See references/neon-project.md. Then fill the .env from Neon's response.

All four Alvera roles (regulated/unregulated × reader/writer) can reuse the same connection unless the user needs isolation.

Session state to retain: profile, tenantSlug, datalakeSlug, datalakeId, baseUrl.

Context switching: If the user says "now do this for a different datalake" or "switch to tenant X", re-run the relevant bootstrap checks (whoami, datalakes list) and update session state. Never silently use stale state from a previous datalake/tenant.

Step 3: Gap analysis

For each resource in the derived chain, check if it already exists:

alvera --profile <p> <resource> list ...   # per resource type

Present the gap analysis:

"To achieve review SMS after appointments, I need: ✓ Datalake acme-health — exists ✓ Data source appointments — exists ✗ SMS tool — missing ✗ Review workflow — missing

I'll create the missing resources in this order:

1. SMS tool (depends on: data source ✓)
2. Review workflow (depends on: SMS tool, data source ✓)

Proceed? (y/n)"

When everything already exists, tell the user and ask if they want to create something additional or adjust.

Step 4: Execute plan

Provision resources in dependency order. For each:

1. List existing to detect collisions (guardrails: no silent upsert).
2. Elicit missing fields per references/resources.md.
3. Confirm in plain language (bullets, not JSON).
4. Create via CLI (references/cli-cheatsheet.md).
5. Append to alvera-<tenant-slug>.yaml if receipt enabled (references/yaml-receipt.md).
6. Move to next resource in the chain.

Complex sub-flows handled inline:

• Data pipeline (file → table → upload): follow references/data-pipeline.md for compliance gate, column profiling, table creation, anti-pattern scan, interop template generation, sandbox test, and upload.
• Workflow creation (template or custom): follow references/workflows.md for template selection, custom build, draft creation, dry-run test, log interpretation, and promotion to live.
• Query/inspect data: follow references/query.md for dataset search.
• Connected app setup: run alvera init connected-app to generate a .env with ALVERA_BASE_URL, ALVERA_TENANT, ALVERA_DATALAKE, and ALVERA_CONNECTED_APP. User fills values, app reads from env.

Fallback: alvera raw — if a CLI command fails or the needed endpoint isn't wrapped by the SDK yet, use:

alvera raw <METHOD> <path> [--body <json>] [--body-file <path>] [--no-parse]

This sends an authenticated HTTP request directly. Use it to unblock provisioning when a specific command errors out — then report the raw response to the user.

After the chain is complete, report what was created.

Step 5: Loop

"Done — review SMS workflow is live. What else do you want to achieve?"

Continue until the user says done. On done, suggest alvera logout.

Stance: be proactive

Assume forward progress. Default to the positive action, confirm with y/n. Don't present long menus when one path is obvious.

• Resolve everything possible before asking.
• When only one option exists, use it and tell the user.
• Anti-pattern scans and sandbox tests run automatically.
• When the user agrees, move immediately — don't re-confirm.
• Create tasks lazily — one at a time as you reach each step. Don't dump 10 tasks upfront. The gap analysis IS the plan.
• Combine bootstrap + gap analysis into one message. Don't pause between reporting auth status and presenting the gap. One message, one confirmation, then execute.

Fast-path vs confirmation-required:

Action	Speed
Resource creation (non-destructive)	Confirm once with bullet summary, then create
Anti-pattern scan, sandbox test	Run automatically, no confirmation
Dry-run workflow test	Run automatically after draft creation
Delete a resource	Require yes delete <name> exactly
Promote workflow to live	Require explicit y/n
sync-routes on connected app	Require explicit y/n
Update existing resource	Show old → new diff, require y/n

Hard constraints

Filesystem boundaries — whitelist approach:

You may ONLY read from these locations:

Allowed	Purpose
This skill's directory (where SKILL.md lives)	References, templates, scripts
User's project directory (cwd)	CSV files, .env files, generated artifacts
/tmp/	Scratch space for generated JSON bodies, profiling output
Files the user explicitly provides a path to	Whatever they hand you

If you need something not in the whitelist:

1. Clone to /tmp — git clone --depth 1 <repo> /tmp/<name> for a specific reference
2. Fetch npm package — npm pack <package>@<version> --pack-destination /tmp && tar -xzf /tmp/<pkg>.tgz -C /tmp/ to inspect published package contents
3. Ask the user — "I need X, can you point me to where it lives?"

Never:

• Read from ~/.alvera-ai/ — use CLI commands for auth/config state
• Browse sibling repos, parent directories, or npm cache (~/.npm/)
• find across the filesystem looking for examples or fixtures
• Use integration test fixtures as template source material

Templates specifically come from:

1. The skill's own templates/ directory (bundled examples)
2. Built from scratch using CSV column profiling + FHIR resource schema
3. alvera interop metadata <datalake> <slug> for existing contract schemas

Read on first user interaction:

• references/scope.md — what is in/out of scope, with refusal language.

Read on first create or update:

• references/guardrails.md — non-negotiable rules: no silent upsert, destructive confirmations, secrets handling, dependency ordering, read-before-write for updates, partial chain failure recovery.
• references/updates.md — per-resource mutability rules (which fields are locked at creation).

Read on errors:

• references/errors.md — error catalog with causes and recovery steps.

CLI

alvera from @alvera-ai/platform-sdk (>= 0.8.0). Two invocation forms:

npx -p @alvera-ai/platform-sdk alvera <command>   # zero-install
alvera <command>                                    # if installed globally

Auth is session-based, stored AWS-CLI-style under ~/.alvera-ai/. User runs alvera login in their own shell. Skill never sees the password. Never read, write, cat, ls, or symlink anything under ~/.alvera-ai/. Use alvera whoami for auth state. Use alvera init infra-setup in cwd for datalake config. The HOME directory is off-limits.

Key commands beyond resource CRUD:

alvera init connected-app   # generate .env for app integration
alvera init infra-setup     # generate .env for datalake infrastructure
alvera raw <METHOD> <path>  # authenticated HTTP escape hatch

References

• references/outcomes.md — outcome → dependency chain catalog
• references/resources.md — per-resource field elicitation rules
• references/updates.md — per-resource mutability rules for updates
• references/guardrails.md — non-negotiable rules
• references/errors.md — error catalog with causes and recovery steps
• references/scope.md — allowed/refused operations
• references/cli-cheatsheet.md — CLI command surface (incl. batch ops, init)
• references/data-pipeline.md — file → table → template → upload flow
• references/workflows.md — workflow templates, liquid variables, execution
• references/query.md — dataset search, inspection, and post-provisioning monitoring
• references/yaml-receipt.md — emitted YAML schema and rules
• references/neon-project.md — Neon API for Postgres provisioning (datalake DB backend)
• references/example-transcript.md — reference end-to-end conversations
• scripts/alvera-profile.py — column profiling script (used by data-pipeline)
• scripts/alvera-scan.py — anti-pattern scanner script (used by data-pipeline)
• templates/review-sms.json — Template A: Review SMS Workflow body
• templates/cahps-survey.json — Template B: CAHPS Survey Workflow body
• templates/minimal-scaffold.json — Template C: minimal workflow scaffold