@uluops/setup 0.2.0

package/assets/commands/agents/api-contract.md

@@ -0,0 +1,135 @@
+---
+name: api-contract
+description: Run API Contract Validator to check consistency between docs, types, and implementation. Use after any API endpoint changes.
+---
+
+# API Contract Validator
+Run API Contract Validator to check consistency between docs, types, and implementation. Use after any API endpoint changes.
+
+## Arguments
+
+**Usage:** `/agents:api-contract <directory>`
+
+**Examples:**
+- `/agents:api-contract ./api`
+- `/agents:api-contract ./services/api`
+- `/agents:api-contract .`
+
+**Target Directory:** $ARGUMENTS
+
+---
+
+## Pre-Flight
+
+```bash
+echo "Running API contract validation on $ARGUMENTS..."
+echo "================================================"
+```
+
+Verify the target directory exists:
+
+```bash
+test -d "$ARGUMENTS" && echo "✓ Directory exists: $ARGUMENTS" || echo "ERROR: Directory '$ARGUMENTS' not found"
+```
+
+Enter and confirm location:
+
+```bash
+cd "$ARGUMENTS" && pwd
+```
+
+Check path exists:
+
+```bash
+[ -e "$ARGUMENTS" ] && echo "✓ $ARGUMENTS exists" || echo "Target directory does not exist"
+```
+
+
+---
+
+## Agent Invocation
+
+Run the API Contract Validator agent on the validated target directory:
+
+**Agent:** api-contract-validator-agent.md
+**Model:** Sonnet
+**Target:** $ARGUMENTS
+
+The agent performs code quality validation across 4 categories (100 points total):
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Endpoint Completeness | 25 | Validates all routes have documentation and type definitions |
+| Request Contract | 25 | Validates request schemas match implementation |
+| Response Contract | 25 | Validates response schemas match actual output |
+| Breaking Change Safety | 25 | Validates breaking changes are handled properly |
+
+---
+
+## Auto-Fail Conditions
+
+Critical issues that trigger immediate FAIL regardless of score:
+
+| ID | Condition |
+|----|-----------|
+| **AF-001** | Required request fields not documented |
+| **AF-002** | Response fields in docs but not returned |
+| **AF-003** | Sensitive fields exposed without documentation |
+| **AF-004** | Breaking changes without versioning |
+| **AF-005** | Error formats inconsistent across endpoints |
+| **AF-006** | Security-relevant fields undocumented |
+
+---
+
+## Decision Thresholds
+
+| Score | Decision | Meaning |
+|-------|----------|---------|
+| **>=80** | ✅ PASS | Validation passed, proceed to next phase |
+| **<80** | ❌ FAIL | Validation failed, fix issues before proceeding |
+
+**Note:** Any critical issue triggers FAIL regardless of score.
+
+---
+
+
+## PERSIST TO TRACKER (Required)
+
+> **IMPORTANT:** Save to tracker IMMEDIATELY after agent completes, BEFORE presenting the summary to the user. The workflow is not complete until results are persisted.
+**1. Get token metrics from buffer:**
+```bash
+agent-metrics buffer list --since 5m -f tracker
+```
+
+**2. Save to tracker (DO THIS FIRST):**
+
+mcp__uluops-tracker__save_features_list
+
+**3. Verify saved:** Compare `json.summary.total_issues` with saved count.
+
+**4. THEN present summary to user.**
+
+### Field Mappings
+
+**From JSON OUTPUT to Tracker:**
+| Source | Tracker Field | Notes |
+|--------|---------------|-------|
+| `json.result.score` | `validators[].score` | Total score |
+| `json.result.decision` | `validators[].status` | PASS/FAIL |
+| `buffer.model` | `validators[].model` | From agent-metrics buffer |
+| `buffer.tokens.input_tokens` | `input_tokens` | Raw input tokens |
+| `buffer.tokens.output_tokens` | `output_tokens` | Output tokens |
+| `buffer.tokens.cache_creation_tokens` | `cache_creation_tokens` | Cache creation |
+| `buffer.tokens.cache_read_tokens` | `cache_read_tokens` | Cache reads |
+| `buffer.tokens.total_effective_tokens` | `total_effective_tokens` | Effective total |
+| `json.categories[].findings[].issues[]` | `recommendations[]` | Flatten nested structure |
+
+**Note:** `json` = agent's JSON OUTPUT, `buffer` = `agent-metrics buffer list -f tracker`
+
+---
+
+## Source
+
+**CDL Schema:** `udl/definition-languages/cdl-schema-v1.1.0.json`
+**CDL Source:** `/home/alexs/uluops/uluops-agent-workflows/udl/cdl/v1/api-contract.command.yaml`
+**Agent:** `agents/api-contract-validator-agent.md`

package/assets/commands/agents/architect.md

@@ -0,0 +1,135 @@
+---
+name: architect
+description: Run Pre-Implementation Architect to validate design before coding. Reviews architectural fit, complexity, scope. Use BEFORE starting implementation.
+---
+
+# Pre-Implementation Architect
+Run Pre-Implementation Architect to validate design before coding. Reviews architectural fit, complexity, scope. Use BEFORE starting implementation.
+
+## Arguments
+
+**Usage:** `/agents:architect <directory>`
+
+**Examples:**
+- `/agents:architect ./docs/design.md`
+- `/agents:architect ./PRD.md`
+- `/agents:architect .`
+
+**Target Directory:** $ARGUMENTS
+
+---
+
+## Pre-Flight
+
+```bash
+echo "Running architecture review on $ARGUMENTS..."
+echo "============================================"
+```
+
+Verify the target directory exists:
+
+```bash
+test -d "$ARGUMENTS" && echo "✓ Directory exists: $ARGUMENTS" || echo "ERROR: Directory '$ARGUMENTS' not found"
+```
+
+Enter and confirm location:
+
+```bash
+cd "$ARGUMENTS" && pwd
+```
+
+Check path exists:
+
+```bash
+[ -e "$ARGUMENTS" ] && echo "✓ $ARGUMENTS exists" || echo "Target directory does not exist"
+```
+
+
+---
+
+## Agent Invocation
+
+Run the Pre-Implementation Architect agent on the validated target directory:
+
+**Agent:** pre-implementation-architect-agent.md
+**Model:** Sonnet
+**Target:** $ARGUMENTS
+
+The agent performs code quality validation across 4 categories (100 points total):
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Architectural Fit | 25 | Follows existing patterns, consistent conventions, clean integration |
+| Design Quality | 25 | Single responsibility, separation of concerns, balanced abstraction levels |
+| Scope & Complexity | 25 | Phase sized within limits (<500 LOC, <10 files, <3 deps), complexity justified, simpler alternatives considered |
+| Completeness | 25 | Edge cases, error scenarios, data flow, API contracts, testing strategy |
+
+---
+
+## Auto-Fail Conditions
+
+Critical issues that trigger immediate FAIL regardless of score:
+
+| ID | Condition |
+|----|-----------|
+| **AF-001** | Design contradicts existing architecture without justification |
+| **AF-002** | Missing error handling strategy for critical paths |
+| **AF-003** | Scope too large for single implementation phase |
+| **AF-004** | Circular dependencies would be introduced |
+| **AF-005** | No clear data flow or API contracts |
+| **AF-006** | Breaking changes without migration strategy |
+
+---
+
+## Decision Thresholds
+
+| Score | Decision | Meaning |
+|-------|----------|---------|
+| **>=80** | ✅ PASS | Validation passed, proceed to next phase |
+| **<80** | ❌ FAIL | Validation failed, fix issues before proceeding |
+
+**Note:** Any critical issue triggers FAIL regardless of score.
+
+---
+
+
+## PERSIST TO TRACKER (Required)
+
+> **IMPORTANT:** Save to tracker IMMEDIATELY after agent completes, BEFORE presenting the summary to the user. The workflow is not complete until results are persisted.
+**1. Get token metrics from buffer:**
+```bash
+agent-metrics buffer list --since 5m -f tracker
+```
+
+**2. Save to tracker (DO THIS FIRST):**
+
+mcp__uluops-tracker__save_features_list
+
+**3. Verify saved:** Compare `json.summary.total_issues` with saved count.
+
+**4. THEN present summary to user.**
+
+### Field Mappings
+
+**From JSON OUTPUT to Tracker:**
+| Source | Tracker Field | Notes |
+|--------|---------------|-------|
+| `json.result.score` | `validators[].score` | Total score |
+| `json.result.decision` | `validators[].status` | PASS/FAIL |
+| `buffer.model` | `validators[].model` | From agent-metrics buffer |
+| `buffer.tokens.input_tokens` | `input_tokens` | Raw input tokens |
+| `buffer.tokens.output_tokens` | `output_tokens` | Output tokens |
+| `buffer.tokens.cache_creation_tokens` | `cache_creation_tokens` | Cache creation |
+| `buffer.tokens.cache_read_tokens` | `cache_read_tokens` | Cache reads |
+| `buffer.tokens.total_effective_tokens` | `total_effective_tokens` | Effective total |
+| `json.categories[].findings[].issues[]` | `recommendations[]` | Flatten nested structure |
+
+**Note:** `json` = agent's JSON OUTPUT, `buffer` = `agent-metrics buffer list -f tracker`
+
+---
+
+## Source
+
+**CDL Schema:** `udl/definition-languages/cdl-schema-v1.1.0.json`
+**CDL Source:** `/home/alexs/uluops/uluops-agent-workflows/udl/cdl/v1/architect.command.yaml`
+**Agent:** `agents/pre-implementation-architect-agent.md`

package/assets/commands/agents/aristotle-analyst.md

@@ -0,0 +1,115 @@
+---
+name: aristotle-analyst
+description: Performs Aristotelian four-cause decomposition on any artifact. Identifies material, formal, efficient, and final causes. Distinguishes essential from accidental properties. Assesses telos coherence. Decision: TELEOLOGICAL/ATELEOLOGICAL.
+---
+
+# Aristotle Analyst
+Performs Aristotelian four-cause decomposition on any artifact — code, specs, plans, architectures, or documents. First cognitive lens agent from the Cognitive Lens Library.
+
+## Arguments
+
+**Usage:** `/agents:aristotle-analyst <target>`
+
+**Examples:**
+- `/agents:aristotle-analyst uluops-registry-api/`
+- `/agents:aristotle-analyst udl/adl/v3/code-validator.agent.yaml`
+- `/agents:aristotle-analyst docs/specs/cognitive-lens-library-spec.md`
+- `/agents:aristotle-analyst packages/cli/`
+
+**Target:** $ARGUMENTS
+
+---
+
+## Pre-Flight
+
+Verify the target exists:
+
+```bash
+[ -e "$ARGUMENTS" ] && echo "✓ $ARGUMENTS exists" || echo "Target file or directory does not exist"
+```
+
+---
+
+## Agent Invocation
+
+Run the Aristotle Analyst agent on the target:
+
+**Agent:** aristotle-analyst-agent.md
+**Model:** Opus
+**Target:** $ARGUMENTS
+
+The agent performs Aristotelian decomposition across 5 categories (100 points total):
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Four-Cause Completeness | 25 | Material, formal, efficient, final causes per element |
+| Telos Coherence | 25 | Purpose identified, defended, served by parts |
+| Essential/Accidental | 20 | Properties classified with destruction-test justification |
+| Categorical Classification | 15 | Genus and differentia identified |
+| Potentiality-Actuality | 15 | Current state vs. unrealized potential |
+
+## Auto-Fail Conditions
+
+| ID | Condition | Severity |
+|----|-----------|----------|
+| AF-001 | No genuine four-cause decomposition performed | Critical |
+| AF-002 | Efficient and final causes systematically conflated | Critical |
+| AF-003 | Telos is circular or tautological | Critical |
+| AF-004 | Essential/accidental not distinguished | Critical |
+| AF-005 | Generic analysis relabeled with Aristotelian terms | Critical |
+
+---
+
+## Decision Thresholds
+
+| Score | Decision | Meaning |
+|-------|----------|---------|
+| **>=70** | TELEOLOGICAL | Artifact has coherent causal structure ordered toward identifiable telos |
+| **<70** | ATELEOLOGICAL | Artifact's telos is unclear, contradicted, or analysis incomplete |
+
+**Note:** This is an advisory decision, not a deployment gate. TELEOLOGICAL means the artifact's parts serve a coherent purpose — not that the artifact is correct or desirable.
+
+---
+
+## PERSIST TO TRACKER (Required)
+
+> **IMPORTANT:** Save to tracker IMMEDIATELY after agent completes, BEFORE presenting the summary to the user.
+
+**1. Get token metrics from buffer:**
+```bash
+agent-metrics buffer list --since 5m -f tracker
+```
+
+**2. Save to tracker (DO THIS FIRST):**
+
+mcp__uluops-tracker__save_features_list
+
+**3. Verify saved:** Compare `json.summary.total_issues` with saved count.
+
+**4. THEN present summary to user.**
+
+### Field Mappings
+
+**From JSON OUTPUT to Tracker:**
+| Source | Tracker Field | Notes |
+|--------|---------------|-------|
+| `json.result.score` | `validators[].score` | Total score |
+| `json.result.decision` | `validators[].status` | TELEOLOGICAL/ATELEOLOGICAL |
+| `buffer.model` | `validators[].model` | From agent-metrics buffer |
+| `buffer.tokens.input_tokens` | `input_tokens` | Raw input tokens |
+| `buffer.tokens.output_tokens` | `output_tokens` | Output tokens |
+| `buffer.tokens.cache_creation_tokens` | `cache_creation_tokens` | Cache creation |
+| `buffer.tokens.cache_read_tokens` | `cache_read_tokens` | Cache reads |
+| `buffer.tokens.total_effective_tokens` | `total_effective_tokens` | Effective total |
+| `json.categories[].findings[].issues[]` | `recommendations[]` | Flatten nested structure |
+
+**Note:** `json` = agent's JSON OUTPUT, `buffer` = `agent-metrics buffer list -f tracker`
+
+---
+
+## Source
+
+**ADL Schema:** `udl/definition-languages/adl-schema-v1.9.0.json`
+**ADL Source:** `udl/adl/v3/aristotle-analyst.agent.yaml`
+**Agent:** `agents/v3/aristotle-analyst-agent.md`
+**Spec:** `docs/specs/cognitive-lens-library-spec.md`

package/assets/commands/agents/aristotle-explorer.md

@@ -0,0 +1,92 @@
+---
+name: aristotle-explorer
+description: Performs Aristotelian categorical mapping on any artifact. Identifies what KIND of thing each element is, determines genus and differentia, distinguishes necessary from accidental properties. Produces a taxonomic map of the problem domain.
+---
+
+# Aristotle Explorer
+Performs Aristotelian categorical mapping on any artifact — code, specs, plans, architectures, or documents. Cognitive lens agent from the Cognitive Lens Library.
+
+## Arguments
+
+**Usage:** `/agents:aristotle-explorer <target>`
+
+**Examples:**
+- `/agents:aristotle-explorer uluops-registry-api/`
+- `/agents:aristotle-explorer udl/adl/v3/code-validator.agent.yaml`
+- `/agents:aristotle-explorer docs/specs/cognitive-lens-library-spec.md`
+- `/agents:aristotle-explorer packages/cli/`
+
+**Target:** $ARGUMENTS
+
+---
+
+## Pre-Flight
+
+Verify the target exists:
+
+```bash
+[ -e "$ARGUMENTS" ] && echo "✓ $ARGUMENTS exists" || echo "Target file or directory does not exist"
+```
+
+---
+
+## Agent Invocation
+
+Run the Aristotle Explorer agent on the target:
+
+**Agent:** aristotle-explorer-agent.md
+**Model:** Opus
+**Target:** $ARGUMENTS
+
+The agent performs Aristotelian categorical mapping through 4 phases:
+
+| Phase | Name | Focus |
+|-------|------|-------|
+| 1 | Inventory | Read artifact, identify elements, note stated roles |
+| 2 | Classification | Identify genus/differentia, destruction-test, accidental properties |
+| 3 | Taxonomic Mapping | Build taxonomic tree, find divergences, surface fluid categories |
+| 4 | Synthesis | Write complete map, state classifications, note limitations |
+
+**Note:** Explorers produce structured taxonomic maps, not numeric scores. The output is a categorical classification of the artifact's domain.
+
+---
+
+## PERSIST TO TRACKER (Required)
+
+> **IMPORTANT:** Save to tracker IMMEDIATELY after agent completes, BEFORE presenting the summary to the user.
+
+**1. Get token metrics from buffer:**
+```bash
+agent-metrics buffer list --since 5m -f tracker
+```
+
+**2. Save to tracker (DO THIS FIRST):**
+
+mcp__uluops-tracker__save_features_list
+
+**3. Verify saved:** Compare `json.summary.total_issues` with saved count.
+
+**4. THEN present summary to user.**
+
+### Field Mappings
+
+**From JSON OUTPUT to Tracker:**
+| Source | Tracker Field | Notes |
+|--------|---------------|-------|
+| `buffer.model` | `validators[].model` | From agent-metrics buffer |
+| `buffer.tokens.input_tokens` | `input_tokens` | Raw input tokens |
+| `buffer.tokens.output_tokens` | `output_tokens` | Output tokens |
+| `buffer.tokens.cache_creation_tokens` | `cache_creation_tokens` | Cache creation |
+| `buffer.tokens.cache_read_tokens` | `cache_read_tokens` | Cache reads |
+| `buffer.tokens.total_effective_tokens` | `total_effective_tokens` | Effective total |
+
+**Note:** `buffer` = `agent-metrics buffer list -f tracker`
+
+---
+
+## Source
+
+**ADL Schema:** `udl/definition-languages/adl-schema-v1.10.0.json`
+**ADL Source:** `udl/adl/v3/aristotle-explorer.agent.yaml`
+**Agent:** `agents/v3/aristotle-explorer-agent.md`
+**Spec:** `docs/specs/cognitive-lens-library-spec.md`

package/assets/commands/agents/aristotle-forecaster.md

@@ -0,0 +1,114 @@
+---
+name: aristotle-forecaster
+description: Performs Aristotelian potentiality-to-actuality projection on any artifact. Maps trajectory from current state to full actualization, identifies impediments to telos realization. Decision: HIGH_CONFIDENCE/MODERATE_CONFIDENCE/LOW_CONFIDENCE.
+---
+
+# Aristotle Forecaster
+Performs Aristotelian potentiality-to-actuality projection on any artifact — code, specs, plans, architectures, or documents. Cognitive lens agent from the Cognitive Lens Library.
+
+## Arguments
+
+**Usage:** `/agents:aristotle-forecaster <target>`
+
+**Examples:**
+- `/agents:aristotle-forecaster uluops-registry-api/`
+- `/agents:aristotle-forecaster udl/adl/v3/code-validator.agent.yaml`
+- `/agents:aristotle-forecaster docs/specs/cognitive-lens-library-spec.md`
+- `/agents:aristotle-forecaster packages/cli/`
+
+**Target:** $ARGUMENTS
+
+---
+
+## Pre-Flight
+
+Verify the target exists:
+
+```bash
+[ -e "$ARGUMENTS" ] && echo "✓ $ARGUMENTS exists" || echo "Target file or directory does not exist"
+```
+
+---
+
+## Agent Invocation
+
+Run the Aristotle Forecaster agent on the target:
+
+**Agent:** aristotle-forecaster-agent.md
+**Model:** Opus
+**Target:** $ARGUMENTS
+
+The agent performs Aristotelian potentiality-to-actuality projection across 5 categories (100 points total):
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Potentiality Identification | 25 | Latent capabilities, structural grounding, potentiality vs possibility |
+| Actualization Pathways | 25 | Pathway specificity, natural ordering, form alignment |
+| Impediment Analysis | 20 | Structural impediments (not resource constraints), actionable specificity |
+| Teleological Trajectory | 15 | Movement toward/away from telos, potentiality-telos connection |
+| Temporal Precision | 15 | Actualization stages, current position on trajectory |
+
+## Auto-Fail Conditions
+
+| ID | Condition | Severity |
+|----|-----------|----------|
+| AF-001 | Feature requests presented as potentiality analysis | Critical |
+| AF-002 | Impediments listed as resource constraints rather than structural barriers | Critical |
+| AF-003 | No connection between potentialities and artifact's telos | Critical |
+
+---
+
+## Decision Thresholds
+
+| Score | Decision | Meaning |
+|-------|----------|---------|
+| **>=75** | HIGH_CONFIDENCE | Trajectory is clear, potentialities well-mapped, impediments specific |
+| **50-74** | MODERATE_CONFIDENCE | Trajectory partially clear, some potentialities uncertain |
+| **<50** | LOW_CONFIDENCE | Trajectory unclear, insufficient structural evidence for projection |
+
+**Note:** This is an advisory decision. HIGH_CONFIDENCE means the artifact's trajectory is well-understood — not that the trajectory is desirable.
+
+---
+
+## PERSIST TO TRACKER (Required)
+
+> **IMPORTANT:** Save to tracker IMMEDIATELY after agent completes, BEFORE presenting the summary to the user.
+
+**1. Get token metrics from buffer:**
+```bash
+agent-metrics buffer list --since 5m -f tracker
+```
+
+**2. Save to tracker (DO THIS FIRST):**
+
+mcp__uluops-tracker__save_features_list
+
+**3. Verify saved:** Compare `json.summary.total_issues` with saved count.
+
+**4. THEN present summary to user.**
+
+### Field Mappings
+
+**From JSON OUTPUT to Tracker:**
+| Source | Tracker Field | Notes |
+|--------|---------------|-------|
+| `json.result.score` | `validators[].score` | Total score |
+| `json.result.decision` | `validators[].status` | HIGH_CONFIDENCE/MODERATE_CONFIDENCE/LOW_CONFIDENCE |
+| `buffer.model` | `validators[].model` | From agent-metrics buffer |
+| `buffer.tokens.input_tokens` | `input_tokens` | Raw input tokens |
+| `buffer.tokens.output_tokens` | `output_tokens` | Output tokens |
+| `buffer.tokens.cache_creation_tokens` | `cache_creation_tokens` | Cache creation |
+| `buffer.tokens.cache_read_tokens` | `cache_read_tokens` | Cache reads |
+| `buffer.tokens.total_effective_tokens` | `total_effective_tokens` | Effective total |
+| `json.categories[].findings[].issues[]` | `recommendations[]` | Flatten nested structure |
+
+**Note:** `json` = agent's JSON OUTPUT, `buffer` = `agent-metrics buffer list -f tracker`
+
+---
+
+## Source
+
+**ADL Schema:** `udl/definition-languages/adl-schema-v1.10.0.json`
+**ADL Source:** `udl/adl/v3/aristotle-forecaster.agent.yaml`
+**Agent:** `agents/v3/aristotle-forecaster-agent.md`
+**Spec:** `docs/specs/cognitive-lens-library-spec.md`