paulasilvatech Backstage Software Templates
Build self-service workflows with typed inputs, explicit effects, deterministic skeletons, and visible outputs.
When to invoke
- "Create a Golden Path template."
- "Add or test a custom scaffolder action."
- "Fix a broken template step output."
- "Publish a generated repository and register it in the catalog."
Procedure
- Detect Backstage version, installed scaffolder modules, available actions, and template conventions.
- Define the user outcome, owner, generated component type, external effects, and rollback.
- Model parameters with types, validation, required fields, pickers, and safe defaults.
- Use stable step IDs and camelCase custom action IDs. Do not use kebab-case custom action IDs because step-output expressions can fail.
- Render a minimal skeleton with explicit values and no embedded credentials.
- Keep repository publication, workflow dispatch, infrastructure provisioning, and catalog registration as separate visible steps.
- Add typed custom action schemas, input validation, permissions, dry-run behavior, and tests.
- Render the template with representative inputs and inspect every generated file.
- Require approval before creating repositories, dispatching provisioning, deploying, or incurring cost.
- Validate catalog registration and return links or entity references in template outputs.
Failure handling
- Stop on unknown actions, missing integrations, unresolved step outputs, invalid repository hosts, or ambiguous ownership.
- Do not report success when publication succeeded but catalog registration failed.
- Preserve the task log needed for diagnosis while redacting secrets.
Output template
## Software Template result
**Template:** <name>
**Effects:** <repositories, workflows, infrastructure, catalog>
| Step | Action | Validation | Result |
| --- | --- | --- | --- |
### Approval-gated actions
- <action and status>
Quality gate
- Parameters, required fields, validation, and defaults are intentional.
- Custom action IDs use camelCase and step-output references resolve.
- Skeleton rendering is tested with representative inputs.
- External effects are visible, least-privilege, and approval-gated.
- Catalog registration and result links are validated.
- Generated content contains no secrets or unresolved template expressions.