<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/configuration/pack-yaml/">
  <id>https://docs.spec-kitty.ai/configuration/pack-yaml/</id>
  <title>pack.yaml reference</title>
  <updated>2026-10-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/configuration/pack-yaml/"/>
  <summary>Field reference for a Charter Pack pack.yaml descriptor: identity, lineage, the declared pack_level, requires_core and layout pointers, plus regenerate-graph --pack-root.</summary>
  <content type="html">&lt;span id=&quot;packyaml-reference&quot;&gt;&lt;/span&gt;
&lt;p&gt;Every Charter Pack carries an authored &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; at its root. The model is
&lt;code dir=&quot;auto&quot;&gt;PackDescriptor&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/packs/pack_descriptor.py&lt;/code&gt;); unknown
fields are refused, and a field retired by an earlier release is refused with
&lt;code dir=&quot;auto&quot;&gt;RETIRED_PACK_FIELD&lt;/code&gt;. The generated &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; is a separate file and
is never hand-edited.&lt;/p&gt;
&lt;h2 id=&quot;fields&quot;&gt;Fields&lt;/h2&gt;


















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Field&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Stable 26-character ULID identity. Minted once, never changed.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Human-readable handle. Display only, not the identity.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;pack_version&lt;/code&gt;&lt;/td&gt;&lt;td&gt;built-in only&lt;/td&gt;&lt;td&gt;Semantic version string. Required when &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;; optional for &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;ULID of the pack this one extends. Omit or &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; for a root pack.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes (see below)&lt;/td&gt;&lt;td&gt;The tier the pack belongs to: &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;PEP 440 version specifier of the Spec Kitty core versions the pack supports, for example &lt;code dir=&quot;auto&quot;&gt;&quot;&gt;=4.0,&amp;#x3C;5.0&quot;&lt;/code&gt;. An unparsable value is a schema error. Absent means no constraint (#6046).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;active_charter&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Pack-relative path to the active-charter file. Defaults to &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; for an &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; pack.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;pack_drg&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Pack-relative path to the DRG source. Defaults per level: the sharded &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; files at the root (&lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;graph.yaml&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;active_charter&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;pack_drg&lt;/code&gt; must resolve inside the pack; an absolute path or a &lt;code dir=&quot;auto&quot;&gt;..&lt;/code&gt; escape is rejected by
&lt;code dir=&quot;auto&quot;&gt;charter pack validate&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;pack_level&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;The allowed values are the three tiers owned by &lt;code dir=&quot;auto&quot;&gt;kernel.pack_tiers&lt;/code&gt;. The
declared value must match the position the pack is configured at:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;org packs:&lt;/strong&gt; a mismatch is refused when the pack is loaded
(&lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISMATCH&lt;/code&gt;, attributed to &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;). A &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; that cannot
be read or fails the schema is refused too.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;built-in and project positions:&lt;/strong&gt; nothing refuses at load. The validator
can report the mismatch when a caller passes the configured position
(&lt;code dir=&quot;auto&quot;&gt;validate_pack(..., expected_level=...)&lt;/code&gt;), but &lt;code dir=&quot;auto&quot;&gt;charter pack validate&lt;/code&gt; on a
bare path has no position, so it skips the mismatch check and still reports
&lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISSING&lt;/code&gt; and schema faults.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Deprecation window.&lt;/strong&gt; During the window a &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; that omits &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt;
(or an org pack with no &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;) still loads under the tier of the position
it is configured at, and reports a &lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISSING&lt;/code&gt; warning. After the
window the omission is a refusal. The &lt;code dir=&quot;auto&quot;&gt;pack_level_backfill&lt;/code&gt; upgrade migration
writes &lt;code dir=&quot;auto&quot;&gt;pack_level: project&lt;/code&gt; into an existing project pack.&lt;/p&gt;
&lt;h2 id=&quot;regenerating-a-built-in-packs-graph&quot;&gt;Regenerating a built-in pack’s graph&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter pack regenerate-graph [--check] --pack-root &amp;#x3C;dir&gt;&lt;/code&gt;
regenerates (or, with &lt;code dir=&quot;auto&quot;&gt;--check&lt;/code&gt;, verifies) the sharded &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; fragments
and &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; for a fetched copy of a &lt;strong&gt;built-in-level&lt;/strong&gt; pack. The
root needs a valid &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; declaring &lt;code dir=&quot;auto&quot;&gt;pack_level: built-in&lt;/code&gt;; org and project
packs are refused with exit 1 before anything is written, because the generators
would overwrite their &lt;code dir=&quot;auto&quot;&gt;graph.yaml&lt;/code&gt; or write a wrong manifest. Without the flag
the command targets the shipped built-in pack.&lt;/p&gt;</content>
</entry>
