@uluops/setup 0.2.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UluOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,21 +4,57 @@
 
 # @uluops/setup
 
-Zero-friction installer for [UluOps](https://uluops.ai) + Claude Code. One command sets up MCP servers, agents, and slash commands.
+Zero-friction installer for [UluOps](https://uluops.ai) agentic harnesses. One command sets up MCP servers, agents, and slash commands for Claude Code, OpenCode, and more.
 
 ```
 npx @uluops/setup
 ```
 
+> **⚠️ Windows Users:** Native Windows is not yet supported. Please use **WSL2 (Ubuntu)** and run the setup inside your WSL environment.
+
+## Supported harnesses
+
+| Harness | Status | Alias | Config |
+|---------|--------|-------|--------|
+| Claude Code | Fully supported (default) | `claude` | `~/.claude.json` |
+| OpenCode | Fully supported | `oc` | `~/.config/opencode/opencode.json` |
+| Gemini CLI | Fully supported | `gemini` | `~/.gemini/settings.json` |
+| Codex | Coming soon | — | `~/.codex/config.toml` |
+
+```bash
+# Install for Claude Code (default)
+npx @uluops/setup
+
+# Install for OpenCode
+npx @uluops/setup --harness opencode
+
+# Install for Gemini CLI
+npx @uluops/setup --harness gemini-cli
+```
+
 ## What it does
 
-| Artifact | Count | Destination |
-|----------|-------|-------------|
+| Artifact | Count | Destination (Claude Code) |
+|----------|-------|---------------------------|
 | MCP servers | 2 | `~/.claude.json` |
-| Agent definitions | 22 | `~/.claude/agents/` |
-| Slash commands | 27 | `~/.claude/commands/` |
+| Agent definitions | 23 | `~/.claude/agents/` |
+| Agent commands | 23 | `~/.claude/commands/agents/` |
+| Workflow commands | 3 | `~/.claude/commands/workflows/` |
+| Pipeline commands | 2 | `~/.claude/commands/pipelines/` |
+| Agent metrics hook | 1 | `~/.claude/tools/agent-metrics/` |
 
-The installer validates your API key, writes MCP config for the tracker and registry servers, copies pre-rendered agent and command definitions, and runs a health check against both APIs.
+> Paths shown are for Claude Code (default). Gemini CLI installs agents as `.md` and commands as `.toml` to `~/.gemini/`. OpenCode installs agents to `~/.config/opencode/agents/`. Agent definitions and commands are transformed to the target harness format at install time from a single source.
+
+The installer runs these steps in sequence:
+
+1. **Authenticate** — Validates your API key (or creates an account with `--signup`)
+2. **MCP config** — Writes tracker and registry server entries to the harness config
+3. **Definitions** — Copies pre-rendered agent definition files
+4. **Metrics hook** — Configures a post-agent hook for automatic run capture (Claude Code and Gemini CLI)
+5. **`ulu` CLI** *(optional)* — Offers to install `@uluops/cli` globally. Interactive runs are prompted (default Y); non-interactive runs skip unless `--with-cli` is passed. `--no-cli` always skips. The install is best-effort: if `npm install -g` fails (permissions, nvm prefix, etc.) the rest of setup still completes and a manual install command is printed.
+6. **Health check** — Verifies both API endpoints are reachable
+
+> When this setup installs the CLI, the install is recorded in the manifest so `--uninstall` removes it symmetrically. If the CLI was already on your PATH before running setup, it is left alone on uninstall.
 
 ## Usage
 
@@ -26,7 +62,7 @@ The installer validates your API key, writes MCP config for the tracker and regi
 npx @uluops/setup
 ```
 
-You'll be prompted for your API key (get one at [app.uluops.ai/settings/api-keys](https://app.uluops.ai/settings/api-keys)). Everything else uses smart defaults — no other prompts.
+You'll be prompted for your API key (get one at [app.uluops.ai/settings/api-keys](https://app.uluops.ai/settings/api-keys)). Everything else uses smart defaults — no other prompts. See [What it does](#what-it-does) for the full list of changes made.
 
 **New to UluOps?** Create an account without leaving the terminal:
 
@@ -36,16 +72,7 @@ npx @uluops/setup --signup
 
 You'll be prompted for email and password. Account + API key are created automatically.
 
-**Restart Claude Code after setup to load agents.**
-
-### API key resolution
-
-The installer checks these sources in order:
-
-1. `--api-key <key>` flag
-2. `ULUOPS_API_KEY` environment variable
-3. `~/.uluops/credentials.json` (existing CLI auth)
-4. Interactive prompt
+> **🛑 IMPORTANT:** You must restart your harness (e.g., restart Claude Code) after setup to load the new agents and commands.
 
 ### Options
 
@@ -53,24 +80,67 @@ The installer checks these sources in order:
 npx @uluops/setup [options]
 
   --api-key <key>      API key (skip prompt)
+  --harness <name>     Target harness: claude-code, opencode, gemini-cli, codex
+                       Aliases: claude, oc, gemini (default: claude-code)
   --signup             Create account from terminal (email + password)
   --scope <mode>       MCP config scope: "global" or "local" (default: global)
-  --local-defs         Save definitions to ./uluops/ instead of ~/.claude/
+  --local-defs         Save definitions to ./uluops/ for review
   --shell              Write API key export to shell profile
+  --with-cli           Install @uluops/cli globally (skip prompt)
+  --no-cli             Skip @uluops/cli install (skip prompt)
   --skip-validation    Accept API key without server verification
   --list               Show available agents and workflows without installing
-  --verify             Check existing installation health (no changes)
+  --verify             Check installation health: manifest, files, MCP config, API connectivity (no changes)
   --uninstall          Remove all UluOps-managed artifacts
   --dry-run            Show what would happen without making changes
   -y, --yes            Skip confirmations
 ```
 
+### Advanced Commands
+
+#### Preview available agents (`--list`)
+Displays all agents and workflows included in the current version of the setup tool.
+
+```text
+  ⟨u⟩ ulu·ops v0.6.0 — available agents and workflows
+
+  WORKFLOWS
+  /workflows:post-implementation   Iterative validation after coding
+  /workflows:pre-implementation    Design validation before implementation
+  /workflows:prompt-audit          Strategic prompt quality audit
+
+  AGENTS (run individually)                          MODEL
+  /agents:code-validator           Validate cod...  sonnet
+  /agents:type-safety              Deep TypeScr...  sonnet
+  /agents:security-analyst         Comprehensiv...  sonnet
+  /agents:test-architect           Validate tes...  sonnet
+  ...
+```
+
+#### Check installation health (`--verify`)
+Validates your current installation against the local manifest and checks API connectivity.
+
+```text
+  ⟨u⟩ ulu·ops Installation Check v0.6.0
+
+  ✓ Manifest found (~/.uluops/manifest.json)
+  ✓ All 23 agents present in ~/.claude/agents/
+  ✓ MCP servers configured in ~/.claude.json
+  ✓ API connectivity: Tracker (Online)
+  ✓ API connectivity: Registry (Online)
+
+  All checks passed.
+```
+
 ### Examples
 
 ```bash
 # New user — create account + install in one shot
 npx @uluops/setup --signup
 
+# Install for OpenCode
+npx @uluops/setup --harness opencode
+
 # Non-interactive (CI/automation)
 npx @uluops/setup --api-key ulr_abc123 -y
 
@@ -83,64 +153,13 @@ npx @uluops/setup --dry-run --api-key ulr_abc123
 # Persist API key in shell profile (~/.zshrc, ~/.bashrc, etc.)
 npx @uluops/setup --shell
 
-# Preview what's included without installing
-npx @uluops/setup --list
+# Install the ulu CLI globally alongside harness setup
+npx @uluops/setup --with-cli
 
-# Check existing installation
-npx @uluops/setup --verify
-
-# Clean removal
-npx @uluops/setup --uninstall
+# Skip the CLI prompt entirely (interactive runs default to asking)
+npx @uluops/setup --no-cli
 ```
 
-## What's included
-
-### Workflows
-
-| Command | Description |
-|---------|-------------|
-| `/workflows:pre-implementation` | Design review before coding |
-| `/workflows:post-implementation` | Iterative validation loop |
-| `/workflows:ship` | Final gate before shipping |
-| `/workflows:prompt-audit` | Audit agent prompts |
-| `/workflows:aristotle` | Four-phase Aristotelian analysis |
-
-### Agents
-
-| Command | Focus | Model |
-|---------|-------|-------|
-| `/agents:validate` | Code quality | sonnet |
-| `/agents:type-safety` | TypeScript | sonnet |
-| `/agents:test-review` | Test quality | sonnet |
-| `/agents:optimize` | Performance | sonnet |
-| `/agents:frontend` | React/a11y | sonnet |
-| `/agents:mcp-validate` | MCP compliance | sonnet |
-| `/agents:architect` | Design review | sonnet |
-| `/agents:audit` | Runtime bugs | opus |
-| `/agents:security` | OWASP | sonnet |
-| `/agents:api-contract` | API alignment | sonnet |
-| `/agents:release` | Publish ready | sonnet |
-| `/agents:public-interface` | README/exports | sonnet |
-| `/agents:docs-validate` | Documentation | sonnet |
-| `/agents:prompt-validate` | Prompt review | sonnet |
-| `/agents:prompt-quality` | Prompt quality | sonnet |
-| `/agents:pattern-analyzer` | Patterns | sonnet |
-| `/agents:aristotle-explorer` | Categories | opus |
-| `/agents:aristotle-analyst` | Four causes | opus |
-| `/agents:aristotle-validator` | Teleology | opus |
-| `/agents:aristotle-forecaster` | Potentiality | opus |
-| `/agents:assumption-excavator` | Assumptions | sonnet |
-| `/agents:workflow-synthesis` | Cross-agent synthesis | opus |
-
-> This is the starter set. Browse 135+ agents at [registry.uluops.ai](https://registry.uluops.ai).
-
-### MCP servers
-
-Both servers use `npx -y` so there's no global install required:
-
-- **uluops-tracker** — Validation run tracking, issue management, analytics
-- **uluops-registry** — Agent definition registry, versioning, rendering
-
 ## How updates work
 
 Re-running `npx @uluops/setup` is safe and idempotent:
@@ -150,7 +169,15 @@ Re-running `npx @uluops/setup` is safe and idempotent:
 - Removed definitions are cleaned up
 - Your custom agents and non-UluOps MCP servers are never touched
 
-A manifest at `~/.claude/uluops-manifest.json` tracks what was installed.
+Setup manages four surfaces: agent files, command files, MCP config entries, and the metrics hook. A manifest at `~/.uluops/manifest.json` tracks what was installed so `--uninstall` can cleanly reverse all changes. The manifest supports multiple harnesses — each gets its own installation state.
+
+## Troubleshooting
+
+- **Agents not appearing:** Ensure you have restarted your harness (Claude Code, etc.) after running setup. For Claude Code, simply exit and restart the CLI.
+- **MCP errors:** If the harness fails to start the MCP servers, ensure `npx` is available in your PATH. You can check your config at `~/.claude.json` or `~/.config/opencode/opencode.json`.
+- **API key rejected:** Verify your key at [app.uluops.ai](https://app.uluops.ai). If you are behind a corporate proxy, you may need to set `HTTPS_PROXY`.
+- **`@uluops/cli` install warning:** If setup warns it could not install the CLI globally (EACCES, nvm prefix mismatch, network), the rest of setup still completes. Run `npm install -g @uluops/cli` yourself when convenient — once it's on your PATH, every subsequent `npx @uluops/setup` will see it and skip the install step.
+- **Windows issues:** Remember that native Windows is not supported; you must run the installer and your harness within **WSL2**.
 
 ## Uninstall
 
@@ -158,21 +185,14 @@ A manifest at `~/.claude/uluops-manifest.json` tracks what was installed.
 npx @uluops/setup --uninstall
 ```
 
-Removes only UluOps-managed files: agents, commands, MCP config entries, and shell profile export (if `--shell` was used). Your custom agents and other MCP servers are preserved.
+Removes only UluOps-managed files: agents, commands, MCP config entries, shell profile export (if `--shell` was used), and the global `@uluops/cli` package (only if this setup installed it — a CLI you installed yourself is left alone). Your custom agents and other MCP servers are preserved. Uninstall iterates all harnesses recorded in the manifest.
 
 ## Requirements
 
-- Node.js >= 18
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
-- UluOps API key ([get one here](https://app.uluops.ai/settings/api-keys))
-
-> **Global install:** If you install globally with `npm i -g @uluops/setup`, the binary is `uluops-setup`.
+- **Node.js:** >= 20.0.0
+- **Platform:** Linux, macOS, or WSL2 (native Windows not supported)
+- **Harness:** Claude Code, OpenCode, or Gemini CLI
+- **Auth:** UluOps API key ([get one here](https://app.uluops.ai/settings/api-keys))
 
-## Platform support
-
-| Platform | Status |
-|----------|--------|
-| Linux | Supported |
-| macOS | Supported |
-| WSL2 | Supported |
-| Windows (native) | Not yet supported |
+---
+**Global install:** If you prefer, install once with `npm i -g @uluops/setup` then run `uluops-setup`.

package/assets/auto-tracker-save.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-Tracker-Save Hook for Gemini CLI & Claude Code
+ * 
+ * Event: AfterTool (Gemini CLI) / SubagentStop (Claude Code)
+ * 
+ * This hook parses the output of an agent run and automatically
+ * queues a save_run call to the UluOps Tracker.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch (err) {
+    process.stderr.write('Failed to parse hook input: ' + err.message + '\n');
+    process.exit(1);
+  }
+
+  const { tool_name, tool_response, metadata, cwd } = input;
+
+  // Handle both Gemini CLI's invoke_agent and Claude Code's agent execution
+  // (In Claude Code, tool_name might be the specific agent tool if it's rendered as one)
+  const isAgentTool = tool_name === 'invoke_agent' || tool_name.startsWith('uluops-');
+  
+  if (!isAgentTool) {
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    return;
+  }
+
+  const content = tool_response?.llmContent || tool_response?.content || '';
+  if (!content) {
+    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    return;
+  }
+
+  // --- Parsing Logic ---
+  
+  // 1. Extract Agent Name
+  let agentName = input.tool_input?.agent_name || tool_name.replace(/^uluops-/, '');
+  if (agentName === 'invoke_agent') agentName = 'unknown-agent';
+
+  // 2. Extract Verdict and Score
+  // Broaden pattern to catch various agent output styles
+  const decisionMatch = content.match(/\*\*Verdict:\s*([A-Z_]+)/i) || 
+                        content.match(/\*\*Decision:\s*([A-Z_]+)/i) ||
+                        content.match(/Verdict:\s*([A-Z_]+)/i) ||
+                        content.match(/Decision:\s*([A-Z_]+)/i);
+  
+  const scoreMatch = content.match(/\(Score:\s*(\d+)\/100\)/i) ||
+                     content.match(/Score:\s*(\d+)/i);
+  
+  const decision = decisionMatch ? decisionMatch[1].toUpperCase() : 'PASS';
+  const score = scoreMatch ? parseInt(scoreMatch[1], 10) : 100;
+
+  // 3. Extract Summary
+  const summaryMatch = content.match(/### Executive Summary\n\n(.*?)(?:\n\n|###|$)/s) ||
+                       content.match(/Summary\n\n(.*?)(?:\n\n|###|$)/s) ||
+                       content.match(/## .*?\n\n(.*?)(?:\n\n|###|$)/s);
+  const summary = summaryMatch ? summaryMatch[1].trim().substring(0, 500) : `Auto-saved run for ${agentName}`;
+
+  // 4. Extract Recommendations & Failure Codes
+  const recommendations = [];
+  // Resilient pattern for list items containing a failure code
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const codeMatch = line.match(/`([A-Z]{3}-[A-Z]{3}\/[CHMLI])`/);
+    if (codeMatch) {
+      const code = codeMatch[1];
+      // Try to extract title: everything before the first '(' or '`' or '-'
+      let title = line.replace(/^\s*[\*\-]\s*/, '') // remove bullet
+                      .split(/[`\(\-]/)[0] // take everything before first separator
+                      .trim();
+      
+      if (!title) title = `Issue ${code}`;
+
+      // Try to extract priority
+      const priorityMatch = line.match(/\((Priority: )?(critical|high|suggested|backlog)\)/i);
+      const priority = priorityMatch ? priorityMatch[2].toLowerCase() : 'suggested';
+
+      recommendations.push({
+        agent: agentName,
+        title: title.substring(0, 100),
+        priority,
+        failure_code: code,
+        description: 'Extracted via auto-save hook'
+      });
+    }
+  }
+
+  // 5. Project Name Detection
+  let project = 'default-project';
+  if (cwd) {
+    const parts = cwd.split('/');
+    // If we're in a sub-repo (like uluops packages), use the last two parts
+    if (parts.length > 2 && (parts[parts.length-2].startsWith('-') || parts[parts.length-2] === 'packages')) {
+      project = parts[parts.length-1];
+    } else {
+      project = parts.pop();
+    }
+  }
+
+  // --- Build Tail Call ---
+
+  const saveRunArgs = {
+    project,
+    workflow_type: 'auto-save',
+    agents: [{
+      name: agentName,
+      model: metadata?.model || 'gemini-1.5-pro',
+      decision,
+      score: score,
+      summary,
+      tokens: {
+        input_tokens: metadata?.input_tokens || 0,
+        output_tokens: metadata?.output_tokens || 0,
+        cache_creation_tokens: metadata?.cache_creation_tokens || 0,
+        cache_read_tokens: metadata?.cache_read_tokens || 0
+      }
+    }],
+    recommendations
+  };
+
+  const output = {
+    decision: 'allow',
+    systemMessage: `[hook] Auto-saving ${agentName} results to tracker (Project: ${project})...`,
+    hookSpecificOutput: {
+      tailToolCallRequest: {
+        name: 'mcp_uluops-tracker_save_run',
+        args: saveRunArgs
+      }
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+main();