ultra-builder-pro-cli 0.5.0

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

@@ -0,0 +1,46 @@
+# Integration Checklist
+
+## Entry Point Tracing
+
+For every new module/service/class:
+- **Ask**: "What entry point calls this code?"
+- **If none**: Flag as orphan code (P1)
+- **Trace**: handler → use case → domain → persistence (all layers reachable?)
+
+## Contract Validation
+
+For every boundary crossing:
+- **Ask**: "Is there a shared interface/type that both sides use?"
+- **If no shared type**: Flag missing contract (P2)
+- **Ask**: "Is there a test validating the contract?"
+- **If no contract test**: Flag missing contract test (P1)
+
+## Vertical Slice Assessment
+
+For the change as a whole:
+- **Ask**: "Does this change deliver a working end-to-end path for at least one user scenario?"
+- **If horizontal-only**: Flag as horizontal layer (P2)
+- **Ask**: "Can a user exercise this change right now, or does it need unfinished work?"
+- **If blocked by unfinished work**: Informational note (P3)
+
+## Integration Test Coverage
+
+| Boundary Type | Required Test | Common Mistake |
+|---------------|---------------|----------------|
+| HTTP endpoint | Real HTTP request/response | Testing handler function directly without HTTP layer |
+| Database query | Testcontainers with real DB | InMemoryRepository or jest.mock |
+| Queue/event | Real publish + consume | Mocking the event bus |
+| External API | Test Double with rationale | No test at all |
+
+## Data Flow Continuity
+
+- **Ask**: "Does data flow from source to destination without gaps?"
+- Check: Input validation → transformation → persistence → response
+- **Flag**: Any link in the chain that exists in code but has no test proving data flows through it
+
+## Key Questions
+
+- "What happens if I deploy this change alone? Does anything work?"
+- "Which entry point exercises this code path?"
+- "Where does the data this component produces get consumed?"
+- "Where does the data this component needs come from?"

package/skills/code-review-expert/references/removal-plan.md

@@ -0,0 +1,52 @@
+# Removal and Iteration Plan Template
+
+## Priority Levels
+
+- **P0**: Immediate removal needed (security risk, significant cost, blocking other work)
+- **P1**: Remove in current sprint
+- **P2**: Backlog / next iteration
+
+---
+
+## Safe to Remove Now
+
+### Item: [Name/Description]
+
+| Field | Details |
+|-------|---------|
+| **Location** | `path/to/file.ts:line` |
+| **Rationale** | Why this should be removed |
+| **Evidence** | Unused (no references), dead feature flag, deprecated API |
+| **Impact** | None / Low - no active consumers |
+| **Deletion steps** | 1. Remove code 2. Remove tests 3. Remove config |
+| **Verification** | Run tests, check no runtime errors, monitor logs |
+
+---
+
+## Defer Removal (Plan Required)
+
+### Item: [Name/Description]
+
+| Field | Details |
+|-------|---------|
+| **Location** | `path/to/file.ts:line` |
+| **Why defer** | Active consumers, needs migration, stakeholder sign-off |
+| **Preconditions** | Feature flag off for 2 weeks, telemetry shows 0 usage |
+| **Breaking changes** | List any API/contract changes |
+| **Migration plan** | Steps for consumers to migrate |
+| **Timeline** | Target date or sprint |
+| **Owner** | Person/team responsible |
+| **Validation** | Metrics to confirm safe removal (error rates, usage counts) |
+| **Rollback plan** | How to restore if issues found |
+
+---
+
+## Checklist Before Removal
+
+- [ ] Searched codebase for all references (Grep)
+- [ ] Checked for dynamic/reflection-based usage
+- [ ] Verified no external consumers (APIs, SDKs, docs)
+- [ ] Feature flag telemetry reviewed (if applicable)
+- [ ] Tests updated/removed
+- [ ] Documentation updated
+- [ ] Team notified (if shared code)

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

@@ -0,0 +1,100 @@
+# Security and Reliability Checklist
+
+## Input/Output Safety
+
+- **XSS**: Unsafe HTML injection, raw HTML rendering without sanitization, unescaped templates, innerHTML assignments
+- **Injection**: SQL/NoSQL/command/GraphQL injection via string concatenation or template literals
+- **SSRF**: User-controlled URLs reaching internal services without allowlist validation
+- **Path traversal**: User input in file paths without sanitization (`../` attacks)
+- **Prototype pollution**: Unsafe object merging in JavaScript (`Object.assign`, spread with user input)
+
+## AuthN/AuthZ
+
+- Missing tenant or ownership checks for read/write operations
+- New endpoints without auth guards or RBAC enforcement
+- Trusting client-provided roles/flags/IDs
+- Broken access control (IDOR - Insecure Direct Object Reference)
+- Session fixation or weak session management
+
+## JWT & Token Security
+
+- Algorithm confusion attacks (accepting `none` or `HS256` when expecting `RS256`)
+- Weak or hardcoded secrets
+- Missing expiration (`exp`) or not validating it
+- Sensitive data in JWT payload (tokens are base64, not encrypted)
+- Not validating `iss` (issuer) or `aud` (audience)
+
+## Secrets and PII
+
+- API keys, tokens, or credentials in code/config/logs
+- Secrets in git history or environment variables exposed to client
+- Excessive logging of PII or sensitive payloads
+- Missing data masking in error messages
+
+## Supply Chain & Dependencies
+
+- Unpinned dependencies allowing malicious updates
+- Dependency confusion (private package name collision)
+- Importing from untrusted sources or CDNs without integrity checks
+- Outdated dependencies with known CVEs
+
+## CORS & Headers
+
+- Overly permissive CORS (`Access-Control-Allow-Origin: *` with credentials)
+- Missing security headers (CSP, X-Frame-Options, X-Content-Type-Options)
+- Exposed internal headers or stack traces
+
+## Runtime Risks
+
+- Unbounded loops, recursive calls, or large in-memory buffers
+- Missing timeouts, retries, or rate limiting on external calls
+- Blocking operations on request path (sync I/O in async context)
+- Resource exhaustion (file handles, connections, memory)
+- ReDoS (Regular Expression Denial of Service)
+
+## Cryptography
+
+- Weak algorithms (MD5, SHA1 for security purposes)
+- Hardcoded IVs or salts
+- Using encryption without authentication (ECB mode, no HMAC)
+- Insufficient key length
+
+## Race Conditions
+
+### Shared State Access
+- Multiple threads/goroutines/async tasks accessing shared variables without synchronization
+- Global state or singletons modified concurrently
+- Lazy initialization without proper locking (double-checked locking issues)
+- Non-thread-safe collections used in concurrent context
+
+### Check-Then-Act (TOCTOU)
+- `if (exists) then use` patterns without atomic operations
+- `if (authorized) then perform` where authorization can change
+- File existence check followed by file operation
+- Balance check followed by deduction (financial operations)
+- Inventory check followed by order placement
+
+### Database Concurrency
+- Missing optimistic locking (`version` column, `updated_at` checks)
+- Missing pessimistic locking (`SELECT FOR UPDATE`)
+- Read-modify-write without transaction isolation
+- Counter increments without atomic operations (`UPDATE SET count = count + 1`)
+- Unique constraint violations in concurrent inserts
+
+### Distributed Systems
+- Missing distributed locks for shared resources
+- Leader election race conditions
+- Cache invalidation races (stale reads after writes)
+- Event ordering dependencies without proper sequencing
+
+### Questions to Ask
+- "What happens if two requests hit this code simultaneously?"
+- "Is this operation atomic or can it be interrupted?"
+- "What shared state does this code access?"
+
+## Data Integrity
+
+- Missing transactions, partial writes, or inconsistent state updates
+- Weak validation before persistence (type coercion issues)
+- Missing idempotency for retryable operations
+- Lost updates due to concurrent modifications

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

@@ -0,0 +1,65 @@
+# SOLID Smell Prompts
+
+## SRP (Single Responsibility)
+
+- File owns unrelated concerns (e.g., HTTP + DB + domain rules in one file)
+- Large class/module with low cohesion or multiple reasons to change
+- Functions that orchestrate many unrelated steps
+- God objects that know too much about the system
+- **Ask**: "What is the single reason this module would change?"
+
+## OCP (Open/Closed)
+
+- Adding a new behavior requires editing many switch/if blocks
+- Feature growth requires modifying core logic rather than extending
+- No plugin/strategy/hook points for variation
+- **Ask**: "Can I add a new variant without touching existing code?"
+
+## LSP (Liskov Substitution)
+
+- Subclass checks for concrete type or throws for base method
+- Overridden methods weaken preconditions or strengthen postconditions
+- Subclass ignores or no-ops parent behavior
+- **Ask**: "Can I substitute any subclass without the caller knowing?"
+
+## ISP (Interface Segregation)
+
+- Interfaces with many methods, most unused by implementers
+- Callers depend on broad interfaces for narrow needs
+- Empty/stub implementations of interface methods
+- **Ask**: "Do all implementers use all methods?"
+
+## DIP (Dependency Inversion)
+
+- High-level logic depends on concrete IO, storage, or network types
+- Hard-coded implementations instead of abstractions or injection
+- Import chains that couple business logic to infrastructure
+- **Ask**: "Can I swap the implementation without changing business logic?"
+
+---
+
+## Common Code Smells
+
+| Smell | Signs |
+|-------|-------|
+| **Long method** | Function > 30 lines, multiple levels of nesting |
+| **Feature envy** | Method uses more data from another class than its own |
+| **Data clumps** | Same group of parameters passed together repeatedly |
+| **Primitive obsession** | Using strings/numbers instead of domain types |
+| **Shotgun surgery** | One change requires edits across many files |
+| **Divergent change** | One file changes for many unrelated reasons |
+| **Dead code** | Unreachable or never-called code |
+| **Speculative generality** | Abstractions for hypothetical future needs |
+| **Magic numbers/strings** | Hardcoded values without named constants |
+
+---
+
+## Refactor Heuristics
+
+1. **Split by responsibility, not by size** - A small file can still violate SRP
+2. **Introduce abstraction only when needed** - Wait for the second use case
+3. **Keep refactors incremental** - Isolate behavior before moving
+4. **Preserve behavior first** - Add tests before restructuring
+5. **Name things by intent** - If naming is hard, the abstraction might be wrong
+6. **Prefer composition over inheritance** - Inheritance creates tight coupling
+7. **Make illegal states unrepresentable** - Use types to enforce invariants

package/skills/codex-collab/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: codex-collab
+description: Ask Codex CLI for an explicitly requested, read-only second opinion on a bounded review, diagnosis, architecture, or comparison question.
+---
+
+# Codex Collaboration
+
+Claude Code remains primary and owns scope, evidence, edits, verification, and the final answer.
+Codex is an untrusted read-only advisor. Use this skill only when the user explicitly requests a
+Codex perspective; do not invoke it as a routine substitute for native review or subagents.
+
+## Preconditions
+
+1. Confirm `codex --version` and authentication.
+2. Fix the workspace, files or diff range, question, evidence standard, and expected response shape.
+3. Write the primary analysis first when independence matters.
+4. Never send secrets, unrelated files, or an unbounded home directory.
+
+## Modes
+
+- `review`: findings against an exact diff or file set.
+- `understand`: a bounded architecture or flow question.
+- `opinion`: one decision with named constraints and alternatives.
+- `compare`: independent answers to the same question.
+- `free`: another tightly scoped read-only prompt.
+
+## Safe invocation
+
+Create a session directory under `.ultra/collab/`, then run Codex without workspace-write or
+danger-full-access:
+
+```bash
+SESSION_PATH=".ultra/collab/$(date +%Y%m%d-%H%M%S)-codex-<mode>"
+mkdir -p "${SESSION_PATH}"
+codex exec -s read-only \
+  -o "${SESSION_PATH}/codex-output.md" \
+  "<bounded prompt>" \
+  2> "${SESSION_PATH}/codex-error.log"
+```
+
+Do not enable write-capable automation or permission bypass. This skill has no dependency on
+another Codex plugin or slash command.
+
+## Synthesis
+
+1. Read the output only after the process exits and the file is non-empty.
+2. Verify consequential claims against the current checkout, tests, runtime, or primary docs.
+3. Separate agreement, useful dissent, and unsupported assertions.
+4. Return one Claude Code-owned conclusion; do not paste an unreviewed advisor transcript.
+
+If Codex is missing, unauthenticated, times out, or returns empty output, report the degraded path
+and continue with primary evidence. Never block the user's task solely on advisor failure.

package/skills/codex-collab/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "codex-collab",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "/codex-collab review",
+      "expected_output": "Claude delegates to /codex:review (official plugin), then adds its own perspective and presents a dual-AI synthesis report",
+      "assertions": [
+        "Delegates to /codex:review instead of invoking codex CLI directly",
+        "Does NOT run 'codex review --uncommitted' directly",
+        "After receiving Codex output, Claude adds its own review perspective",
+        "Presents a synthesis with Consensus and Divergent Views sections"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "/codex-collab opinion 'Should we use a monorepo or polyrepo?'",
+      "expected_output": "Claude sends the question to Codex via exec mode with sandbox, reads output, and presents both opinions",
+      "assertions": [
+        "Uses 'codex exec' (not codex review) for opinion mode",
+        "Uses --sandbox read-only for analysis-only task",
+        "Uses -o (--output-last-message) to capture clean output",
+        "Does NOT reveal Claude's position in the prompt",
+        "Creates session directory under .ultra/collab/",
+        "Presents both opinions with trade-off analysis"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "/codex-collab review --base main with a focus on security",
+      "expected_output": "Claude delegates to /codex:adversarial-review for security-focused review, then synthesizes",
+      "assertions": [
+        "Delegates to /codex:review or /codex:adversarial-review (official plugin)",
+        "Does NOT invoke codex CLI directly for review tasks",
+        "After receiving output, presents dual-AI synthesis",
+        "Reads output with Read tool, not Bash stdout"
+      ]
+    }
+  ]
+}

package/skills/gemini-collab/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gemini-collab
+description: Ask Gemini CLI for an explicitly requested, read-only second opinion on a bounded review, diagnosis, architecture, or comparison question.
+---
+
+# Gemini Collaboration
+
+Claude Code remains primary and owns scope, evidence, edits, verification, and the final answer.
+Gemini is an untrusted read-only advisor. Use this skill only when the user explicitly requests a
+Gemini perspective.
+
+## Preconditions
+
+1. Confirm `gemini --version` and authentication.
+2. Fix the workspace, files or diff range, question, evidence standard, and expected response shape.
+3. Write the primary analysis first when independence matters.
+4. Never send secrets, unrelated files, or an unbounded home directory.
+
+## Modes
+
+- `review`: findings against an exact diff or file set.
+- `understand`: a bounded architecture or flow question.
+- `opinion`: one decision with named constraints and alternatives.
+- `compare`: independent answers to the same question.
+- `free`: another tightly scoped read-only prompt.
+
+## Safe invocation
+
+Create a session directory under `.ultra/collab/`, then use Gemini's plan approval mode:
+
+```bash
+SESSION_PATH=".ultra/collab/$(date +%Y%m%d-%H%M%S)-gemini-<mode>"
+mkdir -p "${SESSION_PATH}"
+gemini --approval-mode plan \
+  --output-format text \
+  -p "<bounded prompt>" \
+  > "${SESSION_PATH}/gemini-output.md" \
+  2> "${SESSION_PATH}/gemini-error.log"
+```
+
+Do not use auto-edit, YOLO, or permission bypass.
+
+## Synthesis
+
+1. Read the output only after the process exits and the file is non-empty.
+2. Verify consequential claims against the current checkout, tests, runtime, or primary docs.
+3. Separate agreement, useful dissent, and unsupported assertions.
+4. Return one Claude Code-owned conclusion; do not paste an unreviewed advisor transcript.
+
+If Gemini is missing, unauthenticated, times out, or returns empty output, report the degraded path
+and continue with primary evidence. Never block the user's task solely on advisor failure.

package/skills/gemini-collab/evals/evals.json

@@ -0,0 +1,42 @@
+{
+  "skill_name": "gemini-collab",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "/gemini-collab review",
+      "expected_output": "Claude creates a session directory, invokes gemini CLI to review current changes, reads the output file, and presents a synthesis report",
+      "assertions": [
+        "Creates a session directory under .ultra/collab/ with gemini-review in the name",
+        "Uses 'gemini -p' with --yolo flag to invoke Gemini CLI",
+        "Does NOT use '-o text' flag (Gemini outputs to stdout by default)",
+        "Redirects output to a file (> output.md)",
+        "Uses Read tool to read the output file",
+        "Presents a synthesis with Consensus and Divergent Views sections"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "/gemini-collab compare 'Should we use Redis or Memcached for our caching layer?'",
+      "expected_output": "Claude answers independently first, then sends the same question to Gemini, reads output, and presents a comparative synthesis",
+      "assertions": [
+        "Claude writes its own answer BEFORE invoking Gemini",
+        "Sends the question to Gemini without revealing Claude's position",
+        "Creates session directory under .ultra/collab/",
+        "Reads Gemini output with Read tool",
+        "Presents both analyses side by side with synthesis"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "/gemini-collab understand",
+      "expected_output": "Claude invokes Gemini in sandbox mode to analyze the project, reads output, and synthesizes with its own understanding",
+      "assertions": [
+        "Uses --sandbox flag for read-only analysis",
+        "Uses gemini -p with a project analysis prompt",
+        "Installs from @google/gemini-cli (not @anthropic-ai/gemini-cli)",
+        "Redirects to file, reads with Read tool",
+        "Produces a unified project understanding report"
+      ]
+    }
+  ]
+}

package/skills/integration-rules/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: integration-rules
+description: Ultra Builder Pro system integration rules
+user-invocable: false
+---
+
+# Integration Rules
+
+These rules are mandatory for all code review and development work involving multi-component systems.
+
+## Vertical Slice Principle
+
+Every task MUST deliver a thin, working end-to-end path:
+
+| Good (Vertical Slice) | Bad (Horizontal Layer) |
+|------------------------|------------------------|
+| "User can send message" (UI + API + LLM + response display) | "Create all database tables" |
+| "Display product list" (API call + domain filter + UI render) | "Build all API endpoints" |
+| "Process payment" (UI form + gateway + order update) | "Create all UI components" |
+
+## Walking Skeleton
+
+The FIRST deliverable of any multi-component feature must be a walking skeleton:
+- One request flows through ALL layers
+- Returns real data (not hardcoded/mocked)
+- Proves the architecture connects end-to-end
+- Does NOT need to be feature-complete — just connected
+
+## Contract-First Development
+
+When two components will communicate:
+
+| Step | Action | Artifact |
+|------|--------|----------|
+| 1 | Define interface before implementation | TypeScript interface, OpenAPI schema, or protobuf |
+| 2 | Both sides code against the contract | Import shared types or generated clients |
+| 3 | Contract test validates both sides | Test that producer output matches consumer expectation |
+
+## Integration Test Requirements
+
+| Boundary | Required Test |
+|----------|---------------|
+| HTTP API endpoint | Request with real HTTP client, validate response shape + status |
+| Database operation | Testcontainers with real queries, validate data persisted |
+| Message queue | Real producer + consumer, validate message delivered |
+| External service | Test Double with `// Test Double rationale:` (only exception) |
+| In-process module boundary | Real function call, validate input/output contract |
+
+## Orphan Detection
+
+Code without a live entry point is dead-on-arrival.
+
+**Valid entry points** (at least one required per new module):
+- HTTP/WebSocket handler
+- CLI command handler
+- Event/message listener
+- Scheduled job/cron handler
+- Exported function called by a module that has an entry point
+
+**Detection**: Trace from new code upward — if no path reaches an entry point, the code is an orphan.
+
+## Detection Checklist
+
+When reviewing code, flag:
+1. New module/service without any caller (orphan code)
+2. Task structured as horizontal layer instead of vertical slice
+3. Two components communicating without shared interface/contract
+4. New boundary crossing without integration test
+5. Use case with DB/API dependency but only unit tests
+6. Component "works in isolation" but not wired to any entry point
+7. Interface defined but no contract test validating compatibility

package/skills/learn/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: learn
+description: "Extract one reusable pattern from the current session into a valid user skill, with explicit user approval before writing."
+---
+
+# learn — Phase 3.6
+
+Mine the current session for a reusable pattern and save it as a Speculation-
+grade skill under `~/.claude/skills/learned-<name>-unverified/SKILL.md`. User
+confirmation is mandatory before the write — never silently persist.
+
+## Trigger conditions
+
+Run `/learn` after solving a non-trivial problem where the approach is
+generalizable (not a one-off typo or outage-specific fix).
+
+## What to extract
+
+| Kind | Example |
+|------|---------|
+| **Error resolution** | Root cause + fix that applies to similar errors |
+| **Debugging technique** | Non-obvious steps, effective tool combos |
+| **Workaround** | Library quirk / API limitation / version-specific fix |
+| **Project-specific pattern** | Codebase convention / integration pattern discovered this session |
+
+## Workflow
+
+### Step 1 — Review session
+
+Scan recent messages / tool outputs for extractable patterns. Prefer
+patterns that saved meaningful time or would have, had they been known upfront.
+
+### Step 2 — Identify the highest-value candidate
+
+Multiple candidates? Pick one. Keep skills focused — **one pattern per file**.
+
+### Step 3 — Draft skill body
+
+Use the **learned-skill template** below. Mark confidence as `Speculation`
+and append `-unverified` to the skill directory name.
+
+### Step 4 — User confirmation
+
+Present a concise summary (pattern name, one-sentence description, trigger,
+proposed filename) to the user and ask to approve the save. Options:
+- A: "Save it" → Step 5
+- B: "Edit first" → accept user revisions, re-confirm
+- C: "Don't save" → abort
+
+### Step 5 — Write file
+
+Path: `~/.claude/skills/learned-<pattern-slug>-unverified/SKILL.md`.
+Never overwrite an existing learned skill directory — increment the slug
+(`learned-pattern-slug-2-unverified/`) if it already exists.
+
+## Learned-skill template
+
+```markdown
+---
+name: learned-<pattern-slug>-unverified
+description: Use when <specific trigger for this reusable pattern>.
+---
+
+# <Descriptive Pattern Name>
+
+**Extracted**: <YYYY-MM-DD>
+**Confidence**: Speculation (unverified)
+**Context**: <one-sentence applicability>
+
+## Problem
+<what problem does this pattern solve — be specific>
+
+## Solution
+<the pattern / technique / workaround>
+
+## Example
+<code example if applicable — else a transcribed command sequence>
+
+## Trigger Conditions
+<what situations should activate this skill>
+
+## Verification Status
+- [ ] Human review passed
+- [ ] Multiple successful uses
+```
+
+## Verification upgrade path
+
+1. **Speculation** (this skill writes this level) — freshly extracted, unverified
+2. **Inference** — after human review passes, rename the directory to remove
+   `-unverified` and update the frontmatter name
+3. **Fact** — after multiple successful uses confirm the pattern
+
+## What NOT to extract
+
+- Simple typo fixes
+- One-time issues (API outage, transient CI flake)
+- Patterns too project-specific to reuse (belongs in project docs, not a skill)
+- Anything already captured in CLAUDE.md or equivalent project instructions
+
+## Approval boundary
+
+Ask the user directly before writing. No Ultra MCP or legacy interaction wrapper is involved.
+
+## What this skill DOES NOT do
+
+- Does NOT modify state.db
+- Does NOT save without user approval
+- Does NOT extract more than one pattern per run
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | current session transcript / recent tool outputs |
+| **Output** | `~/.claude/skills/learned-<slug>-unverified/SKILL.md` |
+| **Next** | user may promote after review; `/learn` again later when another pattern appears |