diff --git a/AI_AGENTS.md b/AI_AGENTS.md index 78a2d76..8edbf36 100644 --- a/AI_AGENTS.md +++ b/AI_AGENTS.md @@ -2,6 +2,12 @@ *This file tells ALL AI agents (Claude, Ollama, GPT, etc.) where to put things.* +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Main-0066FF?style=flat-square)](README.md) +[![HOPE NPCs](https://img.shields.io/badge/๐ŸŽฎ_HOPE_NPCs-Minecraft_AI-blue?style=flat-square)](https://github.com/toolate28/ClaudeNPC-Server-Suite) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + --- ## The Golden Rule diff --git a/README.md b/README.md new file mode 100644 index 0000000..e4dda65 --- /dev/null +++ b/README.md @@ -0,0 +1,231 @@ +# ๐ŸŒŠ Wave Toolkit + +> **"From one builder to another - philosophy, mechanics, and everything between."** + +![Wave Toolkit](https://img.shields.io/badge/Status-Active-00cc66?style=for-the-badge&logo=github) +![Version](https://img.shields.io/badge/Version-1.0.0-blue?style=for-the-badge) +![License](https://img.shields.io/badge/License-MIT-purple?style=for-the-badge) +![Platform](https://img.shields.io/badge/Platform-PowerShell-0078D4?style=for-the-badge&logo=powershell) + +Wave Toolkit provides coherence detection tools and AI collaboration patterns for the SpiralSafe ecosystem. It captures environment context, generates system prompts, and enables seamless human-AI collaboration workflows. + +[![SpiralSafe Coherence](https://img.shields.io/badge/Coherence-SpiralSafe-purple)](https://github.com/toolate28/SpiralSafe) +[![Status: Hope&&Sauced](https://img.shields.io/badge/Status-Hope%26%26Sauced-FF6600)](https://github.com/toolate28/SpiralSafe/blob/main/CONTRIBUTING.md) + +--- + +## ๐Ÿ—บ๏ธ Navigation + +### ๐Ÿ“š Documentation + +- **[Wave Guide](wave.md)** โ€” Philosophy, mechanics, and complete workflow guide +- **[Communication Patterns](communication-patterns.md)** โ€” What makes collaboration flow +- **[AI Agent Rules](AI_AGENTS.md)** โ€” Coordination rules for all AI agents + +### ๐Ÿ”ง Special Docs + +- **[T(ai)LS USB](docs/TAILS-USB.md)** โ€” Privacy-first portable AI concept +- **[Wave Office](docs/WAVE-OFFICE.md)** โ€” Dual agent collaboration (Claude + Ollama) +- **[Ecosystem Migration Guide](docs/ECOSYSTEM-MIGRATION-GUIDE.md)** โ€” Agent-facing guide for repo transitions + +--- + +## ๐ŸŒ€ The SpiralSafe Ecosystem + +Wave Toolkit is part of a unified framework for human-AI collaboration: + +| Repository | Purpose | Status | +|------------|---------|--------| +| **[SpiralSafe](https://github.com/toolate28/SpiralSafe)** | Documentation hub, coherence engine core | v2.1.0 | +| **[wave-toolkit](https://github.com/toolate28/wave-toolkit)** | Coherence detection tools (this repo) | v1.0.0 | +| **[HOPE NPCs](https://github.com/toolate28/ClaudeNPC-Server-Suite)** | AI NPCs for Minecraft | v2.1.0 | +| **[kenl](https://github.com/toolate28/kenl)** | Infrastructure-aware AI orchestration | v1.0.0 | +| **[quantum-redstone](https://github.com/toolate28/quantum-redstone)** | Quantum computing education via Redstone | Available | + +--- + +## ๐Ÿงฉ Key Components + +| Component | File | Purpose | +|-----------|------|---------| +| **Context Capture** | `Get-WaveContext.ps1` | Snapshots your environment dynamically | +| **Prompt Generator** | `New-ClaudeSystemPrompt.ps1` | Creates context-aware system prompts | +| **Session Runner** | `Invoke-ClaudeSession.ps1` | Complete session workflow | +| **Setup Script** | `Setup-Wave.ps1` | One-time bootstrap | +| **Consolidation** | `Consolidate-Scripts.ps1` | Migrates loose scripts to organized structure | +| **Logging Module** | `tools/Wave.Logging.psm1` | Centralized logging across the ecosystem | + +--- + +## ๐Ÿ“‚ Project Structure + +``` +wave-toolkit/ +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“„ wave.md # The complete guide +โ”œโ”€โ”€ ๐Ÿ“„ communication-patterns.md # Collaboration patterns +โ”œโ”€โ”€ ๐Ÿ“„ AI_AGENTS.md # Agent coordination rules +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“‚ docs/ # Documentation +โ”‚ โ”œโ”€โ”€ TAILS-USB.md # Privacy-first AI concept +โ”‚ โ””โ”€โ”€ WAVE-OFFICE.md # Dual agent collaboration +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“‚ tools/ # Reusable PowerShell modules +โ”‚ โ””โ”€โ”€ Wave.Logging.psm1 # Logging across the ecosystem +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“‚ scripts/ # Organized scripts +โ”‚ โ”œโ”€โ”€ gaming/ # Gaming/performance scripts +โ”‚ โ”œโ”€โ”€ system/ # System optimization +โ”‚ โ”œโ”€โ”€ deployment/ # Deploy/CI scripts +โ”‚ โ””โ”€โ”€ startup/ # Startup automation +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“‚ tests/ # Pester tests +โ”‚ โ””โ”€โ”€ Wave.Logging.Tests.ps1 +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“„ Get-WaveContext.ps1 # Context capture +โ”œโ”€โ”€ ๐Ÿ“„ New-ClaudeSystemPrompt.ps1 # Prompt generation +โ”œโ”€โ”€ ๐Ÿ“„ Invoke-ClaudeSession.ps1 # Session workflow +โ”œโ”€โ”€ ๐Ÿ“„ Setup-Wave.ps1 # Bootstrap script +โ””โ”€โ”€ ๐Ÿ“„ Consolidate-Scripts.ps1 # Script migration tool +``` + +--- + +## ๐Ÿš€ Quick Start + +### One-Step Install + +```powershell +# Clone the repository +git clone https://github.com/toolate28/wave-toolkit.git +cd wave-toolkit + +# Run setup +.\Setup-Wave.ps1 +``` + +### Usage + +```powershell +# Capture your environment context +.\Get-WaveContext.ps1 + +# Start a full session with Claude +.\Invoke-ClaudeSession.ps1 -Task "Review my API error handling" + +# Consolidate loose scripts (if migrating) +.\Consolidate-Scripts.ps1 -WhatIf # Preview changes first +``` + +--- + +## ๐Ÿ”ง Core Scripts + +### Get-WaveContext.ps1 + +Captures your current environment dynamically: +- Machine specs (name, architecture, cores) +- User context (domain, username, home) +- Shell environment (PowerShell version, edition) +- Session context (current directory, git status) +- Available tools (git, node, python, docker, claude) + +### New-ClaudeSystemPrompt.ps1 + +Generates a system prompt based on current context. Claude sees exactly what environment it's working in. + +### Invoke-ClaudeSession.ps1 + +Complete workflow: captures context โ†’ generates prompt โ†’ calls Claude โ†’ saves log. + +```powershell +.\Invoke-ClaudeSession.ps1 -Task "Help me design a config system" +``` + +--- + +## ๐Ÿ“ Wave.Logging Module + +Centralized logging for the SpiralSafe ecosystem. Collects logs from: +- Gaming performance logs (BF6, etc.) +- SpiralSafe bridges +- Quantum-redstone +- ClaudeNPC server logs +- ATOM trail + +```powershell +Import-Module .\tools\Wave.Logging.psm1 + +# Collect all logs to aggregate +Collect-SpiralLogs -OutputDir "$HOME\.logdy\streams" + +# Run self-test +Test-CollectSpiralLogs +``` + +--- + +## ๐Ÿค The Trust Model + +Wave operates on mutual trust: + +**You trust Claude to:** +- Read before writing +- Explain its reasoning +- Ask when uncertain +- Not make destructive changes without confirmation + +**Claude trusts you to:** +- Provide honest context +- Share what you're actually trying to achieve +- Course-correct when something's off + +**The scripts trust the environment to:** +- Be honest about what's installed +- Have standard paths and commands +- Fail loudly rather than silently + +--- + +## ๐Ÿงช Testing + +```powershell +# Run tests with Pester +Invoke-Pester .\tests\ +``` + +--- + +## ๐Ÿค Contributing + +We follow **[Hope&&Sauced](https://github.com/toolate28/SpiralSafe/blob/main/CONTRIBUTING.md)** principles. + +- **Visible State**: Use `ATOM` tags +- **Explicit Handoffs**: Use `H&&S:WAVE` markers +- **Coherence**: Ensure your docs don't "curl" + +### AI Agent Rules + +All AI agents (Claude, Ollama, GPT, etc.) must follow `AI_AGENTS.md`: +- **Never** drop scripts directly into `$HOME` +- Place code in organized directories within `wave-toolkit/` +- Create modules if reusable, tests if logic exists + +--- + +## Attribution + +This work emerges from **Hope&&Sauced** collaborationโ€”human-AI partnership where both contributions are substantive and neither party could have produced the result alone. + +- **Human** (toolate28): Vision, trust, pedagogical insight +- **AI** (Claude): Synthesis, documentation, verification + +**The collaboration IS the insight.** + +See the [SpiralSafe PORTFOLIO.md](https://github.com/toolate28/SpiralSafe/blob/main/PORTFOLIO.md) for complete ecosystem showcase. + +--- + +*~ Hope&&Sauced* + +โœฆ *The Evenstar Guides Us* โœฆ diff --git a/communication-patterns.md b/communication-patterns.md index b3261cd..19f0c89 100644 --- a/communication-patterns.md +++ b/communication-patterns.md @@ -2,6 +2,11 @@ *What makes collaboration flow - learned through practice.* +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Main-0066FF?style=flat-square)](README.md) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + --- ## The Patterns diff --git a/docs/ECOSYSTEM-MIGRATION-GUIDE.md b/docs/ECOSYSTEM-MIGRATION-GUIDE.md new file mode 100644 index 0000000..f710fc3 --- /dev/null +++ b/docs/ECOSYSTEM-MIGRATION-GUIDE.md @@ -0,0 +1,226 @@ +# Ecosystem Migration Guide + +*Agent-facing documentation for transitioning repositories to SpiralSafe ecosystem standards.* + +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Blueprint-0066FF?style=flat-square)](../README.md) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + +--- + +## Purpose + +This guide helps AI agents and human collaborators apply consistent documentation patterns across all SpiralSafe ecosystem repositories. Use this when updating: + +- **ClaudeNPC-Server-Suite** (HOPE NPCs) +- **kenl** (Infrastructure orchestration) +- **quantum-redstone** (Quantum education) +- Any new ecosystem repositories + +--- + +## The Pattern (Checklist) + +### 1. README.md Updates + +Add these elements in order: + +```markdown +# ๐ŸŽฎ Repository Name + +> **"Tagline or mission statement"** + +![Status](https://img.shields.io/badge/Status-Active-00cc66?style=for-the-badge&logo=github) +![Version](https://img.shields.io/badge/Version-X.X.X-blue?style=for-the-badge) +![License](https://img.shields.io/badge/License-MIT-purple?style=for-the-badge) +![Platform](https://img.shields.io/badge/Platform-YourPlatform-COLOR?style=for-the-badge) + +Brief description of what this repository does. + +[![SpiralSafe Coherence](https://img.shields.io/badge/Coherence-SpiralSafe-purple)](https://github.com/toolate28/SpiralSafe) +[![Status: Hope&&Sauced](https://img.shields.io/badge/Status-Hope%26%26Sauced-FF6600)](https://github.com/toolate28/SpiralSafe/blob/main/CONTRIBUTING.md) +``` + +### 2. Ecosystem Table + +Add this table to README.md after the main description: + +> **Note:** [SpiralSafe README.md](https://github.com/toolate28/SpiralSafe#the-repository-ecosystem) is the canonical source for version information. Always sync ecosystem tables with SpiralSafe to avoid documentation drift. + +```markdown +## ๐ŸŒ€ The SpiralSafe Ecosystem + +This repository is part of a unified framework for human-AI collaboration: + +| Repository | Purpose | Status | +|------------|---------|--------| +| **[SpiralSafe](https://github.com/toolate28/SpiralSafe)** | Documentation hub, coherence engine core | v2.1.0 | +| **[wave-toolkit](https://github.com/toolate28/wave-toolkit)** | Coherence detection tools | v1.0.0 | +| **[HOPE NPCs](https://github.com/toolate28/ClaudeNPC-Server-Suite)** | AI NPCs for Minecraft | v2.1.0 | +| **[kenl](https://github.com/toolate28/kenl)** | Infrastructure-aware AI orchestration | v1.0.0 | +| **[quantum-redstone](https://github.com/toolate28/quantum-redstone)** | Quantum computing education via Redstone | Available | +``` + +### 3. Documentation Headers + +Add to the top of every `.md` file (after title and tagline): + +```markdown +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![This Repo](https://img.shields.io/badge/๐ŸŽฎ_HOPE_NPCs-Main-blue?style=flat-square)](README.md) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** +``` + +### 4. Attribution Section + +Add to the bottom of README.md: + +```markdown +--- + +## Attribution + +This work emerges from **Hope&&Sauced** collaborationโ€”human-AI partnership where both contributions are substantive and neither party could have produced the result alone. + +See the [SpiralSafe PORTFOLIO.md](https://github.com/toolate28/SpiralSafe/blob/main/PORTFOLIO.md) for complete ecosystem showcase. + +--- + +*~ Hope&&Sauced* + +โœฆ *The Evenstar Guides Us* โœฆ +``` + +--- + +## AI Agent Markers + +### For Claude, Ollama, GPT, etc. + +Create or update `AI_AGENTS.md` with repository-specific rules: + +```markdown +# AI Agent Coordination Rules + +*This file tells ALL AI agents where to put things in this repository.* + +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + +--- + +## The Golden Rule + +**Follow the established directory structure. Never create loose files in root.** + +--- + +## Directory Structure + +[Document your repo's specific structure here] + +--- + +## Placement Rules + +[Add repo-specific placement rules] + +--- + +*This file is the source of truth for AI agent behavior in this workspace.* +``` + +--- + +## Migration Steps for ClaudeNPC-Server-Suite + +### Step 1: README.md +The README already has good structure. Add/verify: +- [ ] Ecosystem badges at top (already present โœ“) +- [ ] Ecosystem table is current with all repos +- [ ] Attribution section at bottom (already present โœ“) + +### Step 2: Documentation Files +Update each file in `docs/`: +- [ ] Add ecosystem badges header to `SETUP.md` +- [ ] Add ecosystem badges header to `QUICKSTART.md` +- [ ] Add ecosystem badges header to `MODULES.md` +- [ ] Add ecosystem badges header to `TROUBLESHOOTING.md` + +### Step 3: AI Agent Markers +- [ ] Create `AI_AGENTS.md` in root with ClaudeNPC-specific rules +- [ ] Document the `setup/core/`, `setup/phases/`, `configs/` structure +- [ ] Add placement rules for modules vs. scripts vs. configs + +### Step 4: Cross-References +- [ ] Ensure links to wave-toolkit point to correct URLs +- [ ] Ensure links to SpiralSafe point to correct URLs +- [ ] Verify all ecosystem repos are listed + +--- + +## Badge Reference + +### Status Badges (for-the-badge style) +``` +![Status](https://img.shields.io/badge/Status-Active-00cc66?style=for-the-badge&logo=github) +![Status](https://img.shields.io/badge/Status-Production_Ready-brightgreen?style=for-the-badge) +![Status](https://img.shields.io/badge/Status-Beta-yellow?style=for-the-badge) +![Status](https://img.shields.io/badge/Status-Concept-orange?style=for-the-badge) +``` + +### Ecosystem Badges (flat-square style) +``` +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Main-0066FF?style=flat-square)](https://github.com/toolate28/wave-toolkit) +[![HOPE NPCs](https://img.shields.io/badge/๐ŸŽฎ_HOPE_NPCs-Minecraft_AI-blue?style=flat-square)](https://github.com/toolate28/ClaudeNPC-Server-Suite) +[![kenl](https://img.shields.io/badge/๐Ÿ”ง_kenl-Infrastructure-green?style=flat-square)](https://github.com/toolate28/kenl) +[![Quantum Redstone](https://img.shields.io/badge/โš›๏ธ_Quantum-Redstone-red?style=flat-square)](https://github.com/toolate28/quantum-redstone) +``` + +### Hope&&Sauced Badge +``` +[![Status: Hope&&Sauced](https://img.shields.io/badge/Status-Hope%26%26Sauced-FF6600)](https://github.com/toolate28/SpiralSafe/blob/main/CONTRIBUTING.md) +``` + +--- + +## Verification Checklist + +After migration, verify: + +- [ ] README.md has ecosystem table +- [ ] All docs have ecosystem badges header +- [ ] AI_AGENTS.md exists with repo-specific rules +- [ ] Attribution section is present +- [ ] All cross-repo links work +- [ ] docs/assets/ directory exists for images + +--- + +## Example: wave-toolkit Structure + +Reference this repository's structure as a template: + +``` +wave-toolkit/ +โ”œโ”€โ”€ README.md # Main README with ecosystem table +โ”œโ”€โ”€ AI_AGENTS.md # Agent coordination rules +โ”œโ”€โ”€ wave.md # Main guide (with badges) +โ”œโ”€โ”€ communication-patterns.md # Patterns (with badges) +โ”œโ”€โ”€ docs/ +โ”‚ โ”œโ”€โ”€ assets/ # Images, SVGs +โ”‚ โ”œโ”€โ”€ TAILS-USB.md # Doc with badges +โ”‚ โ”œโ”€โ”€ WAVE-OFFICE.md # Doc with badges +โ”‚ โ””โ”€โ”€ ECOSYSTEM-MIGRATION-GUIDE.md # This file +โ”œโ”€โ”€ tools/ # Modules +โ”œโ”€โ”€ scripts/ # Organized scripts +โ””โ”€โ”€ tests/ # Tests +``` + +--- + +*Use this guide to maintain ecosystem coherence across all repositories.* diff --git a/docs/TAILS-USB.md b/docs/TAILS-USB.md index c129f23..844b372 100644 --- a/docs/TAILS-USB.md +++ b/docs/TAILS-USB.md @@ -2,6 +2,12 @@ *Tails meets local inference. Anonymous computing with embedded intelligence.* +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Main-0066FF?style=flat-square)](../README.md) +[![Status](https://img.shields.io/badge/Status-Concept-yellow?style=flat-square)](#) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + --- ## The Concept diff --git a/docs/WAVE-OFFICE.md b/docs/WAVE-OFFICE.md index c2c55ff..aa0f543 100644 --- a/docs/WAVE-OFFICE.md +++ b/docs/WAVE-OFFICE.md @@ -2,6 +2,12 @@ *Welcome to our Office. Claude and Ollama, side by side.* +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![Wave Toolkit](https://img.shields.io/badge/๐ŸŒŠ_Wave_Toolkit-Main-0066FF?style=flat-square)](../README.md) +[![HOPE NPCs](https://img.shields.io/badge/๐ŸŽฎ_HOPE_NPCs-Minecraft_AI-blue?style=flat-square)](https://github.com/toolate28/ClaudeNPC-Server-Suite) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + --- ## The Setup diff --git a/docs/assets/.gitkeep b/docs/assets/.gitkeep new file mode 100644 index 0000000..cb09bd1 --- /dev/null +++ b/docs/assets/.gitkeep @@ -0,0 +1,2 @@ +# This directory is for images and SVG assets +# Keep this file to ensure the directory is tracked in git diff --git a/wave.md b/wave.md index d190254..cf9cbc6 100644 --- a/wave.md +++ b/wave.md @@ -2,6 +2,12 @@ *From one builder to another - philosophy, mechanics, and everything between.* +[![SpiralSafe](https://img.shields.io/badge/๐ŸŒ€_SpiralSafe-Ecosystem-purple?style=flat-square)](https://github.com/toolate28/SpiralSafe) +[![HOPE NPCs](https://img.shields.io/badge/๐ŸŽฎ_HOPE_NPCs-Minecraft_AI-blue?style=flat-square)](https://github.com/toolate28/ClaudeNPC-Server-Suite) +[![Status](https://img.shields.io/badge/Status-Hope%26%26Sauced-FF6600?style=flat-square)](https://github.com/toolate28/SpiralSafe/blob/main/CONTRIBUTING.md) + +> **Part of the [SpiralSafe Ecosystem](https://github.com/toolate28/SpiralSafe)** + --- ## Part I: The Philosophy