<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/guides/how-to/installation/tool-surface-upgrade-and-repair/">
  <id>https://docs.spec-kitty.ai/guides/how-to/installation/tool-surface-upgrade-and-repair/</id>
  <title>Repair Tool Surfaces After an Upgrade</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/guides/how-to/installation/tool-surface-upgrade-and-repair/"/>
  <summary>How to understand the Tool vs Agent vs Tool Surface distinction in Spec Kitty 3.2 and repair missing generated surfaces with doctor tool-surfaces --fix after upgrading.</summary>
  <content type="html">&lt;span id=&quot;repair-tool-surfaces-after-an-upgrade&quot;&gt;&lt;/span&gt;
&lt;p&gt;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 — &lt;strong&gt;Tool&lt;/strong&gt;, &lt;strong&gt;Agent&lt;/strong&gt;, and &lt;strong&gt;Tool Surface&lt;/strong&gt; — and shows you how
to repair the generated surfaces with a single command.&lt;/p&gt;
&lt;h2 id=&quot;tool-vs-agent-vs-tool-surface&quot;&gt;Tool vs Agent vs Tool Surface&lt;/h2&gt;
&lt;p&gt;These three words look interchangeable but mean different things in Spec Kitty.
Getting them straight makes the diagnostics readable.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Tool&lt;/strong&gt; — 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 &lt;em&gt;integration target&lt;/em&gt;. You choose your tools with
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config add&lt;/code&gt; and list them with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config list&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Agent&lt;/strong&gt; — a &lt;em&gt;role/persona&lt;/em&gt; 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 &lt;em&gt;who is acting&lt;/em&gt;;
“tool” answers &lt;em&gt;which assistant is running it&lt;/em&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Tool Surface&lt;/strong&gt; — a concrete file (or set of files) that Spec Kitty
&lt;em&gt;generates for a tool&lt;/em&gt; 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.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;In short: a &lt;strong&gt;tool&lt;/strong&gt; consumes &lt;strong&gt;tool surfaces&lt;/strong&gt; in order to run &lt;strong&gt;agents&lt;/strong&gt;.&lt;/p&gt;
&lt;h2 id=&quot;when-you-need-this-guide&quot;&gt;When you need this guide&lt;/h2&gt;
&lt;p&gt;Run the repair flow whenever any of these are true:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You just ran &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; and your assistant stopped seeing Spec Kitty
commands or skills.&lt;/li&gt;
&lt;li&gt;You cloned a project fresh and the per-tool surfaces were never generated
locally.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt; reports missing, stale, or drifted command-skill or
agent-profile files.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;step-1--diagnose-the-surfaces&quot;&gt;Step 1 — Diagnose the surfaces&lt;/h2&gt;
&lt;p&gt;Ask the doctor what is missing before changing anything:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tool-surfaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The 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.&lt;/p&gt;
&lt;p&gt;To narrow the report to a single kind or a single tool:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tool-surfaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--kind&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;command-skill&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tool-surfaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--tool&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;codex&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;step-2--repair-the-surfaces&quot;&gt;Step 2 — Repair the surfaces&lt;/h2&gt;
&lt;p&gt;When the report shows gaps or stale entries, regenerate them:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tool-surfaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--fix&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; flag regenerates the missing and stale surfaces for every tool in
your project’s agent configuration. It is &lt;strong&gt;safe and conservative&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It only touches surfaces that Spec Kitty manages.&lt;/li&gt;
&lt;li&gt;It refuses to overwrite a managed file that you have edited (reported as
&lt;em&gt;drift&lt;/em&gt;) — resolve the edit first, then re-run.&lt;/li&gt;
&lt;li&gt;It refuses to act when a managed surface path resolves outside the project
(reported as &lt;em&gt;unsafe&lt;/em&gt;).&lt;/li&gt;
&lt;li&gt;It leaves files it does not own alone.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A repair that cannot complete is reported, never silent. &lt;code dir=&quot;auto&quot;&gt;doctor tool-surfaces --fix&lt;/code&gt;
prints a &lt;code dir=&quot;auto&quot;&gt;Failed to repair:&lt;/code&gt; line listing each surface it could not repair and the
reason, and exits non-zero; the JSON output carries the same ids in &lt;code dir=&quot;auto&quot;&gt;repair.failed&lt;/code&gt;
and the causes in &lt;code dir=&quot;auto&quot;&gt;repair.findings_after&lt;/code&gt;. A clean repair prints
&lt;code dir=&quot;auto&quot;&gt;Repaired: N surface(s)&lt;/code&gt; and exits 0.&lt;/p&gt;
&lt;p&gt;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 &lt;code dir=&quot;auto&quot;&gt;.agents/skills&lt;/code&gt; rendering for skills);
a Codex TOML agent profile is never renamed into a Markdown bundle member.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; uses the same owner assessments in its finalizer. Inspect
them without writing via &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --plan-json&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;effects&lt;/code&gt; are exact
owned writes, while &lt;code dir=&quot;auto&quot;&gt;dispositions&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;--no-worktrees&lt;/code&gt;; that option excludes worktree discovery and
repair only. An incomplete required owner blocks apply instead of becoming an
empty successful plan.&lt;/p&gt;
&lt;p&gt;If the report flagged drift or unsafe paths, the repair will decline and tell
you why. Reconcile those entries by hand, then run &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; again.&lt;/p&gt;
&lt;h2 id=&quot;step-3--confirm-the-repair&quot;&gt;Step 3 — Confirm the repair&lt;/h2&gt;
&lt;p&gt;Re-run the diagnostic and confirm the report is clean:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tool-surfaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;When &lt;code dir=&quot;auto&quot;&gt;ok&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;true&lt;/code&gt; and there are no gaps, your tools can find Spec Kitty’s
commands and agent profiles again.&lt;/p&gt;
&lt;h2 id=&quot;related-repair-commands&quot;&gt;Related repair commands&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Command-skill drift only: &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt; targets the
skill-based tools (Codex, Vibe, Pi, Letta) specifically.&lt;/li&gt;
&lt;li&gt;Whole-installation problems: see
&lt;a href=&quot;/guides/how-to/installation/diagnose-installation/&quot;&gt;Diagnose Installation Problems&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Upgrading the project after a CLI upgrade: see
&lt;a href=&quot;/guides/how-to/installation/upgrade-project/&quot;&gt;Upgrade a Project&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;notes&quot;&gt;Notes&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;These surfaces are &lt;em&gt;generated&lt;/em&gt;. 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 &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; until reconciled.&lt;/li&gt;
&lt;li&gt;The set of tools the repair acts on is your project’s configured tool set
(&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config list&lt;/code&gt;). Adding or removing a tool changes which
surfaces are generated.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
