[skills-sync] Update skills after SuperPlane main @ 9c9164307a0c8edc5b6b2f13cc69e0c398e0947c #12

Opened automatically by SuperPlane (Skills and Docs Sync canvas).

What changed in this push

Commit 9c9164307a0c changes how both the SuperPlane CLI and API handle unknown fields in YAML files and API request payloads. Previously, unknown fields were silently ignored. Now they are rejected with an error. This applies to:

• CLI: YAML files parsed for canvases, groups, roles, and secrets commands. A new pkg/cli/core/decoder.go was introduced (with tests), indicating a centralized strict-decoding layer. Canvas model parsing (pkg/cli/commands/canvases/models/canvas.go) was also updated.
• API: The public server (pkg/public/server.go) now rejects requests containing unknown JSON/YAML fields.

The motivation is predictability, particularly for coding agents authoring canvas YAML or calling the API programmatically.

Which skills files are likely affected

Concrete edits to make

skills/superplane-cli/SKILL.md

• Add a clearly labeled callout or warning section (e.g., > **Note:** Strict YAML validation) stating:

  • As of this change, the CLI performs strict field validation on all YAML input files (canvases, groups, roles, secrets).
  • Any unknown, misspelled, or extraneous field in a YAML file will cause the command to fail with an error rather than silently continue.
  • Users and coding agents must ensure YAML files conform exactly to the documented schema — no extra or experimental fields are permitted.
  • Example error scenario: a canvas YAML with a typo like naem: instead of name: will now produce an explicit error.

• Add practical guidance:

  • Before running CLI commands, validate YAML against the documented schema.
  • When generating YAML programmatically (e.g., via a coding agent), only include fields that are explicitly documented.
  • If you see an unknown field error, check the field name against the current schema — do not attempt to add undocumented fields to bypass validation.

• Update any existing examples or sample YAML snippets to ensure they contain no extraneous fields (audit existing snippets if present).

skills/canvas-yaml-spec/SKILL.md (if it exists)

• Add a note at the top or in a validation/constraints section:
  • The canvas YAML spec is now strictly enforced by the CLI parser. Unknown fields are rejected at parse time.
  • Coding agents should treat the documented spec as exhaustive — omit any field not listed.
  • Recommend testing YAML locally with the CLI before committing or submitting to a pipeline.

skills/superplane-api/SKILL.md (if it exists)

• Add a note in the request payload section:
  • API requests containing unknown fields in the JSON/YAML body will now receive an error response (previously they were silently dropped).
  • Clients and coding agents must only send fields defined in the current API schema.
  • This affects all endpoints served by the public server.

Verification

A human reviewer should confirm the skills remain accurate by:

1. CLI smoke test — unknown field rejection:

   • Create a minimal canvas YAML with one deliberate unknown field (e.g., unknownField: true).
   • Run the relevant CLI command (e.g., superplane apply -f canvas.yaml).
   • Confirm the CLI returns a non-zero exit code and an error message referencing the unknown field.
   • Confirm the same YAML without the unknown field succeeds.

2. CLI smoke test — all resource types:

   • Repeat the above for group, role, and secret YAML inputs to confirm the strict decoder is applied uniformly, not just for canvases.

3. API smoke test — unknown field rejection:

   • Send a POST/PUT request to a public API endpoint with an extra unknown field in the body.
   • Confirm a 4xx error response is returned (not a 2xx with the field silently dropped).

4. Skills accuracy review:

   • Read the updated SKILL.md files and compare the documented field lists against the current schema files (pkg/cli/commands/canvases/models/canvas.go and related models).
   • Confirm no currently-documented example YAML in the skills repo contains fields that would now be rejected.

5. Coding agent dry-run (optional but recommended):

   • Have a coding agent generate a canvas YAML from the skill instructions alone.
   • Apply it via CLI and confirm it passes validation without unknown-field errors.