@miller-tech/uap 1.40.0 → 1.41.0

package/docs/reference/UAP_CLI_REFERENCE.md

@@ -1,620 +0,0 @@
-# UAP CLI Reference
-
-**Complete command reference for Universal Agent Protocol**
-
----
-
-## Quick Start
-
-```bash
-# Initialize UAP in existing project
-uap init
-
-# Create a new task with memory tracking
-uap task create --title "Add user authentication" --type feature
-
-# Query past decisions
-uap memory query "authentication patterns"
-
-# Create worktree for parallel development
-uap worktree create add-api-endpoints
-```
-
----
-
-## Command Reference
-
-### `uap init`
-
-Initialize UAP in your project.
-
-```bash
-uap init [options]
-```
-
-**Options:**
-
-- `--interactive, -i` - Run interactive setup wizard
-- `--force, -f` - Overwrite existing configuration
-- `--skip-qdrant` - Skip Qdrant setup (use SQLite only)
-- `--skip-hooks` - Skip session hook installation
-
-**Example:**
-
-```bash
-uap init --interactive
-```
-
----
-
-### `uap task`
-
-Task creation and management with memory integration.
-
-#### `uap task create`
-
-Create a new tracked task.
-
-```bash
-uap task create --title "<name>" --type <task|bug|feature> [options]
-```
-
-**Options:**
-
-- `--priority, -p` - Priority level: low, medium, high, critical (also accepts P0-P4)
-- `--estimate` - Estimated time in minutes
-- `--depends` - Task ID this task depends on
-- `--label, -l` - Add label (can be specified multiple times)
-
-**Example:**
-
-```bash
-uap task create --title "Fix login timeout bug" --type bug --priority high
-uap task create --title "Add OAuth support" --type feature --label auth --label v2.0
-```
-
-#### `uap task list`
-
-List all tasks with optional filters.
-
-```bash
-uap task list [options]
-```
-
-**Options:**
-
-- `--status, -s` - Filter by status: pending/open, in_progress, completed/done, blocked
-- `--type, -t` - Filter by type: task, bug, feature
-- `--priority, -p` - Filter by priority
-- `--json` - Output as JSON
-
-**Example:**
-
-```bash
-uap task list --status in_progress
-uap task list --type bug --priority high --json
-```
-
-#### `uap task update`
-
-Update task status or details.
-
-```bash
-uap task update <task-id> [options]
-```
-
-**Options:**
-
-- `--status, -s` - New status
-- `--priority, -p` - New priority
-- `--label, -l` - Add label
-- `--remove-label, -R` - Remove label
-- `--comment, -c` - Add comment
-
-**Example:**
-
-```bash
-uap task update abc123 --status in_progress
-uap task update def456 --comment "Blocked waiting on API key"
-```
-
-#### `uap task ready`
-
-Initialize session with memory context (run at start of agent session).
-
-```bash
-uap task ready [options]
-```
-
-**Options:**
-
-- `--verbose, -v` - Show detailed memory queries
-- `--quiet, -q` - Suppress all output except errors
-
-**Output:**
-
-```
-=== UAP SESSION INITIALIZED ===
-Current Task: abc123 - Fix login timeout bug
-Recent Memories: 5 relevant decisions found
-Past Failures: 2 similar bugs resolved
-Active Patterns: P13, P26, P32
-```
-
----
-
-### `uap memory`
-
-Memory storage and retrieval operations.
-
-#### `uap memory store`
-
-Store a new memory entry.
-
-```bash
-uap memory store "<text>" [options]
-```
-
-**Options:**
-
-- `--type, -t` - Memory type: decision, pattern, lesson, failure
-- `--tags, -T` - Comma-separated tags
-
-**Example:**
-
-```bash
-uap memory store "Always validate CSRF tokens in auth flows" --type decision --tags security,auth
-uap memory store "Docker container timeout at 300s - increase to 600s" --type lesson --tags docker
-```
-
-#### `uap memory query`
-
-Search memories using semantic search.
-
-```bash
-uap memory query "<query>" [options]
-```
-
-**Options:**
-
-- `--top-k, -k` - Number of results (default: 10, alias for --limit)
-- `--threshold, -t` - Minimum similarity score (0-1, default: 0.35)
-- `--type, -t` - Filter by memory type
-- `--tags, -T` - Filter by tags
-
-**Example:**
-
-```bash
-uap memory query "authentication errors" --top-k 10
-uap memory query "performance optimization" --threshold 0.5
-```
-
-#### `uap memory clear-session`
-
-Clear session-specific memories.
-
-```bash
-uap memory clear-session [session-id]
-```
-
-**Example:**
-
-```bash
-uap memory clear-session current
-```
-
----
-
-### `uap worktree`
-
-Worktree management for isolated development.
-
-#### `uap worktree create`
-
-Create a new worktree with automatic branch naming.
-
-```bash
-uap worktree create <slug> [options]
-```
-
-**Options:**
-
-- `--from, -f` - Base branch (default: current)
-- `--description, -d` - Worktree description
-
-**Example:**
-
-```bash
-uap worktree create add-rate-limiting
-uap worktree create hotfix-auth-bug --from develop
-```
-
-#### `uap worktree pr`
-
-Create a pull request for a worktree. This command now syncs the branch with `origin/master` before push/PR creation to reduce mergeability issues.
-
-```bash
-uap worktree pr <worktree-id> [options]
-```
-
-**Options:**
-
-- `--draft` - Create as draft PR
-
-**Example:**
-
-```bash
-uap worktree pr 123
-uap worktree pr 123 --draft
-```
-
-#### `uap worktree finish`
-
-Recommended completion flow for worktrees. This command enforces the safe sequence to prevent sync/merge problems:
-
-1. Sync branch with `origin/master`
-2. Push branch
-3. Create PR if missing
-4. Merge PR
-5. Auto-clean local worktree and branch
-
-If GitHub cannot delete the local branch due worktree branch locks, `uap worktree finish` automatically falls back to merge + local cleanup, so local branch deletion still completes.
-
-```bash
-uap worktree finish <worktree-id>
-```
-
-**Example:**
-
-```bash
-uap worktree finish 123
-```
-
-#### `uap worktree cleanup`
-
-Remove merged worktrees.
-
-```bash
-uap worktree cleanup <worktree-id> [options]
-```
-
-**Options:**
-
-- `--force, -f` - Skip confirmation prompt
-
-**Example:**
-
-```bash
-uap worktree cleanup 123 --force
-```
-
-#### `uap worktree list`
-
-List all active worktrees.
-
-```bash
-uap worktree list [options]
-```
-
-**Options:**
-
-- `--json` - Output as JSON
-
----
-
-### `uap hooks`
-
-Session hook management for persistent memory.
-
-#### `uap hooks install`
-
-Install session hooks for automatic memory tracking.
-
-```bash
-uap hooks install [options]
-```
-
-**Options:**
-
-- `--platform, -p` - Platform: claude/claude-code, factory, vscode, opencode
-- `--force, -f` - Overwrite existing hooks
-
-**Example:**
-
-```bash
-uap hooks install --platform claude-code
-```
-
-#### `uap hooks uninstall`
-
-Remove session hooks.
-
-```bash
-uap hooks uninstall [options]
-```
-
-**Options:**
-
-- `--all` - Remove all platform hooks
-
----
-
-### `uap compliance`
-
-Protocol compliance checking and verification.
-
-#### `uap compliance check`
-
-Run all compliance checks.
-
-```bash
-uap compliance check [options]
-```
-
-**Options:**
-
-- `--verbose, -v` - Show all checks including passed
-- `--fail-fast` - Stop on first failure
-- `--json` - Output as JSON
-
-**Output:**
-
-```
-=== UAP COMPLIANCE CHECK ===
-[✓] CLAUDE.md present and valid
-[✓] .uap.json configuration exists
-[✓] Memory database accessible
-[✓] Worktree workflow enforced
-[✓] No direct commits to main
-[✓] All outputs verified with ls -la
-[✓] Schema matches test expectations
-[✓] Tests run 3+ times minimum
-[✓] CLI tested as ./script
-[✓] Critical files backed up
-[✓] Decoder round-trip passes
-[✓] Recovery artifacts copied
-
-=== COMPLIANCE SCORE: 12/12 (100%) ===
-```
-
-#### `uap compliance report`
-
-Generate detailed compliance report.
-
-```bash
-uap compliance report [options]
-```
-
-**Options:**
-
-- `--output, -o` - Output file path
-- `--format, -f` - Format: text, markdown, json
-
----
-
-### `uap coordination`
-
-Multi-agent collaboration tools.
-
-#### `uap coordination check`
-
-Check for overlapping work between agents.
-
-```bash
-uap coordination check --agents <agent1,agent2,...> [options]
-```
-
-**Options:**
-
-- `--verbose, -v` - Show detailed overlap analysis
-- `--json` - Output as JSON
-
-#### `uap coordination resolve`
-
-Resolve identified overlaps.
-
-```bash
-uap coordination resolve <overlap-id> --action <assign|merge|delegate>
-```
-
----
-
-### `uap skill`
-
-Skill management and loading.
-
-#### `uap skill list`
-
-List available skills.
-
-```bash
-uap skill list [options]
-```
-
-**Options:**
-
-- `--category, -c` - Filter by category
-- `--json` - Output as JSON
-
-#### `uap skill load`
-
-Load a specific skill for current session.
-
-```bash
-uap skill load <skill-name> [options]
-```
-
-**Example:**
-
-```bash
-uap skill load chess-engine
-uap skill load compression --category optimization
-```
-
----
-
-### `uap agent`
-
-Agent status and management.
-
-#### `uap agent status`
-
-Show current agent status.
-
-```bash
-uap agent status [options]
-```
-
-**Options:**
-
-- `--verbose, -v` - Show detailed memory stats
-- `--json` - Output as JSON
-
----
-
-### `uap generate`
-
-Generate CLAUDE.md from template.
-
-```bash
-uap generate [options]
-```
-
-**Options:**
-
-- `--force, -f` - Overwrite existing CLAUDE.md
-- `--template, -t` - Custom template path
-- `--sections` - Comma-separated section list to include
-
-**Example:**
-
-```bash
-uap generate --force
-uap generate --sections memorySystem,worktreeWorkflow,troubleshooting
-```
-
----
-
-## Environment Variables
-
-| Variable             | Description                  | Default                              |
-| -------------------- | ---------------------------- | ------------------------------------ |
-| `UAP_VERBOSE`        | Enable verbose logging       | `false`                              |
-| `UAP_DB_PATH`        | Custom database path         | `./agents/data/memory/short_term.db` |
-| `UAP_QDRANT_URL`     | Qdrant endpoint              | `localhost:6333`                     |
-| `UAP_DEFAULT_BRANCH` | Default worktree base branch | `main`                               |
-
----
-
-## Exit Codes
-
-| Code | Meaning                   |
-| ---- | ------------------------- |
-| 0    | Success                   |
-| 1    | General error             |
-| 2    | Invalid arguments         |
-| 3    | Configuration error       |
-| 4    | Memory operation failed   |
-| 5    | Worktree operation failed |
-| 6    | Compliance check failed   |
-
----
-
-## Shell Completion
-
-Enable tab completion for your shell:
-
-```bash
-# Bash
-echo 'eval "$(_UAP_COMPLETE=bash_source uap)"' >> ~/.bashrc
-
-# Zsh
-echo 'eval "$(_UAP_COMPLETE=zsh_source uap)"' >> ~/.zshrc
-
-# Fish
-_uap_complete_fish | source
-```
-
----
-
-## Examples
-
-### Complete Development Workflow
-
-```bash
-# 1. Initialize project
-uap init --interactive
-
-# 2. Create task
-uap task create --title "Implement user registration" --type feature --priority high
-
-# 3. Start session with memory
-uap task ready
-
-# 4. Create worktree for changes
-uap worktree create implement-user-registration
-
-# 5. Make changes, commit
-cd .worktrees/NNN-implement-user-registration/
-git add -A && git commit -m "feat: add user registration endpoint"
-
-# 6. Create PR
-uap worktree pr 123 --title "Add user registration API"
-
-# 7. Store lessons learned
-uap memory store "User validation must check email format before DB insert" \
-  --type decision --tags auth,validation
-
-# 8. After merge, cleanup
-uap worktree cleanup 123 --force
-
-# 9. Verify compliance
-uap compliance check
-```
-
-### Memory-Enhanced Debugging
-
-```bash
-# 1. Start with memory context
-uap task ready --verbose
-
-# 2. Query similar past failures
-uap memory query "database connection timeout" --top-k 5
-
-# 3. Apply pattern P26 (same error twice = change approach)
-# 4. Fix and test
-# 5. Store solution
-uap memory store "Connection pool exhaustion fixed by increasing maxPoolSize from 10 to 50" \
-  --type lesson --tags database,performance
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-| Error                      | Solution                                |
-| -------------------------- | --------------------------------------- |
-| `command not found: uap`   | Ensure npm global bin is in PATH        |
-| `Database locked`          | Close other processes using the DB      |
-| `Qdrant connection failed` | Run `cd agents && docker-compose up -d` |
-| `Worktree already exists`  | Use `uap worktree cleanup <id>` first   |
-| `Compliance check failed`  | Review specific gate failure in output  |
-
-### Debug Mode
-
-```bash
-# Enable verbose logging
-export UAP_VERBOSE=true
-
-# Check database contents
-sqlite3 ./agents/data/memory/short_term.db "SELECT * FROM memories ORDER BY id DESC LIMIT 5;"
-
-# Inspect session state
-sqlite3 ./agents/data/memory/short_term.db "SELECT * FROM session_memories WHERE session_id='current';"
-```
-
----
-
-For more information, see [UAP Overview](./UAP_OVERVIEW.md) or visit the [GitHub repository](https://github.com/DammianMiller/universal-agent-protocol).