feat(cli): Canonical install store with per-tool reference stubs

[thecodedrift]

Replace the per-tool full-copy install model with a single canonical store plus thin reference stubs. taskless init/update now writes the skill and command content exactly once — to .taskless/skills/<name>/SKILL.md and .taskless/commands/tskl/<name>.md — and drops a small delegating stub into each enabled tool directory (.claude/, .cursor/, .opencode/, .agents/).

Why

The old model wrote a full identical copy of every skill into each detected tool's directory. N tools meant N copies that drift and churn PR diffs. A customer standardizing on a shared skill hit the deeper flaw: the model conflated where content lives with where tools read it. Codex's install directory is .agents, so the Codex target's rm -rf cleanup destroyed the directory other targets pointed into — symlinks broke update, and wrapper files were clobbered with full copies.

Putting the canonical content in .taskless/ — a directory no tool target ever installs into or cleans up — makes that whole class of bug structurally impossible. Each tool directory holds only a featherweight stub, so there is one source of truth and no drift.

What changed

• Canonical store: full skill/command content written once to .taskless/skills/ and .taskless/commands/.
• Reference stubs: each enabled tool directory gets an ordinary file (never a symlink) with name/description frontmatter, a metadata: { type: shim, version } marker, and a body that delegates to the canonical file. .claude/ and .cursor/ also get a tskl command stub.
• Per-target mode (canonical | reference) in .taskless/taskless.json — additive and backward-compatible (absent reads as canonical).
• Self-healing applyInstallPlan: rewrites any reference file that is not a current shim stub — a full copy from an older install, a symlink, or a drifted stub — converging stale layouts on the next init/update. The destructive rm -rf glob cleanup is gone.
• Wizard: the location step is reframed as "which tools do you want to enable Taskless for?".

Approach notes

• No symlinks — symlink-based skill discovery is unreliable across Cursor, OpenCode, and Codex (open upstream bugs) and breaks on Windows checkout. Stubs are ordinary files.
• No migration — convergence is handled by self-healing applyInstallPlan rather than a .taskless/ schema migration. A migration would form an import cycle through install.ts/state.ts/migrate.ts and would run on every ensureTasklessDirectory call (including taskless check).

Review focus

• packages/cli/src/install/install.ts — the install-plan model and applyInstallPlan.
• packages/cli/src/install/canonical.ts — canonical writes, stub builders, drift/shim detection.

Full design and the synced cli-init spec are in openspec/changes/archive/2026-05-17-cli-canonical-install/.

A redundant-info/checkStaleness follow-up is filed as OSS-9.

Refs OSS-8

[Copilot]

Pull request overview

Replaces the per-tool full-copy install model with a single canonical store (.taskless/skills/, .taskless/commands/) plus thin reference stubs in each enabled tool directory. This fixes a destructive-cleanup bug where Codex's .agents/ target's rm -rf could wipe content other targets pointed into, and ends the N-identical-copies drift problem.

Changes:

• Introduces canonical store under .taskless/ with new canonical.ts (writes + stub builders + shim detection) and adds a per-target mode (canonical | reference) to the manifest (legacy entries default to canonical).
• Refactors applyInstallPlan to be mode-aware and self-healing: rewrites any reference file that isn't a current shim stub (full copies, symlinks, or drifted stubs), and scopes manifest-driven cleanup to each target's own directory so it can never reach .taskless/.
• Reframes the wizard's location step as a tool-selection multiselect over a fixed catalog (SHIM_TARGETS), removes AGENTS_FALLBACK plumbing and installForTool, and updates init/update non-interactive flow and help text accordingly.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/cli/src/install/install.ts	Adds canonical/reference plan model, mode-aware writes, self-healing reference rewrite, removes glob cleanup and AGENTS_FALLBACK
packages/cli/src/install/canonical.ts	New module: canonical write helpers, skill/command stub builders, shim detection, drift checks
packages/cli/src/install/state.ts	Adds InstallMode, plumbs mode through state read/write and diff
packages/cli/src/filesystem/migrate.ts	Adds optional mode field to manifest target type
packages/cli/src/filesystem/migrations/0001-init.ts	Adds README entries for skills/ and commands/ canonical dirs
packages/cli/src/wizard/steps/locations.ts	Refactors to pure locationChoices over SHIM_TARGETS; new prompt wording
packages/cli/src/wizard/index.ts	Switches to buildInstallPlan / planToStateTargets; drops TOOL_BY_INSTALL_DIR
packages/cli/src/commands/init.ts	Non-interactive flow uses new plan model + per-target summary with mode-aware noun
packages/cli/src/help/init.txt, update.txt	Doc updates for canonical-plus-stub model
packages/cli/README.md, .taskless/README.md	User-facing docs for new layout
packages/cli/test/* (apply-install-plan, install, install-state, migrate-install, canonical-store, wizard-steps)	Rewrites/adds tests for canonical writes, stubs, drift, symlink/full-copy convergence, mode round-trip, migration matrix
.changeset/canonical-install.md	Minor changeset documenting the new install model
openspec/changes/archive/2026-05-17-cli-canonical-install/* + openspec/specs/cli-init/spec.md	Archived change proposal/design/tasks and synced spec
.claude/settings.json	Adds WebSearch permission (unrelated)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.