feat(cli): Add taskless onboard subcommand for post-install rule discovery

[thecodedrift]

Add a post-install discovery flow that helps a fresh Taskless user go from zero rules to a useful starter set. Implements the add-onboard-command OpenSpec change end-to-end (5 spec deltas: new cli-onboard capability + modifications to cli-help, cli-init, cli-taskless-bootstrap, and skill-taskless).

taskless init already gets users installed — but until now there was no path between "installed" and "actively producing rules from real codebase signal." First-time users typically don't know what kinds of patterns Taskless is well-suited to capture, what sources to mine for candidates, or how to prioritize them. This change closes that gap.

What's in the change

• taskless onboard subcommand with three modes: default prints an agent-facing recipe (refused if already complete), --force re-runs regardless of state, --mark-complete writes install.onboarded: true. The recipe is conversational by design — it asks the user which sources to scan (codebase TODOs/FIXMEs, agent-memory files, recent PR comments via gh, issue tracker via MCP, plus user-suggested sources), probes tool availability before promising scans, filters for high-signal candidates (repeated patterns, cited docs, merge-blocking feedback), and outputs a bullet list of <kebab-name>: <description> the user can materialize one by one via taskless rule create.
• 3-state install.onboarded manifest field (absent / false / true). Only the agent writes it, and only after explicit user confirmation per the recipe — taskless init never touches it. writeInstallState was updated to preserve the flag across re-installs (otherwise init/update would silently clobber it).
• Conditional post-install trailer: after a successful taskless init, prints a one-line trailer pointing the user at the new flow. Wording adapts to the install plan — when commands were installed (Claude Code, Cursor) the trailer mentions /tskl onboard, the Taskless skill, and the bare CLI; when no commands were installed (OpenCode, Codex, .agents/ fallback) it mentions only the skill and the CLI.
• Skill description trigger expanded: the consolidated taskless skill now also volunteers Taskless when the user asks to add/write/create a rule and has NOT named a specific lint/format/static-analysis tool. Suppressing examples (illustrative — any named tool of this kind suppresses): eslint, ruff, biome, ast-grep. Behavior on this trigger is a quiet single-line offer, not a full recipe; declines are sticky within the conversation only and never written to disk. This intentionally reverses a prior deliberate narrowing — see the design doc for the tradeoff.
• Recipe substitution refactor (sprintf-js): in support of the new subcommand sharing the renderer with the help command, recipe substitution moved from ad-hoc {{KEY}} replaceAll calls to sprintf-js named arguments. All 15 recipes migrated to %(KEY)s syntax. PACKAGE_MANAGER_DLX joins CLI_VERSION and INPUT_SCHEMA in the variable table as an explicit "agent-fill" marker rendered as <package-manager-dlx> (was previously left literal as {{PACKAGE_MANAGER_DLX}} — the new marker is more self-documenting).

Where to focus review

• packages/cli/src/commands/onboard.ts — the new subcommand. The --force --mark-complete rejection and the manifest preservation in --mark-complete mode are the spots to scrutinize.
• packages/cli/src/install/state.ts — the small but load-bearing change that makes re-installs preserve install.onboarded. Without this, taskless update after onboarding would silently wipe the flag.
• packages/cli/src/commands/help.ts — renderRecipe now uses sprintf-js. Worth confirming the PACKAGE_MANAGER_DLX → <package-manager-dlx> translation reads naturally in ci.txt.
• skills/taskless/SKILL.md — the description trigger is widening. The previous spec explicitly told the agent NOT to trigger on generic linting requests; this PR replaces that with named-tool suppression and a quiet-suggestion behavior. If real-world feedback shows the trigger feels spammy, the description can be re-narrowed in a follow-up without changing the rest.
• openspec/changes/add-onboard-command/design.md — six decisions with rationale, including why the gate lives in the CLI (not the recipe), why onboarded is a boolean (not a richer enum), and why the recipe is conversational (not a fixed phase script).

Release

A minor changeset for @taskless/cli is queued at .changeset/onboard-command.md. Release tooling rolls it into the next published version.

Refs the add-onboard-command OpenSpec change.

[Copilot]

Pull request overview

Adds a post-install onboarding flow to the Taskless CLI and skill ecosystem so new users can discover high-signal starter rules from real repo signals, while also refactoring recipe rendering to a single sprintf-js–based interpolator shared across help and onboard.

Changes:

• Introduces taskless onboard (with --force and --mark-complete) plus a new embedded help onboard recipe and manifest flag install.onboarded.
• Refactors recipe interpolation from {{KEY}} placeholders to sprintf-js named args (%(KEY)s) and adds <package-manager-dlx> agent-fill rendering.
• Adds a post-install “Next: … onboard” trailer to successful taskless init paths and expands the consolidated taskless skill triggers + routing guidance.

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/taskless/SKILL.md	Expands trigger guidance and adds routing + “quiet suggestion” behavior for generic rule requests.
pnpm-lock.yaml	Locks new sprintf-js and @types/sprintf-js dependencies.
packages/cli/test/onboard.test.ts	Adds coverage for gating/force/mark-complete behaviors and recipe parity with help onboard.
packages/cli/test/init-no-interactive.test.ts	Asserts init trailer wording and onboarded-flag preservation on reinstall.
packages/cli/test/help-extensions.test.ts	Updates interpolation tests for new %(KEY)s syntax and <package-manager-dlx> rendering.
packages/cli/src/wizard/index.ts	Prints onboarding trailer after successful wizard installs.
packages/cli/src/install/state.ts	Preserves install.onboarded across reinstalls when writing install state.
packages/cli/src/index.ts	Registers the new onboard subcommand.
packages/cli/src/help/update.txt	Migrates recipe placeholders to %(CLI_VERSION)s.
packages/cli/src/help/rule.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/rule-verify.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/rule-meta.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/rule-improve.txt	Migrates placeholders to %(CLI_VERSION)s / %(INPUT_SCHEMA)s.
packages/cli/src/help/rule-improve.anonymous.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/rule-delete.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/rule-create.txt	Migrates placeholders to %(CLI_VERSION)s / %(INPUT_SCHEMA)s.
packages/cli/src/help/rule-create.anonymous.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/onboard.txt	Adds the new conversational onboarding recipe.
packages/cli/src/help/init.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/info.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/ci.txt	Migrates placeholders to sprintf-js and documents <package-manager-dlx> substitution.
packages/cli/src/help/check.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/help/auth.txt	Migrates header placeholder to %(CLI_VERSION)s.
packages/cli/src/filesystem/migrate.ts	Extends manifest typing with install.onboarded?: boolean.
packages/cli/src/commands/onboard.ts	Implements taskless onboard, gating, mark-complete writes, telemetry, and shared trailer text.
packages/cli/src/commands/init.ts	Prints onboarding trailer after successful non-interactive init and threads commandsInstalled.
packages/cli/src/commands/help.ts	Switches recipe rendering to sprintf-js and exports getRecipe.
packages/cli/README.md	Documents the new taskless onboard command and semantics.
packages/cli/package.json	Adds sprintf-js and its types.
openspec/changes/add-onboard-command/tasks.md	Tracks implementation checklist for the OpenSpec change.
openspec/changes/add-onboard-command/specs/skill-taskless/spec.md	Specifies updated skill trigger and quiet-suggestion behavior requirements.
openspec/changes/add-onboard-command/specs/cli-taskless-bootstrap/spec.md	Specifies manifest schema + 3-state semantics for install.onboarded.
openspec/changes/add-onboard-command/specs/cli-onboard/spec.md	Specifies the onboard subcommand contract and telemetry.
openspec/changes/add-onboard-command/specs/cli-init/spec.md	Specifies init trailer behavior and wording rules.
openspec/changes/add-onboard-command/specs/cli-help/spec.md	Specifies sprintf-js placeholder conventions and onboard topic registration.
openspec/changes/add-onboard-command/proposal.md	Describes rationale/impact of the onboard feature and associated changes.
openspec/changes/add-onboard-command/design.md	Captures key design decisions and trade-offs.
openspec/changes/add-onboard-command/.openspec.yaml	Declares the OpenSpec change metadata.
.changeset/onboard-command.md	Declares a minor release for @taskless/cli including onboard + sprintf refactor.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

packages/cli/src/help/rule.txt:7

• rule.txt doesn’t follow the canonical recipe section structure (it has ## Subcommands but no ## Preconditions, ## Steps, or ## Errors). Since this PR updates the help-file templating/spec to standardize sections, either add the missing sections here (even if brief) or explicitly document/encode an exception for “router” topics like rule.

---

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

[Copilot]

Pull request overview

Copilot reviewed 44 out of 45 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported