<?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-04-19-2-ticket-delivery-is-cli-plumbing-specification-is-llm-content/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-19-2-ticket-delivery-is-cli-plumbing-specification-is-llm-content/</id>
  <title>Ticket Delivery Is CLI Plumbing; Specification Is LLM Content</title>
  <updated>2026-04-19T00: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-04-19-2-ticket-delivery-is-cli-plumbing-specification-is-llm-content/"/>
  <summary>Creating a mission from a tracker ticket only fetches context and registers a pending origin record, then hands off; the CLI never writes specification prose.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket linear:PRI-42&lt;/code&gt; command must do two distinct
things:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Fetch an external tracker ticket and make its content available&lt;/strong&gt; so an LLM
agent can write a mission specification from it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Establish a durable mission-origin link&lt;/strong&gt; between the external ticket and the
resulting mission so SaaS can route lifecycle egress (status updates, comments)
back to the originating issue.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The question is where the boundary falls: how much of the work belongs to the
CLI, and how much belongs to the LLM?&lt;/p&gt;
&lt;h3 id=&quot;the-wrong-answer&quot;&gt;The wrong answer&lt;/h3&gt;
&lt;p&gt;A naive implementation would make the CLI do everything: fetch the ticket, parse
its content, scaffold a mission directory, fill in a spec template from the ticket
fields, register the origin, and post a backlink comment. The LLM would be
bypassed entirely.&lt;/p&gt;
&lt;p&gt;This is wrong for several reasons:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Ticket bodies contain requirements phrasing, implicit constraints, stakeholder
context, and edge cases that a template filler cannot reason over. The LLM
produces a better spec by reading the real content than by consuming an
auto-generated summary.&lt;/li&gt;
&lt;li&gt;It violates the established principle from
&lt;code dir=&quot;auto&quot;&gt;2026-03-09-1-prompts-do-not-discover-context-commands-do.md&lt;/code&gt;: commands own
execution context and plumbing; LLMs own content reasoning. A command that
writes spec content is inverting that boundary.&lt;/li&gt;
&lt;li&gt;It makes the flow provider-specific in ways that are hard to generalise: ticket
schema differences across Linear, Jira, GitHub Issues, and GitLab Issues should
not influence what the LLM sees. The CLI normalises; the LLM reasons.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;the-right-answer&quot;&gt;The right answer&lt;/h3&gt;
&lt;p&gt;The CLI does exactly and only the plumbing:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Fetch and normalise the ticket into a local context file.&lt;/li&gt;
&lt;li&gt;Register a pending mission origin on SaaS.&lt;/li&gt;
&lt;li&gt;Hand off to the LLM with a clear instruction.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The LLM does exactly and only the content work:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Read the ticket context file.&lt;/li&gt;
&lt;li&gt;Run &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; to produce the mission specification.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The CLI then finalises the mission-origin link once the mission exists.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;LLM specification quality&lt;/strong&gt; — free-form reasoning over raw ticket content
produces better specs than template substitution.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Principle of least knowledge&lt;/strong&gt; — the CLI should not know how to interpret
ticket requirements; the LLM should not know how to call SaaS APIs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consistency with established ADRs&lt;/strong&gt; — this decision follows directly from
&lt;code dir=&quot;auto&quot;&gt;2026-03-09-1&lt;/code&gt; (commands do context, prompts do not) and
&lt;code dir=&quot;auto&quot;&gt;2026-04-04-1&lt;/code&gt; (binding context is discovered, not user-supplied).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Provider neutrality&lt;/strong&gt; — the ticket normalisation layer in the CLI means the
LLM sees the same context shape regardless of whether the ticket came from
Linear, Jira, GitHub Issues, or GitLab.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Backlink correctness&lt;/strong&gt; — the SaaS backlink comment should only be posted after
a mission actually exists. Posting it before &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; runs creates phantom links
if the user abandons the session.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core decision&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket &amp;#x3C;provider:ID&gt;&lt;/code&gt; is a CLI plumbing command. It MUST
NOT write mission specification content. It MUST hand off to the LLM.&lt;/p&gt;
&lt;h3 id=&quot;responsibilities&quot;&gt;Responsibilities&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;CLI (&lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket&lt;/code&gt;):&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;Fetch the ticket via SaaS → normalise to a local context file at
&lt;code dir=&quot;auto&quot;&gt;.kittify/ticket-context.md&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Register a pending mission-origin record on SaaS, associating the ticket with
this repo and assigning a provisional &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;. This record is &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt;
until a mission is confirmed to exist.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Write the pending &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt; to local tracker config so
&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; can read them without re-fetching.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Print a handoff message and exit 0:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&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:#d6deeb;--1:#403f53&quot;&gt;Ticket PRI-42 fetched → .kittify/ticket-context.md&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:#d6deeb;--1:#403f53&quot;&gt;Mission origin registered (pending): 01KPXXXXXX&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;/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:#d6deeb;--1:#403f53&quot;&gt;Run /spec-kitty.specify to create the mission from this ticket.&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:#d6deeb;--1:#403f53&quot;&gt;The mission will be linked to PRI-42 automatically on completion.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;LLM (via &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;):&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Detect the presence of &lt;code dir=&quot;auto&quot;&gt;.kittify/ticket-context.md&lt;/code&gt; and treat it as the
mission brief.&lt;/li&gt;
&lt;li&gt;Read the full ticket content — title, body, labels, comments — as written to
&lt;code dir=&quot;auto&quot;&gt;.kittify/ticket-context.md&lt;/code&gt; by the CLI (the context file includes labels and
comments in addition to the standard fields) and produce a spec from it using
normal specification reasoning.&lt;/li&gt;
&lt;li&gt;On completion, call the mission origin finalisation surface (exact command name
to be determined by sk#695 implementation; the current placeholder is
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission finalize-origin&lt;/code&gt;) to confirm the mission and trigger
SaaS finalisation.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;SaaS (on mission confirmation):&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Promote the pending mission-origin record to confirmed.&lt;/li&gt;
&lt;li&gt;Post a backlink comment on the originating ticket referencing the confirmed
mission.&lt;/li&gt;
&lt;li&gt;Begin routing lifecycle egress events to the ticket.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;invariants&quot;&gt;Invariants&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The CLI MUST NOT write to any file under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;. That directory is
owned by the specify/plan/tasks pipeline.&lt;/li&gt;
&lt;li&gt;The CLI MUST NOT post a backlink comment before the mission is confirmed.
Abandoned specify runs MUST NOT leave comments on tracker issues.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; MUST treat &lt;code dir=&quot;auto&quot;&gt;.kittify/ticket-context.md&lt;/code&gt; as optional
context, not a required input. The specify flow must work without it.&lt;/li&gt;
&lt;li&gt;The SaaS provisional record ID assigned at &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; time MUST be the
same one promoted to confirmed when the mission is finalised. This is a
SaaS-internal record ID, not the spec-kitty mission ULID (as defined in
&lt;code dir=&quot;auto&quot;&gt;2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix.md&lt;/code&gt;); the two
namespaces are separate. The CLI MUST NOT allow a second &lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket&lt;/code&gt; on the same ticket to create a duplicate pending record
while one is already active. Deduplication is checked against the local
&lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; state first; if local state is absent, the CLI queries SaaS to
confirm no active pending record exists for that ticket ID and repo.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Spec quality reflects the LLM’s reasoning over the full ticket, not a
template.&lt;/li&gt;
&lt;li&gt;The same CLI surface works unchanged for Linear, Jira, GitHub Issues, and
GitLab Issues.&lt;/li&gt;
&lt;li&gt;No phantom backlink comments from abandoned sessions.&lt;/li&gt;
&lt;li&gt;The boundary between CLI plumbing and LLM content is explicit and testable.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The flow is two-step from the user’s perspective: run the command, then run
&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;. A user who runs the command and walks away will have a
dangling pending origin record that must be cleaned up.&lt;/li&gt;
&lt;li&gt;The CLI must implement a pending-origin TTL or explicit cancel path to prevent
orphaned records accumulating on SaaS. The specific TTL value and cancel
interface are deferred to sk#695; a provisional default of 7 days is assumed
until that implementation decides otherwise.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The ticket context file is a normalised Markdown document. Its schema is
intentionally simple: a heading, standard fields (status, assignee, URL), the
raw body, labels (as a comma-separated list), and any comments appended in
chronological order. The LLM is not constrained to a fixed template.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty mission create --from-ticket linear:PRI-42&lt;/code&gt; exits 0 without
writing anything under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/ticket-context.md&lt;/code&gt; contains the full ticket body in a form the LLM
can reason over.&lt;/li&gt;
&lt;li&gt;Running &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; after the command produces a spec that
demonstrably reflects the ticket content, not a generic template.&lt;/li&gt;
&lt;li&gt;The Linear ticket receives a backlink comment only after specify completes and
a mission directory exists.&lt;/li&gt;
&lt;li&gt;Running the command twice on the same ticket does not produce two pending
origin records or two backlink comments.&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id=&quot;related-adrs&quot;&gt;Related ADRs&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/adrs/2026-03-09-1-prompts-do-not-discover-context-commands-do.md&lt;/code&gt; — the parent
principle: commands own execution context, LLMs own content reasoning. This ADR
applies that principle to the ticket-to-mission surface.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-04-1-tracker-binding-context-is-discovered-not-user-supplied.md&lt;/code&gt; —
establishes that binding uses discovered context, not user-typed metadata.
&lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket&lt;/code&gt; is the user-facing entry point into that
discovery model at mission-origin time.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-27-2-host-owned-tracker-persistence-boundary.md&lt;/code&gt; — tracker state lives
in the host control plane. The pending/confirmed mission-origin lifecycle is
SaaS-owned, consistent with that boundary.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related-issues&quot;&gt;Related Issues&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;sk#695 — implementation tracking for &lt;code dir=&quot;auto&quot;&gt;mission create --from-ticket&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;saas#79 — mission-origin E2E validation&lt;/li&gt;
&lt;li&gt;saas#74 — terminal-state policy (what the CLI does to the ticket on mission completion; a separate decision)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
