The core loop

Every interaction with Valved flows through one loop:

Intent → Plan → Build → Run → Deploy → Schedule → Observe

Steps 1–3 are LLM-mediated (subagents reason, grounded in real tool output); steps 4–7 are deterministic mechanics. The loop is the same whether the goal is a new pipeline, a change to an existing dbt model, a config change, or a schedule adjustment — and whether it’s driven by a human at the CLI, an agent via MCP, or a CI workflow via REST.

1. Intent

A user or external agent expresses a goal in natural language — “onboard Salesforce”, “make stg_orders incremental”, “add freshness checks to all marts”. Intent enters via the CLI, REST API, MCP server, or web UI.

2. Plan

The orchestrator (the harness’s main loop) classifies and decomposes the goal, delegates to the right domain subagents, gathers component context, and synthesizes a structured plan with file diffs and cost estimates.

A plan is a durable, reviewable artifact. Iterate on it with valved plan --refine <plan_id> "…"; the new plan is recorded with parent_plan_id pointing at its predecessor.

valved plan "ingest the Stripe charges API into raw_stripe"
valved plan --refine <plan_id> "also add a not-null test on charge_id"

3. Build

Once approved, the subagents generate code into the relevant component — dlt sources and resources, dbt models and tests, the SQL glue, and the pipelines/<name>.toml that composes them. They verify by executing (dlt pipeline run, dbt build / test) until green. Output lands in the working tree, not committed yet.

valved build <plan_id>

In orchestration-only mode (you bring existing dlt/dbt/sql), build composes and registers your components by name without generating component code.

4. Run

The user (or agent, or scheduler) executes the composed pipeline against the dev target. Iteration is cheap — re-run, refine, re-run, until the rows look right.

valved run <pipeline> --watch

5. Deploy

Promote the component(s) plus the control-plane composition from dev to prod via a configurable handoff:

files → commit → push → pr        (default: pr)

A change spanning a separate-repo component and the control-plane repo produces linked PRs (ingest-first ordering). Valved opens and orders the PRs; you merge.

valved deploy <pipeline>                 # default handoff (PR)
valved deploy <pipeline> --handoff push  # stop at push, no PR

6. Schedule

Once merged, the control plane fires runs against prod on the configured cadence. The schedule is data, not code: a pipeline’s optional [seed_schedule] block seeds the schedules table at first registration, and thereafter the live schedule is changed instantly (and audited) via valved schedule — not via a code change or PR. See Scheduling & runs.

7. Observe

Every run, log line, status transition, and cost number is queryable via CLI, REST, MCP, or the static UI. External agents can subscribe to run-completion webhooks. Failed runs surface for recovery.

A sibling verb outside the loop: ask

valved ask is the explorer subagent — it handles investigative, read-only questions (“Where do we calculate net revenue?”, “Which models depend on stg_orders?”) by investigating dbt’s manifest, dlt’s schema, and your code, and answers with citations. It runs in the harness’s read_only permission mode, is strictly side-effect-free, and can run concurrently with anything else.

valved ask "what breaks if I change raw_stripe.charges?"