fix(workflows): remove unavailable core-profile handoffs

[clay-good]

Status

LGTM after hardening at 03631d8d5. All CI checks pass, including Linux, macOS, Windows, security, and CodeRabbit. Maintainer review remains a merge gate; this PR is not merged.

What was wrong

Core installs neither continue nor new, but update/apply handoffs still named them. The CLI's runtime apply instructions also recommended the missing continue skill, including when planning was complete but its tracking file was missing or empty.

Fixes #1734. Follows up on #963 and #919's default-profile acceptance criteria. Preserves the existing #913 archive/sync dependency and #1409 profile-aware console guidance.

How it was fixed

• Replace optional handoffs with concept-based guidance and existing CLI commands: status / instructions for missing artifacts, new change for distinct intent.
• Put recovery at the failure point, preserve the selected store, and keep update planning-only.
• Remove unavailable workflow recommendations from runtime JSON and text output. Distinguish missing artifacts from tracking-file repair, where no artifact may be ready. Preserve the schema's full tracking path.
• Regenerate the two affected distributed skills and parity hashes; include a patch changeset.

This follows PR #726's decision 9. No new transformer, CLI command, dependency, core workflow, schema field, or artifact-graph behavior. Task parsing, readiness, progress, and completion calculations are unchanged.

Replication / proof

• Reported reference counts on main: update → continue 5, update → new 2, apply → continue 1. All become 0.
• Original regression set: 215 failures / 429 cases on unchanged main. Hardening additionally reproduces 5 runtime recovery failures on the original PR head and 2 false negatives in the test reference guard.
• Coverage includes all skill-capable tools (including global-only MiniMax), delivery modes, core/full custom/update-only/archive+sync profiles, fresh init, stale refresh, and profile switching.
• Custom-schema CLI cases cover local/store scope, missing artifacts, missing/empty/text-less tracking, read-only instructions, preserved plans, and blocked → ready → all-done transitions.
• CI run: 4,677 tests pass on both Linux and macOS; Windows has 4,610 passed, 67 platform skips. All required checks pass.
• 555 focused local tests pass, as do build, lint, source/changed-test type checks, changeset validation, and deterministic regeneration.
• Three subagents reviewed workflow semantics, tests, and Cloud warnings. The follow-up semantic review is LGTM.

Notes / nits

• fix(update): close the dead end for partially populated glob artifacts #1733 remains separate: no expansion of update's write targets or partially populated glob semantics. Its eventual textual merge must preserve both fixes.
• Refactor skill packaging so optional workflows do not break default experiences #919's broader packaging discussion remains open; this does not promise every optional-only custom combination is dependency-free.
• Cloud warnings on the initial head cited unchanged baseline code/specs, not introduced drift. No unrelated repairs were added.
• Tests verify emitted guidance and CLI contracts, not an agent executing prose. Local tests isolate global skill discovery and shell settings. A parallel rerun was terminated with exit 137; the serial run had 4,676 passes and one failure in the unchanged binary version-probe test. That entire file passed on isolated rerun (48 tests). Neither local run is represented as a full pass; the complete cross-platform CI results above are green.

Summary by CodeRabbit

• Workflow Improvements

  • Streamlined update and apply guidance by removing optional workflow handoffs.
  • Added clear CLI-based recovery steps for missing or blocked artifacts.
  • Preserved store selection when checking status and retrieving instructions.
  • Intent changes now direct users to create a new change explicitly.
  • Improved tracking-file recovery when planning is complete.

• Bug Fixes

  • Improved workflow guidance consistency across generated profiles and tools.
  • Prevented references to workflows that are not installed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f32c36b5-7bee-4dd6-bf73-15031d19048b

📥 Commits

Reviewing files that changed from the base of the PR and between 728b94d and 03631d8.

📒 Files selected for processing (8)

• .changeset/fix-core-workflow-handoffs.md
• skills/openspec-apply-change/SKILL.md
• src/commands/workflow/instructions.ts
• src/core/templates/workflows/apply-change.ts
• test/commands/profile-handoffs.test.ts
• test/core/templates/profile-handoffs.test.ts
• test/core/templates/skill-templates-parity.test.ts
• test/utils/command-references.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/fix-core-workflow-handoffs.md

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The update and apply workflows no longer reference optional workflow handoffs. Missing artifacts and tracking files now use direct CLI recovery guidance. Tests cover generated references, profile transitions, CLI recovery, and updated template hashes.

Core workflow handoffs

Layer / File(s)	Summary
CLI recovery guidance src/core/templates/workflows/*.ts, src/commands/workflow/instructions.ts, skills/openspec-*-change/SKILL.md, .changeset/fix-core-workflow-handoffs.md	Workflow guidance now directs missing-artifact and tracking-file recovery through status and instructions commands. Intent changes use openspec new change.
Profile-generated reference validation test/commands/profile-handoffs.test.ts, test/core/templates/profile-handoffs.test.ts	Tests verify that generated content references only installed workflows and that local and store-scoped CLI recovery works.
Template regression coverage test/core/templates/update-change.test.ts, test/utils/command-references.test.ts, test/core/init.test.ts, test/core/templates/skill-templates-parity.test.ts	Tests assert the removed handoffs, new CLI guidance, and refreshed template hashes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 03631

This PR redirects workflow guidance to existing commands without adding new dependencies, permissions, or state-changing behavior. No actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant Workflow
  participant OpenSpecCLI
  participant Schema
  Workflow->>OpenSpecCLI: Request status for the change
  OpenSpecCLI->>Schema: Resolve artifact rules and tracking configuration
  Schema-->>OpenSpecCLI: Return instructions and template
  OpenSpecCLI-->>Workflow: Return recovery guidance

Loading

Suggested reviewers: tabishb, alfred-openspec

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 9 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue [#1734]. Core-profile update and apply workflows no longer reference unavailable handoff workflows. They provide CLI-based recovery guidance and add profile-aware regression …
Out of Scope Changes check	✅ Passed	The changes remain within scope. They update workflow guidance, runtime instructions, generated-content tests, parity hashes, and the related patch changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: removing unavailable handoffs from core-profile workflows.

Full details: Linked Issues check

Explanation

The changes satisfy issue [#1734]. Core-profile update and apply workflows no longer reference unavailable handoff workflows. They provide CLI-based recovery guidance and add profile-aware regression coverage.

Full details: Docstring Coverage

Explanation

Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 9 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-core-workflow-handoffs-1734

---

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.}

[openspec-cloud]

▶ View full results and scan again

🔎 11 requirements drifted — 7 pointing at code, 4 at stale specs.

AI-generated · A citation proves the line exists, not that it makes the case — verify before acting.

On 728b94d; 2 requirements could not be verified — not a clean result.

🔴 Apply Instructions Command — code is wrong · high

Expected — openspec/specs/cli-artifact-workflow/spec.md:214

The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.

Observed — src/commands/workflow/instructions.ts:388

const tracksFile = applyConfig?.tracks ?? null;
First observed in retained OpenSpec Cloud history — 728b94d in PR #1735.

Next → fix the code at src/commands/workflow/instructions.ts:388 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

Agent prompt

Update the implementation starting at src/commands/workflow/instructions.ts:388 so it satisfies the requirement in openspec/specs/cli-artifact-workflow/spec.md (line 214). Add or update a regression check for that behavior. Do not edit the requirement or any specification file.

🔴 Archive Command Argument Support — code is wrong · high

Expected — openspec/specs/cli-update/spec.md:155

The archive slash command template SHALL support optional change ID arguments for tools that support `$ARGUMENTS` placeholder.

Observed — src/core/command-generation/adapters/opencode.ts:30

* Frontmatter: description. $ARGUMENTS is injected after the complete input
First observed in retained OpenSpec Cloud history — 728b94d in PR #1735.

Next → fix the code at src/core/command-generation/adapters/opencode.ts:30 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

Agent prompt

Update the implementation starting at src/core/command-generation/adapters/opencode.ts:30 so it satisfies the requirement in openspec/specs/cli-update/spec.md (line 155). Add or update a regression check for that behavior. Do not edit the requirement or any specification file.

🔴 Slash Command Updates — code is wrong · high

Expected — openspec/specs/cli-update/spec.md:52

The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.

Observed — src/core/command-generation/adapters/opencode.ts:30

* Frontmatter: description. $ARGUMENTS is injected after the complete input
First observed in retained OpenSpec Cloud history — 728b94d in PR #1735.

Next → fix the code at src/core/command-generation/adapters/opencode.ts:30 so it satisfies the requirement.
Protect the fix: add a regression check and link it from this requirement.

Agent prompt

Update the implementation starting at src/core/command-generation/adapters/opencode.ts:30 so it satisfies the requirement in openspec/specs/cli-update/spec.md (line 52). Add or update a regression check for that behavior. Do not edit the requirement or any specification file.

8 more findings are in the full check.

View results · Click Refresh, then Scan again in the check. Or comment /openspec-cloud.