Objective

Adopt repository-level specs with github/spec-kit and define a version-controlled action update workflow using pinned action SHAs.

Current Limitation

We currently do not have a repository-wide spec-kit baseline for specs, and action references for published action versions are often managed through moving branches/refs, which increases version drift and review ambiguity.

Proposed Work

• Evaluate and integrate github/spec-kit in dev-tools so repository specs can be generated/managed from resources/github-actions, workflow surfaces, and relevant contributor docs.
• Use/borrow skill structure from dceoy/speckit-agent-skills to bootstrap how specs and checks are authored and applied.
• Introduce a dedicated versioning policy for actions published/consumed here: prefer SHA-pinned refs over branch refs for automation and production usage.
• Add a new skill/subagent for action add/update operations that enforces pinned hash usage and documents required update steps.
• Update this new skill/subagent guidance to include: every new or updated action in this repo must update the pinned hash and any associated lock-like reference notes.
• As a transition, include a migration list for existing action references that still point to branch-based versions.

Scope

• In-scope: spec-kit introduction strategy, docs/tooling guidance, action pinning strategy, and action lifecycle subagent/skill.
• In-scope: include a migration path for branch-based refs in action surfaces managed by this repo.
• Out-of-scope: full migration of all historical workflows outside this repository.

Non-goals

• Do not mandate changing all third-party action references globally in one commit.
• Do not replace existing action semantics; only versioning and spec-driven governance.

Acceptance Criteria

Functional Criteria

• github/spec-kit integration path is defined with concrete docs and command examples for this repo.
• The action/versioning workflow requires or documents SHA-based references when adding/updating actions.
• A subagent/skill exists (or is planned with explicit issue plan) to guide action add/update with pinned references.
• A short migration list is captured for current non-pinned action refs.
• Existing action behavior compatibility remains documented when branch refs are kept during rollout.

Architectural / Isolation Criteria

• MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
• MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
• MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
• MUST: The design MUST allow future extraction or reuse with minimal changes.
• MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.
• MUST: Document why this should be treated as a governance change tied to action publication safety.

Related work

• Related to existing action refactor discussions in this repo, especially issue Define release-safe refs for consumer workflow wrappers and checked-out actions #238 (release-safe refs for consumer workflow wrappers and checked-out actions).