<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/</id>
  <title>ADR: the Team Kitty surfaces are hidden unless hosted drain is on</title>
  <updated>2026-10-14T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-06-1-team-kitty-surfaces-are-hidden-unless-drain-is-on/"/>
  <summary>Team Kitty is no longer supported: the spk-team-* skills are retired and its six CLI entries are hidden from listings unless the hosted drain posture is on.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted. &lt;strong&gt;Amended 2026-10-12&lt;/strong&gt; — the “do not build toward Team Kitty” rule is
&lt;strong&gt;scoped-lifted&lt;/strong&gt;: consumer-side UI/multiplayer built on the Mission Status Read API, and the
event-dispatch / produce-drain adapter seam (&lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;), are no longer blocked.
Everything else hosted (zeitgeist auth, the hosted backend, the SaaS surface) stays frozen
unless the operator asks. The original decision below (hidden hosted CLI surfaces, retired
&lt;code dir=&quot;auto&quot;&gt;spk-team-*&lt;/code&gt; skills) is unchanged. See “Amendment 2026-10-12” at the end.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-06 (amended 2026-10-12)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (repository owner).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; the 4.0.0 &lt;a href=&quot;/changelog/4.0.0/&quot;&gt;direction amendment&lt;/a&gt; (2026-10-01) froze Team Kitty / SaaS work; this record takes the step from “frozen” to “no longer actively supported” for the surfaces the CLI ships.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing the root command registration, the shipped skill pack, the generated CLI reference, or anything under the hosted drain posture.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Team Kitty is the hosted collaboration product: the SaaS authenticates a team member and mints a capability, and the CLI publishes each status moment to the team’s Zeitgeist relay. Since 2026-10-01 nothing hosted gates 4.0.0 GA. This record ends active support.&lt;/p&gt;
&lt;p&gt;Hosted interaction is already off by default (&lt;a href=&quot;/adr/3.x/2026-09-26-3-hosted-interaction-opt-in/&quot;&gt;ADR 2026-09-26-3&lt;/a&gt;), behind two gates. Moments, Live Work and the relay commands need the drain posture (&lt;code dir=&quot;auto&quot;&gt;specify_cli.core.hosted_posture&lt;/code&gt;): &lt;code dir=&quot;auto&quot;&gt;hosted.drain&lt;/code&gt; in the repository’s &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;[hosted] drain&lt;/code&gt; in the personal &lt;code dir=&quot;auto&quot;&gt;config.toml&lt;/code&gt; must both be true, and no environment variable can turn it on. Authentication and the SaaS-backed tracker calls need a configured endpoint (&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;config.toml [sync].server_url&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;specify_cli.auth.server_target&lt;/code&gt;). Neither ships configured.&lt;/p&gt;
&lt;p&gt;What still pointed at Team Kitty was the guidance:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Four shipped skills, &lt;code dir=&quot;auto&quot;&gt;spk-team-auth&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spk-team-sync&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spk-team-tracker&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spk-team-connectors&lt;/code&gt;, were installed into every configured agent’s skill root. &lt;code dir=&quot;auto&quot;&gt;spk-start-here&lt;/code&gt; routed “team, SaaS, tracker, or sync” questions to them, and three of them told the agent that hosted mode “is already on” and explained the residue variable &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;, which does not gate the moment path.&lt;/li&gt;
&lt;li&gt;Six top-level CLI entries that only serve the hosted surface were listed in &lt;code dir=&quot;auto&quot;&gt;spec-kitty --help&lt;/code&gt;, in shell completion and in the generated CLI reference: &lt;code dir=&quot;auto&quot;&gt;auth&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;issue-search&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;live-work&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;moments&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;routes&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;zeitgeist&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A user or an agent harness reading either surface was steered toward an offering that is not supported.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The four &lt;code dir=&quot;auto&quot;&gt;spk-team-*&lt;/code&gt; skills are retired.&lt;/strong&gt; Their sources are deleted and their names join &lt;code dir=&quot;auto&quot;&gt;RETIRED_CANONICAL_SKILL_NAMES&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;specify_cli.skills.retired&lt;/code&gt;), so the existing installers remove the copies Spec Kitty installed and preserve any unproven custom skill. The skill-selection lines that named them are removed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The six hosted entries register hidden.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;register_commands&lt;/code&gt; marks every entry named in &lt;code dir=&quot;auto&quot;&gt;_HOSTED_SURFACE_NAMES&lt;/code&gt; hidden on the full and the single-command registration paths. The &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;live-work hook&lt;/code&gt; fast paths skip it; neither renders the root listing. Each one still runs when invoked by name, so a script or an operator who knows the command is not broken.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;They are listed again only when drain is on.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;reveal_hosted_surfaces&lt;/code&gt;, called from the CLI entry point’s app assembly, unhides them when &lt;code dir=&quot;auto&quot;&gt;hosted_posture.drain_posture()&lt;/code&gt; is enabled for the current checkout. It reads the posture only when argv does not resolve to one top-level command, because only the root listing reads the flag; a normal command invocation pays no extra config read. An unparseable posture file is treated as off, as the hosted edges treat it, and its warning is not printed on the root listing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Generated artifacts describe the default posture.&lt;/strong&gt; The completion manifest and &lt;code dir=&quot;auto&quot;&gt;docs/api/cli-commands.md&lt;/code&gt; are built from the registration tree without the reveal, so they are deterministic and record the six entries as hidden whatever the generating machine’s drain posture is. The CLI reference walker (&lt;code dir=&quot;auto&quot;&gt;scripts/docs/_typer_walker.py&lt;/code&gt;) now counts a path under a hidden group as hidden, since &lt;code dir=&quot;auto&quot;&gt;--help&lt;/code&gt; never lists it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt; stays visible.&lt;/strong&gt; It also serves the local providers (&lt;code dir=&quot;auto&quot;&gt;beads&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;fp&lt;/code&gt;), which need no SaaS. Its help no longer sends SaaS-backed providers to &lt;code dir=&quot;auto&quot;&gt;auth login&lt;/code&gt;; it says they need a Team Kitty sign-in, which is not supported.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Gate visibility on the drain posture (chosen).&lt;/strong&gt; Drain is the opt-in for the moment and relay edges, it is off by default and no environment variable can enable it, so the default listing is clean and a checkout that opted in still sees what it opted into. The endpoint opt-in that gates &lt;code dir=&quot;auto&quot;&gt;auth&lt;/code&gt; is weaker, because an environment variable can supply it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Gate visibility on &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;.&lt;/strong&gt; Rejected. It is residue of the retired sync transport and defaults to on since the #3980 launch defaults, so the surfaces would stay listed for everyone.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Hide unconditionally.&lt;/strong&gt; Rejected. An operator who turned drain on deliberately would lose discoverability of the commands that drive it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Remove the hosted command groups.&lt;/strong&gt; Rejected for now. The relay client and the moment path are still wired to the status pipeline behind the drain gate, and removing the commands is a larger change than the support decision requires.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;With the default posture, &lt;code dir=&quot;auto&quot;&gt;spec-kitty --help&lt;/code&gt;, shell completion and the CLI reference no longer offer the hosted entries; an agent loading the shipped skills is no longer routed to Team Kitty.&lt;/li&gt;
&lt;li&gt;The reveal depends on the live posture, so with drain on the root listing shows the six entries while completion (served from the committed manifest) does not. Completion describes the default posture by design.&lt;/li&gt;
&lt;li&gt;Children of groups that were already hidden (for example the deprecated &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; group) leave the main CLI reference body too. That is the walker rule from point 4 applied to every hidden group, not only the hosted ones.&lt;/li&gt;
&lt;li&gt;The visible-path baseline in &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_check_cli_reference_freshness.py&lt;/code&gt; drops from 310 to 252.&lt;/li&gt;
&lt;li&gt;In the charter, the SaaS Docker-mode rules bind only requested hosted work, and the CLI-to-SaaS contract section says no new hosted work starts unasked; a change to the hosted wire surface still updates the contract.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/team-kitty.md&lt;/code&gt; and the 4.0.0 declaration carry the support status.&lt;/li&gt;
&lt;li&gt;Remediation messages on hosted-only paths still name &lt;code dir=&quot;auto&quot;&gt;spec-kitty auth login&lt;/code&gt;, which still runs by name. This is deliberate: a user who reaches a hosted path needs the real command. The sites are &lt;code dir=&quot;auto&quot;&gt;_saas_error_hint&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt; authentication message (~759) in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/tracker.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_AUTH_LOGIN_REMEDIATION&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/readiness/render.py&lt;/code&gt;, and the missing-auth remedy in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/saas_readiness.py&lt;/code&gt; (~85).&lt;/li&gt;
&lt;li&gt;Reversible: removing a name from &lt;code dir=&quot;auto&quot;&gt;_HOSTED_SURFACE_NAMES&lt;/code&gt; and from the retired-skill set, and restoring the skill sources, brings a surface back.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-12-accepted-team-kitty-is-multiplayer-mode-the-consumer-side--the-rule-is-scoped-lifted-not-dropped&quot;&gt;Amendment 2026-10-12 (Accepted): Team Kitty is “Multiplayer Mode,” the consumer side — the rule is scoped-lifted, not dropped&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator), 2026-10-12.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Why.&lt;/strong&gt; “Do not build toward Team Kitty” was a blanket freeze. The direction has since
split Team Kitty into a &lt;strong&gt;producer&lt;/strong&gt; and a &lt;strong&gt;consumer&lt;/strong&gt; side. The producer side — the
Mission Status Read API (&lt;a href=&quot;/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction/&quot;&gt;ADR 2026-10-01-2&lt;/a&gt;,
Accepted) — is open-core and is being built now. Team Kitty is the &lt;strong&gt;consumer&lt;/strong&gt; side, now
framed as &lt;strong&gt;“Multiplayer Mode”:&lt;/strong&gt; the UI/multiplayer surfaces (mission-ui, the pack composer) that &lt;em&gt;consume&lt;/em&gt; the open-core API across its contract boundary. Blocking
all consumer work no longer matches the direction, so the freeze is scoped, not kept whole.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What changes.&lt;/strong&gt; The standing “do not build toward Team Kitty” rule (charter; &lt;code dir=&quot;auto&quot;&gt;AGENTS.md&lt;/code&gt;
Team Kitty section) is &lt;strong&gt;scoped-lifted&lt;/strong&gt;. It no longer blocks:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Consumer-side UI/multiplayer built on the Mission Status Read API.&lt;/strong&gt; A UI or multiplayer
surface that reads the open-core producer API across its public contract (never reaching
into CLI internals) is permitted work.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The event-dispatch / produce-drain adapter seam&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/adapters.py&lt;/code&gt;).
The produce/drain decoupling (its own 4.x ADR, roadmap next step) and the adapter seam as a
publish/subscribe surface are permitted work. Producing an event never depends on whether a
drain is enabled.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;What stays frozen.&lt;/strong&gt; Everything else hosted stays frozen unless the operator asks for it:
zeitgeist auth, the hosted &lt;strong&gt;backend&lt;/strong&gt;, and the hosted SaaS surface. The original decision in
this ADR is &lt;strong&gt;unchanged&lt;/strong&gt;: the six hosted CLI entries still register hidden unless drain is on,
the &lt;code dir=&quot;auto&quot;&gt;spk-team-*&lt;/code&gt; skills stay retired, and nothing hosted ships configured. This amendment lifts
a &lt;em&gt;build-toward&lt;/em&gt; prohibition for two consumer/seam carve-outs; it does not turn any hosted
runtime edge on, and it does not re-list the hidden CLI surfaces.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Consequences.&lt;/strong&gt; Consumer-side Multiplayer-Mode work and the adapter seam can proceed against
the open-core contract. The hosted backend surfaces remain dormant and off by default. The
charter and &lt;code dir=&quot;auto&quot;&gt;AGENTS.md&lt;/code&gt; Team Kitty sections are updated to this scoped producer-API-vs-
consumer-UI model; on any conflict the charter wins.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-10-14&quot;&gt;Amendment 2026-10-14&lt;/h2&gt;
&lt;p&gt;Amendment 2026-10-14: the hosted surfaces this ADR fences were removed from open-core by #6164; the code is preserved in spec-kitty/event-router.&lt;/p&gt;</content>
</entry>
