Tech Proposal: Pre-Structured Template Repository

[mkellerman]

Executive Summary

This proposal outlines a repository structure that serves as a "what you see is what you get" template, where the repository itself demonstrates the exact final state users will have after initialization, eliminating the need for complex generation logic.

Problem Statement

Current approach involves:

• Complex ZIP generation or file copying logic
• Unclear end-state for users before installation
• Difficulty understanding what files will be added
• Potential confusion about the transformation process

Proposed Solution

Core Concept

The repository itself is the template - structured exactly as it will appear in the user's project after installation.

Repository Structure

spec-kit/
├── .claude/
│   ├── commands/
│   │   ├── plan.md
│   │   ├── specify.md
│   │   └── taks.md
├── .gemini/
│   └── < ... >
├── .cursor/
│   └── < ... >
├── .github/
│   └── copilot/
│       └── < ... >
├── .speckit/
│   ├── memory/
│   ├── scripts/
│   └── templates/
├── .windsurf/
│       └── < ... >
├── spec-kit.yaml          # Main configuration
├── README.md
├── LICENSE
└── install.py             # Simple copy script

Implementation Strategy

1. Direct Repository Cloning

When users run:

uvx --from git+https://github.com/github/spec-kit.git specify init

The tool will:

• Clone the repository to a temporary location
• Copy the AI assistant directories directly to the user's project
• Skip meta files (README.md, LICENSE, install.py)
• Preserve the exact structure

2. Configuration Approach

spec-kit.yaml - Manifest file defining what gets copied:

version: 1.0.0
directories:
  - .claude
  - .gemini
  - .cursor
  - .github/copilot
  - .aider
  - .windsurf
exclude:
  - README.md
  - LICENSE
  - install.py
  - spec-kit.yaml
  - .git
options:
  merge_existing: true
  backup_conflicts: true

3. Simple Installation Script

install.py - Minimal logic, maximum clarity:

import shutil
import yaml
from pathlib import Path

def init_command(target_dir="."):
    """Copy template directories to target project"""
    source_dir = Path(__file__).parent
    target_dir = Path(target_dir)
    
    # Read manifest
    with open(source_dir / "spec-kit.yaml") as f:
        config = yaml.safe_load(f)
    
    # Copy each directory
    for dir_name in config["directories"]:
        source = source_dir / dir_name
        target = target_dir / dir_name
        
        if source.exists():
            shutil.copytree(source, target, dirs_exist_ok=True)
            print(f"✓ Added {dir_name}")
    
    print("✓ Specification kit initialized")

Benefits

1. Transparency

• Repository browsing shows exactly what users get
• No hidden transformations or surprises
• Easy to audit and understand

2. Simplicity

• No complex generation logic
• Direct file copying
• Minimal installation code

3. Template-Ready

• Users can use GitHub's "Use this template" feature
• Fork and customize directly
• Clone and modify for specific needs

4. Documentation as Code

• The repository structure IS the documentation
• Each file can contain helpful comments
• Example configurations included

5. Version Control Friendly

• Changes to templates are clearly visible in commits
• Easy to track evolution of best practices
• Simple to contribute improvements