chore(speckit): upgrade Spec Kit to 1.2.5 and opsmill-speckit to 1.4.1

Merged
PO
11d ago
+3752-9179

What changed

Upgrades Spec Kit from 0.11.9 to 1.2.5 and opsmill-speckit from 1.1.0 to 1.4.1, following its upgrade steps. Task 2.9 of the migration plan.

Changes to the spec-kit setup

  • The spec-kit commands become skills with hyphenated names: /speckit-opsmill-auto replaces /speckit.opsmill.auto.
  • The review extension is removed, because it does not install on Spec Kit 1.x. The review step now uses the pr-review-toolkit plugin, or /code-review when the plugin is not installed.
  • The checkpoint extension, the critique-opsmill preset and the jira-branch preset are added.
  • The agent-context extension is disabled, so /speckit-specify and /speckit-plan no longer update CLAUDE.md.

Changes to the repository setup

  • Ruff no longer checks .specify/, which holds Python code from spec-kit.
  • The Claude Code and Codex hooks that opsmill-speckit 1.4.1 ships point spec-kit at the project's Python environment, which provides PyYAML. .claude/settings.json and .codex/hooks.json run them from .specify/extensions/opsmill/scripts/.

Alternatives considered:

  • Static path in the agent settings -> breaks when a script runs outside the repository root.
  • direnv -> every developer must install and allow it.
  • Python of the specify CLI -> its path differs on each machine.
  • PyYAML in the system Python -> PEP 668 blocks it on Homebrew and Debian.
  • Patch to the spec-kit scripts -> the next upgrade overwrites it.
  • Upstream fix (github/spec-kit#4674, #4884) -> not released yet.

How to set up/maintain

What the next Spec Kit or opsmill-speckit upgrade overwrites

  • The rule against citing line numbers in plans and tasks, added in #10421, is restored by hand in the speckit-plan and speckit-tasks skills.
  • The next upgrade regenerates these skills and removes the rule again. opsmill/opsmill-speckit#35 tracks keeping the rule across upgrades for every repository.
  • The routing of error handling conventions to dev/guidelines/backend/exceptions.md in the speckit-opsmill-extract skill, also added in #10421, is restored by hand as well. opsmill/opsmill-speckit#45 asks opsmill-speckit to carry it for every repository.

Steps for each developer after the merge

  • In Codex: trust the project hooks, so that the spec-kit scripts run with the project's Python.
  • Optional: install the pr-review-toolkit plugin for a full review.
  • Optional, only to manage extensions: upgrade the specify CLI to 1.2.5.

How to review

Review commit by commit. Most of the diff is in the second commit, and Spec Kit generated it.

  1. Exclude the vendored spec-kit scripts from ruff and ty: read it all. It adds .specify to the ruff and ty exclusions, in pyproject.toml, in CI and in the invoke tasks.
  2. Upgrade Spec Kit to 1.2.5 and opsmill-speckit to 1.4.1: ignore .specify/, .agents/skills/, .github/agents/ and .github/prompts/, which the upgrade generated or removed.
  3. Name .specify in the ruff and ty scope of invoke: read AGENTS.md.
  4. Run the spec-kit scripts with the project's Python: read the entries in .claude/settings.json and .codex/hooks.json. opsmill/opsmill-speckit#39 reviewed the hooks they run.
  5. Disable the agent-context extension: read it all. It sets the extension and its hooks to disabled in .specify/.
  6. Restore the infrahub routing in the extract skill: read it all. It restores the changes from #10421 that the upgrade removed.

Testing

Claude Code

  • A fresh checkout of this branch, set up with the project's virtual environment and without any spec-kit environment variables, ran /speckit-opsmill-auto on a test feature.
  • Every phase completed, from branch creation to the implementation report, with the review step run by /code-review.
  • The plan and tasks scripts ran with the project's Python, which the session start hook provides.

Codex

  • Ran /speckit-opsmill-auto on a fake greeting feature in a fresh worktree; specification, planning, critique, tasks, implementation, and review completed. The fallback review found no issues.
  • uv run pytest backend/tests/unit/core/test_format_smoke_greeting.py -q: 3 passed. Ruff formatting and lint passed.
  • setup-plan.sh and setup-tasks.sh passed from dev/specs through the Codex wrapper, using the project's .venv.
  • Codex skipped the project PreToolUse hook in the untrusted checkout; running setup-tasks.sh without the wrapper failed because system Python lacks PyYAML. Trust the project before using its hooks.

opsmill-speckit 1.4.1 hooks

  • The runs above used earlier copies of the hooks in .agents/hooks/. On this branch, the hooks that opsmill-speckit 1.4.1 ships set the project's Python for a Claude Code session, and rerouted setup-plan.sh for Codex.

šŸ¤– Generated with Claude Code