spec

The spec skill is a core component of the Spec-Driven Development (SDD) workflow, designed to streamline architectural decision-making for cloud-native platform engineering. It enables platform engineers to draft, track, and manage non-trivial changes—such as new Crossplane compositions, major infrastructure modifications via OpenTofu, or security policy updates—before implementation begins. By anchoring every change to a dedicated GitHub issue and a version-controlled specification directory, it ensures that all changes follow a consistent review process aligned with the project's constitution.

• Automatically infers change types (security, composition, infrastructure, or platform) based on description keywords like 'KCL', 'RBAC', 'VPC', or 'Karpenter'.

• Generates standardized artifact structures including spec.md, plan.md, and clarifications.md based on pre-defined SDD templates.

• Facilitates multi-persona reviews (PM, Security, SRE, Platform) to minimize post-implementation rework and technical debt.

• Integrates with lifecycle management commands like /clarify for resolving ambiguities, /validate for quality gate checks, and /create-pr for seamless GitOps transitions.

• Provides a clear migration path from design to execution by transitioning issue labels from spec:draft to spec:implementing.

• Use this skill for significant architectural shifts, multi-component platform features, or changes that require pre-implementation sign-off.

• Avoid using this for trivial tasks like version bumps, documentation-only updates, or minor Helm value tweaks.

• When the inferred type is inaccurate, users can override it by providing an explicit type (e.g., /spec security '...' or /spec infrastructure '...') before the description.

• The skill creates artifacts within the docs/specs/ structure and maps to existing GitHub workflows, ensuring all changes remain fully traceable via Flux and GitOps principles.

• Always refer to the generated spec.md file to fill in technical details, mark requirements needing clarification, and verify compliance with the platform's zero-trust and GitOps-first requirements.