ecosystem-patterns

What this skill does

# Preferred Patterns

## Overview

## Universal Paths

**Environment Variables:**

- $IMI_SYSTEM_PATH = $CODE = `~/code/` - All repositories
- `$VAULT` = `~/code/DeLoDocs` - Obsidian vault
- `$STACKS` = `~/docker/trunk-main/stacks` - Domain-based service stacks
  - $AI` = `$STACKS/ai` - AI/ML services
  - `$MONITORING` = `$STACKS/monitoring` - Monitoring services
  - etc.
- `$ZC` = `~/.config/zshyzsh` - Shell configuration

> [!IMPORTANT] **Critical Pattern:**
> Every repo in `$CODE` (ideally) has a matching folder in `$VAULT/Projects/` for non-tracked brainstorming and iteration documents.
> There is a `helper.zsh` script function `syncDocs` that ensures this relationship is maintained.

> [!IMPORTANT] **Critical Convention**
> `exported` paths are ALWAYS in caps.
> `aliases` and `functions` are ALWAYS lowercase.

- For every exported path, there is an alias to navigate to it quickly.
  - `alias zv='cd $ZV'` to go to the vault.

- This convention is reused and applied to LLM model and Agent invocations of that model.
  - `export KK='openrouter/moonshotai/kimi-k2'`
  - `alias kk='gptme --model $KK'`

## Pattern Categories

### 0. Universal Code Hygiene Rules

> [!CRITICAL] **The No-Script-Disease Rule**
> NEVER create versioned script variants (`-improved`, `-new`, `-v2`, `-old`, `.bak`). This creates runaway technical debt through:
>
> 1. **Ambiguity** - Which version is canonical? Which runs in production?
> 2. **Dead Code** - Old versions linger because "what if we need to roll back?"
> 3. **Discovery Friction** - New developers don't know which script to read/modify
> 4. **Merge Conflicts** - Multiple versions diverge, reconciliation becomes painful
>
> **Correct Pattern:**
> - Replace files in-place
> - Use git history for rollback capability
> - Use feature branches for experimental variants, NEVER file suffixes
> - If you must keep old versions for reference, move to archive directory with date stamp, not inline suffixes
>
> **Examples:**
> ```bash
> # ❌ WRONG - Creates script disease
> scripts/build.sh
> scripts/build-improved.sh
> scripts/build-new.sh
> scripts/build-old.sh
> scripts/build.sh.bak
>
> # ✅ CORRECT - Single canonical version
> scripts/build.sh  # Current version, git history for rollback
>
> # ✅ ACCEPTABLE - If archival needed
> scripts/build.sh
> archive/build-20251106.sh  # Explicit date, separate archive directory
> ```

> [!CRITICAL] **Port Selection Rule (avoid obvious/common ports)**
> When starting local servers (Vite dev/preview, FastAPI, etc) that will be proxied or accessed across your LAN/WAN, **do not grab the obvious/default ports** (especially `3000`). They are collision magnets.
>
> **Correct pattern:**
> - Pick a random port in **8000-19000**
> - If it collides, pick another random port
> - Update Traefik (or whatever proxy) upstream to match
>
> **Quick collision check:**
> ```bash
> ss -ltn | rg ":${PORT} " || echo "free"
> ```

### 1. Local Repo Worktree File Structure (iMi Worktrees)

I made a custom Rust CLI tool called iMi (sticking with my Bon Iver inspired project names) to manage git worktrees for all my projects. Its strict rules allow us to leverage convention over configuration. When working with AI, this is an easy way to reduce complexity and tokens by trading some agency for deterministic behavior. The rules are as follows:

- Every `iMi` project lives in the $IMI_SYSTEM_PATH (`~/code/`) directory.
- The project's top-level directory contains zero or more git worktrees for different branches and purposes.
- The top-level directory MUST contain a copy of the repo's remote `trunk`
- Each feature, PR, review, experiment, or fix gets its own worktree named according to a strict convention.
  - Branches are name by `type/descriptive-name` (e.g., `feat/add-auth`, `fix/login-bug`)
  - Worktrees are named by `type-descriptive-name` (e.g., `pr-42`, `fix-login-bug`)
  - The main trunk worktree is always named `trunk-[branch-name]` (e.g., `trunk-main`, `trunk-master`, `trunk-develop`)
  - Theses conventions can be customized per host machine via `iMi` config file (`~/.config/iMi/config.toml`)
- All worktrees are siblings with the trunk in the top-level project directory.
- The top-level project directory is referred to as the `iMi Sandbox` and contains no code itself. Instead, it contains:
  - An `.iMi/` directory for iMi's internal config and metadata.
  - A `dotfiles` directory that manages user-level and project-level, non-tracked dotfiles via symlinks.
  - `iMi` handles manages these symlinks automatically when creating worktrees.
- Before working with a new repo, it needs to be initialized:
  - If it already exists locally, run `imi init` from within the repo directory.
  - If it does not exist locally, run `imi clone {repo-url}` and it will be cloned and initialized automatically and placed in `$CODE/`
  - After initialization, the repo exists as a project in the `iMi Database` and can be managed via `imi` commands.
- When outside a project directory, list all projects with `imi list` (or `imi ls` for short).
- From within a project directory, list all worktrees with `imi list` (or `imi ls -p` to override and list all projects).
- Each worktree at any one time can be assigned either
  - one developer
    - e.g. If you manually edit files, you are implicitly assigned to that worktree.
  - one agent
    - If the worktree is created as part of a task picked up by an agent, that agent is assigned to the worktree.
  - one developer and one agent
    - If you are working in an interactive shell or REPL, it is considered pair programming and you are assigned to that worktree with the paired agent.
- iMi is loosely coupled to Agents as far as linking through foreign key. `iMi` does not manage agent spawning, lifecycle, business logic.
- iMi is tied to the 33GOD Agent Framework via generous publishing of key events to the Bloodbank Event Bus.
  - e.g., When a worktree is created, an event is published to the bus that agents registered with the Flume task service can listen for and pick up tasks depending on their expertise and stage of the task lifecycle.

**Location:** `$CODE/{project-name}/`

```bash
$CODE/repo-name/
├── .iMi/              # Main repository branch
├── trunk-main/              # Main repository branch
├── feature-{name}/          # Feature branches
├── pr-{number}-{name}/      # PR worktrees
├── pr-review-{number}/      # Review worktrees
├── experiment-{name}/       # Experimental branches
└── fix-{name}/              # Bug fixes
```

**Vault Documentation:** `$VAULT/Projects/{project-name}/`

```bash
$VAULT/Projects/repo-name/
├── markdown/                # Docs sync'd from repo
├──── PRD.md                  # Product requirements
├──── Architecture.md         # Technical architecture
├── Brainstorming.md         # non-tracked Ideas and iterations
├── Meeting-Notes.md         # Discussion notes
└── Research/                # Background research
```

**Critical Pattern:** Every project in `$CODE` has corresponding documentation in `$VAULT/Projects/` for non-tracked brainstorming and iteration.

### 2. Shell Configuration Patterns (zshyzsh)

**Theme**: Dark (Catppuccin Mocha or Gruvbox Material Dark)
**Terminal**: Alacritty
**Editor**: neovim (Lazyvim flavor, aliased to vi)
**IDE**: None. Never. I only work in a zellij multiplexed terminal with floating neovim instances.

**Key Patterns:**

- Modular zsh config in $ZSH_CUSTOM == $ZC == `~/.config/zshyzsh/`
- Zellij terminal multiplexing
- Custom aliases and functions
- Terminal logging system [WIP]
- Settings in ~/.config are moved to home/delorenj/.config/zshyzsh and symlinked back to ~/.config

### 2a. Editor Configuration (LazyVim)

**Environment Variable:**
```bash
export NVIM_APPNAME=lazyvim  # Points to ~/.config/lazyvim (symlinked to zshyzsh/lazyvim)
```

**Config Location:**
- Primary: `~/.config/zshyzsh/lazyvim/`
- Symlinked: `~/.config/lazyvim -> zshyzsh/lazyvim`

**Key Files:**
```bash
~/.config/zshyzsh/lazyvim/
├── init.lua