<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/guides/tutorials/getting-started/">
  <id>https://docs.spec-kitty.ai/guides/tutorials/getting-started/</id>
  <title>Getting Started with Spec Kitty</title>
  <updated>2026-11-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/guides/tutorials/getting-started/"/>
  <summary>Install Spec Kitty 3.2, initialize a project, and create your first mission with a guided beginner workflow.</summary>
  <content type="html">&lt;span id=&quot;getting-started-with-spec-kitty&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Divio type&lt;/strong&gt;: Tutorial&lt;/p&gt;
&lt;p&gt;In this tutorial, you’ll install Spec Kitty and create your first mission specification.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Time&lt;/strong&gt;: ~30 minutes
&lt;strong&gt;Prerequisites&lt;/strong&gt;: Python 3.11+, Git, an AI coding agent (Claude Code, Cursor, Gemini CLI, etc.)&lt;/p&gt;
&lt;p&gt;Getting started with Spec Kitty - Mission Kitty hero&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Stylized splash — the “GET STARTED” lettering is decorative. Install steps and the rest of this tutorial are in the text below; for a dedicated install guide see &lt;a href=&quot;/guides/how-to/installation/install-spec-kitty/&quot;&gt;Install Spec Kitty&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;step-1-install-spec-kitty&quot;&gt;Step 1: Install Spec Kitty&lt;/h2&gt;
&lt;p&gt;Install the CLI with &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt;:&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;pipx&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;install&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;--pip-args=--pre&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;spec-kitty-cli&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; is preferred for command-line tools because it creates an isolated
virtual environment for Spec Kitty and avoids the
&lt;code dir=&quot;auto&quot;&gt;externally-managed-environment&lt;/code&gt; errors that modern Linux distributions can
raise for direct &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; commands.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;4.x is in release candidate.&lt;/strong&gt; Until 4.0.0 is released, a plain install gets the latest stable 3.x release, which has no &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; command. The pre-release flag in each install command on this page (&lt;code dir=&quot;auto&quot;&gt;--pip-args=--pre&lt;/code&gt; for pipx, &lt;code dir=&quot;auto&quot;&gt;--prerelease=allow&lt;/code&gt; for uv, &lt;code dir=&quot;auto&quot;&gt;--pre&lt;/code&gt; for pip) installs the latest 4.x release candidate.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Other supported install methods:&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;uv&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&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;install&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;--prerelease=allow&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;spec-kitty-cli&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&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:#919F9F;--1:#5F636F&quot;&gt;# Inside an activated virtual environment&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;python&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;-m&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;pip&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;install&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;--pre&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;spec-kitty-cli&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Verify the CLI is available:&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:#82AAFF;--1:#3B61B0&quot;&gt;--version&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Expected output (abridged):&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;spec-kitty-cli version 4.0.0rc8&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If this step gives you trouble — a platform not covered above, an
&lt;code dir=&quot;auto&quot;&gt;externally-managed-environment&lt;/code&gt; error, or a Git credential prompt on Linux —
the &lt;a href=&quot;/guides/how-to/installation/install-spec-kitty/&quot;&gt;installation guide&lt;/a&gt; has the full per-platform
instructions and troubleshooting.&lt;/p&gt;
&lt;h2 id=&quot;step-2-initialize-a-project&quot;&gt;Step 2: Initialize a Project&lt;/h2&gt;
&lt;p&gt;Create a new project directory with the agent you plan to use, then put it under
git:&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;init&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;my-spec-project&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;--ai&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;claude&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:#C5E478;--1:#3B61B0&quot;&gt;cd&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;my-spec-project&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;git&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;init&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;-b&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;main&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;git&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;add&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;-A&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&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;commit&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;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Initial commit&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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;git&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;checkout&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;-b&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;my-first-mission&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Expected output (abridged):&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;OK Initialized Spec Kitty project&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;OK Created .kittify/ scaffold&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;aside aria-label=&quot;Important&quot; class=&quot;starlight-aside starlight-aside--note&quot;&gt;&lt;p class=&quot;starlight-aside__title&quot; aria-hidden=&quot;true&quot;&gt;&lt;svg viewBox=&quot;0 0 24 24&quot; width=&quot;16&quot; height=&quot;16&quot; fill=&quot;currentColor&quot; class=&quot;starlight-aside__icon&quot;&gt;&lt;path d=&quot;M12 11a1 1 0 0 0-1 1v4a1 1 0 0 0 2 0v-4a1 1 0 0 0-1-1Zm.38-3.92a1 1 0 0 0-.76 0 1 1 0 0 0-.33.21 1.15 1.15 0 0 0-.21.33 1 1 0 0 0 .21 1.09c.097.088.209.16.33.21A1 1 0 0 0 13 8a1.05 1.05 0 0 0-.29-.71 1 1 0 0 0-.33-.21ZM12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm0 18a8 8 0 1 1 0-16.001A8 8 0 0 1 12 20Z&quot;&gt;&lt;/path&gt;&lt;/svg&gt;Important&lt;/p&gt;&lt;div class=&quot;starlight-aside__content&quot;&gt;&lt;p&gt;&lt;strong&gt;Complete the git setup before continuing.&lt;/strong&gt; The first two commands prepare
the repository; the working branch allows planning artifacts to be committed:&lt;/p&gt;&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;git init -b main&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; creates files and never runs
&lt;code dir=&quot;auto&quot;&gt;git init&lt;/code&gt; (inside an existing repository it commits the files it wrote
instead). It even prints &lt;code dir=&quot;auto&quot;&gt;Required: run git init here before agent/worktree commands&lt;/code&gt;. Without a repository, &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; stops with
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_REPO_NOT_INITIALIZED&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;git commit&lt;/code&gt; — Spec Kitty needs a committed HEAD to create and commit
its mission scaffold. Without it you get “this checkout has no commits
yet”.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;git checkout -b my-first-mission&lt;/code&gt; — use a working branch so Spec Kitty
can commit planning artifacts. On a protected branch, mission creation can
succeed with a warning listing uncommitted files. Continue that existing
mission after switching branches; do not run &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; again. The branch
name is yours to choose.&lt;/li&gt;
&lt;/ol&gt;&lt;p&gt;Already working in an existing git repository with history? Skip the first two
and just make a working branch before continuing.&lt;/p&gt;&lt;/div&gt;&lt;/aside&gt;
&lt;aside aria-label=&quot;Tip&quot; class=&quot;starlight-aside starlight-aside--tip&quot;&gt;&lt;p class=&quot;starlight-aside__title&quot; aria-hidden=&quot;true&quot;&gt;&lt;svg viewBox=&quot;0 0 24 24&quot; width=&quot;16&quot; height=&quot;16&quot; fill=&quot;currentColor&quot; class=&quot;starlight-aside__icon&quot;&gt;&lt;path fill-rule=&quot;evenodd&quot; d=&quot;M1.44 8.855v-.001l3.527-3.516c.34-.344.802-.541 1.285-.548h6.649l.947-.947c3.07-3.07 6.207-3.072 7.62-2.868a1.821 1.821 0 0 1 1.557 1.557c.204 1.413.203 4.55-2.868 7.62l-.946.946v6.649a1.845 1.845 0 0 1-.549 1.286l-3.516 3.528a1.844 1.844 0 0 1-3.11-.944l-.858-4.275-4.52-4.52-2.31-.463-1.964-.394A1.847 1.847 0 0 1 .98 10.693a1.843 1.843 0 0 1 .46-1.838Zm5.379 2.017-3.873-.776L6.32 6.733h4.638l-4.14 4.14Zm8.403-5.655c2.459-2.46 4.856-2.463 5.89-2.33.134 1.035.13 3.432-2.329 5.891l-6.71 6.71-3.561-3.56 6.71-6.711Zm-1.318 15.837-.776-3.873 4.14-4.14v4.639l-3.364 3.374Z&quot; clip-rule=&quot;evenodd&quot;&gt;&lt;/path&gt;&lt;path d=&quot;M9.318 18.345a.972.972 0 0 0-1.86-.561c-.482 1.435-1.687 2.204-2.934 2.619a8.22 8.22 0 0 1-1.23.302c.062-.365.157-.79.303-1.229.415-1.247 1.184-2.452 2.62-2.935a.971.971 0 1 0-.62-1.842c-.12.04-.236.084-.35.13-2.02.828-3.012 2.588-3.493 4.033a10.383 10.383 0 0 0-.51 2.845l-.001.016v.063c0 .536.434.972.97.972H2.24a7.21 7.21 0 0 0 .878-.065c.527-.063 1.248-.19 2.02-.447 1.445-.48 3.205-1.472 4.033-3.494a5.828 5.828 0 0 0 .147-.407Z&quot;&gt;&lt;/path&gt;&lt;/svg&gt;Tip&lt;/p&gt;&lt;div class=&quot;starlight-aside__content&quot;&gt;&lt;p&gt;Use &lt;code dir=&quot;auto&quot;&gt;spec-kitty init . --ai claude&lt;/code&gt; to initialize the current folder instead of
creating a new one. The git requirement above applies either way.&lt;/p&gt;&lt;/div&gt;&lt;/aside&gt;
&lt;h2 id=&quot;step-3-create-your-first-specification&quot;&gt;Step 3: Create Your First Specification&lt;/h2&gt;
&lt;p&gt;Open your AI agent in this repository and run the &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; command.&lt;/p&gt;
&lt;p&gt;In your agent:&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;text&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;/spec-kitty.specify Build a tiny command-line task list app with add, complete, and delete actions.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;You’ll be asked a discovery interview. Answer each question until the command completes.&lt;/p&gt;
&lt;p&gt;Expected results:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One new mission directory under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;, named &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;slug&gt;-&amp;#x3C;id&gt;&lt;/code&gt; — for
example &lt;code dir=&quot;auto&quot;&gt;task-list-01M20JM4&lt;/code&gt;. The trailing token is the mission’s own
identifier, so yours will differ.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; inside it (the mission spec)&lt;/li&gt;
&lt;li&gt;Mission creation commits its generated metadata, event log, and task scaffold.
Your agent then writes the substantive specification and commits it with
&lt;code dir=&quot;auto&quot;&gt;spec-kitty spec-commit&lt;/code&gt;; the initial &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; scaffold alone is not ready
for planning.&lt;/li&gt;
&lt;/ul&gt;
&lt;aside aria-label=&quot;Note&quot; class=&quot;starlight-aside starlight-aside--note&quot;&gt;&lt;p class=&quot;starlight-aside__title&quot; aria-hidden=&quot;true&quot;&gt;&lt;svg viewBox=&quot;0 0 24 24&quot; width=&quot;16&quot; height=&quot;16&quot; fill=&quot;currentColor&quot; class=&quot;starlight-aside__icon&quot;&gt;&lt;path d=&quot;M12 11a1 1 0 0 0-1 1v4a1 1 0 0 0 2 0v-4a1 1 0 0 0-1-1Zm.38-3.92a1 1 0 0 0-.76 0 1 1 0 0 0-.33.21 1.15 1.15 0 0 0-.21.33 1 1 0 0 0 .21 1.09c.097.088.209.16.33.21A1 1 0 0 0 13 8a1.05 1.05 0 0 0-.29-.71 1 1 0 0 0-.33-.21ZM12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm0 18a8 8 0 1 1 0-16.001A8 8 0 0 1 12 20Z&quot;&gt;&lt;/path&gt;&lt;/svg&gt;Note&lt;/p&gt;&lt;div class=&quot;starlight-aside__content&quot;&gt;&lt;p&gt;Run &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; &lt;strong&gt;once&lt;/strong&gt;. Each run creates a separate mission, so running it
again gives you two, not an edited one. The next tutorial continues the mission
you just created rather than making another.&lt;/p&gt;&lt;/div&gt;&lt;/aside&gt;
&lt;h2 id=&quot;step-4-verify-your-work&quot;&gt;Step 4: Verify Your Work&lt;/h2&gt;
&lt;p&gt;Confirm the mission directory exists:&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;ls&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;kitty-specs&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Example output (your identifier will differ):&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;task-list-01M20JM4&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If the command created a new worktree later in the workflow, it will appear here:&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;ls&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;.worktrees&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;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty: command not found&lt;/code&gt;&lt;/strong&gt;: Reopen your shell, run &lt;code dir=&quot;auto&quot;&gt;pipx ensurepath&lt;/code&gt; if you installed with &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt;, or reinstall via &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt;. Then rerun &lt;code dir=&quot;auto&quot;&gt;spec-kitty --version&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; fails with &lt;code dir=&quot;auto&quot;&gt;externally-managed-environment&lt;/code&gt;&lt;/strong&gt;: Use &lt;code dir=&quot;auto&quot;&gt;pipx install --pip-args=--pre spec-kitty-cli&lt;/code&gt;, or create and activate a virtual environment before using &lt;code dir=&quot;auto&quot;&gt;python -m pip install --pre spec-kitty-cli&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Planning artifacts left uncommitted on a protected branch&lt;/strong&gt;: mission creation can succeed while reporting its uncommitted files. Run &lt;code dir=&quot;auto&quot;&gt;git checkout -b my-first-mission&lt;/code&gt;, review and commit those files, and continue the existing mission. Do not run &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt; again.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_REPO_NOT_INITIALIZED&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;specify&lt;/code&gt;&lt;/strong&gt;: the project directory is not a git repository. Run &lt;code dir=&quot;auto&quot;&gt;git init -b main&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;git add -A &amp;#x26;&amp;#x26; git commit -m &quot;Initial commit&quot;&lt;/code&gt;, and retry. &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; does not create the repository for you.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;“This checkout has no commits yet”&lt;/strong&gt;: the repository exists but has no commit, so Spec Kitty cannot commit its mission scaffold. Run &lt;code dir=&quot;auto&quot;&gt;git add -A &amp;#x26;&amp;#x26; git commit -m &quot;Initial commit&quot;&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;git commit --allow-empty -m &quot;Initial commit&quot;&lt;/code&gt; if there is nothing to stage) and retry.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; command available&lt;/strong&gt;: Re-run &lt;code dir=&quot;auto&quot;&gt;spec-kitty init . --ai &amp;#x3C;your-agent&gt;&lt;/code&gt; from the project root, then verify the setup with &lt;code dir=&quot;auto&quot;&gt;spec-kitty verify-setup --diagnostics&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;WAITING_FOR_DISCOVERY_INPUT&lt;/code&gt;&lt;/strong&gt;: The command is paused for your answers; provide the requested details and continue.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;whats-next&quot;&gt;What’s Next?&lt;/h2&gt;
&lt;p&gt;Continue with &lt;a href=&quot;/guides/tutorials/your-first-mission/&quot;&gt;Your First Mission&lt;/a&gt; for the complete
workflow from specification to merge. It picks up the mission you just created:
its Step 1 is only about confirming you have that mission, so &lt;strong&gt;start at
&lt;a href=&quot;/guides/tutorials/your-first-mission/#step-2-create-the-technical-plan&quot;&gt;Step 2&lt;/a&gt; and do not run
&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; again&lt;/strong&gt;.&lt;/p&gt;
&lt;h3 id=&quot;related-how-to-guides&quot;&gt;Related How-To Guides&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-and-upgrade/&quot;&gt;Install and Upgrade&lt;/a&gt; - Additional installation options&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/create-specification/&quot;&gt;Create a Specification&lt;/a&gt; - Deep dive into &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/non-interactive-init/&quot;&gt;Non-Interactive Init&lt;/a&gt; - Scripted project setup&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;reference-documentation&quot;&gt;Reference Documentation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/api/cli-commands/&quot;&gt;CLI Commands&lt;/a&gt; - Full command reference&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/slash-commands/&quot;&gt;Slash Commands&lt;/a&gt; - AI agent slash commands&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/supported-agents/&quot;&gt;Supported Agents&lt;/a&gt; - Slash-command agents supported by the CLI&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;learn-more&quot;&gt;Learn More&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/spec-driven-development/&quot;&gt;Spec-Driven Development&lt;/a&gt; - Why specs matter&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/mission-system/&quot;&gt;Mission System&lt;/a&gt; - How missions shape workflows&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
