<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-23-3-centralized-workspace-context-storage/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-23-3-centralized-workspace-context-storage/</id>
  <title>Centralized Workspace Context Storage</title>
  <updated>2026-01-23T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-23-3-centralized-workspace-context-storage/"/>
  <summary>Centralised runtime workspace context in a shared .kittify directory in the main checkout, so agents could read it from anywhere and it outlived the worktree.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Superseded by &lt;code dir=&quot;auto&quot;&gt;architecture/2.x/adr/2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;.
This ADR was written for the legacy filtered-worktree era. The current
runtime uses mandatory execution lanes, mission/lane branches, and
lane-scoped runtime context instead of per-WP workspace metadata.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;LLM agents working in worktrees need runtime visibility into workspace state
(base branch, dependencies, creation time, etc.). In the legacy
filtered-worktree model, base-branch metadata in frontmatter was not visible
inside every workspace.&lt;/p&gt;
&lt;p&gt;This creates a visibility problem:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents in worktrees cannot read their own WP frontmatter&lt;/li&gt;
&lt;li&gt;Must query main repo to get workspace metadata&lt;/li&gt;
&lt;li&gt;No consolidated runtime context available in worktree&lt;/li&gt;
&lt;li&gt;Context information scattered across multiple sources&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Where should we store runtime context information that is:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Accessible from both main repo and worktrees&lt;/li&gt;
&lt;li&gt;Not hidden by workspace-local filtering&lt;/li&gt;
&lt;li&gt;Survives worktree deletion (for audit trail)&lt;/li&gt;
&lt;li&gt;Doesn’t create merge conflicts&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Agents in worktrees need runtime access to workspace metadata&lt;/li&gt;
&lt;li&gt;Context should be readable without querying main repo files&lt;/li&gt;
&lt;li&gt;Need audit trail that persists after worktree deletion&lt;/li&gt;
&lt;li&gt;Must not create merge conflicts or git state issues&lt;/li&gt;
&lt;li&gt;Should align with existing architecture patterns&lt;/li&gt;
&lt;li&gt;Want single query to get all workspace context&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 1:&lt;/strong&gt; Per-worktree &lt;code dir=&quot;auto&quot;&gt;.spec-kitty-context&lt;/code&gt; file&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Centralized storage in &lt;code dir=&quot;auto&quot;&gt;.kittify/workspaces/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Environment variables only&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Store in git config&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 2: Centralized storage in &lt;code dir=&quot;auto&quot;&gt;.kittify/workspaces/&lt;/code&gt;”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Aligns with existing &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; pattern (config, metadata, merge-state all in &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Survives worktree deletion (audit trail)&lt;/li&gt;
&lt;li&gt;Avoids workspace-local filtering complexity&lt;/li&gt;
&lt;li&gt;Queryable from anywhere (main repo and worktrees)&lt;/li&gt;
&lt;li&gt;Simple cleanup on merge&lt;/li&gt;
&lt;li&gt;No risk of merge conflicts (files in main repo, not worktrees)&lt;/li&gt;
&lt;/ul&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;Context accessible from both main repo and worktrees via relative path&lt;/li&gt;
&lt;li&gt;Persists after worktree deletion (post-mortem debugging)&lt;/li&gt;
&lt;li&gt;No .gitignore or workspace-filtering complexity&lt;/li&gt;
&lt;li&gt;Consistent with existing architecture (all state in &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Simple cleanup (delete JSON file)&lt;/li&gt;
&lt;li&gt;Queryable via CLI (&lt;code dir=&quot;auto&quot;&gt;spec-kitty context info&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Context files stored separately from worktrees&lt;/li&gt;
&lt;li&gt;Agents must use relative path (&lt;code dir=&quot;auto&quot;&gt;../../.kittify/workspaces/&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Could become orphaned if worktree deleted without cleanup&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;JSON format for context files&lt;/li&gt;
&lt;li&gt;One file per workspace: &lt;code dir=&quot;auto&quot;&gt;###-feature-WP##.json&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Cleanup command: &lt;code dir=&quot;auto&quot;&gt;spec-kitty context cleanup&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We’ll validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents successfully reading context from worktrees&lt;/li&gt;
&lt;li&gt;No reports of context visibility issues&lt;/li&gt;
&lt;li&gt;Orphaned context detection working correctly&lt;/li&gt;
&lt;li&gt;Performance acceptable (&amp;#x3C; 50ms to read context)&lt;/li&gt;
&lt;/ul&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-1-per-worktree-spec-kitty-context-file&quot;&gt;Option 1: Per-Worktree &lt;code dir=&quot;auto&quot;&gt;.spec-kitty-context&lt;/code&gt; File&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;High visibility (in worktree root)&lt;/li&gt;
&lt;li&gt;No relative path needed&lt;/li&gt;
&lt;li&gt;Colocated with workspace files&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;Lost when worktree deleted (no audit trail)&lt;/li&gt;
&lt;li&gt;Requires gitignoring (untracked, ephemeral)&lt;/li&gt;
&lt;li&gt;Duplicates info from frontmatter&lt;/li&gt;
&lt;li&gt;Adds .gitignore complexity&lt;/li&gt;
&lt;li&gt;Could be accidentally committed&lt;/li&gt;
&lt;li&gt;Not accessible from main repo&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-centralized-storage-in-kittifyworkspaces&quot;&gt;Option 2: Centralized Storage in &lt;code dir=&quot;auto&quot;&gt;.kittify/workspaces/&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Survives worktree deletion (audit trail)&lt;/li&gt;
&lt;li&gt;No .gitignore complexity&lt;/li&gt;
&lt;li&gt;Consistent with &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; pattern&lt;/li&gt;
&lt;li&gt;Queryable from anywhere&lt;/li&gt;
&lt;li&gt;Simple cleanup&lt;/li&gt;
&lt;li&gt;No merge conflicts&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 relative path from worktree&lt;/li&gt;
&lt;li&gt;Context stored separately from workspace&lt;/li&gt;
&lt;li&gt;Could become orphaned&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-environment-variables-only&quot;&gt;Option 3: Environment Variables Only&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No files to manage&lt;/li&gt;
&lt;li&gt;Available to all processes&lt;/li&gt;
&lt;li&gt;Traditional Unix approach&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;Ephemeral (lost when shell exits)&lt;/li&gt;
&lt;li&gt;Not queryable after command finishes&lt;/li&gt;
&lt;li&gt;No audit trail&lt;/li&gt;
&lt;li&gt;Must be set manually&lt;/li&gt;
&lt;li&gt;Not accessible to new shells/processes&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-store-in-git-config&quot;&gt;Option 4: Store in Git Config&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Git-native approach&lt;/li&gt;
&lt;li&gt;Persistent across shell sessions&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;Pollutes git config namespace&lt;/li&gt;
&lt;li&gt;Difficult to query programmatically&lt;/li&gt;
&lt;li&gt;Not human-readable&lt;/li&gt;
&lt;li&gt;Cleanup complex&lt;/li&gt;
&lt;li&gt;Non-standard use of git config&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;h3 id=&quot;implementation-summary&quot;&gt;Implementation Summary&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Context file location:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.kittify/workspaces/###-feature-WP##.json&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Context includes:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP ID, feature slug, worktree path, branch name&lt;/li&gt;
&lt;li&gt;Base branch and commit SHA&lt;/li&gt;
&lt;li&gt;Dependencies list&lt;/li&gt;
&lt;li&gt;Creation timestamp and VCS backend&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;CLI commands:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty context info&lt;/code&gt; - Show context for workspace&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty context list&lt;/code&gt; - List all workspaces&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty context cleanup&lt;/code&gt; - Remove orphaned contexts&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Test coverage:&lt;/strong&gt; 9 tests for persistence, orphaned detection, and visibility&lt;/p&gt;
&lt;h3 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/&quot;&gt;2026-01-23-2-explicit-base-branch-tracking&lt;/a&gt; - Provides base branch data for context&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-5-decorator-based-context-validation/&quot;&gt;2026-01-23-5-decorator-based-context-validation&lt;/a&gt; - Uses context for validation&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;code-references&quot;&gt;Code References&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace_context.py&lt;/code&gt; - Context management (save, load, list, cleanup)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/context.py&lt;/code&gt; - CLI commands&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/unit/test_base_branch_tracking.py&lt;/code&gt; - Test suite&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
