v0.23.0 Migration Guide

pipeline templates is now sparkwing examples, and --template takes a shapeSection anchor link

The sparks-core registry moved off the pipeline-creation path. It is browsed with its own verb and read rather than scaffolded from.

# before
sparkwing pipeline templates
sparkwing pipeline templates --name lint-test-go --body
sparkwing pipeline new --name deploy --template go-test-build-deploy-k8s \
  --param image=myapp --param namespace=myapp

# after
sparkwing examples
sparkwing examples --name lint-test-go --body
sparkwing pipeline new --name deploy --template build-test-deploy

--param is gone from pipeline new. --template accepts one of five shapes -- minimal, build-test-deploy, ci-pr-check, release, scheduled-report -- and rejects a registry name with an error naming the shapes and pointing at sparkwing examples --name <name> --body to read the entry instead.

Nothing in the registry was removed. Every entry pipeline templates listed is still there under sparkwing examples, still verified by the template-verify pipeline, and --category / --cloud / --name / --body / -o json work as before.

Pipelines you already scaffolded from a registry template are unaffected. The rendered Go source is yours; it does not resolve anything from the registry at build or run time.

If you were scaffolding from a registry template in a script, the replacement is to read the example and write the pipeline from a shape. There is no flag that restores the old behaviour, because the rendered output was a starting point that still needed editing -- the registry entries are wiring over sparks-core libraries for someone else's repo, not a place to begin.

WhySection anchor link

Templates and examples were one list doing two jobs. Measured agent trials spent about a quarter of their turns choosing between forty entries before writing anything, and the entry that reads like the obvious pick for a task is frequently the wrong place to start.

sparkwing commands prints an index; pass -o json for the old outputSection anchor link

sparkwing commands defaulted to a full JSON record for every verb -- 139 of them, roughly 235KB. It now prints one line per verb.

# before: JSON on stdout
sparkwing commands | jq '.[].path'

# after: same JSON, explicitly requested
sparkwing commands -o json | jq '.[].path'

-o json is byte-identical to the old default, so any script keeps working with that one flag added. -o markdown and -o plain are unchanged.

Two ways to narrow the surface instead of dumping it:

sparkwing commands --path "sparkwing pipeline"    # one subtree
sparkwing pipeline run --help                     # one verb, in full

WhySection anchor link

The old default was chosen because agents are the primary audience, which is true and is exactly why JSON was wrong for it: agents do not size output before reading it. A measured trial piped the bare command into a narrow lookup, spent roughly 58,000 tokens, and had the output truncated anyway.

Nothing else needs actionSection anchor link

No schema migration, no config change, no SDK API removal. The pkg/docs.Section type gained a Breadcrumb field, which is additive.