universal-agent-protocol 0.5.0

package/templates/CLAUDE_ARCHITECTURE.template.md

@@ -0,0 +1,103 @@
+# Architecture Guide Template
+
+**Version**: {{VERSION}}
+**Branch**: {{DEFAULT_BRANCH}}
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Cluster Topology
+
+{{#if HAS_MULTI_CLUSTER}}
+This project operates multiple dedicated clusters - **one concern per cluster**.
+
+| Cluster | Context | Purpose | Services |
+|---------|---------|---------|----------|
+{{#each CLUSTERS}}
+| **{{name}}** | `{{context}}` | {{purpose}} | {{services}} |
+{{/each}}
+{{else}}
+Single cluster deployment.
+
+### Cluster Commands
+
+```bash
+kubectl config use-context {{MAIN_CLUSTER_CONTEXT}}
+```
+{{/if}}
+
+---
+
+## Cross-Cluster Communication Rules
+
+{{#if HAS_MULTI_CLUSTER}}
+**CRITICAL**: Always use public HTTPS URLs for cross-cluster communication.
+
+### Do's and Don'ts
+
+| ✅ DO | ❌ DON'T |
+|-------|----------|
+| Use public HTTPS URLs | Use cluster-internal DNS across clusters |
+| Use service accounts for auth | Use internal IPs for cross-cluster |
+
+### Whitelisted URLs
+{{#each WHITELISTED_URLS}}
+- `{{this}}`
+{{/each}}
+{{/if}}
+
+---
+
+## Technology Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+{{#each TECH_STACK}}
+| **{{layer}}** | {{technology}} | {{version}} |
+{{/each}}
+
+---
+
+## High Availability
+
+| Component | Configuration |
+|-----------|---------------|
+{{#each HA_CONFIG}}
+| **{{component}}** | {{configuration}} |
+{{/each}}
+
+---
+
+## Infrastructure as Code Policy
+
+### Two-Phase Infrastructure Workflow
+
+```
+PHASE 1: LOCAL PROOF (ALLOWED - NO SECRETS)
+  - Read-only operations
+  - terraform plan (via pipeline for secrets)
+
+PHASE 2: IaC PARITY (MANDATORY - VIA PIPELINE)
+  - Translate manual changes to Terraform/K8s YAML
+  - Deploy via pipeline
+  - Delete manual/ephemeral resources
+```
+
+### Secrets
+
+**ALL secrets are stored in GitHub Actions secrets.** Operations requiring secrets MUST use pipelines.
+
+---
+
+## Service URLs
+
+{{#each SERVICE_URLS}}
+| {{name}} | {{url}} |
+{{/each}}
+
+---
+
+## See Also
+
+- `docs/ARCHITECTURE-OVERVIEW.md` - Detailed architecture
+- `.factory/compliance_rules.yaml` - Architecture constraints (if applicable)

package/templates/CLAUDE_CODING.template.md

@@ -0,0 +1,125 @@
+# Coding Standards Template
+
+**Version**: 1.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Core Principles
+
+1. **State assumptions** before writing code
+2. **Verify correctness** -- do not claim it
+3. **Handle error paths**, not just the happy path
+4. **Do not import complexity** you do not need
+5. **Produce code you would want to debug at 3am**
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] Functions <= 30 lines
+- [ ] Self-documenting names
+- [ ] Error paths handled explicitly
+- [ ] No debug prints or commented-out code
+- [ ] Consistent with surrounding code style
+- [ ] No hardcoded values that should be constants
+- [ ] Imports are minimal
+
+---
+
+{{#if HAS_MULTI_TENANCY}}
+## Multi-Tenancy
+
+All database queries must include organization scope.
+
+### Correct Patterns
+
+```sql
+-- ✅ Organization-scoped query
+SELECT * FROM products WHERE owner_id = $1;
+```
+
+### Incorrect Patterns
+
+```sql
+-- ❌ Cross-tenant access
+SELECT * FROM products;
+```
+{{/if}}
+
+---
+
+## Security
+
+### Secrets
+
+Never hardcode secrets. Use environment variables.
+
+```typescript
+// ✅ Correct
+const dbPassword = process.env.DB_PASSWORD;
+
+// ❌ Wrong
+const dbPassword = "hardcoded_password";
+```
+
+### Input Validation
+
+Always validate and sanitize inputs.
+
+```typescript
+// ✅ Parameterized queries
+db.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+---
+
+## Error Handling
+
+Log with context for debugging.
+
+```typescript
+// ✅ Correct
+logger.error('Failed to fetch', { 
+  error: error.message, 
+  correlationId: req.id 
+});
+```
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+{{TEST_COMMAND}}
+```
+
+---
+
+## Code Quality Tools
+
+```bash
+{{LINT_COMMAND}}
+```
+
+---
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Variables | camelCase | `userName` |
+| Constants | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Functions | camelCase | `getUserById` |
+| Classes | PascalCase | `UserService` |
+| Files | kebab-case | `user-service.ts` |
+| Database | snake_case | `user_accounts` |
+
+---
+
+## See Also
+
+- `CLAUDE_WORKFLOWS.md` - Task workflows and testing
+- `.factory/skills/code-reviewer/` - Code review checklists (if applicable)

package/templates/CLAUDE_DROIDS.template.md

@@ -0,0 +1,109 @@
+# Droids and Skills Guide Template
+
+**Version**: 1.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Available Droids
+
+Droids are specialized AI agents for specific tasks.
+
+### Language Specialists
+
+| Droid | Purpose |
+|-------|---------|
+| `cpp-pro` | C++ development, RAII, STL, templates |
+| `python-pro` | Python, async/await, decorators |
+| `javascript-pro` | JavaScript/TypeScript, ES6+, async |
+
+### Review Droids
+
+| Droid | Purpose | Blocks PR |
+|-------|---------|-----------|
+| `security-code-reviewer` | OWASP, secrets, injection | CRITICAL/HIGH |
+| `code-quality-reviewer` | Naming, complexity, style | CRITICAL only |
+| `performance-reviewer` | Algorithms, N+1, caching | Advisory |
+| `test-coverage-reviewer` | Test gaps, brittle tests | Advisory |
+
+### Utility Droids
+
+| Droid | Purpose |
+|-------|---------|
+| `worktree-manager` | Git worktree lifecycle, PR creation |
+| `git-summarizer` | Repository context for reviewers |
+| `release-notes-writer` | Generate release notes from commits |
+| `project-analyzer` | Extract project metadata |
+
+---
+
+## Available Skills
+
+Skills provide domain-specific guidance.
+
+{{#each SKILLS}}
+| `{{name}}` | {{purpose}} |
+{{/each}}
+
+---
+
+## Agent Routing
+
+| Task Type | Route To |
+|-----------|----------|
+| Security review | `security-code-reviewer` |
+| Performance analysis | `performance-reviewer` |
+| Code quality | `code-quality-reviewer` |
+| C++ code | `cpp-pro` |
+| Python code | `python-pro` |
+| JavaScript/TypeScript | `javascript-pro` |
+
+---
+
+## Parallel Execution
+
+When safe, run independent droids in parallel:
+
+```bash
+# Before PR - run all reviewers
+Task(subagent_type: "security-code-reviewer", prompt: "Audit: <files>")
+Task(subagent_type: "code-quality-reviewer", prompt: "Review: <files>")
+```
+
+---
+
+## Multi-Agent Coordination
+
+**Skip for single-agent sessions.** Only activate when multiple agents work concurrently.
+
+```bash
+# Check for overlaps
+uap agent overlaps --resource "<files-or-directories>"
+```
+
+| Risk Level | Action |
+|------------|--------|
+| `none` | Proceed immediately |
+| `low` | Proceed, note merge order |
+| `medium` | Announce, coordinate sections |
+| `high`/`critical` | Wait or split work |
+
+---
+
+## Invoking Droids
+
+```bash
+# Via Task tool
+Task(subagent_type: "python-pro", prompt: "Refactor this code: <code>")
+
+# Via Skill tool
+Skill(skill: "openobserve-expert")
+```
+
+---
+
+## See Also
+
+- `.factory/droids/` - Droid definitions
+- `.factory/skills/` - Skill definitions
+- `CLAUDE_WORKFLOWS.md` - Review protocols

package/templates/CLAUDE_MEMORY.template.md

@@ -0,0 +1,130 @@
+# Memory System Guide Template
+
+**Version**: 1.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Memory Layers
+
+| Layer | Storage | Capacity | Latency |
+|-------|---------|----------|---------|
+| L1 Working | SQLite `memories` | {{SHORT_TERM_LIMIT}} max | <1ms |
+| L2 Session | SQLite `session_memories` | Current session | <5ms |
+| L3 Semantic | {{LONG_TERM_BACKEND}} | Unlimited | ~50ms |
+| L4 Knowledge | SQLite `entities/rels` | Graph | <20ms |
+
+**Database**: `./{{MEMORY_DB_PATH}}`
+**Vector DB**: {{LONG_TERM_BACKEND}} at `{{LONG_TERM_ENDPOINT}}`
+
+---
+
+## Working Memory (L1)
+
+Quick actions stored directly in SQLite.
+
+```bash
+# Store action
+sqlite3 ./{{MEMORY_DB_PATH}} "INSERT INTO memories (timestamp,type,content) VALUES (datetime('now'),'action','...');"
+
+# Query recent
+sqlite3 ./{{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
+```
+
+---
+
+## Session Memory (L2)
+
+Session-specific context for current task.
+
+```bash
+# Store decision
+sqlite3 ./{{MEMORY_DB_PATH}} "INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','...',7);"
+```
+
+---
+
+## Semantic Memory (L3)
+
+Long-term lessons stored in Qdrant vector database.
+
+```bash
+# Store lesson
+{{MEMORY_STORE_CMD}} lesson "..." --tags t1,t2 --importance 8
+
+# Query relevant lessons
+{{MEMORY_QUERY_CMD}} "security best practices"
+```
+
+---
+
+## Pattern RAG
+
+Patterns are retrieved dynamically from the `{{PATTERN_RAG_COLLECTION}}` collection.
+
+Top-2 relevant patterns are injected per task (score >= {{PATTERN_RAG_THRESHOLD}}).
+
+```bash
+# Query patterns
+{{PATTERN_RAG_QUERY_CMD}} "task description"
+
+# Re-index patterns
+{{PATTERN_RAG_INDEX_CMD}}
+
+# Check status
+uap patterns status
+```
+
+---
+
+## Pattern Files
+
+Patterns are defined in `.factory/patterns/`:
+
+```
+.factory/patterns/
+├── P12_output_existence.md
+├── P13_iterative_refinement.md
+├── ...
+├── IaC-Parity.md
+└── index.json
+```
+
+To add a new pattern:
+1. Create `P37_new_pattern.md` in `.factory/patterns/`
+2. Add entry to `index.json`
+3. Run `python agents/scripts/index_patterns.py`
+
+---
+
+## Reinforcement Learning
+
+Pattern effectiveness is tracked for self-improvement.
+
+```bash
+# View pattern effectiveness
+sqlite3 ./agents/data/memory/reinforcement.db "SELECT * FROM v_pattern_effectiveness;"
+
+# View recent outcomes
+sqlite3 ./agents/data/memory/reinforcement.db "SELECT * FROM v_recent_outcomes;"
+```
+
+---
+
+## Qdrant Setup
+
+```bash
+# Start Qdrant
+docker run -p 6333:6333 qdrant/qdrant
+
+# Or with persistence
+docker run -p 6333:6333 -v $(pwd)/qdrant_data:/qdrant/storage qdrant/qdrant
+```
+
+---
+
+## See Also
+
+- `.factory/patterns/` - Pattern definitions
+- `agents/scripts/index_patterns.py` - Pattern indexing
+- `agents/scripts/query_patterns.py` - Pattern query

package/templates/CLAUDE_WORKFLOWS.template.md

@@ -0,0 +1,136 @@
+# Workflows Guide Template
+
+**Version**: 1.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Session Start
+
+```bash
+uap task ready
+sqlite3 ./{{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
+uap agent status
+```
+
+---
+
+## Decision Loop
+
+```
+1. CLASSIFY  -> complexity? backup? tools?
+2. PROTECT   -> cp file file.bak (configs, DBs)
+3. MEMORY    -> query context + past failures
+4. WORK      -> implement (ALWAYS use worktree)
+5. REVIEW    -> self-review diff
+6. TEST      -> completion gates pass
+7. LEARN     -> store outcome
+```
+
+---
+
+## Worktree Workflow (MANDATORY)
+
+**ALL file changes MUST use a worktree.** No exceptions.
+
+```bash
+{{WORKTREE_CREATE_CMD}} <slug>
+cd {{WORKTREE_DIR}}/NNN-<slug>/
+git add -A && git commit -m "type: description"
+{{WORKTREE_PR_CMD}} <id>
+# After merge:
+{{WORKTREE_CLEANUP_CMD}} <id>  # MANDATORY
+```
+
+---
+
+## Testing Requirements
+
+1. Create worktree
+2. Update/create tests
+3. Run `{{TEST_COMMAND}}`
+4. Run linting: `{{LINT_COMMAND}}`
+5. Create PR
+
+---
+
+## Completion Gates
+
+**CANNOT say "done" until ALL gates pass.**
+
+### GATE 1: Output Existence
+
+```bash
+for f in $EXPECTED_OUTPUTS; do
+  [ -f "$f" ] && echo "ok $f" || echo "MISSING: $f"
+done
+```
+
+### GATE 2: Constraint Compliance
+
+Extract ALL constraints from task:
+- "exactly", "only", "must be", "no more than"
+- Verify EACH constraint
+
+### GATE 3: Tests Pass
+
+```bash
+{{TEST_COMMAND}}
+```
+
+If < 100%: iterate (fix specific failure, re-run).
+
+---
+
+## Completion Checklist
+
+```
+☐ Tests pass
+☐ Lint pass
+☐ Worktree used (MANDATORY)
+☐ Worktree cleaned up after PR merge (MANDATORY)
+☐ Self-review completed
+☐ Memory updated
+☐ PR created
+☐ Reviews passed
+☐ No secrets in code
+```
+
+---
+
+## Parallel Review Protocol
+
+**Before ANY commit/PR, invoke quality droids in PARALLEL:**
+
+```bash
+Task(subagent_type: "code-quality-reviewer", prompt: "Review: <files>")
+Task(subagent_type: "security-code-reviewer", prompt: "Audit: <files>")
+```
+
+---
+
+## Automatic Triggers
+
+| Pattern | Action |
+|---------|--------|
+| work request | `uap task create --type task` |
+| bug report | `uap task create --type bug` |
+| feature request | `uap task create --type feature` |
+| ANY file change | **create worktree (MANDATORY)** |
+
+---
+
+## Completion Protocol
+
+```
+MERGE -> CLEANUP WORKTREE -> DEPLOY -> MONITOR -> FIX (iterate until 100%)
+```
+
+**Never "done" until:** PR merged + worktree cleaned up + deployed + verified working
+
+---
+
+## See Also
+
+- `CLAUDE_CODING.md` - Coding standards
+- `.factory/droids/worktree-manager.md` - Worktree automation (if applicable)