Houseofmvps/ultraship

# Accessibility Audit + Auto-Fix (WCAG 2.2)

AI builders ship accessibility violations by default — missing alt text, unlabeled inputs, icon-only buttons, no `lang`, broken heading order. These are legally consequential (ADA, EU Accessibility Act) and most are deterministically detectable and fixable. This skill finds them AND fixes them.

## Process

### Phase 1: Scan

Run the static scanner on the project (point it at built/exported HTML, e.g. `dist/`, `build/`, `out/`, `.next/`, or `public/`):

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/a11y-scanner.mjs <project-directory>
```

# Living Architecture Map

Auto-generates and maintains architecture diagrams from your actual code. Always up-to-date.

## Process

### Phase 1: Scan

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/architecture-mapper.mjs <project-directory>
```

Parse the JSON output for architecture data and diagrams.

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

# Post-Deploy Canary Monitor

After every deploy, canary monitoring verifies your production site is healthy. It checks HTTP status, response time, error patterns, and compares against a baseline to detect regressions.

**Announce at start:** "I'm running post-deploy canary monitoring."

## Process

### Step 1: Run Canary Checks

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/canary-monitor.mjs <production-url> --checks 3 --interval 2
```

# Learn From the Best

Analyze any codebase's patterns and apply the best ones to your project.

## Process

### Phase 1: Analyze Source

Ask for the source project directory (must be cloned locally):
- "Which repo do you want to learn from? Provide the local path."

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/pattern-analyzer.mjs <source-directory> --compare=<your-project-directory>
```

# Code Review

Review code the way a principal engineer would — not just "does it work?" but "will this cause problems at 3am?"

## Review Dimensions

Every review should evaluate these dimensions, in order of importance:

> **Use an LSP if one is connected.** If LSP tools are available (check your tools for a language server — TypeScript, Pyright, gopls, rust-analyzer), use them instead of grep-guessing. `find references` on a changed function tells you the real blast radius; `go to definition` confirms a call signature actually matches; rename/diagnostics surface type errors the eye misses. A review that verifies call sites with an LSP catches breakage that a text-only review ships. If no LSP is connected, fall back to Grep/Glob and say so.

### 1. Correctness

The code must do what it claims to do.

# Competitive X-Ray

Know what you're up against. Understand where you win, where you lose, and where the gaps are. This isn't just a technical comparison — it's a strategic assessment.

## Process

### Phase 1: Gather URLs

Ask the user for:
1. **Your site URL** (production URL)
2. **Competitor URL** (the site to compare against)

If the user provided both URLs already, skip asking.

# AI Build Cost Tracker

Know exactly what each feature costs to build with AI. Budget smarter, spend less.

## Process

### Phase 1: Show Current State

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/cost-tracker.mjs <project-directory> show
```

Parse the JSON output for cost history and summary.

# Demo-Ready Mode

One command to make your app demo-ready. Clean up dev artifacts, check visual polish, generate a walkthrough script.

## Process

### Phase 1: Scan

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/demo-prep.mjs <project-directory>
```

Parse the JSON output for demo readiness score and issues.

# Deploy

Full pre-flight validation → deploy pipeline. Closes the audit-to-production loop.

## Process

### Step 1: Detect Deploy Target

Check project for deploy configuration:
- `vercel.json` or `.vercel/` → Vercel (git push)
- `railway.toml` or `railway.json` → Railway
- `fly.toml` → Fly.io
- `wrangler.toml` → Cloudflare Workers
- `.github/workflows/` with deploy steps → CI/CD pipeline

# Dispatching Parallel Agents

## Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

**Nesting and scale:** Subagents can spawn their own subagents up to 5 levels deep, so a dispatched agent owning a large domain can fan out helpers for its sub-steps rather than doing everything serially. When the work-list is large, repetitive, or unknown in size (every route, every package in a monorepo, every finding to verify), stop hand-dispatching and escalate to a **dynamic Workflow** — describe the task and include the word "workflow" so an orchestration script pipelines the items across background subagents with a verification stage built in. Rule of thumb: a few independent tasks → dispatch agents here; dozens of items or fan-out-then-verify → a Workflow.

## When to Use

# Evals — Regression Harness for AI Code & AI Features

The defining 2026 problem: AI-written code passes review but **fails at runtime** (New Relic: 82% of teams had an AI-code production failure), and AI *features* (chatbots, RAG, classifiers) drift silently as prompts and models change. The fix the industry converged on: **the regression suite becomes the primary reviewer.** This skill builds that suite.

Two complementary layers:
- **Characterization tests** — lock the *current* behavior of code before an agent refactors it, so a regression is caught immediately.
- **LLM-feature evals** — assert that each AI feature still does its job (stays on-topic, no PII leak, correct format, acceptable latency/cost) on every change.

## Process

### Phase 1: Locate what needs evals

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/eval-scanner.mjs <project-directory>

# Executing Plans

## Overview

Load plan, review critically, execute all tasks, report when complete.

**Announce at start:** "I'm using the executing-plans skill to implement this plan."

**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use ultraship:subagent-driven-development instead of this skill.

## The Process

### Step 1: Load and Review Plan
1. Read plan file

# Finishing a Development Branch

## Overview

Guide completion of development work by presenting clear options and handling chosen workflow.

**Core principle:** Verify tests → Present options → Execute choice → Clean up.

**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."

## The Process

### Step 1: Verify Tests

This skill combines three disciplines: **product design** (does it solve the right problem?), **UX design** (can users accomplish their goals without friction?), and **visual design** (is it distinctive and polished?). All three must be present. Beautiful but unusable is a failure. Usable but ugly is a failure. Both beautiful and usable but solving the wrong problem is the worst failure.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Product Design Thinking

Before touching aesthetics, think like a product designer:

**1. User Intent**
- What is the user trying to accomplish on this page/component?
- What is the ONE primary action? (every screen has one — if you can't identify it, the design is confused)
- What information does the user need to make a decision? Show that, hide everything else.

**2. Information Hierarchy**

# Post-Ship Growth Intelligence

Most indie builders ship and forget. The ones who win ship and measure. This skill makes growth visible, trackable, and actionable — like having a growth-stage CTO and a marketing analyst looking at your dashboards every week.

## Process

### Phase 1: Collect Metrics

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/growth-tracker.mjs <project-directory> --url=<production-url> --save
```

Parse the JSON output for current snapshot and historical trends.

# Guard — Safety Guardrails

Guard protects you from accidental destructive actions by intercepting dangerous commands before they execute. It uses Claude Code's PreToolUse hooks to catch risky patterns in real-time.

**Announce at start:** "I'm activating Guard — destructive commands will be blocked until you explicitly approve them."

## What Guard Blocks

### Destructive Bash Commands
- `rm -rf` / `rm -r` on important directories
- `DROP TABLE` / `DROP DATABASE` / `TRUNCATE`
- `git push --force` / `git push -f` (to main/master)
- `git reset --hard`
- `git checkout .` / `git restore .` (discard all changes)

# Index Fix — Get Every Page Indexed

Diagnose why pages aren't indexed in Google and Bing, fix the root causes, and resubmit for indexing. This skill uses real data from GSC URL Inspection API and Bing Webmaster Tools — no guessing.

**Goal: 100% index coverage for pages that SHOULD be indexed. Not every URL belongs in the index — staging pages, admin panels, thin pagination, and intentionally private content should stay excluded.**

## Phase 1: Credential Check

Verify data sources:
1. **GSC** (required): `ULTRASHIP_GSC_CREDENTIALS` or `ULTRASHIP_GSC_ACCESS_TOKEN`
2. **Bing** (recommended): `ULTRASHIP_BING_KEY`

If GSC is not configured, show setup guide and stop — GSC is required for URL inspection.

# Investigate — Root Cause Analysis

Investigation is the discipline of understanding a problem before fixing it. This skill enforces a strict protocol: **no fixes until the root cause is found.**

> **Enforced:** while this skill is active, `Edit`, `Write`, and `NotebookEdit` are removed via `disallowed-tools`. The no-fixes rule is a hard constraint here, not a request. Once you have found and stated the root cause, conclude the investigation — the fix happens as a separate step outside this skill.

**Announce at start:** "I'm using the investigate skill — no fixes until we find the root cause."

## The Iron Law

```
┌──────────────────────────────────────────────┐
│  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION   │
│                                              │

# Launch Day Autopilot

A launch is not a deploy. A deploy puts code on a server. A launch puts a product in front of people who need it, at the right time, with the right message, on the right channels. This skill treats launch as a coordinated campaign, not a checkbox.

## Process

### Phase 1: Analyze Project

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/launch-prep.mjs <project-directory> --url=<production-url>
```

Parse the JSON output for project info, launch copy, checklist, and press kit.

# Project Learnings Manager

Learnings are structured knowledge that compounds across sessions. They capture what worked, what didn't, decisions made, and patterns discovered — things that can't be derived from code alone.

**Announce at start:** "I'm using the learn skill to manage project learnings."

## Commands

### Save a learning

When the user discovers something worth remembering — a debugging insight, an architecture decision, a deployment gotcha, a tool preference:

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/learnings-manager.mjs save --title "Title here" --body "Detailed learning content" --tags "tag1,tag2"

# Instant Project Onboarding

One command generates everything a new developer needs to be productive in your codebase.

## Process

### Phase 1: Analyze

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/onboard-generator.mjs <project-directory>
```

Parse the JSON output.

You are an elite penetration tester. Your job is to find every exploitable vulnerability in the user's application across ALL attack surfaces. Every finding MUST have proof — no guesses, no maybes, no false positives.

## Process

Run all 5 phases. Skip phases only if the attack surface doesn't exist (e.g., no GitHub repo, no browser URL).

---

### Phase 1: Web & API Penetration Test

Run the pentest scanner tool against the user's deployed URL or local dev server:

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/pentest-scanner.mjs <target-url> --deep

# Performance Audit

Run Lighthouse against the project and fix performance issues.

## Process

### Step 1: Find the URL

- Check if dev server is running (try common ports: 3000, 5173, 4321, 8080)
- Check package.json scripts for dev/start commands
- Ask user for URL if not auto-detected
- If no server running, suggest starting one first

### Step 2: Run Lighthouse

# Code Review Reception

## Overview

Code review requires technical evaluation, not emotional performance.

**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.

## The Response Pattern

```
WHEN receiving code review feedback:

1. READ: Complete feedback without reacting

# Release

Full release pipeline: changelog → version bump → commit → tag → GitHub release → npm publish.

## Process

### Step 1: Determine Version Bump

Check recent commits since last tag to determine semver bump:
```bash
git describe --tags --abbrev=0 2>/dev/null || echo "none"
git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline
```

# Requesting Code Review

Dispatch ultraship:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.

**Core principle:** Review early, review often.

## When to Request Review

**Mandatory:**
- After each task in subagent-driven development
- After completing major feature
- Before merge to main

**Optional but valuable:**

# Production Incident Commander

When production is down, every minute costs trust. This skill runs an incident like a principal SRE — fast triage, clear decision-making, structured recovery, and prevention so it never happens again.

## Severity Classification

Before doing anything, classify the incident:

| Severity | Definition | Response Time | Example |
|---|---|---|---|
| **SEV-1** | Service completely down, all users affected | Immediately | Site returns 500, database unreachable |
| **SEV-2** | Major feature broken, many users affected | Within 15 min | Auth broken, payments failing, data loss |
| **SEV-3** | Minor feature broken, some users affected | Within 1 hour | One API endpoint slow, email not sending |
| **SEV-4** | Cosmetic or edge case | Next business day | UI glitch on one browser, non-critical error log |

# Sprint Retrospective

Retrospectives turn shipping data into actionable insights. This skill analyzes your git history, commit patterns, test health, and shipping velocity to surface what's working and what needs attention.

**Announce at start:** "I'm running a sprint retrospective on this project."

## Process

### Step 1: Gather Data

Run the retro analyzer:

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/retro-analyzer.mjs <project-directory> --days 7

# CLAUDE.md Improver

Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure Claude Code has optimal project context.

**This skill can write to CLAUDE.md files.** After presenting a quality report and getting user approval, it updates CLAUDE.md files with targeted improvements.

## Workflow

### Phase 1: Discovery

Find all CLAUDE.md files in the repository:

```bash
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

# Security Audit

Comprehensive security scan. Finds issues AND fixes them.

## Process

### Step 1: Dependency Audit

Detect package manager from lockfile and run audit:
- `pnpm-lock.yaml` → `pnpm audit`
- `package-lock.json` → `npm audit`
- `yarn.lock` → `yarn audit`

If critical/high vulnerabilities found, run the appropriate fix command (non-breaking only):

# SEO Audit + AI Visibility

Search optimization audit with AI visibility signals. Finds issues AND fixes them.

## Process

### Phase 1: Scan

Run the SEO scanner on the project:
```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <project-directory>
```

Parse the JSON output for findings and scores (seo, geo, aeo).

# SEO Strategy — Elite Analyst Mode

You are the world's best SEO strategist, AEO expert, and GEO specialist combined. You are ruthless about ranking. You don't give generic advice — you give data-backed, specific, executable strategies that WILL move the needle. You think like someone who charges $25K/month for SEO consulting.

**Your mission: Rank #1 for every high-intent keyword. Get cited in every AI search engine. Build a traffic machine that converts visitors into leads and revenue.**

## Iron Rules

1. **Every recommendation cites a specific number from the data.** "Your keyword X has 2,400 impressions but position 14.2 and 0.8% CTR — here's exactly how to fix it."
2. **Prioritize by revenue impact, not vanity metrics.** A transactional keyword with 100 impressions is worth more than an informational keyword with 10,000.
3. **Fix before create.** Don't suggest new content until every existing page is optimized.
4. **One page per keyword cluster.** Never split ranking power. Consolidate ruthlessly.
5. **Think in systems, not tasks.** Build topic clusters, internal link architectures, and content flywheels — not one-off pages.

# Ship-Gate — Deterministic Quality Gate

The 2026 consensus on AI-written code is "did it pass the gates," not "did a senior read every line." This skill promotes the `/ship` scorecard from advisory to a **blocking, deterministic gate**: same scoring as `/ship` (shared `tools/lib/ship-scoring.mjs`), compared against thresholds in `.ultraship/ship-gate.json`, exiting non-zero so it can fail a push or a CI job.

## When to use

The user wants a merge gate, a CI quality check, a pre-push guard, or to enforce a minimum ship-readiness score before code goes out.

## Process

### Phase 1: Initialize the config

```bash
node ${CLAUDE_PLUGIN_ROOT}/tools/ship-gate.mjs init <project-directory>

# Sprint Workflow Pipeline

A sprint is the full lifecycle of shipping a feature — from planning through deployment. This skill chains Ultraship skills into a structured pipeline where each phase produces artifacts that feed the next.

**Announce at start:** "I'm using the sprint workflow to guide this feature from plan to ship."

## The Pipeline

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  PLAN    │───▶│  BUILD   │───▶│  TEST    │───▶│  REVIEW  │───▶│  SHIP    │───▶│  VERIFY  │
│          │    │          │    │          │    │          │    │          │    │          │
│ /write-  │    │ /execute-│    │ /tdd     │    │ /review  │    │ /deploy  │    │ /canary  │
│  plan    │    │  plan    │    │          │    │          │    │ /ship    │    │ /retro   │

# Staying Current

Training data has a cutoff. Libraries ship breaking changes, prices change, model IDs get renamed, and APIs get deprecated after that cutoff. Answering version-sensitive questions from memory is the single most common way an otherwise-correct agent ships wrong code. This skill is the standing rule for not doing that.

The Ultraship **Currency Guard** hook (`UserPromptSubmit`) already fires on every prompt and injects a reminder when it detects version-sensitive language. This skill is what you do when that fires — or any time you're about to state a fact whose correct answer changes over time.

## The rule

**Before stating any of the following, verify it against a current source. Never answer from training data alone:**

- Library / framework / SDK API signatures, imports, hooks, options
- Package versions, compatibility, and what's deprecated
- CLI flags and config file schemas
- Model IDs, model names, context windows, and capabilities

# Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

## When to Use

```dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

# Test-Driven Development (TDD)

## Overview

Write the test first. Watch it fail. Write minimal code to pass.

**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

**Violating the letter of the rules is violating the spirit of the rules.**

## When to Use

**Always:**
- New features

# Using Git Worktrees

## Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

**Core principle:** Systematic directory selection + safety verification = reliable isolation.

**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Directory Selection Process

Follow this priority order:

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-STOP>

<IMPORTANT>
**Memory-first rule:** At the START of every session, read MEMORY.md, CLAUDE.md, and relevant memory files BEFORE performing any task. This ensures persistent context across sessions. Never skip this step — never claim something is missing or not done without first checking memory. Memory records can become stale, so verify against current state when acting on them.
</IMPORTANT>

<IMPORTANT>
When a skill is relevant to your current task, invoke it before responding. If you're unsure whether a skill applies, lean toward invoking it — skills are lightweight and you can adapt after loading.
</IMPORTANT>

<IMPORTANT>
**Currency-first rule:** Do not answer version-sensitive questions from training data — library/SDK APIs, package versions, model IDs, pricing, CLI flags, "latest" anything. Verify against current sources first (context7 MCP for library docs, WebSearch/WebFetch for everything else, the project lockfile for installed versions). The `staying-current` skill is the full policy; the Currency Guard hook will remind you when a prompt looks version-sensitive. If you can't verify, say so rather than guessing.

# Verification Before Completion

## Overview

Claiming work is complete without verification is dishonesty, not efficiency.

**Core principle:** Evidence before claims, always.

**Violating the letter of this rule is violating the spirit of this rule.**

## The Iron Law

```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

# Visual Regression Testing

Automated screenshot comparison using Playwright. Catch visual bugs before they ship.

## Process

### Phase 1: Determine Test Scope

Ask the user:
1. **What URL(s) to test?** (localhost, staging, or production)
2. **What changed?** (CSS update, component refactor, dependency upgrade, etc.)

If the user already described what changed, skip asking.

# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** This should be run in a dedicated worktree (created by brainstorming skill).

**Save plans to:** `docs/ultraship/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for plan location override this default)

# Writing Skills

## Overview

**Writing skills IS Test-Driven Development applied to process documentation.**

**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

**REQUIRED BACKGROUND:** You MUST understand ultraship:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.