fix(templates): replace Claude-only TodoWrite instruction with a generic todo list

[clay-good]

Status: Ready for review. CI green on all platforms; CodeRabbit reviewed with no actionable comments. Full suite: 2,027 passed; the only local failures are the 17 known environment-only ZshInstaller tests (#1321, fixed separately in #1400).

What was wrong

The generated openspec-propose and openspec-ff-change skills (and their /opsx:propose / /opsx:ff commands) instructed agents to "Use the TodoWrite tool to track progress through the artifacts." TodoWrite is a Claude Code-specific tool — the same templates generate commands for every supported tool, so Codex, Cursor, Gemini, Copilot, and the rest were told to use a tool they don't have. Reported in #643 (and TodoWrite is one of the unsupported references reported for Codex in #1103); the maintainer note on #643 already pointed the way: "this instruction probably needs to be generic anyways."

How it was fixed

The instruction is now runtime-neutral:

-   Use the **TodoWrite tool** to track progress through the artifacts.
+   Use a todo list to track progress through the artifacts.

Applied to all 4 template sites (propose + ff-change, skill and command variants), with the static skills/ copies regenerated via npm run generate:skills and the golden hashes in skill-templates-parity.test.ts updated. Tools with a native todo mechanism (Claude Code) still use it; tools without one track progress however they normally would. No behavior, CLI, or schema changes.

Proof

End-to-end from the built CLI (init --tools claude,codex,cursor, plus a custom-profile run that installs the ff workflow), then inspecting every generated asset:

$ grep -rn "TodoWrite" <project>          # → no matches
$ grep -c "Use a todo list to track progress through the artifacts" ...
.claude/commands/opsx/ff.md:1
.claude/skills/openspec-ff-change/SKILL.md:1
.codex/skills/openspec-ff-change/SKILL.md:1
.cursor/commands/opsx-ff.md:1
.cursor/skills/openspec-ff-change/SKILL.md:1

(Same result for the propose assets across all three tools.)

• grep -rn "TodoWrite" src/ skills/ test/ docs/ → no matches after the change.
• test/core/templates/ (parity + skills.sh parity + generator guards): 20/20 pass.
• Full suite: 2,027 passed (only the pre-existing ZshInstaller tests fail on machines with a real Oh My Zsh install (17/50 failures) #1321 environment failures remain).

Notes

• Scoped strictly to what fast forward command instructs to use TodoWrite tool but claude no longer has it #643 reports. The AskUserQuestion references in the same templates are the subject of Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103/fix(codex): rewrite unsupported tool references #1133 (Codex adapter-level rewriting) and are deliberately not touched here — no conflict with that PR, which doesn't modify these template files.

Fixes #643

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Propose and fast-forward workflow instructions now use generic todo lists instead of the Claude-specific TodoWrite tool. Corresponding generated skill content, parity hashes, and the package patch changeset were updated.

Changes

Runtime-neutral todo tracking

Layer / File(s)	Summary
Update propose and fast-forward instructions src/core/templates/workflows/*, skills/openspec-*-change/SKILL.md, skills/openspec-propose/SKILL.md	Replaces TodoWrite references with generic todo-list progress tracking in propose and fast-forward templates and skills.
Refresh parity checks and release metadata test/core/templates/skill-templates-parity.test.ts, .changeset/generic-todo-tracking.md	Updates template and generated-skill hash baselines and adds a patch changeset describing the wording changes.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Fission-AI/OpenSpec#448: Also updates fast-forward skill and command template content.
• Fission-AI/OpenSpec#1368: Modifies the same workflow templates and parity hash baselines.

Suggested reviewers: tabishb, alfred-openspec

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The templates and generated skill copies were updated to remove TodoWrite references, matching issue #643's requirement.
Out of Scope Changes check	✅ Passed	The hash/test updates and regenerated skill files are supporting changes for the template text edits and do not appear unrelated.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: replacing the Claude-only TodoWrite instruction with a runtime-neutral todo list in templates.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/generic-todo-tracking

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[alfred-openspec]

All four generated workflow variants now use runtime-neutral todo guidance, the checked-in skills regenerate cleanly, and no TodoWrite references remain. Exact-head build, 20 template/parity tests, CodeRabbit, and the full cross-platform matrix passed.