@miller-tech/uap 1.0.0

package/tools/agents/plugin/README.md

@@ -0,0 +1,91 @@
+# UAP Plugins
+
+This directory contains all UAP (Universal Agent Protocol) plugins, hooks, and utilities.
+
+## Plugin Files
+
+### TypeScript Plugins
+
+- **uap-commands.ts** - Defines UAP-specific commands for opencode integration
+- **uap-droids.ts** - Specialized agent droids (code reviewer, security auditor, etc.)
+- **uap-skills.ts** - Domain-specific skills (git workflow, testing patterns, etc.)
+- **uap-patterns.ts** - Reusable coding patterns distilled from experience
+
+### Shell Hooks
+
+- **session-start.sh** - Runs at session initialization to enforce UAP compliance
+- **pre-compact.sh** - Runs before context compression to preserve critical information
+
+## Usage
+
+### Install Plugins
+
+To install all UAP plugins for opencode:
+
+```bash
+uap install opencode
+```
+
+This will copy all plugin files to `~/.opencode/plugin/`.
+
+### Available Droids
+
+- **code-reviewer** - Reviews code changes for quality and security
+- **security-auditor** - Audits code for security vulnerabilities
+- **performance-optimizer** - Analyzes and optimizes performance bottlenecks
+- **unit-tester** - Generates comprehensive unit tests
+- **debug-helper** - Helps diagnose and fix bugs
+
+### Available Skills
+
+- **git-workflow** - Manages git workflows with worktrees and branches
+- **testing-patterns** - Applies testing best practices and patterns
+- **ci-cd-setup** - Configures continuous integration and deployment pipelines
+- **documentation-gen** - Generates and maintains project documentation
+
+### Available Patterns
+
+- **generic-uap-patterns** - Distilled patterns from tbench-specific implementation
+- **worktree-isolation** - Use git worktrees for isolated feature development
+- **session-persistence** - Maintain state across sessions using memory system
+- **task-tracking** - Track and manage tasks with UAP task system
+- **agent-coordination** - Coordinate multiple AI agents for complex tasks
+
+## Plugin Manifest
+
+Each plugin is registered in the `index.ts` file which exports:
+
+- Version information
+- Plugin manifest with hooks, droids, skills, and patterns
+- Individual plugin modules
+
+## Creating New Plugins
+
+To add a new plugin:
+
+1. Create a new TypeScript file in this directory
+2. Export definitions using the appropriate interfaces
+3. Add to the `index.ts` exports
+4. Register in the `uapPluginManifest`
+
+Example:
+
+```typescript
+export interface MyPlugin {
+  id: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+}
+
+export const myPlugin: MyPlugin = {
+  id: 'my-plugin',
+  name: 'My Plugin',
+  description: 'Description of my plugin',
+  enabled: true,
+};
+```
+
+## License
+
+Part of Universal Agent Protocol v0.10.3

package/tools/agents/plugin/index.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * UAP Plugin Index
+ *
+ * This file serves as the main entry point for all UAP plugins.
+ * It exports all available plugins, hooks, and utilities.
+ */
+
+import { uapCommands } from './uap-commands.js';
+import { uapDroids } from './uap-droids.js';
+import { uapSkills } from './uap-skills.js';
+import { uapPatterns } from './uap-patterns.js';
+
+export const UAP_VERSION = '7.0.2';
+
+export interface UAPPluginManifest {
+  name: string;
+  version: string;
+  description: string;
+  hooks?: string[];
+  droids?: string[];
+  skills?: string[];
+  patterns?: string[];
+}
+
+export const uapPluginManifest: UAPPluginManifest = {
+  name: 'universal-agent-protocol',
+  version: UAP_VERSION,
+  description: 'Universal Agent Protocol - AI agents that learn and remember across sessions',
+  hooks: ['session-start.sh', 'pre-compact.sh'],
+  droids: uapDroids.map((d) => d.id),
+  skills: uapSkills.map((s) => s.id),
+  patterns: uapPatterns.map((p) => p.id),
+};
+
+export { uapCommands, uapDroids, uapSkills, uapPatterns };
+
+// Default export for easy importing
+export default {
+  version: UAP_VERSION,
+  manifest: uapPluginManifest,
+  commands: uapCommands,
+  droids: uapDroids,
+  skills: uapSkills,
+  patterns: uapPatterns,
+};

package/tools/agents/plugin/pre-compact.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# UAP Pre-Compact Hook for Claude Code
+# 1. Checks compliance state and warns on violations
+# 2. Writes a timestamp marker to the daily log before context compaction
+# 3. Marks any agents registered by this session as completed
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
+
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Record a compaction marker in memory so sessions can detect context resets
+sqlite3 "$DB_PATH" "
+  INSERT OR IGNORE INTO memories (timestamp, type, content)
+  VALUES ('$TIMESTAMP', 'action', '[pre-compact] Context compaction at $TIMESTAMP');
+" 2>/dev/null || true
+
+# Check if any lessons were stored this session
+recent_lessons=$(sqlite3 "$DB_PATH" "
+  SELECT COUNT(*) FROM session_memories
+  WHERE timestamp >= datetime('now', '-2 hours')
+    AND type = 'decision';
+" 2>/dev/null || echo "0")
+
+output=""
+
+# Compliance reminder on compaction
+output+="<system-reminder>"$'\n'
+output+="## UAP COMPLIANCE REMINDER (Pre-Compact)"$'\n'
+output+=""$'\n'
+output+="Context is being compacted. Before continuing work after compaction:"$'\n'
+output+="1. Re-run: uap task ready"$'\n'
+output+="2. Re-query memory for current task context"$'\n'
+output+="3. Check for stale worktrees: uap worktree list"$'\n'
+output+=""$'\n'
+
+if [ "$recent_lessons" = "0" ]; then
+  output+="WARNING: No lessons stored this session. Before compaction completes,"$'\n'
+  output+="store a summary: sqlite3 ./agents/data/memory/short_term.db \"INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','<summary>',7);\""$'\n'
+fi
+
+output+="</system-reminder>"$'\n'
+
+echo "$output"
+
+# Clean up agents with recent heartbeats (likely from this session being compacted)
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+    );
+    UPDATE work_announcements SET completed_at='$TIMESTAMP'
+      WHERE completed_at IS NULL AND agent_id IN (
+        SELECT id FROM agent_registry
+        WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+      );
+    UPDATE agent_registry SET status='completed'
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes');
+  " 2>/dev/null || true
+fi

package/tools/agents/plugin/session-start.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# UAP Session Start Hook for Claude Code
+# COMPLIANCE ENFORCEMENT: Outputs mandatory protocol checklist
+# that the AI agent MUST complete before any work begins.
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
+
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+fi
+
+# Auto-create coordination DB if missing (self-healing)
+if [ ! -f "$COORD_DB" ]; then
+  mkdir -p "$(dirname "$COORD_DB")"
+  sqlite3 "$COORD_DB" "
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = 10000;
+
+    CREATE TABLE IF NOT EXISTS agent_registry (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL, session_id TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('active','idle','completed','failed')),
+      current_task TEXT, worktree_branch TEXT, started_at TEXT NOT NULL,
+      last_heartbeat TEXT NOT NULL, capabilities TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_session ON agent_registry(session_id);
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_status ON agent_registry(status);
+
+    CREATE TABLE IF NOT EXISTS agent_messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, channel TEXT NOT NULL,
+      from_agent TEXT, to_agent TEXT,
+      type TEXT NOT NULL CHECK(type IN ('request','response','notification','claim','release')),
+      payload TEXT NOT NULL, priority INTEGER DEFAULT 5,
+      created_at TEXT NOT NULL, read_at TEXT, expires_at TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_messages_channel ON agent_messages(channel);
+    CREATE INDEX IF NOT EXISTS idx_messages_to_agent ON agent_messages(to_agent);
+    CREATE INDEX IF NOT EXISTS idx_messages_created ON agent_messages(created_at);
+
+    CREATE TABLE IF NOT EXISTS work_announcements (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, agent_id TEXT NOT NULL,
+      agent_name TEXT, worktree_branch TEXT,
+      intent_type TEXT NOT NULL CHECK(intent_type IN ('editing','reviewing','refactoring','testing','documenting')),
+      resource TEXT NOT NULL, description TEXT, files_affected TEXT,
+      estimated_completion TEXT, announced_at TEXT NOT NULL, completed_at TEXT,
+      FOREIGN KEY (agent_id) REFERENCES agent_registry(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_announcements_agent ON work_announcements(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_announcements_resource ON work_announcements(resource);
+    CREATE INDEX IF NOT EXISTS idx_announcements_active ON work_announcements(completed_at) WHERE completed_at IS NULL;
+
+    CREATE TABLE IF NOT EXISTS work_claims (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, resource TEXT NOT NULL,
+      agent_id TEXT NOT NULL, claim_type TEXT NOT NULL CHECK(claim_type IN ('exclusive','shared')),
+      claimed_at TEXT NOT NULL, expires_at TEXT,
+      FOREIGN KEY (agent_id) REFERENCES agent_registry(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_claims_agent ON work_claims(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_claims_resource ON work_claims(resource);
+
+    CREATE TABLE IF NOT EXISTS deploy_queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, agent_id TEXT NOT NULL,
+      action_type TEXT NOT NULL CHECK(action_type IN ('commit','push','merge','deploy','workflow')),
+      target TEXT NOT NULL, payload TEXT,
+      status TEXT NOT NULL CHECK(status IN ('pending','batched','executing','completed','failed')),
+      batch_id TEXT, queued_at TEXT NOT NULL, execute_after TEXT,
+      priority INTEGER DEFAULT 5, dependencies TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_deploy_status ON deploy_queue(status);
+    CREATE INDEX IF NOT EXISTS idx_deploy_batch ON deploy_queue(batch_id);
+    CREATE INDEX IF NOT EXISTS idx_deploy_target ON deploy_queue(target);
+
+    CREATE TABLE IF NOT EXISTS deploy_batches (
+      id TEXT PRIMARY KEY, created_at TEXT NOT NULL, executed_at TEXT,
+      status TEXT NOT NULL CHECK(status IN ('pending','executing','completed','failed')),
+      result TEXT
+    );
+  " 2>/dev/null || true
+fi
+
+# Clean stale agents from coordination DB (heartbeat >24h old)
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    );
+    DELETE FROM work_announcements WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    ) AND completed_at IS NULL;
+    UPDATE agent_registry SET status='failed'
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours');
+    DELETE FROM agent_registry
+      WHERE status IN ('completed','failed') AND started_at < datetime('now','-7 days');
+    DELETE FROM agent_messages WHERE created_at < datetime('now','-24 hours');
+  " 2>/dev/null || true
+fi
+
+output=""
+
+# ============================================================
+# COMPLIANCE ENFORCEMENT BLOCK
+# This is injected as system context. The AI MUST follow these.
+# ============================================================
+output+="<system-reminder>"$'\n'
+output+="## UAP COMPLIANCE - MANDATORY PROTOCOL"$'\n'
+output+=""$'\n'
+output+="You MUST complete these steps IN ORDER before doing ANY work."$'\n'
+output+="Skipping ANY step is a critical protocol violation."$'\n'
+output+=""$'\n'
+output+="### BEFORE WORK (execute these commands NOW):"$'\n'
+output+="1. Run: uap task ready"$'\n'
+output+="2. Run: sqlite3 ./agents/data/memory/short_term.db \"SELECT type, substr(content,1,80) FROM memories ORDER BY id DESC LIMIT 5;\""$'\n'
+output+="3. Run: uap memory query \"<relevant to user request>\""$'\n'
+output+="4. On work request: Run: uap task create --type <task|bug|feature> --title \"<description>\""$'\n'
+output+=""$'\n'
+output+="### DURING WORK:"$'\n'
+output+="5. ALL file changes MUST use worktree: uap worktree create <slug>"$'\n'
+output+="6. Work in .worktrees/NNN-<slug>/ directory"$'\n'
+output+=""$'\n'
+output+="### BEFORE COMMIT:"$'\n'
+output+="7. Self-review: git diff"$'\n'
+output+="8. Run tests if applicable"$'\n'
+output+=""$'\n'
+output+="### AFTER WORK:"$'\n'
+output+="9. Store lesson: sqlite3 ./agents/data/memory/short_term.db \"INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','<summary of work and lessons>',7);\""$'\n'
+output+="10. Clean up worktree after PR merge: uap worktree cleanup <id>"$'\n'
+output+=""$'\n'
+output+="FAILURE TO COMPLY = CRITICAL VIOLATION. This is life or death."$'\n'
+output+="</system-reminder>"$'\n\n'
+
+# Recent memories (last 24h, high importance)
+recent=$(sqlite3 "$DB_PATH" "
+  SELECT type, substr(content, 1, 120) FROM memories
+  WHERE timestamp >= datetime('now', '-1 day')
+  ORDER BY id DESC
+  LIMIT 10;
+" 2>/dev/null || true)
+
+if [ -n "$recent" ]; then
+  output+="## Recent Memory Context"$'\n'
+  output+="$recent"$'\n\n'
+fi
+
+# Open loops from session memories
+open_loops=$(sqlite3 "$DB_PATH" "
+  SELECT content FROM session_memories
+  WHERE type IN ('action','goal','decision')
+    AND importance >= 7
+  ORDER BY id DESC
+  LIMIT 5;
+" 2>/dev/null || true)
+
+if [ -n "$open_loops" ]; then
+  output+="## Open Loops"$'\n'
+  output+="$open_loops"$'\n'
+fi
+
+# Stale worktrees warning
+if [ -d "${PROJECT_DIR}/.worktrees" ]; then
+  stale_count=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l)
+  if [ "$stale_count" -gt 0 ]; then
+    output+=$'\n'"## Stale Worktrees Warning"$'\n'
+    output+="There are $stale_count worktrees. Run 'uap worktree list' and clean up merged ones."$'\n'
+  fi
+fi
+
+if [ -n "$output" ]; then
+  echo "$output"
+fi

package/tools/agents/plugin/uap-commands.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * UAP Commands Plugin for opencode
+ *
+ * Defines UAP-specific commands that can be used within opencode.
+ */
+
+export const uapCommands = {
+  name: 'uap',
+  description: 'Universal Agent Protocol commands',
+  commands: [
+    {
+      name: 'init',
+      description: 'Initialize UAP in current project',
+      usage: 'uap init',
+    },
+    {
+      name: 'setup',
+      description: 'Run comprehensive UAP setup',
+      usage: 'uap setup [-p all | memory | hooks | mcp-router]',
+    },
+    {
+      name: 'install',
+      description: 'Install UAP plugins for a harness',
+      usage: 'uap install <harness>',
+    },
+    {
+      name: 'task',
+      description: 'Create and manage tasks',
+      usage: 'uap task create --type <task|bug|feature> --title "<description>"',
+    },
+    {
+      name: 'worktree',
+      description: 'Manage git worktrees for isolated development',
+      usage: 'uap worktree <command>',
+    },
+    {
+      name: 'memory',
+      description: 'Query and manage memory system',
+      usage: 'uap memory query "<query>"',
+    },
+  ],
+};
+
+export default uapCommands;

package/tools/agents/plugin/uap-droids.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * UAP Droids Plugin for opencode
+ *
+ * Defines specialized agent droids that can be invoked via UAP.
+ */
+
+export interface UDroidDefinition {
+  id: string;
+  name: string;
+  description: string;
+  category: 'code' | 'review' | 'debug' | 'test' | 'deploy';
+  enabled: boolean;
+}
+
+export const uapDroids: UDroidDefinition[] = [
+  {
+    id: 'code-reviewer',
+    name: 'Code Reviewer',
+    description: 'Reviews code changes for quality and security',
+    category: 'review',
+    enabled: true,
+  },
+  {
+    id: 'security-auditor',
+    name: 'Security Auditor',
+    description: 'Audits code for security vulnerabilities',
+    category: 'review',
+    enabled: true,
+  },
+  {
+    id: 'performance-optimizer',
+    name: 'Performance Optimizer',
+    description: 'Analyzes and optimizes performance bottlenecks',
+    category: 'code',
+    enabled: true,
+  },
+  {
+    id: 'unit-tester',
+    name: 'Unit Tester',
+    description: 'Generates comprehensive unit tests',
+    category: 'test',
+    enabled: true,
+  },
+  {
+    id: 'debug-helper',
+    name: 'Debug Helper',
+    description: 'Helps diagnose and fix bugs',
+    category: 'debug',
+    enabled: true,
+  },
+];
+
+export default uapDroids;

package/tools/agents/plugin/uap-patterns.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * UAP Patterns Plugin for opencode
+ *
+ * Provides reusable coding patterns and distilled knowledge from tbench.
+ */
+
+export interface UpatternDefinition {
+  id: string;
+  name: string;
+  description: string;
+  category: 'memory' | 'workflow' | 'architecture' | 'testing';
+  tags: string[];
+}
+
+export const uapPatterns: UpatternDefinition[] = [
+  {
+    id: 'generic-uap-patterns',
+    name: 'Generic UAP Patterns',
+    description: 'Distilled patterns from tbench-specific implementation',
+    category: 'workflow',
+    tags: ['memory', 'hooks', 'patterns'],
+  },
+  {
+    id: 'worktree-isolation',
+    name: 'Worktree Isolation Pattern',
+    description: 'Use git worktrees for isolated feature development',
+    category: 'workflow',
+    tags: ['git', 'isolation', 'parallel'],
+  },
+  {
+    id: 'session-persistence',
+    name: 'Session Persistence Pattern',
+    description: 'Maintain state across sessions using memory system',
+    category: 'memory',
+    tags: ['state', 'persistence', 'context'],
+  },
+  {
+    id: 'task-tracking',
+    name: 'Task Tracking Pattern',
+    description: 'Track and manage tasks with UAP task system',
+    category: 'workflow',
+    tags: ['tasks', 'tracking', 'management'],
+  },
+  {
+    id: 'agent-coordination',
+    name: 'Agent Coordination Pattern',
+    description: 'Coordinate multiple AI agents for complex tasks',
+    category: 'architecture',
+    tags: ['agents', 'coordination', 'parallel'],
+  },
+];
+
+export default uapPatterns;

package/tools/agents/plugin/uap-skills.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * UAP Skills Plugin for opencode
+ *
+ * Defines domain-specific skills that agents can use.
+ */
+
+export interface USkillDefinition {
+  id: string;
+  name: string;
+  description: string;
+  category: 'development' | 'testing' | 'deployment' | 'documentation';
+  triggers: string[];
+  enabled: boolean;
+}
+
+export const uapSkills: USkillDefinition[] = [
+  {
+    id: 'git-workflow',
+    name: 'Git Workflow',
+    description: 'Manages git workflows with worktrees and branches',
+    category: 'development',
+    triggers: ['git', 'branch', 'commit', 'push'],
+    enabled: true,
+  },
+  {
+    id: 'testing-patterns',
+    name: 'Testing Patterns',
+    description: 'Applies testing best practices and patterns',
+    category: 'testing',
+    triggers: ['test', 'spec', 'coverage'],
+    enabled: true,
+  },
+  {
+    id: 'ci-cd-setup',
+    name: 'CI/CD Setup',
+    description: 'Configures continuous integration and deployment pipelines',
+    category: 'deployment',
+    triggers: ['ci', 'cd', 'pipeline', 'workflow'],
+    enabled: false,
+  },
+  {
+    id: 'documentation-gen',
+    name: 'Documentation Generator',
+    description: 'Generates and maintains project documentation',
+    category: 'documentation',
+    triggers: ['doc', 'readme', 'comment'],
+    enabled: true,
+  },
+];
+
+export default uapSkills;