universal-agent-memory 4.4.4 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "4.4.4",
+  "version": "5.0.0",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",

package/templates/CLAUDE.template.md

@@ -1,33 +1,35 @@
 <!--
-  CLAUDE.md Universal Template - v11.0-slim
-
+  CLAUDE.md Universal Template - v12.0-modular
+  
   Core Variables:
     {{PROJECT_NAME}}, {{DESCRIPTION}}, {{DEFAULT_BRANCH}}, {{STRUCTURE_DATE}}
 
   Memory System:
-    {{MEMORY_DB_PATH}}, {{MEMORY_QUERY_CMD}}, {{MEMORY_STORE_CMD}}, {{MEMORY_START_CMD}},
-    {{MEMORY_STATUS_CMD}}, {{MEMORY_STOP_CMD}}, {{LONG_TERM_BACKEND}}, {{LONG_TERM_ENDPOINT}},
-    {{LONG_TERM_COLLECTION}}, {{SHORT_TERM_LIMIT}}
+    {{MEMORY_DB_PATH}}, {{MEMORY_QUERY_CMD}}, {{MEMORY_STORE_CMD}},
+    {{LONG_TERM_BACKEND}}, {{LONG_TERM_ENDPOINT}}, {{SHORT_TERM_LIMIT}}
 
   Worktree:
     {{WORKTREE_CREATE_CMD}}, {{WORKTREE_PR_CMD}}, {{WORKTREE_CLEANUP_CMD}},
-    {{WORKTREE_DIR}}, {{BRANCH_PREFIX}}, {{WORKTREE_APPLIES_TO}}
-
-  Paths:
-    {{SKILLS_PATH}}, {{DROIDS_PATH}}, {{COMMANDS_PATH}}, {{DOCS_PATH}}, {{SCREENSHOTS_PATH}},
-    {{DOCKER_COMPOSE_PATH}}
+    {{WORKTREE_DIR}}
 
   Commands:
     {{TEST_COMMAND}}, {{BUILD_COMMAND}}, {{LINT_COMMAND}}
 
-  Pattern RAG (optional):
+  Pattern RAG:
     {{PATTERN_RAG_ENABLED}}, {{PATTERN_RAG_COLLECTION}}, {{PATTERN_RAG_QUERY_CMD}},
     {{PATTERN_RAG_INDEX_CMD}}, {{PATTERN_RAG_TOP_K}}, {{PATTERN_RAG_THRESHOLD}}
--->
 
-<coding_guidelines>
+  Modular Documentation:
+    CLAUDE_ARCHITECTURE.md - Cluster topology, IaC rules
+    CLAUDE_CODING.md - Coding standards, security
+    CLAUDE_WORKFLOWS.md - Task workflows, completion gates
+    CLAUDE_MEMORY.md - Memory system, Pattern RAG
+    CLAUDE_DROIDS.md - Available droids/skills
+    
+  Patterns are dynamically retrieved from .factory/patterns/ via Pattern RAG.
+-->
 
-# {{PROJECT_NAME}} - Autonomous Agent Guide
+# {{PROJECT_NAME}} - Core Directives
 
 {{#if DESCRIPTION}}
 > {{DESCRIPTION}}
@@ -39,7 +41,7 @@
 
 | Priority | Source | Override |
 |----------|--------|----------|
-| 1-HIGHEST | This CLAUDE.md | Never |
+| 1-HIGHEST | This file | Never |
 | 2-HIGH | Anthropic safety | Only by #1 |
 | 3-MEDIUM | User instructions | By #1-2 |
 | 4-LOW | Best practices | By #1-3 |
@@ -48,67 +50,11 @@
 
 ---
 
-## CODE PRINCIPLES
-
-- State assumptions before writing code
-- Verify correctness -- do not claim it
-- Handle error paths, not just the happy path
-- Do not import complexity you do not need
-- Produce code you would want to debug at 3am
-
----
-
-{{#if HAS_INFRA}}
-## INFRASTRUCTURE AS CODE POLICY - IaC PARITY REQUIRED
-
-**Local testing is ALLOWED for proving solutions. IaC parity is MANDATORY before completion.**
-
-### Critical: Secrets Are in GitHub
-
-**ALL secrets are stored in GitHub Actions secrets.** Operations requiring secrets MUST use pipelines:
-
-| If operation needs... | Use this pipeline |
-|-----------------------|-------------------|
-| Terraform with secrets | `iac-terraform-cicd.yml` or `ops-ephemeral-terraform.yml` |
-| kubectl with secrets | `ops-approved-operations.yml` |
-| One-time secret operation | `ops-create-ephemeral.yml` (self-destructs after run) |
-
-### Two-Phase Infrastructure Workflow
-
-```
-PHASE 1: LOCAL PROOF (ALLOWED - NO SECRETS)
-  - kubectl get/describe/logs (read-only operations)
-  - terraform plan (uses GitHub pipeline for secrets)
-  - Direct cloud console changes for rapid prototyping
-  - SECRETS REQUIRED? -> Use pipeline, not local commands
-
-PHASE 2: IaC PARITY (MANDATORY - VIA PIPELINE)
-  - Translate ALL manual changes to Terraform/Kubernetes YAML
-  - Commit IaC changes to feature branch
-  - Run terraform plan via pipeline (has secrets)
-  - Deploy via pipeline to confirm 100% match
-  - Delete any manual/ephemeral resources
-  - RULE: Work is NOT complete until IaC matches live state
-```
-
-### Approved Pipelines
-
-| Task | Pipeline | Trigger |
-|------|----------|---------|
-| Kubernetes operations | `ops-approved-operations.yml` | Manual dispatch |
-| Ephemeral environments | `ops-create-ephemeral.yml` | Manual dispatch |
-| Terraform changes | `iac-terraform-cicd.yml` | PR to {{DEFAULT_BRANCH}} |
-| Ephemeral Terraform | `ops-ephemeral-terraform.yml` | Manual dispatch |
-{{/if}}
-
----
-
 ## SESSION START
 
 ```bash
 uam task ready
 sqlite3 ./{{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
-sqlite3 ./{{MEMORY_DB_PATH}} "SELECT * FROM session_memories WHERE session_id='current' ORDER BY id DESC LIMIT 5;"
 uam agent status
 ```
 
@@ -119,311 +65,39 @@ uam agent status
 ## DECISION LOOP
 
 ```
-1. CLASSIFY  -> complexity? backup needed? tools?
-2. PROTECT   -> cp file file.bak (for configs, DBs, critical files)
-3. MEMORY    -> query relevant context + past failures
-4. AGENTS    -> check overlaps (if multi-agent)
-5. SKILLS    -> check {{SKILLS_PATH}} for domain-specific guidance
-6. WORK      -> implement (ALWAYS use worktree for ANY file changes)
-7. REVIEW    -> self-review diff before testing
-8. TEST      -> completion gates pass
-9. LEARN     -> store outcome in memory
+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
 ```
 
 ---
 
-## MEMORY SYSTEM
+## WORKTREE (MANDATORY)
 
-```
-L1 Working  | SQLite memories      | {{SHORT_TERM_LIMIT}} max | <1ms
-L2 Session  | SQLite session_mem   | current session          | <5ms
-L3 Semantic | {{LONG_TERM_BACKEND}}| search                   | ~50ms
-L4 Knowledge| SQLite entities/rels | graph                    | <20ms
-```
-
-### Commands
+**ALL file changes require a worktree.** No exceptions.
 
 ```bash
-# L1: Working Memory
-sqlite3 ./{{MEMORY_DB_PATH}} "INSERT INTO memories (timestamp,type,content) VALUES (datetime('now'),'action','...');"
-
-# L2: Session Memory
-sqlite3 ./{{MEMORY_DB_PATH}} "INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','...',7);"
-
-# L3: Semantic Memory
-{{MEMORY_STORE_CMD}} lesson "..." --tags t1,t2 --importance 8
-
-# L4: Knowledge Graph
-sqlite3 ./{{MEMORY_DB_PATH}} "INSERT INTO entities (type,name,first_seen,last_seen,mention_count) VALUES ('file','x.ts',datetime('now'),datetime('now'),1);"
-```
-
-Decay: `effective_importance = importance * (0.95 ^ days_since_access)`
-
-{{#if PATTERN_RAG_ENABLED}}
-### Pattern RAG (On-Demand)
-
-Patterns are retrieved dynamically from the `{{PATTERN_RAG_COLLECTION}}` Qdrant collection instead of being embedded statically. Top-{{PATTERN_RAG_TOP_K}} relevant patterns are injected per task (score >= {{PATTERN_RAG_THRESHOLD}}).
-
-```bash
-{{PATTERN_RAG_QUERY_CMD}} "task description"   # Query relevant patterns
-{{PATTERN_RAG_INDEX_CMD}}                       # Re-index after CLAUDE.md changes
-uam patterns status                             # Check collection status
-```
-{{/if}}
-
-{{#if RELEVANT_PATTERNS}}
-{{#unless PATTERN_RAG_ENABLED}}
-### Active Patterns
-
-{{{RELEVANT_PATTERNS}}}
-{{/unless}}
-{{/if}}
-
----
-
-## WORKTREE WORKFLOW — MANDATORY
-
-> **MANDATORY**: ALL file changes MUST use a worktree. No exceptions. Never commit directly to any branch without a worktree. After PR is merged, worktree cleanup is MANDATORY — never leave stale worktrees.
-
-| Change Scope | Workflow |
-|-------------|----------|
-| ANY file change (even single-file) | **Worktree REQUIRED** |
-
-```bash
-{{WORKTREE_CREATE_CMD}} <slug>           # ALWAYS create first
+{{WORKTREE_CREATE_CMD}} <slug>
 cd {{WORKTREE_DIR}}/NNN-<slug>/
 git add -A && git commit -m "type: description"
-{{WORKTREE_PR_CMD}} <id>                 # Create PR
-# After PR merge:
-{{WORKTREE_CLEANUP_CMD}} <id>            # MANDATORY cleanup after merge
-```
-
-**Applies to**: {{WORKTREE_APPLIES_TO}} — ALL changes without exception
-
-**Cleanup is MANDATORY**: After every PR merge, immediately run `{{WORKTREE_CLEANUP_CMD}} <id>`. Never leave merged worktrees behind.
-
----
-
-## MULTI-AGENT COORDINATION
-
-**Skip for single-agent sessions.** Only activate when multiple agents work concurrently.
-
-```bash
-uam 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 |
-
-### Agent Routing
-
-| Task Type | Route To |
-|-----------|----------|
-| Security review | `security-auditor` |
-| Performance | `performance-optimizer` |
-| Documentation | `documentation-expert` |
-| Code quality | `code-quality-guardian` |
-
-{{#if LANGUAGE_DROIDS}}
-### Language Droids
-| Droid | Purpose |
-|-------|---------|
-{{{LANGUAGE_DROIDS}}}
-{{/if}}
-
-{{#if MCP_PLUGINS}}
-### MCP Plugins
-| Plugin | Purpose |
-|--------|---------|
-{{{MCP_PLUGINS}}}
-{{/if}}
-
-### Parallel Execution
-
-When safe, run independent tool calls in parallel. When using parallel subagents:
-1. Decompose into discrete work items. Map dependencies.
-2. Parallelize dependency-free items with separate agents and explicit file boundaries.
-3. Gate edits with `uam agent overlaps` before touching any file.
-4. Merge in dependency order (upstream first).
-
----
-
-## PARALLEL REVIEW PROTOCOL
-
-**Before ANY commit/PR, invoke quality droids in PARALLEL:**
-
-```bash
-Task(subagent_type: "code-quality-guardian", prompt: "Review: <files>")
-Task(subagent_type: "security-auditor", prompt: "Audit: <files>")
-Task(subagent_type: "performance-optimizer", prompt: "Analyze: <files>")
-Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
-```
-
-| Droid | Blocks PR | Fix Before Merge |
-|-------|-----------|------------------|
-| security-auditor | CRITICAL/HIGH | Always |
-| code-quality-guardian | CRITICAL only | CRITICAL |
-| performance-optimizer | Advisory | Optional |
-| documentation-expert | Advisory | Optional |
-
----
-
-## CODE QUALITY
-
-### Pre-Commit Checklist
-- Functions <= 30 lines
-- Self-documenting names
-- Error paths handled explicitly
-- No debug prints or commented-out code left behind
-- Consistent with surrounding code style
-- No hardcoded values that should be constants
-- Imports are minimal
-
----
-
-## AUTOMATIC TRIGGERS
-
-| Pattern | Action |
-|---------|--------|
-| work request (fix/add/change/update/create/implement/build) | `uam task create --type task` |
-| bug report/error | `uam task create --type bug` |
-| feature request | `uam task create --type feature` |
-| ANY file change | **create worktree (MANDATORY)** |
-| review/check/look | query memory first |
-| ANY code change | tests required |
-
----
-
-## UAM VISUAL STATUS FEEDBACK
-
-**When UAM tools are in use, show visual feedback:**
-
-```bash
-uam dashboard overview     # Full overview at session start
-uam dashboard progress     # After task operations
-uam task stats             # After task state changes
-uam memory status          # After memory operations
-uam dashboard agents       # After agent/coordination operations
+{{WORKTREE_PR_CMD}} <id>
+# After merge:
+{{WORKTREE_CLEANUP_CMD}} <id>  # MANDATORY
 ```
 
 ---
 
-{{#if HAS_PROJECT_MD}}
-{{> PROJECT}}
-{{else}}
-## REPOSITORY STRUCTURE
-
-```
-{{PROJECT_NAME}}/
-{{{REPOSITORY_STRUCTURE}}}
-```
-
-{{#if ARCHITECTURE_OVERVIEW}}
-## Architecture
-{{{ARCHITECTURE_OVERVIEW}}}
-{{/if}}
-
-{{#if CORE_COMPONENTS}}
-## Components
-{{{CORE_COMPONENTS}}}
-{{/if}}
-
-{{#if AUTH_FLOW}}
-## Authentication
-{{{AUTH_FLOW}}}
-{{/if}}
-
-{{#if CLUSTER_CONTEXTS}}
-## Quick Reference
+## COMPLETION GATES
 
-### Clusters
-```bash
-{{{CLUSTER_CONTEXTS}}}
-```
-{{/if}}
+**CANNOT say "done" until ALL pass:**
 
-{{#if KEY_WORKFLOWS}}
-### Workflows
-```
-{{{KEY_WORKFLOWS}}}
-```
-{{/if}}
-
-{{#if ESSENTIAL_COMMANDS}}
-### Commands
-```bash
-{{{ESSENTIAL_COMMANDS}}}
-```
-{{/if}}
-{{/if}}
-
----
-
-{{#if HAS_INFRA}}
-## Infrastructure Workflow
-
-{{{INFRA_WORKFLOW}}}
-{{/if}}
-
-## Testing Requirements
-1. Create worktree
-2. Update/create tests
-3. Run `{{TEST_COMMAND}}`
-4. Run linting
-5. Create PR
-
----
-
-{{#if TROUBLESHOOTING}}
-## Troubleshooting
-{{{TROUBLESHOOTING}}}
-{{/if}}
-
-{{#if KEY_CONFIG_FILES}}
-## Config Files
-| File | Purpose |
-|------|---------|
-{{{KEY_CONFIG_FILES}}}
-{{/if}}
-
----
-
-## COMMANDS
-
-```bash
-{{TEST_COMMAND}}     # Tests
-{{BUILD_COMMAND}}    # Build
-{{LINT_COMMAND}}     # Lint
-```
-
-**Paths:** Memory: `{{MEMORY_DB_PATH}}` | Skills: `{{SKILLS_PATH}}` | Droids: `{{DROIDS_PATH}}`
-
----
-
-## COMPLETION GATES - MANDATORY
-
-**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
-```
-If missing: CREATE IT immediately.
-
-### GATE 2: Constraint Compliance
-Extract ALL constraints from task ("exactly", "only", "single", "must be", "no more than"). Verify EACH.
-
-### GATE 3: Tests Pass
-```bash
-{{TEST_COMMAND}} 2>&1 | tail -30
-```
-If < 100%: iterate (fix specific failure, re-run). Reserve 20% of time for iteration.
+1. **Output Existence** - All expected files exist
+2. **Constraint Compliance** - All constraints verified
+3. **Tests Pass** - `{{TEST_COMMAND}}` 100%
 
 ---
 
@@ -431,63 +105,51 @@ If < 100%: iterate (fix specific failure, re-run). Reserve 20% of time for itera
 
 ```
 ☐ Tests pass
-☐ Lint/typecheck pass
-☐ Worktree used (MANDATORY for ALL changes)
-☐ Worktree cleaned up after PR merge (MANDATORY)
-☐ Self-review completed
+☐ Lint pass
+☐ Worktree used + cleaned up
+☐ Self-reviewed
 ☐ Memory updated
 ☐ PR created
-☐ Parallel reviews passed
+☐ Reviews passed
 {{#if HAS_INFRA}}
 ☐ IaC parity verified
 {{/if}}
 ☐ No secrets in code
-☐ No debug artifacts left
 ```
 
 ---
 
-## COMPLETION PROTOCOL
+## QUICK REFERENCE
 
-```
-MERGE -> CLEANUP WORKTREE -> DEPLOY -> MONITOR -> FIX (iterate until 100%)
-```
+| Commands | |
+|----------|-|
+| Tests | `{{TEST_COMMAND}}` |
+| Build | `{{BUILD_COMMAND}}` |
+| Lint | `{{LINT_COMMAND}}` |
 
-**Never "done" until:** PR merged + worktree cleaned up + deployed + verified working
+| Paths | |
+|-------|-|
+| Memory | `{{MEMORY_DB_PATH}}` |
+| Patterns | `.factory/patterns/` |
+| Droids | `.factory/droids/` |
+| Skills | `.factory/skills/` |
 
 ---
 
-{{#if PREPOPULATED_KNOWLEDGE}}
-## PROJECT KNOWLEDGE
-
-{{#if RECENT_ACTIVITY}}
-### Recent Activity
-{{{RECENT_ACTIVITY}}}
-{{/if}}
+## KEY MODULES
 
-{{#if LEARNED_LESSONS}}
-### Lessons
-{{{LEARNED_LESSONS}}}
-{{/if}}
-
-{{#if KNOWN_GOTCHAS}}
-### Gotchas
-{{{KNOWN_GOTCHAS}}}
-{{/if}}
-
-{{#if HOT_SPOTS}}
-### Hot Spots
-{{{HOT_SPOTS}}}
-{{/if}}
-{{/if}}
+- `CLAUDE_ARCHITECTURE.md` - Cluster topology, IaC rules
+- `CLAUDE_CODING.md` - Security, multi-tenancy, testing
+- `CLAUDE_WORKFLOWS.md` - Workflows, parallel review
+- `CLAUDE_MEMORY.md` - Pattern RAG, reinforcement learning
+- `CLAUDE_DROIDS.md` - Droid routing, skills
 
 ---
 
-## TOKEN EFFICIENCY
-
-- Prefer concise, high-signal responses
-- Summarize command output; quote only decision-relevant lines
-- Use parallel tool calls to reduce back-and-forth
-- Check `{{SKILLS_PATH}}` for domain-specific skills before re-inventing approaches
+## CODE PRINCIPLES
 
-</coding_guidelines>
+- State assumptions before writing
+- Verify correctness, don't claim it
+- Handle error paths, not just happy path
+- Don't import complexity you don't need
+- Produce code you'd debug at 3am

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
+uam 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
+uam 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
+uam task ready
+sqlite3 ./{{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
+uam 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 | `uam task create --type task` |
+| bug report | `uam task create --type bug` |
+| feature request | `uam 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)