Tool Rename Migration Plan

Status: draft. Scope: docs/design only. No source, prompt, manifest, or test changes were made for this draft.

Goals

Align common file/shell names with Claude-Code-trained expectations without losing SF's DB-backed semantics.
Collapse milestone/slice/task CRUD pairs into lower-schema facades while preserving old names through a compatibility window.
Add lazy loading for uncommon tools without hiding mandatory completion/planning tools from autonomous units.

Phase 1: Add Aliases And Facades

Add aliases and new facades while preserving every old tool name.

Required lockstep files:

src/resources/extensions/sf/extension-manifest.json — add aliases/facades and any lazy: true metadata shape.
src/resources/extensions/sf/bootstrap/db-tools.js — register milestone, slice, task, and requirements facades that delegate to the existing handlers.
src/resources/extensions/sf/bootstrap/exec-tools.js — route run_command compatibility through the canonical shell tool decision; preserve history/search semantics.
src/resources/extensions/sf/bootstrap/dynamic-tools.js — decide whether Bash/Read/Edit/Write are true aliases or prompt-only labels over lowercase tools.
packages/coding-agent/src/core/tools/find.ts and packages/coding-agent/src/core/tools/index.ts — add glob/Glob alias for the existing find implementation if aliases live in core.
packages/coding-agent/src/core/tools/hashline-read.ts, packages/coding-agent/src/core/tools/hashline-edit.ts, packages/coding-agent/src/core/agent-session.ts — fold hashline behavior behind normal read/edit names before retiring hashline_edit registry exposure.
packages/coding-agent/src/core/system-prompt.ts — show canonical names and alias guidance in the Available tools section.
packages/coding-agent/src/core/extensions/types.ts — extend tool metadata if aliases, canonicalName, or lazy are schema-level fields.
packages/coding-agent/src/core/extensions/loader.ts — register aliases without clobbering canonical tools and preserve compatibility metadata.
packages/coding-agent/src/core/tools/tool-compatibility-registry.ts — copy compatibility from canonical names to aliases.
src/resources/extensions/sf/bootstrap/register-hooks.js — update guard lists that check planning/completion tool names.
src/resources/extensions/sf/workflow-reconcile.js and src/resources/extensions/sf/workflow-tools.js — accept both old and facade names for workflow state transitions.
src/headless-ui.ts and src/tests/headless-progress.test.ts — summarize old names and new aliases.
src/resources/extensions/sf/tools/workflow-tool-executors.js — include facade operation names in operation details and errors.
src/resources/extensions/sf/prompts/*.md and src/resources/extensions/sf/skills/**/*.md — do not rewrite yet; only add compatibility notes if needed.

Phase 1 acceptance:

Old prompts continue working unchanged.
New aliases/facades are visible to the model.
Tool execution events record both name and canonicalName where possible.

Phase 2: Deprecation Banners And Prompt Rewrite

Rewrite all SF-authored prompts, skills, and docs to canonical names. Keep old tools registered, but return a short deprecation note in tool output or UI details when an old name is used.

Required lockstep files:

src/resources/extensions/sf/prompts/complete-task.md if present in generated resources, plus src/resources/extensions/sf/prompts/execute-task.md — replace complete_task with task { op: "complete" } after the facade is proven.
src/resources/extensions/sf/prompts/complete-slice.md — replace complete_slice.
src/resources/extensions/sf/prompts/complete-milestone.md — replace complete_milestone.
src/resources/extensions/sf/prompts/plan-milestone.md, guided-plan-milestone.md, discuss.md, discuss-headless.md — replace plan_milestone, new_milestone_id, and follow-on plan_slice language.
src/resources/extensions/sf/prompts/plan-slice.md, guided-plan-slice.md, refine-slice.md — replace plan_slice.
src/resources/extensions/sf/prompts/replan-slice.md — replace replan_slice.
src/resources/extensions/sf/prompts/reassess-roadmap.md, validate-milestone.md — keep milestone_status explicit; replace mutation tools only after the read/write split is clear.
src/resources/extensions/sf/prompts/research-slice.md, research-milestone.md — update forbidden-tool lists.
src/resources/extensions/sf/prompts/autonomous-executor-contract.md and autonomous-solver-contract.md — update mandatory completion/checkpoint language.
src/resources/extensions/sf/bootstrap/system-context.js — update tool guidance and MCP examples without changing MCP names.
src/resources/extensions/sf/skills/**/SKILL.md — sync any tool name examples.
docs/**/*.md user/developer docs that mention old names.
tests/**/*.test.* and src/resources/extensions/sf/tests/**/*.mjs fixtures that assert exact tool names.

Phase 2 acceptance:

Repo prompts no longer teach old names.
Old names still execute and emit deprecation metadata.
Traces, UI, and workflow reconciler show canonical names while preserving old-name audit evidence.

Phase 3: Remove Old Names

Remove old names only after at least one release cycle with clean telemetry and no prompt references.

Required lockstep files:

src/resources/extensions/sf/extension-manifest.json — remove old names and keep canonical facades.
src/resources/extensions/sf/bootstrap/db-tools.js — delete old direct registrations after facade parity.
src/resources/extensions/sf/bootstrap/exec-tools.js — remove run_command only if bash fully preserves context-mode gating, output history, and read_output replacement.
packages/coding-agent/src/core/tools/index.ts and packages/coding-agent/src/core/sdk.ts — remove find/hashline registry aliases only if all supported providers can call the new names.
packages/coding-agent/src/core/system-prompt.ts — remove old-name deprecation language.
src/resources/extensions/sf/bootstrap/register-hooks.js, workflow-reconcile.js, workflow-tools.js, src/headless-ui.ts — remove fallback cases.
tests/**, src/resources/extensions/sf/tests/**, and docs/** — remove old-name fixture allowances.

Phase 3 acceptance:

Forbidden-name guard passes.
No active prompts, skills, docs, tests, or workflow guards reference removed names except in migration docs.
Existing traces remain readable via historical renderer mapping.

CI Guard Design

Add a smoke script such as scripts/check-tool-name-migration.mjs with three modes:

phase1: fail only if a new prompt/doc introduces an old name outside an allowlist.
phase2: fail on old names in src/resources/extensions/sf/prompts/, src/resources/extensions/sf/skills/, docs/user-docs/, and docs/specs/, except migration docs.
phase3: fail on old names anywhere under src/, packages/, tests/, or docs/, except trace-history render maps and explicit migration notes.

Suggested forbidden-name list for phase 2/3:

[
  "run_command",
  "hashline_edit",
  "hashline_read",
  "find",
  "plan_milestone",
  "complete_milestone",
  "validate_milestone",
  "plan_slice",
  "replan_slice",
  "complete_slice",
  "skip_slice",
  "plan_task",
  "complete_task",
  "save_requirement",
  "update_requirement",
  "new_milestone_id"
]

The guard should scan text with token boundaries, report file:line, and require an inline marker such as tool-name-migration-allow for intentional historical mentions.

Risk Assessment

High risks:

Autonomous completion breakage if complete_task is hidden before prompts and post-unit logic move together.
DB-backed planning corruption if plan_milestone, plan_slice, or replan_slice facade schemas are less strict than existing tools.
Shell safety regression if run_command folds into bash without preserving context-mode policy, output retention, and execution-policy classification.
Provider confusion if both lowercase and uppercase aliases are advertised equally; aliases should be compatibility wrappers, not duplicate prompt guidance.

Medium risks:

UI/status regressions where headless-ui and renderers summarize old names.
MCP confusion if mcp_* and mcp__server__tool adapter names are normalized with SF-owned names.
Telemetry/history ambiguity if old and new names are not linked by canonicalName.

Low risks:

Lazy-loading chapter_open, chapter_close, manage_todos, and product-audit tools because they have limited direct prompt exposure.

8.6 KiB Raw Blame History

Tool Rename Migration Plan

Goals

Phase 1: Add Aliases And Facades

Phase 2: Deprecation Banners And Prompt Rewrite

Phase 3: Remove Old Names

CI Guard Design

Risk Assessment

8.6 KiB

Raw Blame History