Skip to content

ADR: the Team Kitty surfaces are hidden unless hosted drain is on

Status: Accepted. Amended 2026-10-12 — the “do not build toward Team Kitty” rule is scoped-lifted: consumer-side UI/multiplayer built on the Mission Status Read API, and the event-dispatch / produce-drain adapter seam (status/adapters.py), 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 spk-team-* skills) is unchanged. See “Amendment 2026-10-12” at the end.

Date: 2026-10-06 (amended 2026-10-12)

Deciders: Stijn Dejongh (repository owner).

Technical Story: the 4.0.0 direction amendment (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.

Reader: a maintainer changing the root command registration, the shipped skill pack, the generated CLI reference, or anything under the hosted drain posture.


Context and Problem Statement

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.

Hosted interaction is already off by default (ADR 2026-09-26-3), behind two gates. Moments, Live Work and the relay commands need the drain posture (specify_cli.core.hosted_posture): hosted.drain in the repository’s .kittify/config.yaml and [hosted] drain in the personal config.toml must both be true, and no environment variable can turn it on. Authentication and the SaaS-backed tracker calls need a configured endpoint (SPEC_KITTY_SAAS_URL or config.toml [sync].server_url, specify_cli.auth.server_target). Neither ships configured.

What still pointed at Team Kitty was the guidance:

  • Four shipped skills, spk-team-auth, spk-team-sync, spk-team-tracker and spk-team-connectors, were installed into every configured agent’s skill root. spk-start-here 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 SPEC_KITTY_ENABLE_SAAS_SYNC, which does not gate the moment path.
  • Six top-level CLI entries that only serve the hosted surface were listed in spec-kitty --help, in shell completion and in the generated CLI reference: auth, issue-search, live-work, moments, routes and zeitgeist.

A user or an agent harness reading either surface was steered toward an offering that is not supported.

Decision

  1. The four spk-team-* skills are retired. Their sources are deleted and their names join RETIRED_CANONICAL_SKILL_NAMES (specify_cli.skills.retired), 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.
  2. The six hosted entries register hidden. register_commands marks every entry named in _HOSTED_SURFACE_NAMES hidden on the full and the single-command registration paths. The next and live-work hook 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.
  3. They are listed again only when drain is on. reveal_hosted_surfaces, called from the CLI entry point’s app assembly, unhides them when hosted_posture.drain_posture() 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.
  4. Generated artifacts describe the default posture. The completion manifest and docs/api/cli-commands.md 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 (scripts/docs/_typer_walker.py) now counts a path under a hidden group as hidden, since --help never lists it.
  5. tracker stays visible. It also serves the local providers (beads, fp), which need no SaaS. Its help no longer sends SaaS-backed providers to auth login; it says they need a Team Kitty sign-in, which is not supported.

Considered Options

  1. Gate visibility on the drain posture (chosen). 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 auth is weaker, because an environment variable can supply it.
  2. Gate visibility on SPEC_KITTY_ENABLE_SAAS_SYNC. 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.
  3. Hide unconditionally. Rejected. An operator who turned drain on deliberately would lose discoverability of the commands that drive it.
  4. Remove the hosted command groups. 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.

Consequences

  • With the default posture, spec-kitty --help, 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.
  • 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.
  • Children of groups that were already hidden (for example the deprecated doctrine 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.
  • The visible-path baseline in tests/docs/test_check_cli_reference_freshness.py drops from 310 to 252.
  • 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.
  • docs/context/team-kitty.md and the 4.0.0 declaration carry the support status.
  • Remediation messages on hosted-only paths still name spec-kitty auth login, which still runs by name. This is deliberate: a user who reaches a hosted path needs the real command. The sites are _saas_error_hint and the tracker authentication message (~759) in src/specify_cli/cli/commands/tracker.py, _AUTH_LOGIN_REMEDIATION in src/specify_cli/readiness/render.py, and the missing-auth remedy in src/specify_cli/tracker/saas_readiness.py (~85).
  • Reversible: removing a name from _HOSTED_SURFACE_NAMES and from the retired-skill set, and restoring the skill sources, brings a surface back.

Amendment 2026-10-12 (Accepted): Team Kitty is “Multiplayer Mode,” the consumer side — the rule is scoped-lifted, not dropped

Deciders: Stijn Dejongh (operator), 2026-10-12.

Why. “Do not build toward Team Kitty” was a blanket freeze. The direction has since split Team Kitty into a producer and a consumer side. The producer side — the Mission Status Read API (ADR 2026-10-01-2, Accepted) — is open-core and is being built now. Team Kitty is the consumer side, now framed as “Multiplayer Mode”: the UI/multiplayer surfaces (mission-ui, the pack composer) that consume 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.

What changes. The standing “do not build toward Team Kitty” rule (charter; AGENTS.md Team Kitty section) is scoped-lifted. It no longer blocks:

  1. Consumer-side UI/multiplayer built on the Mission Status Read API. A UI or multiplayer surface that reads the open-core producer API across its public contract (never reaching into CLI internals) is permitted work.
  2. The event-dispatch / produce-drain adapter seam (src/specify_cli/status/adapters.py). 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.

What stays frozen. Everything else hosted stays frozen unless the operator asks for it: zeitgeist auth, the hosted backend, and the hosted SaaS surface. The original decision in this ADR is unchanged: the six hosted CLI entries still register hidden unless drain is on, the spk-team-* skills stay retired, and nothing hosted ships configured. This amendment lifts a build-toward 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.

Consequences. 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 AGENTS.md Team Kitty sections are updated to this scoped producer-API-vs- consumer-UI model; on any conflict the charter wins.

Amendment 2026-10-14

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.