Add User QoL install considerations to AI_AGENTS.md by Copilot · Pull Request #15 · toolate28/wave-toolkit

Copilot · 2026-01-20T21:59:05Z

Documents SAIF-processes/methodology for installation QoL across the SpiralSafe ecosystem. Addresses cross-session context loss and platform consistency issues.

Changes

Absolute references - Path resolution patterns that survive working directory changes and agent handoffs
Shell aliases - Cross-platform alias definitions (PowerShell + CMD) with profile-level persistence
Event horizon binding - Strategies for maintaining context across execution boundaries (sub-processes, agent delegation, scheduled tasks)
CI caching - actions/setup-python@v5 pip cache configuration with examples for npm/PowerShell
Bootstrap checklist - Verification table for Setup-Wave.ps1 prerequisites

Example: Repository root detection

# PowerShell 5.1+ compatible (avoids ?? operator issues)
$gitRoot = git rev-parse --show-toplevel 2>$null
$RepoRoot = if ($gitRoot) { $gitRoot } else { $PSScriptRoot }

Original prompt

On AI_AGENTS.md, Review our User QoL consideration process on install.

SAIF-processes/methodology

-absolute references
-creating aliases for the native shell platforms used and ensure binding across execution frame 'event horizons'

Python caching: Uses actions/setup-python@v5 with pip ca

╔═══════════════════════════════════════════════════════════╗
║ ║
║ KENL ECOSYSTEM BOOTSTRAP ║
║ Post-Clone Setup & Configuration ║
║ ║
║ Operational effectiveness • Flow • Execution panache ║
║ ║
╚═══════════════════════════════════════════════════════════╝

Starting bootstrap at 08:53:53
Repository: C:\Users\iamto\SpiralSafe

[1/8] Verifying System Dependencies
✅ Git found
✅ PowerShell 7+ found
✅ Bun Runtime found
✅ Cloudflare Wrangler found
⚠️ VS Code not found
ℹ️ Install hint: winget install Microsoft.VisualStudioCode

[2/8] Initializing Repository Structure
⚠️ Missing: env-config (expected in repository)
⚠️ Missing: frameworks (expected in repository)
✅ Verified: templates
⚠️ Missing: SpiralSafe (expected in repository)

[3/8] Initializing ATOM Trail
✅ ATOM trail exists (4 entries)

[4/8] Installing PowerShell Command Center
⚠️ Install-CommandCenter.ps1 not found

[5/8] Configuring Terminal Profiles
⚠️ Windows Terminal profile template not found

[6/8] Configuring Claude Code Settings
ℹ️ Claude Code settings will be created on first run
✅ Claude Code skills found (0 skills)

[7/8] Verifying VS Code Workspace
⚠️ Workspace file not found

[8/8] Creating Quick Start Commands
⚠️ Start-KenlEnvironment not found at C:\Users\iamto\SpiralSafe\env-config\Start-KenlEnvironment.ps1
⚠️ Write-AtomTrail not found at C:\Users\iamto\SpiralSafe\Write-AtomTrail.ps1
⚠️ View-AtomTrail not found at C:\Users\iamto\SpiralSafe\View-AtomTrail.ps1
ℹ️ Add to PATH or use full paths: .\env-config\Start-KenlEnvironment.ps1

╔═══════════════════════════════════════════════════════════╗
║ ║
║ 🎉 BOOTSTRAP COMPLETE ║
║ ║
║ Your KENL environment is ready for action! ║
║ ║
╚═══════════════════════════════════════════════════════════╝

[>] Quick Start Commands:

Start Environment:
.\env-config\Start-KenlEnvironment.ps1

View ATOM Trail:
.\View-AtomTrail.ps1

Open Workspace:
code kenl-workspace.code-workspace

Command Center (after profile reload):
cc # Show Command Center
ccref # Refresh display

[i] Documentation:

README.md - Overview
frameworks/SPIRALSAFE_FRAMEWORK.md - Core philosophy
frameworks/ULTRATHINK_PROTOCOL.md - Strategic thinking
PUBLICATION_MANIFEST_v1.0.md - All major works

[+] Next Steps:

Restart PowerShell (to load Command Center)

Run: .\env-config\Start-KenlEnvironment.ps1

Open: code kenl-workspace.code-workspace

[*] Optional:

Review docs/reports/verification/SYSTEM_VERIFICATION_REPORT.md for deployment status

Deploy SpiralSafe website: cd SpiralSafe && wrangler pages deploy .

Explore ClaudeNPC: cd claudenpc-server-suite

Bootstrap completed at 08:53:53
ATOM trail updated

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: toolate28 <105518313+toolate28@users.noreply.github.com>

Copilot

Pull request overview

This PR adds comprehensive user quality-of-life (QoL) documentation for installation and setup processes across the SpiralSafe ecosystem, focusing on SAIF (Structured AI Integration Framework) methodology. The documentation addresses common pain points in cross-session context preservation, path resolution, and platform consistency.

Changes:

Added detailed guidance on absolute path references to survive working directory changes
Documented shell alias creation patterns for PowerShell and CMD with cross-platform support
Provided CI/CD caching examples for Python, Node.js, and PowerShell packages
Included bootstrap verification checklist and event horizon boundary mitigation strategies

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-21T00:17:28Z

AI_AGENTS.md

+# Export for persistence
+Export-ModuleMember -Alias * -Function *


The Export-ModuleMember -Alias * -Function * command should only be used in module files (.psm1), not in profile scripts or standalone scripts. If these aliases are being defined in a profile or script, this line will cause an error. Consider clarifying the context where this command should be used, or providing separate examples for module vs profile scenarios.

Copilot · 2026-01-21T00:17:28Z

AI_AGENTS.md

+| 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 |


The table row for "Profile is writable" checks Test-Path $PROFILE, but this command only verifies if the profile file exists, not whether it's writable. To actually verify write permissions, consider using: Test-Path $PROFILE -PathType Leaf -ErrorAction SilentlyContinue; (Get-Item $PROFILE -ErrorAction SilentlyContinue).IsReadOnly -eq $false or a similar approach that specifically checks write access.

Suggested change

| Profile is writable | `Test-Path $PROFILE` | Create profile directory |

| Profile is writable | `Test-Path $PROFILE -PathType Leaf -ErrorAction SilentlyContinue -and -not (Get-Item $PROFILE -ErrorAction SilentlyContinue).IsReadOnly` | Create profile directory |

Copilot · 2026-01-21T00:17:29Z

AI_AGENTS.md

+# 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') }}


The PowerShell module cache path ~/.local/share/powershell/Modules is the Linux/macOS path for PowerShell modules. On Windows, the user module path is typically $HOME\Documents\PowerShell\Modules (PowerShell 7+) or $HOME\Documents\WindowsPowerShell\Modules (PowerShell 5.1). Consider using a platform-specific path or providing examples for different operating systems to ensure the cache works correctly in CI environments.

Suggested change

# 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') }}

# PowerShell module caching (manual, OS-specific paths)

# Linux/macOS

- name: Cache PowerShell modules (Linux/macOS)

if: runner.os != 'Windows'

uses: actions/cache@v4

with:

path: ~/.local/share/powershell/Modules

key: ${{ runner.os }}-pwsh-${{ hashFiles('**/requirements.psd1') }}

# Windows

- name: Cache PowerShell modules (Windows)

if: runner.os == 'Windows'

uses: actions/cache@v4

with:

path: |

${{ env.USERPROFILE }}\Documents\PowerShell\Modules

${{ env.USERPROFILE }}\Documents\WindowsPowerShell\Modules

key: ${{ runner.os }}-pwsh-${{ hashFiles('**/requirements.psd1') }}

Copilot · 2026-01-21T00:17:29Z

AI_AGENTS.md

+
+**Use these environment-aware patterns:**
+```powershell
+# Repository root detection (PowerShell 7+ ternary, or if-else for 5.1)


The comment mentions "PowerShell 7+ ternary" but the code example shown uses the if-else syntax that is compatible with PowerShell 5.1, not the ternary operator. The ternary operator in PowerShell 7+ would be: $RepoRoot = $gitRoot ?? $PSScriptRoot. Consider updating the comment to accurately reflect that this example is specifically for PowerShell 5.1 compatibility, or clarify that both syntaxes work but this one is more compatible.

Suggested change

# Repository root detection (PowerShell 7+ ternary, or if-else for 5.1)

# Repository root detection (PowerShell 5.1-compatible; in PS 7+ you can use: $RepoRoot = $gitRoot ?? $PSScriptRoot)

Copilot · 2026-01-21T00:17:29Z

AI_AGENTS.md

+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


The Set-Alias command with -Scope Global may not work as expected within a script context unless the script is dot-sourced. When run in a script, global aliases typically only persist for the script's session and do not automatically persist to the user's profile. Consider clarifying that these aliases should be added to the PowerShell profile for persistence, or that the script containing them should be dot-sourced.

Suggested change

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

# For persistence, add these lines to your PowerShell profile (e.g. $PROFILE)

# or dot-source a script that defines them: . "$WaveRoot\tools\aliases.ps1"

Set-Alias -Name ll -Value Get-ChildItem

Set-Alias -Name grep -Value Select-String

Set-Alias -Name touch -Value New-Item

Set-Alias -Name which -Value Get-Command

# Export for persistence when used inside a module

Copilot · 2026-01-21T00:17:30Z

AI_AGENTS.md

+# 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


The alias touch pointing to New-Item is incomplete and will not work as expected for creating empty files (the typical Unix touch behavior). New-Item requires additional parameters like -ItemType File. Consider changing this to a function wrapper instead: function touch { New-Item -ItemType File -Path $args }

Suggested change

Set-Alias -Name touch -Value New-Item -Scope Global

function touch {

New-Item -ItemType File -Path $args

}

Copilot · 2026-01-21T00:17:30Z

AI_AGENTS.md

+# Cross-platform home directory
+$UserHome = if ($IsWindows) { $env:USERPROFILE } else { $env:HOME }


The cross-platform home directory check uses $IsWindows, which is an automatic variable available in PowerShell 6+. However, this section already mentions compatibility with PowerShell 5.1 in line 164. For PowerShell 5.1 compatibility, consider using: $UserHome = if ($PSVersionTable.PSVersion.Major -ge 6 -and -not $IsWindows) { $env:HOME } else { $env:USERPROFILE } or simply $UserHome = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }

Suggested change

# Cross-platform home directory

$UserHome = if ($IsWindows) { $env:USERPROFILE } else { $env:HOME }

# Cross-platform home directory (PowerShell 5.1+ safe)

$UserHome = if ($env:HOME) { $env:HOME } else { $env:USERPROFILE }

Copilot · 2026-01-21T00:17:30Z

AI_AGENTS.md

+@{
+    Timestamp = Get-Date -Format "o"
+    WaveRoot = $WaveRoot
+    Branch = git branch --show-current


The command git branch --show-current requires Git 2.22 or later (released in June 2019). While this is generally safe to assume in modern environments, for broader compatibility with older Git installations, consider using: git rev-parse --abbrev-ref HEAD as an alternative, or document the Git version requirement in the prerequisites.

Suggested change

Branch = git branch --show-current

Branch = git rev-parse --abbrev-ref HEAD

toolate28 · 2026-01-21T04:54:34Z

@copilot apply changes based on the comments in this thread

Initial plan

192411a

Copilot AI assigned Copilot and toolate28 Jan 20, 2026

Copilot started work on behalf of toolate28 January 20, 2026 21:59 View session

Add User QoL consideration process on install to AI_AGENTS.md

35ca305

Co-authored-by: toolate28 <105518313+toolate28@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Review user QoL consideration process on installation~~ Add User QoL install considerations to AI_AGENTS.md Jan 20, 2026

Copilot AI requested a review from toolate28 January 20, 2026 22:02

Copilot finished work on behalf of toolate28 January 20, 2026 22:02

toolate28 approved these changes Jan 21, 2026

View reviewed changes

toolate28 marked this pull request as ready for review January 21, 2026 00:13

Copilot AI review requested due to automatic review settings January 21, 2026 00:13

toolate28 merged commit 31c7ff6 into main Jan 21, 2026
1 check passed

toolate28 deleted the copilot/review-user-qol-install-process branch January 21, 2026 00:13

Copilot started reviewing on behalf of toolate28 January 21, 2026 00:13 View session

Copilot AI reviewed Jan 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add User QoL install considerations to AI_AGENTS.md#15

Add User QoL install considerations to AI_AGENTS.md#15
toolate28 merged 2 commits intomainfrom
copilot/review-user-qol-install-process

Copilot AI commented Jan 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

Copilot AI Jan 21, 2026

Uh oh!

toolate28 commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		# Export for persistence
		Export-ModuleMember -Alias * -Function *

	\| Profile is writable \| `Test-Path $PROFILE` \| Create profile directory \|
	\| Profile is writable \| `Test-Path $PROFILE -PathType Leaf -ErrorAction SilentlyContinue -and -not (Get-Item $PROFILE -ErrorAction SilentlyContinue).IsReadOnly` \| Create profile directory \|

	# Repository root detection (PowerShell 7+ ternary, or if-else for 5.1)
	# Repository root detection (PowerShell 5.1-compatible; in PS 7+ you can use: $RepoRoot = $gitRoot ?? $PSScriptRoot)

-Set-Alias -Name touch -Value New-Item -Scope Global
+function touch {
+    New-Item -ItemType File -Path $args
+}

		# Cross-platform home directory
		$UserHome = if ($IsWindows) { $env:USERPROFILE } else { $env:HOME }

	Branch = git branch --show-current
	Branch = git rev-parse --abbrev-ref HEAD

Comments

Conversation

Copilot AI commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Example: Repository root detection

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

toolate28 commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Jan 20, 2026 •

edited

Loading