Project parameters

Some flows need a few answers before they can work: a project name, a brand colour, which framework you use. Project parameters let you give those answers once.

The dashboard’s Settings page carries a Project parameters panel. Pick the flow, fill its fields, press Save, and every later run reuses the values. Underneath, that is a small JSON file:

// .vibestrate/project-params.json
{
  "schemaVersion": 1,
  "values": {
    "scaffold.projectName": {
      "value": "acme-api",
      "setBy": "user",
      "at": "2026-08-12T09:14:02.118Z",
      "secret": false
    },
    "scaffold.framework": {
      "value": "astro",
      "setBy": "user",
      "at": "2026-08-12T09:14:02.118Z",
      "secret": false
    }
  }
}

Each entry records who set it and when.

vibe ui opens the dashboard on 127.0.0.1:4317; the panel is on Settings, at #/settings.

A Flow selector lists only the flows that declare params: at all. Under it, one row per parameter: the name, its type as a tag, a shared tag when it is project-global, an amber secret marker when the flow declared it secret - stored value or not - and the flow’s description. An enum renders as a picker, everything else as a text field, and stored: under each row shows the current value and who set it - you, a generator, or a default.

Save writes the edits, and editing here supersedes a stored value rather than only filling a blank. All stored values below it lists every key across every flow with a bin icon to remove one. Nothing is removed on your behalf.

The composer carries the same fields, under Inputs on the New run page and under Flow parameters on Mission Control’s composer. They are a different thing: an edit there overrides for that one run and is never stored. The fields do not start blank - each one opens on the stored answer, falling back to the flow’s own default. A secret field is the exception and always starts empty, because a stored secret is an env reference rather than a value to show.

At run start each declared param resolves top to bottom, stopping at the first source that has a value:

• Explicit values win, from --param or the composer’s input fields. An empty --param x= means “not provided”, so the stored value or default still fills it.
• VIBESTRATE_PARAM_<NAME> is the clean CI seed: export it, skip the interactive step, and the run never hangs unattended. The name is the param upper-snake-cased, so colorTokens becomes VIBESTRATE_PARAM_COLOR_TOKENS. Two params that would collide on one env var are refused when the flow resolves, rather than leaving one silently un-seedable.
• A required param still unset after all of that prompts on a TTY, or fails fast in CI with a message naming exactly what to set.

A stored value is keyed per Flow (<flowId>.<param>), so two Flows that both call something name never cross-contaminate. Mark a param shared: true to store it under a project-global key - the bare name - that any other Flow declaring it shared reuses.

A secret: true param never stores the raw secret. You give it an environment variable name, and the store keeps an env:NAME reference. Say a Flow of yours declares one:

params:
  apiKey:
    type: string
    secret: true

Its Settings field then asks for the variable name, not the key, and its placeholder says so. On the CLI:

# The store keeps env:OPENAI_API_KEY, not the key
vibe params set --flow my-deploy apiKey=OPENAI_API_KEY

A run that needs it fails fast if that env var isn’t set, rather than starting with a non-functional secret. No built-in Flow declares a secret param, so this only comes up in a Flow you write. Bare-key writes without --flow are non-secret-only, and a best-effort scan still refuses an obvious pasted vendor key.

A param can declare a generate hint:

params:
  palette:
    type: string
    generate:
      instruction: >
        Generate a cohesive color palette
        for a {{params.niche}} brand

Its row in the Settings panel then grows a Generate button, and vibe params generate --flow <id> palette does the same. It calls a provider once, read-only, with your other known param values interpolated in, and returns a suggestion you review, edit, or accept. Strictly user-initiated and never auto-applied, so a model can’t silently make a brand colour your project’s truth.

One project-global key is special. Set methodology to a known value and the planner gets that methodology’s concrete planning guidance:

# Recognized values: tdd, bdd, incremental
vibe params set methodology=tdd

• tdd - plan test-first (failing test -> pass -> refactor).
• bdd - plan as Given-When-Then behaviors, then derive the implementation.
• incremental - smallest safe vertical slices, green at every step.

It reaches the planner and nobody else by default, as one bounded block, once per run; methodologyRoles in project.yml widens that. An unrecognized value is ignored with a methodology.unknown run event, so it never breaks a run. The advisor never sets it for you.

The automation path, and the only surface for a key no flow declares: the Settings panel is organised by flow, writes a shared: true param under its bare project-global name like the CLI does, and cannot reach a key that exists in no flow’s params: block.

# The --flow form type-checks values against the schema
vibe params set --flow scaffold projectName=Acme framework=astro

vibe params list           # every stored value, secrets as env refs
vibe params get <key>
vibe params unset <key>    # explicit, never automatic

vibe shell has no parameters screen. Its Config page is a read-only view of project.yml, which is a different file.

• Flow - declares the typed params: the project params fill.
• Profile - a different thing: how strong a Role runs (provider + model + effort), not project data. Set with vibe profile.