Repository: The Foundation Layer

The super-meta layer that bootstraps your entire development environment. This is where your workflow begins and where it’s maintained.

What This Actually Is

~/repository/ serves three distinct purposes:

System Bootstrap - Set up a new machine from scratch
Configuration Source of Truth - Canonical configs that get synced everywhere
Project Template System - Scaffold new projects with consistent structure

The Real Structure

repository/
├── configs/                    # Source of truth configurations
│   ├── git/aliases.gitconfig   # Git shortcuts
│   └── wsl/essential_packages.txt
│
├── docs/
│   ├── _backup/                # Evolutionary history (old agents/commands)
│   ├── _wip/                   # Active development
│   ├── setup/                  # Step-by-step setup guides
│   │   ├── wsl_installation.md
│   │   ├── wsl_configuration.md
│   │   ├── github_setup.md
│   │   ├── vscode_setup.md
│   │   └── repo_setup.md
│   ├── uv.md                   # UV tooling documentation
│   └── wisdom/                 # Cross-domain knowledge
│
├── packages/setup/             # Project template system
│   ├── src/repository_setup/   # Python automation
│   └── templates/              # Project scaffolding templates
│       ├── getting-started.md
│       ├── package_README.md
│       ├── package_pyproject.toml
│       └── root_pyproject.toml
│
└── scripts/
    ├── repos/                  # Multi-repo management
    │   ├── repos.sh            # Clone and manage repos
    │   └── setup.sh
    ├── setup/                  # System setup
    │   ├── repo_setup.sh
    │   └── wsl_configuration.sh
    └── uv/                     # UV tooling setup
        ├── setup.sh
        └── tools.sh

How This Fits Into Your Flow

New Device Setup (Bootstrap)

1. Get new machine
   ↓
2. Clone ~/repository
   ↓
3. Run setup scripts:
   - scripts/setup/wsl_configuration.sh    (Configure WSL)
   - scripts/repos/setup.sh                (Clone all repos)
   - scripts/uv/setup.sh                   (Install UV tooling)
   ↓
4. Result: Entire dev environment ready

New Project Creation (Templates)

1. Need new project
   ↓
2. Use packages/setup/ templates
   ↓
3. Generates consistent structure:
   - pyproject.toml (with UV)
   - README.md (with getting-started)
   - src/ layout
   - tests/
   ↓
4. Result: Project follows established patterns

Configuration Management (Sync)

1. Update git aliases in configs/git/aliases.gitconfig
   ↓
2. Symlink or sync to system location
   ↓
3. All projects use updated config
   ↓
4. Result: Single source of truth maintained

The Three Flows

Flow 1: Bootstrap New Machine

When: Setting up new device, fresh install, disaster recovery

Process:

Install base system (WSL if Windows)
Clone repository repo
Run scripts/setup/wsl_configuration.sh
Run scripts/repos/setup.sh to clone all other repos
Run scripts/uv/setup.sh for Python tooling
Environment ready

Result: All domain repos, ai_agents, auto-slacker, and configs in place

Flow 2: Create New Project

When: Starting new work, spinning up new service/tool

Process:

Run packages/setup automation
Templates generate:
- Project structure (src/, tests/)
- pyproject.toml with dependencies
- README with getting-started guide
Project inherits standard patterns
Immediately ready for LLM-driven development

Result: Consistent project structure, no setup bikeshedding

Flow 3: Evolve the System

When: Adopting new tool, changing patterns, learning new techniques

Process:

Experiment in _wip/ directory
Update scripts/configs as patterns solidify
LLMs maintain and update based on usage
Old patterns archived to _backup/
Sync changes across all projects

Result: System evolves with your workflow

The Evolutionary Aspect

docs/_backup/

Contains historical configs:

Old agent definitions (before moving to ai_agents)
Previous command structures
Old quality gate hooks
Deprecated patterns

Why keep it: Reference for why things changed, patterns that might return

docs/_wip/

Active development:

New workflow experiments
Untested patterns
Ideas being refined

Why it matters: LLMs can see what’s being developed, reference in-progress ideas

UV-Centric Tooling

Heavy focus on UV (modern Python package manager):

Scripts for UV setup
Templates use UV’s pyproject.toml format
Standardized dependency management

Why: Chosen tool for Python workflow consistency

Integration Points

With ai_agents

Old _backup/ shows agents/commands used to live here, now they’re in ai_agents.

The flow:

repository sets up the environment
ai_agents orchestrates commands across it

With Domain Repos (tester, developer, etc.)

The flow:

repository clones them (scripts/repos/)
templates create structure they expect
configs set standards they follow

With auto-slacker

The flow:

repository implements patterns
auto-slacker documents them
LLMs reference both to maintain everything

With Projects

The flow:

repository templates scaffold new projects
projects follow established patterns
learnings feed back into templates

The Meta Layers

Level 4: repository        - Bootstrap everything, create projects, set standards
Level 3: auto-slacker      - Document everything
Level 2: ai_agents         - Orchestrate everything
Level 1: domain repos      - Know everything about domains
Level 0: projects          - Build everything

repository is the foundation. Without it, nothing else can be set up consistently.

Practical Usage Examples

Example 1: New Machine

# Day 1 with new laptop
git clone https://github.com/you/repository ~/repository
cd ~/repository

# Run setup
./scripts/setup/wsl_configuration.sh
./scripts/repos/setup.sh
./scripts/uv/setup.sh

# Done - all repos cloned, tools installed, ready to work

Example 2: New Python Package

# Need new testing utility package
cd ~/tester
python -m repository_setup.main create-package test-utils

# Generated structure:
# test-utils/
#   ├── pyproject.toml (with UV config)
#   ├── README.md (with template)
#   ├── src/test_utils/
#   └── tests/

Example 3: Update Git Aliases

# Edit the source of truth
vim ~/repository/configs/git/aliases.gitconfig

# Sync to system (manually or via script)
# Now all git commands use updated aliases

LLM Maintenance Flow

LLMs maintain repository through:

Adding new tool setup - When you adopt a new tool, LLM adds setup script
Updating templates - As patterns emerge, templates get updated
Documenting in _wip/ - New experiments documented for future reference
Archiving to _backup/ - Old patterns preserved with context
Refining scripts - Setup scripts improved based on actual usage

Why This Structure Works

Evolved, Not Designed: The _backup/ shows this grew organically - patterns that work stayed, others archived

Template-Driven Consistency: New projects start with proven structure, not blank slate

Single Source of Truth: Configs live here, synced everywhere else

Workflow-Oriented: Three flows (bootstrap, create, evolve) map to actual work patterns

LLM-Accessible: Structure and docs let LLMs understand and maintain the system

The Foundation Promise

Clone repository → Run scripts → Everything else works

That’s the contract. repository is the one repo that makes all others possible.