uv-suite 0.1.0

package/bin/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const UV_SUITE_DIR = path.resolve(__dirname, '..');
+const args = process.argv.slice(2);
+const command = args[0];
+
+function usage() {
+  console.log(`
+  uv-suite - AI-assisted development framework
+
+  Usage:
+    npx uv-suite install [--persona sport|professional|auto|spike] [--global]
+    npx uv-suite info
+
+  Commands:
+    install   Install agents, skills, hooks, guardrails, and personas
+    info      Show what would be installed
+
+  Personas:
+    spike          Research & documentation (Opus, max effort)
+    sport          New projects, prototyping (Sonnet, high effort)
+    professional   Production code (default, all hooks + guardrails)
+    auto           Fully autonomous (max effort, everything approved)
+
+  Examples:
+    npx uv-suite install                        Install with Professional persona
+    npx uv-suite install --persona sport        Install with Sport persona
+    npx uv-suite install --global               Install to ~/.claude/
+  `);
+}
+
+function info() {
+  console.log(`
+  UV Suite v0.1.0
+
+  Contents:
+    10 agents      Claude Code (.md), Cursor (.mdc), Codex (.toml)
+    9  skills      Slash commands for Claude Code
+    4  hooks       auto-lint, slop-check, danger-zone, block-destructive
+    6  guardrails  Anti-slop rules (comment, overengineering, error, test, doc, architecture)
+    4  personas    Spike, Sport, Professional, Auto
+    1  launcher    uv.sh (session launcher with persona selection)
+
+  Source: ${UV_SUITE_DIR}
+  `);
+}
+
+function install() {
+  const installScript = path.join(UV_SUITE_DIR, 'install.sh');
+  if (!fs.existsSync(installScript)) {
+    console.error('Error: install.sh not found at', installScript);
+    process.exit(1);
+  }
+
+  // Pass through all args after "install"
+  const installArgs = args.slice(1).join(' ');
+  try {
+    execSync(`bash "${installScript}" ${installArgs}`, { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+}
+
+switch (command) {
+  case 'install':
+    install();
+    break;
+  case 'info':
+    info();
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    usage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    usage();
+    process.exit(1);
+}

package/guardrails/architecture-slop.md

@@ -0,0 +1,60 @@
+# Guardrail: Architecture Slop
+
+**Severity:** High (unjustified complexity has compounding cost)
+**Category:** Architecture quality
+
+## Pattern
+
+Architecture decisions that sound sophisticated but don't match actual requirements. Buzzword-driven design. Complexity assumed rather than earned.
+
+## Detection Rules
+
+- Does the proposed architecture match the actual scale? (10 users don't need microservices)
+- Is the complexity justified by a specific requirement, or just "best practice"?
+- Could a simpler approach work? If yes, why isn't it the recommendation?
+- Are buzzwords being used as reasoning? ("event-driven" is not a reason, it's a pattern)
+- Is the "future-proofing" based on concrete plans or speculation?
+
+## Examples
+
+### Slop
+
+```
+"We should use an event-driven microservices architecture with CQRS
+and event sourcing" (for a CRUD app with 3 endpoints and 100 users)
+
+"Let's implement a service mesh with circuit breakers and distributed
+tracing" (for a monolith on a single server)
+
+"We need a Kafka cluster for message passing" (for 10 events per minute)
+
+"Let's use GraphQL for maximum flexibility" (for 5 fixed queries)
+```
+
+### Not Slop
+
+```
+"A monolith with 3 REST endpoints is sufficient. We'll extract
+services if/when we need independent scaling or deployment."
+
+"PostgreSQL handles our query patterns well. We'll add read replicas
+if/when we exceed 10k queries per second."
+
+"A simple task queue (Redis + BullMQ) handles our async processing.
+We'll move to Kafka if/when we need multi-consumer event streaming."
+
+"REST with OpenAPI spec. GraphQL adds complexity we don't need for
+our fixed client requirements."
+```
+
+## The Challenge Test
+
+For every architectural component, ask: **"What breaks if we don't have this?"**
+
+- If the answer is "nothing for the next 6 months" → remove it
+- If the answer is "we'd need to add it in 2 months when X happens" → document the upgrade path, don't build it now
+- If the answer is "users can't complete the core flow" → keep it
+
+## Fix
+
+Start with the simplest architecture that meets current requirements. Document the concrete triggers that would justify more complexity. "We'll add caching when p99 latency exceeds 500ms" is better than "we're adding Redis for performance."

package/guardrails/comment-slop.md

@@ -0,0 +1,53 @@
+# Guardrail: Comment Slop
+
+**Severity:** High (actively obscures code)
+**Category:** Code quality
+
+## Pattern
+
+Comments that restate what the code already says, adding no information.
+
+## Detection Rule
+
+If deleting the comment and reading the code tells you the same thing, the comment is slop. Comments should explain **why**, not **what**.
+
+## Examples
+
+### Slop
+
+```typescript
+// Initialize the database connection
+const db = initDatabase();
+
+// Set the user's name
+user.name = newName;
+
+// Loop through the items
+for (const item of items) {
+
+// Return the result
+return result;
+
+// Check if the user is valid
+if (isValid(user)) {
+```
+
+### Not Slop
+
+```typescript
+// Retry with exponential backoff because the API rate-limits
+// at 100 req/min and our batch size exceeds that
+const db = initDatabase({ retries: 3, backoff: 'exponential' });
+
+// Normalize Unicode before comparison — we've seen cases where
+// visually identical names fail equality checks (NFD vs NFC)
+user.name = newName.normalize('NFC');
+
+// Skip soft-deleted records intentionally — the reports team
+// needs historical data including deleted entries
+const records = db.query('SELECT * FROM orders');
+```
+
+## Fix
+
+Delete the comment. If the code genuinely needs explanation, rename the variable or function to be self-documenting. Only add a comment when there's context the code can't express (business decisions, workarounds, non-obvious constraints).

package/guardrails/doc-slop.md

@@ -0,0 +1,62 @@
+# Guardrail: Documentation Slop
+
+**Severity:** Medium (misleads readers, creates false sense of documentation)
+**Category:** Documentation quality
+
+## Pattern
+
+Documentation that uses words without saying anything specific. Vague adjectives, appeals to authority, feature lists that could describe any system.
+
+## Detection Rules
+
+**Vague adjectives (red flags):**
+- "Robust", "scalable", "maintainable", "comprehensive", "extensive"
+- "Elegant", "clean", "modern", "cutting-edge", "state-of-the-art"
+- "Enterprise-grade", "production-ready", "battle-tested"
+
+**Evasive verbs:**
+- "Leverages", "utilizes", "facilitates", "empowers", "enables"
+
+**Authority appeals:**
+- "Best practices", "industry-standard", "widely adopted"
+- Without naming the specific practice
+
+**Generic feature lists:**
+- "Comprehensive error handling" — what errors? What handling?
+- "Flexible configuration options" — what options? What's configurable?
+- "Extensive logging" — what's logged? Where? What format?
+
+## Examples
+
+### Slop
+
+```markdown
+## Overview
+This module provides a robust, scalable, and maintainable solution for
+handling user authentication. It leverages industry-standard best practices
+to ensure secure and efficient credential management.
+
+## Features
+- Comprehensive authentication flow
+- Secure credential storage
+- Flexible configuration options
+- Extensive error handling
+```
+
+### Not Slop
+
+```markdown
+## What This Does
+Handles login, signup, and session management using bcrypt for password
+hashing and JWT for session tokens. Sessions expire after 24 hours.
+
+## Endpoints
+- POST /auth/signup — Create account (email + password)
+- POST /auth/login — Get JWT token
+- POST /auth/logout — Invalidate session
+- GET /auth/me — Get current user (requires valid JWT)
+```
+
+## Fix
+
+Replace every vague adjective with a specific fact. "Robust error handling" becomes "Retries 3 times with exponential backoff on 5xx errors." If you can't make it specific, delete it — the absence of vague claims is better than their presence.

package/guardrails/error-handling-slop.md

@@ -0,0 +1,65 @@
+# Guardrail: Error Handling Slop
+
+**Severity:** Medium (adds noise, obscures real error paths)
+**Category:** Code quality
+
+## Pattern
+
+Try/catch blocks around code that can't throw, or that catch and re-throw without adding value. Defensive checks for impossible states.
+
+## Detection Rules
+
+- Try/catch where the try block can't throw
+- Catch that only logs and re-throws (the caller handles it)
+- Error handling for impossible states (e.g., validating a non-null TypeScript param isn't null)
+- Defensive checks deep inside internal functions (trust the caller at internal boundaries)
+- Catching generic `Error` when only specific errors are possible
+
+## Examples
+
+### Slop
+
+```typescript
+// JSON.stringify doesn't throw on a plain object
+try {
+  const json = JSON.stringify(user);
+  return json;
+} catch (error) {
+  console.error('Failed to stringify user:', error);
+  throw error;
+}
+
+// Catch, log, re-throw — adds nothing
+try {
+  const result = await fetchUser(id);
+  return result;
+} catch (error) {
+  console.error('Error fetching user:', error);
+  throw error;
+}
+
+// Null check on TypeScript non-null parameter
+function processUser(user: User): void {
+  if (!user) throw new Error('User is required'); // TypeScript already prevents this
+}
+```
+
+### Not Slop
+
+```typescript
+// No try/catch needed — let errors propagate naturally
+const json = JSON.stringify(user);
+return json;
+
+// Handle the error meaningfully at the system boundary
+try {
+  const result = await fetchUser(id);
+  return result;
+} catch (error) {
+  return { error: 'User not found', status: 404 };
+}
+```
+
+## Fix
+
+Remove the try/catch. Only add error handling at system boundaries (user input, network calls, file I/O) or when converting the error to a different type/format. Let internal errors propagate naturally.

package/guardrails/overengineering-slop.md

@@ -0,0 +1,56 @@
+# Guardrail: Over-Engineering Slop
+
+**Severity:** High (inflates maintenance burden)
+**Category:** Code quality
+
+## Pattern
+
+Abstractions, patterns, and indirection that serve no current purpose. AI models love creating "clean architecture" with factories, interfaces, and wrappers that only have one implementation.
+
+## Detection Rules
+
+- Interface with only one implementation
+- Factory that creates only one type
+- Abstract class with only one subclass
+- Wrapper that adds no behavior
+- Configuration for values that never change
+- Generic type parameter that's always the same concrete type
+- "Strategy pattern" with one strategy
+- Builder pattern for objects with 2-3 fields
+
+## Examples
+
+### Slop
+
+```typescript
+// Factory for a single implementation
+interface PaymentProcessor {
+  process(payment: Payment): Promise<Result>;
+}
+
+class PaymentProcessorFactory {
+  static create(type: string): PaymentProcessor {
+    switch (type) {
+      case 'stripe': return new StripePaymentProcessor();
+      default: throw new Error(`Unknown type: ${type}`);
+    }
+  }
+}
+
+class StripePaymentProcessor implements PaymentProcessor {
+  async process(payment: Payment): Promise<Result> {
+    return stripe.charges.create({ amount: payment.amount });
+  }
+}
+```
+
+### Not Slop
+
+```typescript
+// Direct call — add abstraction when you need a second processor
+await stripe.charges.create({ amount: payment.amount });
+```
+
+## Fix
+
+Delete the abstraction. Call the thing directly. Add abstraction when (not before) you need it. If you have two implementations, then the interface earns its place.

package/guardrails/test-slop.md

@@ -0,0 +1,72 @@
+# Guardrail: Test Slop
+
+**Severity:** High (creates false sense of coverage)
+**Category:** Testing quality
+
+## Pattern
+
+Tests that pass but don't actually verify behavior. They inflate coverage metrics without catching bugs.
+
+## Detection Rules
+
+- `expect(x).toBeTruthy()` or `expect(x).toBeDefined()` — almost always slop
+- Tests where the mock is the only thing being tested (you're testing your setup, not your code)
+- Snapshot tests on simple/trivial components
+- Tests with no assertions
+- Tests that test framework behavior ("does React render a component?")
+- Test name doesn't match what's actually being tested
+- Copy-pasted tests with only minor variations (use parameterized tests)
+
+## Examples
+
+### Slop
+
+```typescript
+// Tests existence, not behavior
+test('should create a user', () => {
+  const user = createUser({ name: 'Alice' });
+  expect(user).toBeTruthy();
+});
+
+// Tests the mock, not the code
+test('should fetch user', async () => {
+  mockFetch.mockResolvedValue({ name: 'Alice' });
+  const user = await fetchUser(1);
+  expect(user.name).toBe('Alice'); // You told the mock to return this
+});
+
+// Snapshot of a trivial component
+test('should render', () => {
+  const tree = renderer.create(<Button>Click</Button>);
+  expect(tree.toJSON()).toMatchSnapshot();
+});
+```
+
+### Not Slop
+
+```typescript
+// Tests specific behavior
+test('createUser hashes password before storing', async () => {
+  const user = await createUser({ name: 'Alice', password: 'secret123' });
+  expect(user.passwordHash).not.toBe('secret123');
+  expect(await bcrypt.compare('secret123', user.passwordHash)).toBe(true);
+});
+
+// Tests real behavior with real dependency
+test('fetchUser returns null for non-existent user', async () => {
+  const user = await fetchUser(999);
+  expect(user).toBeNull();
+});
+
+// Tests meaningful interaction
+test('Button calls onClick when clicked', () => {
+  const onClick = jest.fn();
+  render(<Button onClick={onClick}>Click</Button>);
+  fireEvent.click(screen.getByText('Click'));
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+```
+
+## Fix
+
+Delete tests that can't fail meaningfully. Rewrite to test actual behavior: specific values, specific side effects, specific error conditions. Ask: "Would this test catch a real bug?"

package/hooks/auto-lint.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# UV Suite Hook: Auto-lint after file writes
+# Event: PostToolUse (Write|Edit)
+# Reads the tool input from stdin, extracts the file path, runs the appropriate linter.
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+EXT="${FILE_PATH##*.}"
+
+case "$EXT" in
+  ts|tsx|js|jsx|mjs|cjs)
+    # Try prettier first, fall back to eslint
+    if command -v npx &>/dev/null; then
+      npx prettier --write "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  py)
+    if command -v ruff &>/dev/null; then
+      ruff format "$FILE_PATH" 2>/dev/null || true
+    elif command -v black &>/dev/null; then
+      black --quiet "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  go)
+    if command -v gofmt &>/dev/null; then
+      gofmt -w "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+  rs)
+    if command -v rustfmt &>/dev/null; then
+      rustfmt "$FILE_PATH" 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0

package/hooks/block-destructive.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# UV Suite Hook: Block dangerous bash commands
+# Event: PreToolUse (Bash)
+# Blocks rm -rf, DROP TABLE, force push to main, etc.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Block patterns
+if echo "$COMMAND" | grep -qEi "rm\s+-rf\s+/|rm\s+-rf\s+~|rm\s+-rf\s+\.\s*$"; then
+  echo "Blocked: recursive delete of root, home, or current directory" >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qEi "drop\s+(table|database)|truncate\s+table"; then
+  echo "Blocked: destructive database operation — get human approval first" >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qEi "git\s+push\s+.*--force.*\s+(main|master)"; then
+  echo "Blocked: force push to main/master" >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qEi "git\s+reset\s+--hard\s+origin"; then
+  echo "Blocked: hard reset to origin — this discards local work" >&2
+  exit 2
+fi
+
+exit 0

package/hooks/danger-zone-check.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# UV Suite Hook: Check if a file being modified is in a danger zone
+# Event: PreToolUse (Edit|Write)
+# If the file appears in DANGER-ZONES.md, warns Claude via systemMessage.
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+DANGER_FILE="DANGER-ZONES.md"
+if [ ! -f "$DANGER_FILE" ]; then
+  # Check project root
+  DANGER_FILE="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}/DANGER-ZONES.md"
+fi
+
+if [ ! -f "$DANGER_FILE" ]; then
+  exit 0
+fi
+
+# Get just the filename/relative path to search for
+BASENAME=$(basename "$FILE_PATH")
+RELPATH=$(realpath --relative-to="${CLAUDE_PROJECT_DIR:-.}" "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+
+# Search for the file in DANGER-ZONES.md
+MATCH=$(grep -i "$BASENAME\|$RELPATH" "$DANGER_FILE" 2>/dev/null)
+
+if [ -n "$MATCH" ]; then
+  # File is in a danger zone — warn but don't block
+  cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "WARNING: This file is in a DANGER ZONE. Check DANGER-ZONES.md before proceeding. Relevant entry:\n\n${MATCH}\n\nConsider flagging this modification to the human before continuing."
+}
+EOF
+else
+  echo '{"continue": true}'
+fi
+
+exit 0

package/hooks/session-review-reminder.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# UV Suite Hook: Remind to review before ending session
+# Event: Stop
+# If there are uncommitted changes, reminds the user to run /review and /slop-check.
+
+# Check for uncommitted changes
+STAGED=$(git diff --cached --stat 2>/dev/null)
+UNSTAGED=$(git diff --stat 2>/dev/null)
+UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null | head -5)
+
+if [ -z "$STAGED" ] && [ -z "$UNSTAGED" ] && [ -z "$UNTRACKED" ]; then
+  # No changes — nothing to remind about
+  exit 0
+fi
+
+# Build a summary of what's pending
+SUMMARY=""
+if [ -n "$STAGED" ]; then
+  SUMMARY="Staged changes:\n$STAGED\n"
+fi
+if [ -n "$UNSTAGED" ]; then
+  SUMMARY="${SUMMARY}Unstaged changes:\n$UNSTAGED\n"
+fi
+if [ -n "$UNTRACKED" ]; then
+  SUMMARY="${SUMMARY}Untracked files:\n$UNTRACKED\n"
+fi
+
+cat <<EOF
+{
+  "continue": true,
+  "systemMessage": "SESSION END REMINDER: There are uncommitted changes in the working tree.\n\n${SUMMARY}\nConsider running /review and /slop-check before committing."
+}
+EOF
+
+exit 0