Use Git Submodule for team-ai-directives instead of Clone

[kanfil]

Problem

Currently, when specify init --team-ai-directives <url> is run, it clones the team-ai-directives repository into .specify/memory/team-ai-directives/. This creates several issues:

1. Nested Git Repository: The clone creates a .git directory inside the project, which is problematic when .specify is committed to the project repo
2. Worktree Conflicts: When using parallel execution with worktrees (Phase 2 feature), worktrees are created in .specify/worktrees/ which should not be committed
3. Version Tracking: Cannot track which version of team-ai-directives is being used

Solution

Use Git Submodule instead of Clone:

# Current (clone)
git clone <url> .specify/memory/team-ai-directives

# Proposed (submodule)
git submodule add <url> .specify/team-ai-directives

New Directory Structure

project/
├── .specify/
│   ├── team-ai-directives/        ← SUBMODULE (moved from .specify/memory/)
│   │   ├── context_modules/
│   │   ├── skills/
│   │   ├── drafts/                ← Levelup writes here
│   │   └── .git                   ← Submodule reference (not nested repo)
│   ├── memory/
│   │   ├── adr.md
│   │   └── constitution.md
│   └── worktrees/                 ← Excluded via .git/info/exclude
│       ├── feature-login-task1/
│       └── feature-login-task2/

Worktree Exclusion

When creating worktrees for parallel task execution, add to .git/info/exclude:

# Agentic SDLC worktrees
.specify/worktrees/
.specify/worktrees/*

This follows Kilo's approach (.kilocode/worktrees/ in .git/info/exclude).

Changes Required

1. spec-kit CLI (src/specify_cli/__init__.py):

   • Change git clone → git submodule add
   • Handle submodule update commands

2. Levelup Path Updates:

   • Update KNOWLEDGE_ROOT from .specify/memory/team-ai-directives → .specify/team-ai-directives
   • Files: scripts/bash/prepare-levelup.sh, scripts/powershell/prepare-levelup.ps1, templates/commands/levelup.md

3. Auto-exclude Worktrees:

   • When creating worktree, append to .git/info/exclude

4. Documentation:

   • Update README with submodule setup instructions
   • Document submodule update flow: git submodule update --init --recursive

Related

• Phase 2: Worktree Support for Parallel Execution
• PRD: LLM Gateway Integration

[kanfil]

Levelup PR Flow with Submodule

Current Flow (Clone)

1. KNOWLEDGE_ROOT = .specify/memory/team-ai-directives (cloned repo)
2. Create draft: .specify/memory/team-ai-directives/drafts/{slug}.md
3. Create branch: levelup/{slug} (in cloned repo)
4. Commit changes (to cloned repo's .git)
5. git push to remote team-ai-directives
6. MCP create_pull_request → PR to team-ai-directives repo

New Flow (Submodule)

1. KNOWLEDGE_ROOT = .specify/team-ai-directives (submodule)
2. Create draft: .specify/team-ai-directives/drafts/{slug}.md  (same)
3. Create branch: levelup/{slug} (in submodule)
4. Commit changes (submodule's .git, not nested)
5. git push (from submodule) → remote team-ai-directives
6. MCP create_pull_request → PR to team-ai-directives repo  (unchanged!)

Key Differences

Aspect	Clone (Current)	Submodule (New)
Path	.specify/memory/team-ai-directives	.specify/team-ai-directives
Git metadata	Nested .git directory	.git is file reference
Parent repo tracking	Nested repo committed	Submodule reference committed
PR target	Remote team-ai-directives	Remote team-ai-directives (same)
MCP PR creation	Via Git platform MCP	No change

Submodule Commands for Levelup

The levelup script needs to run git commands inside the submodule:

# Change to submodule directory, then run git commands
cd .specify/team-ai-directives
git checkout -b levelup/{slug}
git add drafts/{slug}.md
git commit -m "Add session context"
git push -u origin levelup/{slug}