Repair Tool Surfaces After an Upgrade
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
When you upgrade Spec Kitty, or clone a project fresh, the per-tool files that let your coding assistant find Spec Kitty commands and agent profiles can be missing, partial, or drifted. This guide explains the three terms you will see in diagnostics — Tool, Agent, and Tool Surface — and shows you how to repair the generated surfaces with a single command.
Tool vs Agent vs Tool Surface
These three words look interchangeable but mean different things in Spec Kitty. Getting them straight makes the diagnostics readable.
-
Tool — the coding assistant you run Spec Kitty through: Claude Code, Codex CLI, Cursor, Copilot, Gemini, and the rest of the supported set. A tool is the integration target. You choose your tools with
spec-kitty agent config addand list them withspec-kitty agent config list. -
Agent — a role/persona that does work inside a mission, such as an implementer, a reviewer, or an architect. Agents are defined by agent-profile doctrine, not by your editor. One tool (say, Claude Code) executes many different agents over the life of a mission. “Agent” answers who is acting; “tool” answers which assistant is running it.
-
Tool Surface — a concrete file (or set of files) that Spec Kitty generates for a tool so that tool can discover commands and agent profiles. Examples are the command-skill files a skill-based tool reads and the agent profile files a command-based tool reads. Each tool surface is derived from a registered path pattern in the Tool Surface Contract, so the diagnostics can tell exactly which surface is missing or has drifted.
In short: a tool consumes tool surfaces in order to run agents.
When you need this guide
Run the repair flow whenever any of these are true:
- You just ran
spec-kitty upgradeand your assistant stopped seeing Spec Kitty commands or skills. - You cloned a project fresh and the per-tool surfaces were never generated locally.
spec-kitty doctorreports missing, stale, or drifted command-skill or agent-profile files.
Step 1 — Diagnose the surfaces
Ask the doctor what is missing before changing anything:
spec-kitty doctor tool-surfaces --jsonThe report lists, per configured tool, which surfaces are present, which are missing (gaps), which are stale, and which have drifted from their generated form. Read the gaps and drift entries first — they tell you whether a repair will simply regenerate files or whether you have hand-edited a managed file.
To narrow the report to a single kind or a single tool:
spec-kitty doctor tool-surfaces --kind command-skill --jsonspec-kitty doctor tool-surfaces --tool codex --jsonStep 2 — Repair the surfaces
When the report shows gaps or stale entries, regenerate them:
spec-kitty doctor tool-surfaces --fixThe --fix flag regenerates the missing and stale surfaces for every tool in
your project’s agent configuration. It is safe and conservative:
- It only touches surfaces that Spec Kitty manages.
- It refuses to overwrite a managed file that you have edited (reported as drift) — resolve the edit first, then re-run.
- It refuses to act when a managed surface path resolves outside the project (reported as unsafe).
- It leaves files it does not own alone.
A repair that cannot complete is reported, never silent. doctor tool-surfaces --fix
prints a Failed to repair: line listing each surface it could not repair and the
reason, and exits non-zero; the JSON output carries the same ids in repair.failed
and the causes in repair.findings_after. A clean repair prints
Repaired: N surface(s) and exits 0.
Plugin bundles follow the same rule per distribution target. A project that
configures more than one assistant stages all three bundles, each from its own
native renderings (Claude profiles and skills for the Claude bundle, Copilot or
VS Code renderings for theirs, the shared .agents/skills rendering for skills);
a Codex TOML agent profile is never renamed into a Markdown bundle member.
spec-kitty upgrade uses the same owner assessments in its finalizer. Inspect
them without writing via spec-kitty upgrade --plan-json: effects are exact
owned writes, while dispositions explain unchanged, preserved,
consent-required, or inapplicable paths. Supporting manifests and parent
directories appear as effects rather than hidden side effects. Global roots are
independent of --no-worktrees; that option excludes worktree discovery and
repair only. An incomplete required owner blocks apply instead of becoming an
empty successful plan.
If the report flagged drift or unsafe paths, the repair will decline and tell
you why. Reconcile those entries by hand, then run --fix again.
Step 3 — Confirm the repair
Re-run the diagnostic and confirm the report is clean:
spec-kitty doctor tool-surfaces --jsonWhen ok is true and there are no gaps, your tools can find Spec Kitty’s
commands and agent profiles again.
Related repair commands
- Command-skill drift only:
spec-kitty doctor skills --fixtargets the skill-based tools (Codex, Vibe, Pi, Letta) specifically. - Whole-installation problems: see Diagnose Installation Problems.
- Upgrading the project after a CLI upgrade: see Upgrade a Project.
Notes
- These surfaces are generated. Do not hand-edit the per-tool files — edit the
doctrine sources and regenerate. Hand edits are exactly what the drift guard
protects you from clobbering, and they will block
--fixuntil reconciled. - The set of tools the repair acts on is your project’s configured tool set
(
spec-kitty agent config list). Adding or removing a tool changes which surfaces are generated.