Solution Scaffolding Tutorial#

This tutorial covers using scafctl new solution to quickly scaffold new solution files with the correct structure, providers, and best practices.

Overview#

The new solution command generates a complete, valid solution YAML file based on your inputs. Instead of writing YAML from scratch (and getting field names wrong), scaffolding gives you a working starting point.

flowchart LR
  A["Parameters<br/>(name, etc)"] --> B["scafctl<br/>new solution"] --> C["Solution<br/>YAML File"]

1. Quick Start#

Generate a Basic Solution#

Bash

scafctl new solution \
  --name my-app \
  --description "My application configuration" \
  --output my-app.yaml

PowerShell

scafctl new solution `
  --name my-app `
  --description "My application configuration" `
  --output my-app.yaml

This generates a valid solution file with:

Correct apiVersion and kind
Metadata with name, version, and description
A sample resolver using the static provider
An example workflow action

Verify the Output#

Immediately validate the generated file:

Bash

scafctl lint -f my-app.yaml

PowerShell

scafctl lint -f my-app.yaml

Run it:

Bash

scafctl run solution -f my-app.yaml

PowerShell

scafctl run solution -f my-app.yaml

2. Choosing Providers#

Specify which providers to include in the scaffolded solution:

Bash

# Include specific providers
scafctl new solution \
  --name api-collector \
  --description "Collect data from APIs" \
  --providers http,cel,exec \
  --output api-collector.yaml

PowerShell

# Include specific providers
scafctl new solution `
  --name api-collector `
  --description "Collect data from APIs" `
  --providers http,cel,exec `
  --output api-collector.yaml

The generator creates resolver examples using each specified provider with correct input schemas.

Available Providers#

Not sure which providers to use? List them first:

Bash

scafctl get provider

PowerShell

scafctl get provider

Or get details on a specific provider:

Bash

scafctl get provider http

PowerShell

scafctl get provider http

3. Starting from Examples#

Instead of scaffolding from scratch, you can also start from an existing example:

Bash

# Browse available solution examples
scafctl examples list --category solutions

# Download one as a starting point
scafctl examples get solutions/email-notifier/solution.yaml -o my-solution.yaml

# Modify and validate
scafctl lint -f my-solution.yaml

PowerShell

scafctl examples list --category solutions
scafctl examples get solutions/email-notifier/solution.yaml -o my-solution.yaml
scafctl lint -f my-solution.yaml

This is useful when you want a more complete starting point with real patterns (parameters, validation, actions, composition).

4. Common Scaffolding Patterns#

Resolver-Only Solution#

For solutions that just gather and transform data without side-effect actions:

Bash

scafctl new solution \
  --name data-collector \
  --description "Gather configuration from multiple sources" \
  --providers static,env,http,cel \
  --output data-collector.yaml

PowerShell

scafctl new solution `
  --name data-collector `
  --description "Gather configuration from multiple sources" `
  --providers static,env,http,cel `
  --output data-collector.yaml

Then run with the resolver command:

Bash

scafctl run resolver -f data-collector.yaml -o yaml

PowerShell

scafctl run resolver -f data-collector.yaml -o yaml

Full Workflow Solution#

For solutions with actions:

Bash

scafctl new solution \
  --name deploy-pipeline \
  --description "Deployment automation pipeline" \
  --providers static,exec,cel \
  --output deploy-pipeline.yaml

PowerShell

scafctl new solution `
  --name deploy-pipeline `
  --description "Deployment automation pipeline" `
  --providers static,exec,cel `
  --output deploy-pipeline.yaml

Adding Tests After Scaffolding#

Once your solution works, add functional tests:

Bash

# Validate the solution
scafctl lint -f my-solution.yaml

# Use the MCP server to generate test scaffolding (if using AI tools)
# Or see the Functional Testing Tutorial for manual test writing

PowerShell

scafctl lint -f my-solution.yaml

5. Workflow#

The recommended scaffolding workflow:

Scaffold — scafctl new solution --name my-app --output my-app.yaml
Lint — scafctl lint -f my-app.yaml
Edit — Modify resolvers and actions for your needs
Lint again — scafctl lint -f my-app.yaml
Test — scafctl run resolver -f my-app.yaml to verify resolvers
Run — scafctl run solution -f my-app.yaml for the full workflow

Next Steps#

Getting Started — Full getting started guide
Resolver Tutorial — Deep dive into resolvers
Actions Tutorial — Build workflow actions
Provider Reference — All available providers
Functional Testing Tutorial — Add automated tests
Eval Tutorial — Test expressions before adding to solutions