fix(cli): finish the help → agent rename

[thecodedrift]

taskless help <topic> became taskless agent <topic> in #102, but the rename stopped at the command. The specs, the capability name, the source directory, the telemetry event, and the shipped skill files all still said help. This finishes it.

Four layers

Layer	Change
Spec prose and invocations	~30 edits across 8 spec files
Capability	openspec/specs/cli-help/ → cli-agent/, plus 2 cross-references
Source directory	packages/cli/src/help/ → src/agent/ (20 recipes), 4 referencing files
Telemetry	cli_help → cli_agent, 5 call sites

Not a substitution. Topics also became single tokens in #102, so taskless help rule create is taskless agent route in one place (the authoring front door) and taskless agent create-sg-rule in another (a real fetch, not the multi-positional error path) — read individually rather than swept. Every topic name written was confirmed against a real packages/cli/src/agent/<topic>.txt.

A shipped artifact was telling agents to run a command that does not exist

Outside the four layers, and the reason this is a fix rather than a docs change: skills/taskless/SKILL.md and commands/tskl/tskl.md — the skill files installed into user projects — still instructed agents to run npx @taskless/cli help <topic> with topics that were removed (rule create, static, existing). README.md carried 4 more.

No released version is affected. npm has 0.10.2, which predates the rename, so its CLI and its skill files agree. The breakage exists only on unreleased main, and 0.11.0 ships the agent command and the corrected skill together — so it self-corrects on the first update.

Nothing caught it. recipe-cross-references.test.ts guards exactly this class of defect — a shipped artifact naming a dead topic — for recipes, and the guard does not extend to the skill files. Left as-is deliberately: asserting on markdown contents costs more than it catches.

Telemetry is a hard cut

cli_help → cli_agent, no dual-emit. agent.ts carried a comment explaining that the event name deliberately stayed cli_help; that decision is reversed and the comment now records the reversal rather than contradicting the code. Dashboards keyed on cli_help need updating — the same note the 0.10.0 CHANGELOG made for its rename.

Residual help, all correct

Negative assertions in cli-agent/spec.md that taskless help is gone, the test that enforces them, prose naming the pre-rename event, and CHANGELOG.md / openspec/changes/archive/** / pending changesets — all history or deliberate. Untouched.

Verification

pnpm lint clean · pnpm typecheck 1/1 · pnpm test 602 passing · openspec validate --all --strict 23/0 (spec/cli-agent present, no cli-help)

Built binary re-checked after the directory rename, since import.meta.glob("../help/*.txt") is the piece most likely to break silently: agent check returns real content, agent route and the bare agent index both serve.

git status shows 24 renames as R, not delete+add.

Not fixed

.conventions/posthog.md documents an event table (cli_help_auth, cli_rule_create, …) that is entirely pre-0.10.0 taxonomy — every row was already wrong before this change. Rewriting it against the current scheme is a separate change, not a rename.

Fixes #107

[Copilot]

Pull request overview

Completes the help → agent rename across the Taskless CLI ecosystem so the command surface, embedded recipe directory, exported prompt API, OpenSpec docs, shipped skill artifacts, tests, and telemetry all consistently use agent (including the cli_agent intent event).

Changes:

• Update shipped skill/router docs (skills/taskless, /tskl, README) to fetch recipes via npx @taskless/cli agent <topic> and use the new single-token topic names.
• Move/standardize the embedded recipe directory and prompt embedding to packages/cli/src/agent, updating tests and OpenSpec references accordingly.
• Rename intent telemetry from cli_help to cli_agent and update/extend telemetry regression tests.

Reviewed changes

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

Show a summary per file

File	Description
skills/taskless/SKILL.md	Updates the shipped skill router to fetch via agent and lists new topic names.
README.md	Updates repository docs to reflect src/agent/ and agent <topic> usage.
packages/cli/test/recipe-cross-references.test.ts	Updates recipe directory lookup from src/help → src/agent and validates cross-references.
packages/cli/test/prompts.test.ts	Updates tests to read recipe topics from src/agent.
packages/cli/test/agent-telemetry.test.ts	Updates assertions for cli_agent capture and expands legacy-event scanning.
packages/cli/test/agent-routing-telemetry.test.ts	Updates routing telemetry expectations from cli_help → cli_agent.
packages/cli/test/agent-extensions.test.ts	Minor refactor + keeps coverage for agent topic resolution and anonymous variant fallback.
packages/cli/src/telemetry-run.ts	Updates docs for cli_run.command derivation to reference cli_agent.
packages/cli/src/prompts/recipes.ts	Renames embedding/lookup to use ../agent/*.txt and renames internal maps accordingly.
packages/cli/src/prompts/index.ts	Updates public prompt API docs/error strings to reference agent/*.txt.
packages/cli/src/commands/agent.ts	Renames intent telemetry emission from cli_help → cli_agent and updates inline rationale.
packages/cli/src/agent/verify-rule.txt	Adds/updates agent recipe for verify/test by path (engine-agnostic).
packages/cli/src/agent/update.txt	Adds/updates agent recipe for non-interactive skill update flow.
packages/cli/src/agent/rule.txt	Adds/updates umbrella “rule” topic routing to specific rule operations.
packages/cli/src/agent/rule-meta.txt	Adds/updates agent-internal recipe for reading rule metadata via rule meta.
packages/cli/src/agent/route.txt	Adds/updates the canonical routing decision recipe (route).
packages/cli/src/agent/onboard.txt	Adds/updates onboarding discovery recipe (candidate rule mining flow).
packages/cli/src/agent/init.txt	Adds/updates recipe explaining interactive init/wizard and scripted init.
packages/cli/src/agent/info.txt	Adds/updates recipe for state/version/auth inspection via info --json.
packages/cli/src/agent/improve-rule.txt	Adds/updates API-backed improve recipe (rule improve --from ...).
packages/cli/src/agent/improve-rule.anonymous.txt	Adds/updates local-only improve recipe with verify/test feedback loop.
packages/cli/src/agent/detect.txt	Adds/updates recipe for deterministic local detection via detect --json.
packages/cli/src/agent/delete-rule.txt	Adds/updates recipe for local delete flow via rule delete.
packages/cli/src/agent/create-vale-rule.txt	Adds/updates the Vale authoring recipe (scoping, fixtures, verify/test).
packages/cli/src/agent/create-sg-rule.txt	Adds/updates the ast-grep authoring recipe (local-only).
packages/cli/src/agent/create-runtime-rule.txt	Adds/updates logged-out runtime-rule guidance + login gate explanation.
packages/cli/src/agent/create-remote-rule.txt	Adds/updates service-backed rule generation recipe (rule create --from ...).
packages/cli/src/agent/create-legacy-rule.txt	Adds/updates “write it in the repo’s existing linter” recipe.
packages/cli/src/agent/ci.txt	Adds/updates CI wiring recipe, including a GitHub Actions reference template.
packages/cli/src/agent/check.txt	Adds/updates check recipe, including runtime-rule verification/skip semantics.
packages/cli/src/agent/auth.txt	Adds/updates auth management recipe (login/logout/status) and JSON envelope notes.
openspec/specs/skills/spec.md	Updates skills spec text to reference agent command and src/agent recipes.
openspec/specs/skill-taskless/spec.md	Updates Taskless skill spec requirements to use tskl agent <topic>.
openspec/specs/cli/spec.md	Updates CLI spec references from help embedding/registration to agent.
openspec/specs/cli-rules/spec.md	Updates rules spec cross-reference from cli-help → cli-agent.
openspec/specs/cli-onboard/spec.md	Updates onboard spec to reference agent recipes and src/agent/onboard.txt.
openspec/specs/cli-knowledge-prompts/spec.md	Updates knowledge-prompts spec from help/*.txt to agent/*.txt terminology.
openspec/specs/cli-init/spec.md	Updates init spec wording to reference the agent topic index.
openspec/specs/cli-agent/spec.md	Renames/updates the capability spec from “CLI Help” to “CLI Agent”.
openspec/specs/analytics/spec.md	Updates analytics taxonomy/spec scenarios from cli_help → cli_agent.
commands/tskl/tskl.md	Updates /tskl router command to fetch via agent and use new topic names.
.changeset/rename-help-to-agent.md	Adds a changeset describing the rename completion + telemetry hard cut.

Suppressed comments (1)

packages/cli/test/recipe-cross-references.test.ts:59

• The cross-reference check only validates taskless agent <topic> links. The new recipes include npx @taskless/cli agent <topic> references (e.g. route/auth flows), which currently bypass this guard and could drift to dangling topics unnoticed. Extend the regex to also match the npx @taskless/cli... form.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 3m 40s —— View job

---

Review complete

• Gather context (diff, PR description, CLAUDE.md conventions)
• Understand the request (code review of the help→agent rename completion)
• Line-by-line diff review across the four layers (specs, capability, source dir, telemetry) + shipped skill files
• Cross-check topic-name references against real src/agent/*.txt files
• Check telemetry hard-cut for missed call sites
• Post inline comments for concrete issues
• Post final top-level assessment

Overall assessment

This is a clean, well-scoped mechanical rename with unusually thorough self-verification already documented in the PR description. I reviewed all 42 changed files (specs, source, tests, changeset, skill/router docs), traced call sites of the renamed symbols, and grepped the repo for stragglers. Findings:

No correctness bugs found.

• packages/cli/src/prompts/recipes.ts — import.meta.glob("../agent/*.txt", ...) correctly points at the new directory; this was the highest-risk spot (silent breakage if missed) and it's right. Confirmed no other import.meta.glob/hardcoded path in vite.config.ts still points at ../help.
• packages/cli/src/commands/agent.ts — all four telemetry.capture("cli_help", ...) call sites are renamed to cli_agent; the stale "deliberately stayed cli_help" comment is correctly rewritten to record the reversal rather than contradict the code.
• Grepped packages/cli/src and packages/cli/test for cli_help, src/help, and taskless help — the only survivors are deliberate: the historical-rationale comment in agent.ts, the regression-test literals in agent-telemetry.test.ts that assert the absence of the legacy name, and the negative "former command is gone" assertions in cli-agent/spec.md / analytics/spec.md. All consistent with the PR's stated "residual help, all correct" list.
• Spot-checked every topic name introduced into skills/taskless/SKILL.md, commands/tskl/tskl.md, and README.md (route, onboard, improve-rule, delete-rule, check, auth, ci) against real files in packages/cli/src/agent/ — all resolve. Also grepped the recipe bodies themselves for stale invocations of the removed existing/static/remote/engine-selection/rule-create topic names — none found.
• git diff origin/main...HEAD --stat confirms the 24 file moves are tracked as renames (R), matching the PR's claim.

One test-coverage note (posted as an inline comment on packages/cli/test/recipe-cross-references.test.ts:58): the dangling-topic guard's regex only matches the bare taskless agent <topic> phrasing, so it misses the npx @taskless/cli agent <topic> form used in create-runtime-rule.txt:92 and route.txt:125. Both references happen to resolve today, so nothing is broken by this PR, and the regex itself is unchanged (pre-existing, and already flagged by the automated Copilot review) — but it's worth widening in a follow-up since this is exactly the failure class the guard's own doc comment calls out.

No issues with the telemetry hard-cut, the OpenSpec capability rename (cli-help → cli-agent, cross-references in cli-rules/spec.md updated), or the changeset placement (single PR, not stacked, so the changeset-at-the-bottom rule doesn't apply here).
(branch)

[thecodedrift]

Re: @claude[bot] — "Claude finished @thecodedrift's task in 3m 40s —— Review complete…"
#115 (comment)

Addressed the one finding (the dangling-topic guard missing the npx @taskless/cli agent <topic> form) in cac6c99 rather than deferring it to a follow-up — it is a two-line change in a file this PR already touches, and both cited references (create-runtime-rule.txt:92, route.txt:125) confirmed as real bypasses. Everything else in the assessment matches what I verified: the import.meta.glob("../agent/*.txt") path, the four cli_agent call sites, and the residual help survivors are all deliberate.

— AI Coding Agent

[thecodedrift]

Re: @copilot-pull-request-reviewer — "## Pull request overview — Completes the help → agent rename across the Taskless CLI ecosystem…"

The one suppressed comment (recipe-cross-references.test.ts:59 — the cross-reference guard validating only taskless agent <topic> and letting the npx @taskless/cli agent <topic> form bypass it) is fixed in cac6c99. The regex now anchors on either the binary name or the package specifier, so prose uses of the word "agent" still do not register as citations. No other findings to action.

— AI Coding Agent

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 5m 22s —— View job

---

Review complete

• Gather context (diff, PR description, prior reviews, CLAUDE.md conventions)
• Understand the request (re-review after cac6c99 addressed the earlier finding)
• Line-by-line diff review across the four layers (specs, capability, source dir, telemetry) + shipped skill files
• Cross-check topic-name references against real src/agent/*.txt files
• Check telemetry hard-cut for missed call sites
• Post inline comments for concrete issues
• Post final top-level assessment

Overall assessment

This re-review covers the diff as it stands after cac6c99 (the fix for the npx @taskless/cli agent <topic> guard gap raised in the previous pass). I diffed the PR's two commits directly (git diff 5596e39...cac6c99, 42 files / +215/-188, matching the PR stats) and re-verified every layer independently rather than trusting the prior pass's conclusions.

Confirmed correct, independently re-checked:

• packages/cli/src/prompts/recipes.ts — import.meta.glob("../agent/*.txt", …) and the renamed recipeMap/buildRecipeMaps are consistent; no other import.meta.glob or hardcoded path in the package still points at ../help.
• packages/cli/src/commands/agent.ts — all four telemetry.capture(...) sites now emit cli_agent; the stale "deliberately stayed cli_help" comment is rewritten to record the reversal.
• Repo-wide grep for cli-help, cli_help, src/help, helpMap/helpFiles/buildHelpMaps, taskless help — the only survivors are the deliberately-untouched ones the PR calls out (.conventions/posthog.md, CHANGELOG.md, the regression-test literals asserting the absence of the legacy name, and the negative "former command is gone" assertions in specs).
• openspec/specs/cli-rules/spec.md:173 and cli-onboard/spec.md:132 — both cli-help → cli-agent cross-references correctly updated.
• Every topic name introduced into skills/taskless/SKILL.md, commands/tskl/tskl.md, and README.md resolves to a real packages/cli/src/agent/<topic>.txt, including the deliberate divergence the PR calls out (route vs. create-sg-rule for what used to be one rule create phrase) — confirmed no accidental agent rule create-style three-token reference slipped in anywhere.
• The cac6c99 fix itself: the widened regex ((?:taskless|@taskless\/cli) agent <topic>) now catches create-runtime-rule.txt:92 and route.txt:125, and the same widening was correctly applied to the taskless help negative-assertion regex just above it.
• Recipe .txt files are genuinely content-identical renames (+0/-0), so no new dangling references were introduced by this PR in recipe bodies themselves.

New finding this pass — incomplete rename in spec prose (posted inline):

The PR's stated "spec prose and invocations" layer (~30 edits/8 files) missed several spots, concentrated in openspec/specs/cli-knowledge-prompts/spec.md:

• 6 remaining help-named references (lines 13, 50, 74, 83, 137, 142) survive in paragraphs/scenarios where adjacent lines in the same sentence or section were correctly renamed to agent — e.g. L50's scenario heading says "agent command" but its own WHEN clause still says "the help command renders topic T".
• openspec/specs/cli/spec.md:152 — the scenario body was correctly updated to taskless agent, but the heading is still Scenario: Help subcommand is registered, inconsistent with its siblings (Check subcommand is registered, Auth subcommand group is registered, etc.).

These are documentation-only (OpenSpec doesn't semantically validate prose against code, so openspec validate --all --strict passing doesn't catch this), but they directly undercut the PR's claim of a complete, individually-verified sweep, and a stale "help command" reference is exactly the kind of thing that misleads a future reader/agent into believing the removed command still exists.

No other correctness, security, performance, or test-adequacy issues found. The telemetry hard-cut, the OpenSpec capability rename, source-directory move, and shipped skill/router doc updates are otherwise sound and internally consistent.
(branch)