diff --git a/AI_AGENTS.md b/AI_AGENTS.md index 530c548..31e44df 100644 --- a/AI_AGENTS.md +++ b/AI_AGENTS.md @@ -131,3 +131,177 @@ If this returns results, something violated the rules. --- *This file is the source of truth for AI agent behavior in this workspace.* + +--- + +## User QoL (Quality of Life) Considerations on Install + +*SAIF-processes/methodology — Structured AI Integration Framework* + +When setting up the Wave Toolkit or any SpiralSafe ecosystem repository, follow these installation QoL principles to ensure smooth onboarding and consistent execution across sessions. + +### 1. Absolute References + +**Always use absolute paths** rather than relative paths in scripts and configurations: + +```powershell +# ✅ Good: Absolute references +$WaveToolkitPath = "$HOME\wave-toolkit" +$ScriptPath = Join-Path $WaveToolkitPath "scripts\system" + +# ❌ Bad: Relative paths that break when working directory changes +$ScriptPath = ".\scripts\system" +``` + +**Why it matters:** +- AI agents may execute from different working directories +- Cron jobs and scheduled tasks don't inherit the expected `$PWD` +- Sub-processes spawned by agents start with unpredictable paths +- Cross-session persistence requires stable path anchors + +**Use these environment-aware patterns:** +```powershell +# Repository root detection (PowerShell 7+ ternary, or if-else for 5.1) +$gitRoot = git rev-parse --show-toplevel 2>$null +$RepoRoot = if ($gitRoot) { $gitRoot } else { $PSScriptRoot } + +# Cross-platform home directory +$UserHome = if ($IsWindows) { $env:USERPROFILE } else { $env:HOME } + +# Canonical Wave Toolkit path +$WaveRoot = Join-Path $UserHome "wave-toolkit" +``` + +### 2. Shell Aliases for Cross-Platform Support + +**Create aliases for native shell platforms** to ensure consistent command availability: + +```powershell +# PowerShell aliases for Unix-like commands +Set-Alias -Name ll -Value Get-ChildItem -Scope Global +Set-Alias -Name grep -Value Select-String -Scope Global +Set-Alias -Name touch -Value New-Item -Scope Global +Set-Alias -Name which -Value Get-Command -Scope Global + +# Export for persistence +Export-ModuleMember -Alias * -Function * +``` + +```cmd +:: CMD aliases (system_aliases.cmd) +@echo off +doskey ll=dir /a $* +doskey grep=findstr $* +doskey cat=type $* +doskey clear=cls +``` + +**Binding across execution frame 'event horizons':** + +When an AI agent spawns processes or hands off to sub-agents, aliases may not persist. To ensure binding: + +1. **Profile-level loading**: Add aliases to `$PROFILE` for automatic loading +2. **Explicit sourcing**: Source alias files at the start of each session +3. **Function wrappers**: Prefer functions over aliases for complex operations (functions export more reliably) + +```powershell +# Ensure aliases persist across PowerShell sessions +if (Test-Path "$HOME\wave-toolkit\scripts\system\aliases.ps1") { + . "$HOME\wave-toolkit\scripts\system\aliases.ps1" +} +``` + +### 3. Python Caching for CI/CD Workflows + +**Use `actions/setup-python@v5` with pip caching** to improve install performance in GitHub Actions: + +```yaml +# .github/workflows/ci.yml +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' # Enable pip dependency caching + cache-dependency-path: '**/requirements*.txt' + + - name: Install dependencies + run: pip install -r requirements.txt +``` + +**Why caching matters for QoL:** +- Reduces CI run time by 30-60 seconds per workflow +- Decreases load on package registries (pip, npm, etc.) +- Provides consistent dependency resolution across runs +- Enables faster iteration during development + +**For other package managers:** +```yaml +# Node.js with npm cache +- uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + +# PowerShell module caching (manual) +- name: Cache PowerShell modules + uses: actions/cache@v4 + with: + path: ~/.local/share/powershell/Modules + key: ${{ runner.os }}-pwsh-${{ hashFiles('**/requirements.psd1') }} +``` + +### 4. Bootstrap Verification Checklist + +When running `Setup-Wave.ps1` or similar bootstrap scripts, verify: + +| Check | Status | Recovery Action | +|-------|--------|-----------------| +| Git available | `git --version` | Install Git for Windows | +| PowerShell 7+ | `$PSVersionTable.PSVersion` | Install pwsh from Microsoft Store | +| Execution policy allows scripts | `Get-ExecutionPolicy` | `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` | +| Required directories exist | `Test-Path $WaveRoot` | Run bootstrap again | +| Profile is writable | `Test-Path $PROFILE` | Create profile directory | + +### 5. Event Horizon Boundaries + +**"Event horizons"** in this context refer to execution boundaries where context may be lost: + +- **New shell session**: Aliases, functions, and variables reset +- **Sub-process spawn**: Child processes don't inherit parent's aliases +- **Agent handoff**: When one AI agent delegates to another +- **Scheduled execution**: Cron/Task Scheduler runs have minimal environment + +**Mitigation strategies:** + +```powershell +# 1. Environment variable persistence +[Environment]::SetEnvironmentVariable("WAVE_ROOT", $WaveRoot, "User") + +# 2. Session checkpoint (for agent handoffs) +@{ + Timestamp = Get-Date -Format "o" + WaveRoot = $WaveRoot + Branch = git branch --show-current + Aliases = Get-Alias | Select-Object Name, Definition +} | ConvertTo-Json | Out-File ".wave-session.json" + +# 3. Reload on session start +if (Test-Path ".wave-session.json") { + $session = Get-Content ".wave-session.json" | ConvertFrom-Json + Write-Host "Resuming Wave session from $($session.Timestamp)" +} +``` + +--- + +## Related Documentation + +- **[Development Workflow](docs/guides/DEVELOPMENT_WORKFLOW.md)** — Session boundary errors and recovery patterns +- **[Wave Guide](wave.md)** — Philosophy and complete workflow guide +- **[Setup Script](Setup-Wave.ps1)** — One-time bootstrap implementation