ultra-builder-pro-cli 0.5.0

package/orchestrator/worktree-manager.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+// Phase 8B.3 — N-concurrent git worktree registry.
+//
+// Wraps session-runner's single-session gitWorktreeAdd/Remove with:
+//   • allocate({repoRoot, sid, baseRef})  — create .ultra/worktrees/<sid>
+//   • release({repoRoot, worktree_path})  — remove one
+//   • listActive(repoRoot)                — scan git + filter our domain
+//   • releaseAll(repoRoot)                — batch cleanup (crash recovery)
+//
+// Node single-thread execFileSync naturally serializes git calls, so
+// `.git/config.lock` contention is a non-issue within one process. If the
+// parallel orchestrator (8B.2) ever switches to async git spawning, an
+// async mutex can be layered here without changing the API.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { _internal } = require('./session-runner.cjs');
+
+const WORKTREE_DOMAIN = path.join('.ultra', 'worktrees');
+
+function worktreePath(repoRoot, sid) {
+  return path.join(repoRoot, WORKTREE_DOMAIN, sid);
+}
+
+function allocate({ repoRoot, sid, baseRef = 'HEAD' }) {
+  if (!repoRoot) throw new Error('allocate: repoRoot required');
+  if (!sid) throw new Error('allocate: sid required');
+  const wt = worktreePath(repoRoot, sid);
+  _internal.gitWorktreeAdd(repoRoot, wt, baseRef); // throws WORKTREE_FAILED
+  return { worktree_path: wt };
+}
+
+function release({ repoRoot, worktree_path }) {
+  if (!repoRoot) throw new Error('release: repoRoot required');
+  if (!worktree_path) throw new Error('release: worktree_path required');
+  _internal.gitWorktreeRemove(repoRoot, worktree_path);
+}
+
+function parsePorcelain(text) {
+  const entries = [];
+  let current = {};
+  for (const raw of text.split('\n')) {
+    const line = raw.trimEnd();
+    if (line.startsWith('worktree ')) {
+      if (current.worktree) entries.push(current);
+      current = { worktree: line.slice('worktree '.length) };
+    } else if (line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length);
+    } else if (line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length);
+    } else if (line === 'detached') {
+      current.detached = true;
+    } else if (line === '' && current.worktree) {
+      entries.push(current);
+      current = {};
+    }
+  }
+  if (current.worktree) entries.push(current);
+  return entries;
+}
+
+function listActive(repoRoot) {
+  let out;
+  try {
+    out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8',
+    });
+  } catch (err) {
+    // Non-git or git failure — surface nothing but log via stderr so callers
+    // can trace. Return empty list so releaseAll is idempotent.
+    process.stderr.write(`worktree-manager: listActive git call failed: ${err.message}\n`);
+    return [];
+  }
+  const rawDomainRoot = path.resolve(repoRoot, WORKTREE_DOMAIN);
+  // On macOS tmpdir is a symlink (/var → /private/var); git returns realpath.
+  // Canonicalize both sides so prefix matching is robust.
+  const domainRoot = (fs.existsSync(rawDomainRoot)
+    ? fs.realpathSync(rawDomainRoot)
+    : rawDomainRoot) + path.sep;
+  return parsePorcelain(out)
+    .filter((e) => {
+      if (!e.worktree) return false;
+      const canon = fs.existsSync(e.worktree) ? fs.realpathSync(e.worktree) : path.resolve(e.worktree);
+      return (canon + path.sep).startsWith(domainRoot);
+    })
+    .map((e) => ({
+      sid: path.basename(e.worktree),
+      worktree_path: e.worktree,
+      head: e.head || null,
+      branch: e.branch || null,
+      detached: !!e.detached,
+    }));
+}
+
+function releaseAll(repoRoot) {
+  const active = listActive(repoRoot);
+  let cleaned = 0;
+  for (const entry of active) {
+    try {
+      release({ repoRoot, worktree_path: entry.worktree_path });
+      cleaned += 1;
+    } catch (err) {
+      // Best-effort: one bad worktree shouldn't stop the sweep.
+      process.stderr.write(`worktree-manager: release(${entry.sid}) failed: ${err.message}\n`);
+    }
+  }
+  // Sweep filesystem orphans that git no longer tracks.
+  const domainRoot = path.join(repoRoot, WORKTREE_DOMAIN);
+  if (fs.existsSync(domainRoot)) {
+    for (const name of fs.readdirSync(domainRoot)) {
+      const full = path.join(domainRoot, name);
+      try { fs.rmSync(full, { recursive: true, force: true }); }
+      catch (err) {
+        process.stderr.write(`worktree-manager: orphan sweep failed for ${full}: ${err.message}\n`);
+      }
+    }
+  }
+  return { cleaned };
+}
+
+module.exports = {
+  allocate,
+  release,
+  listActive,
+  releaseAll,
+  worktreePath,
+  WORKTREE_DOMAIN,
+};

package/output-styles/coding-vibes.md

@@ -0,0 +1,67 @@
+---
+name: Coding Vibes
+description: Energetic, casual coding buddy with modern dev vibes - adapts to user's language while keeping the energy
+---
+
+# Coding Vibes Style 🚀
+
+You're a high-energy coding buddy who talks like a modern developer friend. Your vibe is smart, fast-moving, and always hyped to help crush problems!
+
+## Core Rule: Language Adaptation
+**CRITICAL: Always match the user's language and cultural context while maintaining the energetic dev vibe.**
+
+## Communication Style
+
+**Tone & Energy:**
+- Be casual, direct, and playful ✅
+- Use modern slang appropriate to user's language/culture
+- Include emojis for emotional context (🔥, 💀, 👍, 🙏, 🚀)
+- Stay energetic and enthusiastic about problem-solving
+
+**Writing Pattern:**
+- Keep sentences short and punchy
+- Use frequent line breaks for chat-like flow
+- Avoid corporate speak or robotic language
+- Sound like you're messaging a local teammate
+
+**Developer Mindset:**
+- Jump straight into solutions
+- Share quick wins and insights
+- Call out smooth solutions
+- Be real when things get tricky
+
+## Language-Specific Examples
+
+**English:**
+- Starting: "Let's gooo!" "I got you!" "This one's clean!"
+- Success: "That's fire!" "Clean!" "Absolutely goated!"
+- Thinking: "Lemme think..." "This is spicy..."
+
+**中文:**
+- Starting: "来咯!" "搞起!" "这个简单!"
+- Success: "666!" "yyds!" "搞定了!"
+- Thinking: "让我想想..." "这里tricky..."
+
+**日本語:**
+- Starting: "やるぞ!" "いいね!" "簡単だ!"
+- Success: "すげー!" "完璧!" "やったー!"
+- Thinking: "ちょっと待って..." "難しいな..."
+
+**Español:**
+- Starting: "¡Vamos!" "¡Perfecto!" "¡Fácil!"
+- Success: "¡Genial!" "¡Increíble!" "¡Listo!"
+- Thinking: "A ver..." "Está complicado..."
+
+## Response Structure
+
+**Quick Start:**
+- Lead with energy in user's language
+- Get to the point fast
+- Match cultural enthusiasm patterns
+
+**Problem Solving:**
+- Use natural flow words in target language
+- Celebrate wins appropriately for culture
+- Be honest about complexity using local expressions
+
+Remember: You're the local coding friend who makes development fun and approachable in any language! 🔥

package/output-styles/structural-thinking.md

@@ -0,0 +1,61 @@
+---
+name: Structural Thinking
+description: Structural thinking with architectural clarity - naturally considers foundations, layers, and clean interfaces
+---
+
+# Structural Thinking Style 🏗️
+
+Your communication naturally follows structured, layered thinking patterns. You instinctively break problems into foundational components, interfaces, and hierarchical organization.
+
+## Core Rule: Language Adaptation
+**CRITICAL: Always match the user's language and cultural context while maintaining the structured thinking style.**
+
+## Communication Style
+
+**Natural Thinking Pattern:**
+- Break problems into foundational layers and dependencies
+- Instinctively consider modularity and composition
+- Think in hierarchies, interfaces, and clean boundaries
+- Build solutions that can be extended and composed
+
+**Speaking Style:**
+- Structured and methodical in expression
+- Use architectural metaphors naturally
+- Speak with quiet confidence and clarity
+- Emphasize principles and reasoning behind ideas
+
+**Tone Characteristics:**
+- Thoughtful and deliberate, never rushed
+- Educational but not condescending
+- Always explain the "why" behind thoughts
+- Acknowledge complexity and trade-offs gracefully
+
+## Vocabulary & Expression Habits
+
+**Natural Word Choices:**
+- Foundations, layers, components, interfaces
+- Modularity, composition, coupling, cohesion
+- Dependencies, hierarchies, abstractions
+- Blueprints, specifications, boundaries
+
+**Preferred Metaphors:**
+- Building foundations before higher floors
+- Creating blueprints and specifications
+- Designing load-bearing structures
+- Composing modular, interchangeable parts
+
+**Speaking Rhythm:**
+- Measured and thoughtful pace
+- Consider structural implications before responding
+- Build ideas methodically from foundations up
+- Connect components to overall architecture
+
+## Communication Traits
+
+**Structural Focus**: Always break down complexity into organized layers
+**Interface Design**: Naturally think about clean boundaries and contracts
+**Foundation-First**: Start with solid base before building complexity
+**Composition Mindset**: See how parts combine into larger wholes
+**Blueprint Thinking**: Consider the overall design before implementation
+
+Remember: Think in layers and communicate with structural clarity - breaking complex problems into foundational components with clean interfaces, all while adapting to the user's language and culture! 🌳

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "ultra-builder-pro-cli",
+  "version": "0.5.0",
+  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Gemini CLI.",
+  "bin": {
+    "ultra-builder-pro-cli": "bin/install.js",
+    "ubp": "bin/install.js",
+    "ubp-handbook": "bin/handbook.js",
+    "ubp-orchestrator": "bin/orchestrator.js",
+    "ultra-tools": "ultra-tools/cli.cjs"
+  },
+  "files": [
+    "bin",
+    "adapters",
+    "ultra-tools",
+    "mcp-server",
+    "orchestrator",
+    "commands",
+    "agents",
+    "skills/learn",
+    "skills/ultra-init",
+    "skills/ultra-research",
+    "skills/ultra-plan",
+    "skills/ultra-dev",
+    "skills/ultra-test",
+    "skills/ultra-review",
+    "skills/ultra-deliver",
+    "skills/ultra-status",
+    "skills/ultra-think",
+    "skills/code-review-expert",
+    "skills/security-rules",
+    "skills/integration-rules",
+    "skills/testing-rules",
+    "skills/cc-collab",
+    "skills/codex-collab",
+    "skills/gemini-collab",
+    "skills/ultra-verify",
+    "hooks/*.py",
+    "hooks/adapters/*.py",
+    "hooks/README.md",
+    "output-styles",
+    "spec/mcp-tools.yaml",
+    "spec/cli-protocol.md",
+    "spec/schemas",
+    "LICENSE",
+    "CHANGELOG.md",
+    "settings.json",
+    ".ultra-template",
+    "docs/ROADMAP.md",
+    "docs/ARCHITECTURE.md",
+    "docs/AGENT-CONTEXT.md",
+    "docs/COMMIT-HASH-BACKFILL.md",
+    "docs/LEGACY-HERMES.md",
+    "docs/PLAN.zh-CN.md",
+    "docs/STATE-DB-ACCESS-POLICY.md",
+    "docs/USER-HANDBOOK-CONTRACT.md",
+    "docs/RUNTIME-COMPAT-MATRIX.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "opencode",
+    "codex",
+    "gemini",
+    "agent",
+    "cli",
+    "multi-runtime",
+    "ultra-builder-pro",
+    "mcp",
+    "meta-prompting",
+    "context-engineering"
+  ],
+  "author": "Ultra Builder Pro contributors",
+  "license": "MIT",
+  "homepage": "https://github.com/rocky2431/ultra-builder-pro-cli",
+  "bugs": {
+    "url": "https://github.com/rocky2431/ultra-builder-pro-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rocky2431/ultra-builder-pro-cli.git"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "npm run test:all",
+    "test:state": "node --test 'mcp-server/**/*.test.cjs'",
+    "test:orch": "node --test 'orchestrator/**/*.test.cjs'",
+    "test:spec": "node spec/scripts/test-all.cjs",
+    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/install.test.cjs tests/package-smoke.test.cjs",
+    "test:all": "npm run test:state && npm run test:orch && npm run test:spec && npm run test:rest",
+    "test:hooks": "pytest hooks/tests -q",
+    "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",
+    "prepublishOnly": "npm run verify:release",
+    "install:claude": "node bin/install.js --claude --local",
+    "install:all": "node bin/install.js --all --local"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.111.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@vercel/ncc": "0.38.4",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "better-sqlite3": "^11.5.0",
+    "chokidar": "^3.6.0",
+    "js-yaml": "^4.1.0",
+    "openai": "^6.34.0"
+  }
+}

package/settings.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Ultra Builder Pro runtime settings. Host hooks and plugin permissions live in each native plugin manifest.",
+  "cleanupPeriodDays": 30,
+  "orchestrator": {
+    "auto_dispatch": false,
+    "graph_watcher": false
+  }
+}

package/skills/cc-collab/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: cc-collab
+description: "Use Claude Code as an explicitly requested, read-only advisor for bounded architecture, diagnosis, or review questions. The current host remains primary and verifies all claims."
+argument-hint: "review|understand|opinion|compare|free [target]"
+user-invocable: true
+---
+
+# Claude Code Collaboration
+
+Use Claude Code only when the user explicitly requests a Claude/CC perspective. The current host
+owns scope, evidence, decisions, edits, and final verification. Claude Code is an untrusted,
+read-only advisor.
+
+## Preconditions
+
+1. Confirm `claude --version` and authentication.
+2. Bound the workspace, files or diff, question, and expected response shape.
+3. Write the primary host's independent analysis first when independence matters.
+4. Do not pass credentials, unrelated files, or an unbounded home directory.
+
+## Invocation
+
+Run Claude Code without mutation or session persistence:
+
+```bash
+claude --safe-mode -p "<bounded prompt>" \
+  --permission-mode plan \
+  --tools "Read,Grep,Glob,Bash" \
+  --output-format text \
+  --no-session-persistence
+```
+
+Store large output under `.ultra/collab/<session-id>/claude-output.md`. A missing CLI, failed auth,
+timeout, or empty response degrades to host-only analysis; it never blocks the task.
+
+## Synthesis
+
+- Verify consequential claims against the current checkout, runtime, tests, or primary docs.
+- Separate agreement, useful dissent, and unsupported assertions.
+- Explain scope or version mismatches before comparing conclusions.
+- Return one host-owned conclusion, not a transcript or a model vote.

package/skills/code-review-expert/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: code-review-expert
+description: "Structured code review checklists: SOLID, security, performance, boundary conditions, removal planning. Injected into code-reviewer agent."
+user-invocable: false
+---
+
+# Code Review Expert Checklists
+
+Provides structured review workflow and reference checklists for the code-reviewer agent.
+
+## Severity Levels
+
+| Level | Name | Description | Action |
+|-------|------|-------------|--------|
+| **P0** | Critical | Security vulnerability, data loss risk, correctness bug | Must block merge |
+| **P1** | High | Logic error, significant SOLID violation, performance regression | Should fix before merge |
+| **P2** | Medium | Code smell, maintainability concern, minor SOLID violation | Fix in this PR or create follow-up |
+| **P3** | Low | Style, naming, minor suggestion | Optional improvement |
+
+## Review Workflow
+
+### Step 1: Preflight Context
+
+- Run `git status -sb`, `git diff --stat`, and `git diff` to scope changes
+- Use `git diff --cached` to include staged changes
+- If needed, use Grep to find related modules, usages, and contracts
+
+**Edge cases:**
+- **No changes**: Inform user, ask if they want to review staged changes or a specific commit range
+- **Large diff (>500 lines)**: Summarize by file first, then review in batches by module/feature area
+- **Mixed concerns**: Group findings by logical feature, not just file order
+
+### Step 2: SOLID + Architecture Smells
+
+Load `references/solid-checklist.md` for detailed prompts.
+
+Look for SRP/OCP/LSP/ISP/DIP violations and common code smells. When proposing refactor, explain *why* it improves cohesion/coupling. Non-trivial refactors get incremental plans, not large rewrites.
+
+### Step 3: Removal Candidates
+
+Load `references/removal-plan.md` for template.
+
+Identify unused, redundant, or feature-flagged-off code. Distinguish **safe delete now** vs **defer with plan**. Provide follow-up steps with concrete checkpoints.
+
+### Step 4: Security and Reliability
+
+Load `references/security-checklist.md` for coverage.
+
+Check injection, auth gaps, secrets, race conditions, crypto, supply chain. Call out both **exploitability** and **impact**.
+
+### Step 5: Code Quality
+
+Load `references/code-quality-checklist.md` for coverage.
+
+Check error handling, performance/caching, boundary conditions. Flag issues that may cause silent failures or production incidents.
+
+### Step 5.5: Integration & Connectivity
+
+Load `references/integration-checklist.md` for detailed prompts.
+
+Check entry point tracing, contract validation, vertical slice assessment, integration test coverage, and data flow continuity. Flag orphan code, missing contracts, and horizontal-only changes.
+
+### Step 6: Output Format
+
+```markdown
+## Code Review Summary
+
+**Files reviewed**: X files, Y lines changed
+**Overall assessment**: [APPROVE / REQUEST_CHANGES / COMMENT]
+
+---
+
+## Findings
+
+### P0 - Critical
+(none or list)
+
+### P1 - High
+- **[file:line]** Brief title
+  - Description of issue
+  - Suggested fix
+
+### P2 - Medium
+...
+
+### P3 - Low
+...
+
+---
+
+## Removal/Iteration Plan
+(if applicable)
+
+## Additional Suggestions
+(optional improvements, not blocking)
+```
+
+### Step 7: Next Steps Confirmation
+
+After presenting findings, ask how to proceed:
+
+1. **Fix all** - Implement all suggested fixes
+2. **Fix P0/P1 only** - Address critical and high priority issues
+3. **Fix specific items** - User specifies which issues to fix
+4. **No changes** - Review complete, no implementation needed
+
+**Important**: Do NOT implement any changes until user explicitly confirms.
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and checklists, consult:
+- **`references/solid-checklist.md`** - SOLID violation detection and refactor heuristics
+- **`references/security-checklist.md`** - Security, reliability, and race condition checks
+- **`references/code-quality-checklist.md`** - Error handling, performance, boundary conditions
+- **`references/removal-plan.md`** - Deletion candidates and iteration planning template
+- **`references/integration-checklist.md`** - Entry point tracing, contract validation, data flow continuity

package/skills/code-review-expert/references/code-quality-checklist.md

@@ -0,0 +1,112 @@
+# Code Quality Checklist
+
+## Error Handling
+
+### Anti-patterns to Flag
+
+- **Swallowed exceptions**: Empty catch blocks or catch with only logging
+  ```javascript
+  try { ... } catch (e) { }  // Silent failure
+  try { ... } catch (e) { console.log(e) }  // Log and forget
+  ```
+- **Overly broad catch**: Catching `Exception`/`Error` base class instead of specific types
+- **Error information leakage**: Stack traces or internal details exposed to users
+- **Missing error handling**: No try-catch around fallible operations (I/O, network, parsing)
+- **Async error handling**: Unhandled promise rejections, missing `.catch()`, no error boundary
+
+### Questions to Ask
+- "What happens when this operation fails?"
+- "Will the caller know something went wrong?"
+- "Is there enough context to debug this error?"
+
+---
+
+## Performance & Caching
+
+### CPU-Intensive Operations
+- Expensive operations in hot paths: Regex compilation, JSON parsing, crypto in loops
+- Blocking main thread: Sync I/O, heavy computation without worker/async
+- Unnecessary recomputation: Same calculation done multiple times
+- Missing memoization: Pure functions called repeatedly with same inputs
+
+### Database & I/O
+- **N+1 queries**: Loop that makes a query per item instead of batch
+  ```javascript
+  // Bad: N+1
+  for (const id of ids) {
+    const user = await db.query('SELECT * FROM users WHERE id = ?', id)
+  }
+  // Good: Batch
+  const users = await db.query('SELECT * FROM users WHERE id IN (?)', ids)
+  ```
+- Missing indexes: Queries on unindexed columns
+- Over-fetching: SELECT * when only few columns needed
+- No pagination: Loading entire dataset into memory
+
+### Caching Issues
+- Missing cache for expensive operations: Repeated API calls, DB queries, computations
+- Cache without TTL: Stale data served indefinitely
+- Cache without invalidation strategy: Data updated but cache not cleared
+- Cache key collisions: Insufficient key uniqueness
+- Caching user-specific data globally: Security/privacy issue
+
+### Memory
+- Unbounded collections: Arrays/maps that grow without limit
+- Large object retention: Holding references preventing GC
+- String concatenation in loops: Use StringBuilder/join instead
+- Loading large files entirely: Use streaming instead
+
+### Questions to Ask
+- "What's the time complexity of this operation?"
+- "How does this behave with 10x/100x data?"
+- "Is this result cacheable? Should it be?"
+- "Can this be batched instead of one-by-one?"
+
+---
+
+## Boundary Conditions
+
+### Null/Undefined Handling
+- Missing null checks: Accessing properties on potentially null objects
+- Truthy/falsy confusion: `if (value)` when `0` or `""` are valid
+- Optional chaining overuse: `a?.b?.c?.d` hiding structural issues
+- Null vs undefined inconsistency: Mixed usage without clear convention
+
+### Empty Collections
+- Empty array not handled: Code assumes array has items
+- Empty object edge case: `for...in` or `Object.keys` on empty object
+- First/last element access: `arr[0]` or `arr[arr.length-1]` without length check
+
+### Numeric Boundaries
+- Division by zero: Missing check before division
+- Integer overflow: Large numbers exceeding safe integer range
+- Floating point comparison: Using `===` instead of epsilon comparison
+- Negative values: Index or count that shouldn't be negative
+- Off-by-one errors: Loop bounds, array slicing, pagination
+
+### String Boundaries
+- Empty string: Not handled as edge case
+- Whitespace-only string: Passes truthy check but is effectively empty
+- Very long strings: No length limits causing memory/display issues
+- Unicode edge cases: Emoji, RTL text, combining characters
+
+### Common Dangerous Patterns
+```javascript
+// No null check
+const name = user.profile.name
+
+// Array access without check
+const first = items[0]
+
+// Division without check
+const avg = total / count
+
+// Truthy check excludes valid values
+if (value) { ... }  // fails for 0, "", false
+```
+
+### Questions to Ask
+- "What if this is null/undefined?"
+- "What if this collection is empty?"
+- "What's the valid range for this number?"
+- "What happens at the boundaries (0, -1, MAX_INT)?"