<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-02-2-letta-agent-skill-only-support/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-02-2-letta-agent-skill-only-support/</id>
  <title>Letta agent is skill-only: no slash-command templates, invoker and session model deferred</title>
  <updated>2026-06-02T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-02-2-letta-agent-skill-only-support/"/>
  <summary>Letta ships skill-only because its stateless-versus-sticky memory session model is unvalidated; `.letta/commands/` and LettaInvoker are deferred.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Letta Code (&lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt;) is a memory-first coding agent supporting headless automation via &lt;code dir=&quot;auto&quot;&gt;letta -p&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--output-format json&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;--output-format stream-json&lt;/code&gt;. The design spike (#1054) raised two questions:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Should Letta be skill-only, slash-command-template-based (&lt;code dir=&quot;auto&quot;&gt;.letta/commands/&lt;/code&gt;), orchestrator-enabled, or a combination?&lt;/li&gt;
&lt;li&gt;How should Letta’s persistent memory and long-lived agent/conversation model be handled in repeatable WP cycles — stateless (&lt;code dir=&quot;auto&quot;&gt;--new&lt;/code&gt; flag each run) or sticky (reusing the same agent across WPs)?&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The persistent-memory and session-model question is the distinguishing challenge for Letta compared to stateless agents like codex and pi. The wrong choice here could produce either stale cross-mission memory contamination (sticky) or loss of in-session context (stateless-per-WP).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Letta natively discovers &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; as its preferred skill root; skills are available without additional configuration.&lt;/li&gt;
&lt;li&gt;Letta’s persistent memory model introduces state-management complexity (session identity, memory isolation across missions) that is out of scope for this CLI-layer integration.&lt;/li&gt;
&lt;li&gt;A &lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt; with a validated session model belongs in the external &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; package.&lt;/li&gt;
&lt;li&gt;Generating &lt;code dir=&quot;auto&quot;&gt;.letta/commands/&lt;/code&gt; slash-command templates would require a new migration; the incremental value over skills is unclear given that Letta users can invoke skills directly.&lt;/li&gt;
&lt;li&gt;Shipping a half-validated session model risks cross-mission memory contamination, which is a correctness risk for WP automation.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A:&lt;/strong&gt; Skill-only — &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.*/SKILL.md&lt;/code&gt; only; no &lt;code dir=&quot;auto&quot;&gt;.letta/commands/&lt;/code&gt; templates.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B:&lt;/strong&gt; Skills + slash commands — &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; plus &lt;code dir=&quot;auto&quot;&gt;.letta/commands/spec-kitty.&amp;#x3C;command&gt;.md&lt;/code&gt; generated by a new migration.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C:&lt;/strong&gt; Full support — skills + slash commands + &lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt; with a defined session model (stateless vs. sticky), enabling &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent letta&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option A — skill-only”, because Letta’s persistent memory/conversation model (stateless &lt;code dir=&quot;auto&quot;&gt;--new&lt;/code&gt; vs. sticky agent) introduces complexity that has not been prototyped or validated. Committing to a session model without that validation risks cross-mission memory contamination.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt; and the session-model design are deferred to the external &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; package scope. &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; intentionally does not include &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;No new migration for slash-command templates; Letta users get skills immediately via &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --ai letta&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AGENT_SKILL_CONFIG&lt;/code&gt; includes &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt;, so skill packages are installed and kept in sync.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.letta/&lt;/code&gt; gitignore entry prevents runtime state, authentication tokens, and memory stores from polluting the repository.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config add letta&lt;/code&gt; is fully supported.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent letta&lt;/code&gt; is not supported without &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.letta/commands/&lt;/code&gt; is intentionally absent; Letta users cannot use slash-command-style invocation via spec-kitty.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; does not include &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt; — this is by design, not an oversight.&lt;/li&gt;
&lt;li&gt;The session-model question (stateless vs. sticky) is deferred; a follow-up ADR should be written in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; when a prototype is available.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is correct if Letta users can successfully run Spec Kitty work packages using &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; discovery without errors related to missing slash-command templates. The absence of &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; is confirmed by &lt;code dir=&quot;auto&quot;&gt;test_twelve_agent_parity.py:204&lt;/code&gt;. Cross-mission memory contamination is avoided because no session model is activated at this layer.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a--skill-only&quot;&gt;Option A — Skill-only&lt;/h3&gt;
&lt;p&gt;Skills only; Letta reads &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.*/SKILL.md&lt;/code&gt; natively.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero new migrations needed.&lt;/li&gt;
&lt;li&gt;Immediate value: skills install on &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --ai letta&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;No risk of cross-mission memory contamination from an unvalidated session model.&lt;/li&gt;
&lt;li&gt;Consistent pattern with codex and pi integration.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No slash-command surface for Letta users who prefer that interaction style.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent letta&lt;/code&gt; remains unsupported until &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; adds &lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b--skills--slash-commands&quot;&gt;Option B — Skills + slash commands&lt;/h3&gt;
&lt;p&gt;Skills plus &lt;code dir=&quot;auto&quot;&gt;.letta/commands/&lt;/code&gt; generated via a new migration.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Users who prefer slash-command invocation can use that surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires a new migration for a surface whose value is unproven.&lt;/li&gt;
&lt;li&gt;Does not address the session-model question; persistent memory still requires a separate design decision.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-c--full-support&quot;&gt;Option C — Full support&lt;/h3&gt;
&lt;p&gt;Skills + slash commands + &lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt; with session model.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Complete first-class integration; &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent letta&lt;/code&gt; works.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;LettaInvoker&lt;/code&gt; belongs in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;, not in this CLI package.&lt;/li&gt;
&lt;li&gt;Session model (stateless vs. sticky) is unvalidated; incorrect choice risks cross-mission memory contamination.&lt;/li&gt;
&lt;li&gt;Largest scope; highest risk.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Implementation evidence: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/config.py:85&lt;/code&gt; shows &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;AGENT_SKILL_CONFIG&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_twelve_agent_parity.py:204&lt;/code&gt; confirms &lt;code dir=&quot;auto&quot;&gt;letta&lt;/code&gt; absent from &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Related ADR: &lt;a href=&quot;/adr/3.x/2026-06-02-1-pi-agent-skill-only-support/&quot;&gt;2026-06-02-1-pi-agent-skill-only-support.md&lt;/a&gt; — same pattern applied to Pi.&lt;/li&gt;
&lt;li&gt;Tests: &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/test_init_pi_letta.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/test_agent_config_pi_letta.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Deferred design question tracked in &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1054&quot;&gt;GitHub #1054&lt;/a&gt; until resolved.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
