@miller-tech/uap 1.0.0

package/docs/getting-started/OVERVIEW.md

@@ -0,0 +1,344 @@
+# UAP - Universal Agent Protocol
+
+**A persistent memory system for autonomous AI agents**
+
+UAP (Universal Agent Protocol) provides a standardized framework for AI agents to maintain persistent context, learn from past interactions, and apply proven patterns across tasks.
+
+---
+
+## What is UAP?
+
+UAP is an open protocol that enables AI agents to:
+
+1. **Remember Context**: Store and retrieve relevant information across sessions
+2. **Apply Patterns**: Leverage battle-tested workflows and decision frameworks
+3. **Maintain State**: Track progress, failures, and successes over time
+4. **Collaborate**: Coordinate with other agents using shared memory
+
+Unlike temporary context windows, UAP provides **persistent memory** that survives session boundaries, enabling true long-term learning and improvement.
+
+---
+
+## Core Components
+
+### 1. Memory System (4-Layer Architecture)
+
+| Layer | Type                        | Purpose                             | Speed |
+| ----- | --------------------------- | ----------------------------------- | ----- |
+| L1    | SQLite (`memories`)         | Working context, recent decisions   | <1ms  |
+| L2    | SQLite (`session_memories`) | Current task session state          | <5ms  |
+| L3    | Qdrant (vector DB)          | Semantic search across all memories | ~50ms |
+| L4    | SQLite (entities/rels)      | Knowledge graph of relationships    | <20ms |
+
+### 2. CLAUDE.md Protocol
+
+Every UAP-enabled project includes a `CLAUDE.md` file that defines:
+
+- **Directive Hierarchy**: Which rules take precedence
+- **Decision Loop**: Standard workflow for any task
+- **Patterns**: 58+ battle-tested patterns for common scenarios
+- **Skills**: Domain-specific expertise (chess, compression, debugging)
+- **Completion Gates**: Mandatory checks before declaring success
+
+### 3. CLI Tools
+
+```bash
+# Initialize UAP in a project
+uap init
+
+# Create a tracked task with memory
+uap task create --title "Fix login bug" --type bug
+
+# Query semantic memory
+uap memory query "authentication errors"
+
+# Manage worktrees for parallel development
+uap worktree create fix-auth-issue
+```
+
+### 4. Worktree Workflow
+
+UAP enforces a **worktree-only** workflow to prevent accidental changes to main branches:
+
+```bash
+# Create worktree for any change (even single file)
+uap worktree create bugfix-description
+
+# Make changes, commit, create PR
+cd .worktrees/NNN-bugfix-description/
+git add -A && git commit -m "type: description"
+uap worktree pr 123
+
+# After merge, cleanup is mandatory
+uap worktree cleanup 123
+```
+
+---
+
+## How It Works
+
+### Task Execution Flow
+
+```
+1. CLASSIFY → Is this complex? Does it need memory?
+2. PROTECT   → Backup critical files (configs, DBs)
+3. MEMORY    → Query relevant context + past failures
+4. SKILLS    → Load domain-specific patterns if needed
+5. WORK      → Implement using worktree
+6. REVIEW    → Self-review diff before testing
+7. TEST      → Run verifier/tests minimum 3 times
+8. LEARN     → Store outcome in memory for future tasks
+```
+
+### Memory Retrieval
+
+When starting a task, UAP automatically:
+
+1. **Classifies** the task type (coding, debugging, research, etc.)
+2. **Queries** L1/L2 memory for recent relevant decisions
+3. **Searches** L3 semantic memory for similar past tasks
+4. **Loads** L4 knowledge graph for entity relationships
+5. **Applies** patterns based on classification confidence
+
+### Pattern Router
+
+UAP includes 58+ patterns for common scenarios:
+
+| Pattern ID | Trigger                 | Action                              |
+| ---------- | ----------------------- | ----------------------------------- |
+| P3         | Modifies config/DB      | `cp file file.bak` first            |
+| P12        | Creates files           | `ls -la` verify all outputs exist   |
+| P13        | Tests partial pass      | Fix specific failure, re-run        |
+| P26        | Same error twice        | Change approach completely          |
+| P32        | CLI tool                | Test `./script` not `python script` |
+| P37        | Output format specified | Diff output schema vs expectations  |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+- Optional: Docker (for Qdrant semantic search)
+
+### Quick Start
+
+```bash
+# Install globally
+npm install -g universal-agent-protocol
+
+# Initialize in your project
+uap init
+
+# Run the interactive setup
+npx universal-agent-protocol init --interactive
+```
+
+### With Qdrant (Recommended for Full Features)
+
+```bash
+cd agents && docker-compose up -d
+```
+
+---
+
+## Configuration
+
+### `.uap.json` - Project Settings
+
+```json
+{
+  "project": {
+    "name": "my-project",
+    "description": "Project with UAP memory"
+  },
+  "memory": {
+    "shortTerm": {
+      "enabled": true,
+      "path": "./agents/data/memory/short_term.db"
+    },
+    "longTerm": {
+      "enabled": true,
+      "provider": "qdrant",
+      "endpoint": "localhost:6333"
+    }
+  },
+  "worktrees": {
+    "enabled": true,
+    "directory": ".worktrees"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+- Use `uap task create` for all work items
+- Always use worktrees (never commit to main directly)
+- Run verifier/tests minimum 3 times before declaring done
+- Store outcomes in memory after completing tasks
+- Load relevant skills for domain-specific tasks
+
+### DON'T ❌
+
+- Commit directly to main/develop branches
+- Skip backup steps when modifying critical files
+- Declare success without running tests multiple times
+- Ignore pattern recommendations (they prevent bugs)
+- Leave merged worktrees uncleand
+
+---
+
+## Protocol Compliance
+
+UAP enforces **completion gates** before any task is considered done:
+
+```
+[x] If decoder provided: round-trip passes (BLOCKING)
+[x] Outputs verified: ls -la shows all files exist
+[x] Schema diffed against test expectations
+[x] Tests: X/Y pass (must be 100%, run 3+ times)
+[x] CLI tools tested as ./script not python script
+[x] If recovery: artifacts copied before read operation
+```
+
+Run compliance check:
+
+```bash
+npm run verify-uap
+# or
+uap compliance check
+```
+
+---
+
+## Integration Points
+
+### Claude Code
+
+UAP integrates with Anthropic's Claude Code via session hooks:
+
+```bash
+uap hooks install
+```
+
+This adds automatic memory queries at task start and outcome storage on completion.
+
+### Factory.AI
+
+UAP provides skills for Factory.AI droids:
+
+- `@Skill:chess-engine.md` - Chess pattern matching
+- `@Skill:compression.md` - Information-theoretic limits
+- `@Skill:adversarial.md` - Security vulnerability analysis
+- `@Skill:git-forensics.md` - Repository recovery
+
+### Multi-Agent Coordination
+
+UAP detects overlapping work between agents via:
+
+```bash
+uap coordination check --agents agent1,agent2,agent3
+```
+
+This prevents duplicate effort and identifies collaboration opportunities.
+
+---
+
+## API Reference
+
+### Memory Operations
+
+```typescript
+// Store a memory
+await uap.memory.store('Always validate CSRF tokens in auth flows');
+
+// Query memories
+const results = await uap.memory.query('authentication security', {
+  topK: 5,
+  scoreThreshold: 0.35,
+});
+
+// Clear session memory
+await uap.memory.clearSession();
+```
+
+### Task Management
+
+```typescript
+// Create a task
+const task = await uap.task.create({
+  title: 'Implement rate limiting',
+  type: 'feature',
+  priority: 'high',
+});
+
+// Update task status
+await uap.task.update(task.id, { status: 'in_progress' });
+
+// Get task with memory context
+const enrichedTask = await uap.task.get(task.id, { includeMemory: true });
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Error                      | Solution                                          |
+| -------------------------- | ------------------------------------------------- |
+| `ModuleNotFoundError`      | Run `npm install` after cloning                   |
+| `Qdrant connection failed` | Start Docker: `cd agents && docker-compose up -d` |
+| `Worktree already exists`  | Use `uap worktree cleanup <id>` first             |
+| `Memory DB locked`         | Close other processes using the DB                |
+| `Compliance check failed`  | Review specific gate failure in output            |
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+export UAP_VERBOSE=true
+
+# Check memory queries
+uap task ready --verbose
+
+# Inspect database directly
+sqlite3 ./agents/data/memory/short_term.db ".tables"
+```
+
+---
+
+## Contributing
+
+UAP is open source. Contributions welcome:
+
+1. Fork the repository
+2. Create a worktree: `uap worktree create feature-name`
+3. Make changes and run tests: `npm test`
+4. Submit PR via `uap worktree pr <id>`
+
+### Development Setup
+
+```bash
+git clone https://github.com/DammianMiller/universal-agent-protocol.git
+cd universal-agent-protocol
+npm install
+npm run build
+npm test
+```
+
+---
+
+## License
+
+MIT License - See [LICENSE](../LICENSE) file
+
+**Maintained By**: UAP Team  
+**Repository**: https://github.com/DammianMiller/universal-agent-protocol  
+**Issues**: https://github.com/DammianMiller/universal-agent-protocol/issues

package/docs/getting-started/SETUP.md

@@ -0,0 +1,203 @@
+# UAP Setup Guide
+
+Complete setup instructions for Universal Agent Memory.
+
+## Quick Setup
+
+```bash
+# Install UAP CLI
+npm install -g universal-agent-protocol
+
+# Run comprehensive setup
+npm run setup
+
+# Initialize in your project
+uap init
+```
+
+## Dependencies
+
+### Required
+
+- **Node.js >= 18.0.0** - Runtime environment
+- **npm** - Package manager
+- **git** - Version control (required for git hooks)
+- **npx** - Runs CLI tools (included with npm)
+
+### Optional but Recommended
+
+- **Docker** - Enables local Qdrant for semantic search
+- **Python 3** - Enables Pattern RAG indexing
+- **pre-commit** - Provides advanced git hooks
+
+## Installation by Platform
+
+### macOS
+
+```bash
+# Install all dependencies
+brew install node@18 git python docker
+
+# Install UAP
+npm install -g universal-agent-protocol
+
+# Run setup
+npm run setup
+```
+
+### Ubuntu/Debian
+
+```bash
+# Install Node.js 20.x
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Install other dependencies
+sudo apt-get install -y git python3 docker.io
+
+# Install UAP
+npm install -g universal-agent-protocol
+
+# Run setup
+npm run setup
+```
+
+### Windows
+
+```powershell
+# Install all dependencies using winget
+winget install OpenJS.NodeJS.LTS
+winget install Git.Git
+winget install Python.Python.3.12
+winget install Docker.DockerDesktop
+
+# Install UAP
+npm install -g universal-agent-protocol
+
+# Run setup
+npm run setup
+```
+
+## Git Hooks
+
+The setup script automatically configures the following git hooks:
+
+### Pre-commit Hook
+
+- Checks for secrets in committed files
+- Runs linter with zero warnings allowed
+- Prevents accidental commits of sensitive data
+
+### Commit-msg Hook
+
+- Validates conventional commits format
+- Suggests proper format if invalid
+- Allows override with confirmation
+
+### Pre-push Hook
+
+- Runs all tests before pushing
+- Prevents pushing broken code
+
+## Environment Setup
+
+### Required Environment Variables
+
+None required for basic functionality.
+
+### Optional Environment Variables
+
+```bash
+# GitHub token for GitHub memory backend
+export GITHUB_TOKEN=your_token_here
+
+# Qdrant Cloud credentials for semantic search
+export QDRANT_API_KEY=your_key_here
+export QDRANT_URL=your_url_here
+
+# Local Qdrant (if running Docker)
+export QDRANT_URL=http://localhost:6333
+```
+
+## Verification
+
+After setup, verify everything is working:
+
+```bash
+# Check UAP CLI
+uap --version
+
+# Check memory status
+uap memory status
+
+# Run tests
+npm test
+
+# Check git hooks
+ls -la .git/hooks/
+```
+
+## Troubleshooting
+
+### Git hooks not running
+
+```bash
+# Make hooks executable
+chmod +x .git/hooks/*
+
+# Verify hooks are active
+ls -la .git/hooks/ | grep -v sample
+```
+
+### TypeScript build fails
+
+```bash
+# Clear cache and rebuild
+rm -rf dist node_modules/.cache
+npm run build
+```
+
+### npm install fails
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Docker not available
+
+No problem! UAP will use cloud backends. You can add Docker later:
+
+```bash
+# Install Docker
+curl -fsSL https://get.docker.com | sh
+
+# Start Qdrant
+uap memory start
+```
+
+## Next Steps
+
+1. **Review the generated CLAUDE.md** - Customize as needed
+2. **Set up cloud backends** - Add your API keys
+3. **Start working** - Your AI assistant will follow the workflows automatically
+
+## Uninstallation
+
+```bash
+# Remove global package
+npm uninstall -g universal-agent-protocol
+
+# Remove from your project
+rm -rf .uap.json CLAUDE.md agents/ .worktrees/
+```
+
+## Support
+
+- **Documentation**: [GitHub README](https://github.com/DammianMiller/universal-agent-protocol)
+- **Issues**: [GitHub Issues](https://github.com/DammianMiller/universal-agent-protocol/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/DammianMiller/universal-agent-protocol/discussions)