Skip to content

GUIDE.md

Latest commit

 

History

History
509 lines (350 loc) · 16 KB

GUIDE.md

File metadata and controls

509 lines (350 loc) · 16 KB

Shipkit User Guide

A complete guide to using every skill, agent, and feature in shipkit.

Table of Contents

  1. Getting Started
  2. Setup & Unsetup
  3. Skills Reference
  4. Agents
  5. Knowledge Bases
  6. Path-Scoped Rules
  7. Common Workflows
  8. Tips

Getting Started

After installing the plugin, all skills are available as /shipkit:<skill-name>. You can start using them immediately — no configuration needed.

/shipkit:review-my-code    # review your staged changes
/shipkit:test              # run your tests
/shipkit:qa                # full QA workflow

For the best experience, run /shipkit:setup once per project to tailor everything to your stack.

Setup & Unsetup

/shipkit:setup

Configures shipkit for your specific project. Run it once when you start using shipkit in a new codebase.

What it does:

  1. Snapshots your current CLAUDE.md + .claude/ directory to .shipkit-backup-<timestamp>/
  2. Detects your stack (Rails, React, Python, Go, Elixir, static)
  3. Detects test framework and package manager
  4. Asks for your project purpose and team conventions
  5. Creates a tailored CLAUDE.md with workflow rules
  6. Installs stack-specific skills, rules, and knowledge bases
  7. Optionally creates .claude/settings.json with safe defaults

How backups work:

  • Everything is copied to .shipkit-backup-<YYYYMMDD-HHMMSS>/ at project root
  • If an older shipkit backup already exists, you're asked to preserve or delete it
  • Preserved old backups are nested inside the new one and restored automatically by /unsetup

Usage:

/shipkit:setup              # auto-detect stack
/shipkit:setup rails        # skip detection, use Rails
/shipkit:setup react        # skip detection, use React

When to run it:

  • First time using shipkit in a project
  • After cloning a project that doesn't have a CLAUDE.md
  • When switching stacks (run /shipkit:unsetup first)

/shipkit:unsetup

Reverses everything /setup did. Restores your project to its pre-shipkit state.

What it does:

  1. Finds the .shipkit-backup-<timestamp>/ directory
  2. Shows you exactly what will be restored
  3. Asks for confirmation before proceeding
  4. Removes current CLAUDE.md and .claude/ directory
  5. Restores everything from the backup snapshot
  6. If the backup contained a nested older backup, restores that too
  7. Deletes the backup directory after successful restore

Usage:

/shipkit:unsetup

When to run it:

  • You want to remove shipkit's project configuration
  • Before switching to a different stack (then run /setup again)
  • Before uninstalling the plugin entirely

Full removal:

/shipkit:unsetup                     # remove project configuration
/plugin uninstall shipkit@shipkit    # remove the plugin

Note: If you never ran /setup, you don't need /unsetup. Just uninstall the plugin directly.

Skills Reference

/shipkit:qa — Quality Assurance

5-phase QA workflow that asks probing questions before writing tests.

Phases:

  1. Reconnaissance — detect test framework, classify changed files by risk
  2. Interrogation — ask 3-8 probing questions before writing any tests
  3. Test Plan — structured plan organized by category for your approval
  4. Spec Writing — one assertion per test, descriptive names, arrange-act-assert
  5. Execution — run tests, fix failures, produce QA report
/shipkit:qa                              # QA recent changes
/shipkit:qa src/services/payment.ts      # focus on specific file

/shipkit:review-my-code — Code Review

Reviews code through 8 lenses with severity levels.

The 8 lenses:

  1. Clean Code + Single Responsibility
  2. DRY (Don't Repeat Yourself)
  3. KISS (Keep It Simple)
  4. YAGNI (You Aren't Gonna Need It)
  5. Language Idioms
  6. Framework Patterns + OCP/DIP
  7. Performance & Scalability
  8. Error Handling

Severity levels: BLOCKER, CRITICAL, MAJOR, MINOR, NIT, PRAISE

Verdict: APPROVE, REQUEST CHANGES, or NEEDS DISCUSSION

/shipkit:review-my-code                          # review staged changes
/shipkit:review-my-code src/billing.ts           # review specific file
/shipkit:review-my-code 142                      # review PR #142

/shipkit:test — Run Tests

Auto-detects your test framework and runs tests. Diagnoses failures automatically.

/shipkit:test                    # run all tests
/shipkit:test quick              # fast tests only
/shipkit:test specific path/to   # run one test file
/shipkit:test coverage           # with coverage reporting

/shipkit:tdd — Test-Driven Development

Enforces the Red-Green-Refactor cycle. No production code without a failing test first.

Iron Law: Write the test first. Watch it fail. Write minimal code to pass. Refactor.

Includes rationalization prevention (excuse-to-reality table), red flags list, testing anti-patterns catalog, and a verification checklist.

/shipkit:tdd feature       # TDD for a new feature
/shipkit:tdd bugfix        # TDD for a bug fix
/shipkit:tdd refactor      # TDD for refactoring

/shipkit:debug — Systematic Debugging

Root-cause debugging with a 4-phase process. No fixes without investigation first.

Phases:

  1. Root Cause Investigation — read errors, reproduce, trace data flow
  2. Pattern Analysis — find working examples, compare
  3. Hypothesis and Testing — test one variable at a time
  4. Implementation — create failing test, fix root cause, verify

Includes the three-strike rule: after 3 failed fixes, stop and question the architecture.

/shipkit:debug                                  # general debugging
/shipkit:debug "TypeError in checkout flow"     # describe the error
/shipkit:debug src/services/payment.ts          # debug a specific file

/shipkit:humanize — AI Writing Detection

Detects and removes AI-generated writing patterns. Two modes: humanize (rewrite) and analyze (detect only).

Covers 40 patterns across vocabulary, structure, tone, and formatting. Includes a full pattern library reference.

/shipkit:humanize                   # humanize provided text
/shipkit:humanize analyze           # detect patterns only, don't rewrite

/shipkit:onboard — Codebase Onboarding

5-phase exploration for unfamiliar codebases.

Phases:

  1. Trace one request/flow end-to-end
  2. Map the architecture
  3. Analyze git history for hotspots
  4. Generate lightweight docs (ARCHITECTURE.md, CODEBASE_MAP.md)
  5. Suggest project-specific skills
/shipkit:onboard                         # full 5-phase onboarding
/shipkit:onboard zoom-in src/app.ts      # start from specific file
/shipkit:onboard zoom-out                # skip tracing, go to architecture

/shipkit:explain-system — System Design Docs

Explores your codebase and writes a verified system design document explaining WHY it's designed the way it is.

/shipkit:explain-system                  # full 6-phase explanation
/shipkit:explain-system quick            # phases 1-2 only
/shipkit:explain-system section auth     # regenerate just one section

/shipkit:walkthrough — Feature Trace

Traces one feature from entry point through every layer.

/shipkit:walkthrough user-registration           # trace by feature name
/shipkit:walkthrough src/controllers/auth.ts     # trace from file
/shipkit:walkthrough checkout surface            # happy path only
/shipkit:walkthrough checkout deep               # include error paths

/shipkit:update-rules — Update CLAUDE.md

Adds, updates, or removes rules in CLAUDE.md while maintaining structure.

/shipkit:update-rules always use factory_bot, never fixtures
/shipkit:update-rules remove the rule about JIRA references
/shipkit:update-rules add: API responses must include request_id

Never manually edit CLAUDE.md — use this skill to keep formatting consistent.

/shipkit:context-audit — Context Window Health

Reports what's consuming your context window and suggests optimizations.

/shipkit:context-audit

Use this when Claude seems to be forgetting things or losing context.

/shipkit:use-library — Documentation-First Library Usage

Reads docs before using any library. Fetches official docs, checks versions, verifies compatibility.

/shipkit:use-library redis
/shipkit:use-library @tanstack/react-query
/shipkit:use-library fastapi

Will NOT write code until documentation has been read.

/shipkit:ai-feature — AI/LLM Feature Scaffolding

Scaffolds AI features with the right library for your stack.

/shipkit:ai-feature chat
/shipkit:ai-feature embeddings
/shipkit:ai-feature rag
/shipkit:ai-feature agent
/shipkit:ai-feature structured-output

/shipkit:legacy-audit — Legacy Codebase Audit

Audits for modernization opportunities. Read-only — does not modify files.

/shipkit:legacy-audit              # all categories
/shipkit:legacy-audit deps         # dependency age and security
/shipkit:legacy-audit dead-code    # unused files and functions
/shipkit:legacy-audit complexity   # hotspots cross-referenced with git churn
/shipkit:legacy-audit coverage     # test coverage gaps

/shipkit:migration-plan — Dependency Migration Planning

Plans major upgrades with impact analysis. Plan only — does not execute.

/shipkit:migration-plan rails 7.1 8.0
/shipkit:migration-plan react 18 19
/shipkit:migration-plan webpack vite

/shipkit:ui-ux — UI/UX Design & Review

Empathy-driven UI/UX for web and mobile (iOS, Android, Flutter, React Native).

Modes:

  • Design — user flow first, all 5 states, accessibility, mobile, performance
  • Review — 24-point checklist with severity levels and score
  • Audit — comprehensive UI/UX evaluation
  • Improve — identify top 3 improvements and implement them
/shipkit:ui-ux design user-onboarding
/shipkit:ui-ux review
/shipkit:ui-ux audit
/shipkit:ui-ux improve src/UserProfile.tsx

The ui-ux path-scoped rule also auto-loads when editing any UI file, applying core principles without needing to invoke the skill.

Lessons Memory

Shipkit includes a lightweight project memory system via .claude/lessons.md.

How it works

  • When you correct Claude or it discovers a project-specific pattern, it writes a one-line entry to .claude/lessons.md with the date
  • At the start of every session, Claude reads this file to avoid repeating mistakes
  • The file has a 30-line limit — when exceeded, Claude alerts you and suggests consolidating

Why 30 lines?

Research shows frontier LLMs have a ~150-200 effective instruction limit. CLAUDE.md uses ~130 lines, path-scoped rules add ~15-30 when active. Lessons.md needs to stay small to avoid crowding out useful context. 30 lines gives enough room for project-specific corrections without degrading performance.

The graduation cycle

Correction → lessons.md (short-term memory)
        ↓ repeats
/update-rules → CLAUDE.md (permanent rule)
        ↓ lessons entry removed

Lessons that keep recurring should become proper rules via /shipkit:update-rules. This keeps lessons.md lean and CLAUDE.md authoritative.

Example

# Lessons Learned

- 2026-03-11: Use `factory_bot` not fixtures — project convention
- 2026-03-11: API responses must include `request_id` header
- 2026-03-12: Don't use `after_save` for email notifications — use a job

Agents

Agents are used automatically by skills, or you can reference them in prompts.

test-analyzer

Diagnoses test failures. Checks for state leakage, timing issues, environment differences, dependency changes, and order-dependent failures.

Used automatically by /shipkit:test when tests fail. Or reference directly: "use the test-analyzer agent to diagnose this flaky test."

codebase-explorer

Read-only exploration agent. Traces call chains, maps directories, analyzes schemas, finds patterns, identifies hotspots.

Used automatically by /shipkit:onboard during phases 1-3. Or reference directly: "use the codebase-explorer agent to map the services directory."

Both agents: read-only, cap at 20 files per task, report confidence levels.

Knowledge Bases

Loaded on demand by skills — not always in context.

code-review-standards

Backs /shipkit:review-my-code with detailed criteria for each of the 8 lenses, anti-pattern catalog with smell-to-pattern mapping, and severity definitions.

ui-ux-standards

Backs /shipkit:ui-ux with cross-platform accessibility standards, design principles, platform-specific navigation patterns, performance budgets, and anti-pattern catalog.

Stack-specific (installed via /setup)

  • code-review-standards-rails — ActiveRecord performance, Sidekiq best practices, Hotwire consistency
  • ai-rails — RubyLLM patterns for chat, embeddings, streaming, tool use, testing

Path-Scoped Rules

These auto-load when you edit matching files. No action needed.

Rule When It Loads What It Enforces
testing Test files (*_test.*, *_spec.*) Arrange-act-assert, one behavior per test, descriptive names
migrations Database migrations Reversibility, safety checks, rollback strategies
security Controllers, API, auth files Input validation, parameterized queries, no hardcoded secrets
dependencies Dependency files (Gemfile, package.json, etc.) Version constraints, security audits, test suite after changes
monorepo Monorepo configs, workspace files Cross-package testing, dependency hoisting, breaking change paths
ui-ux UI files (web + mobile) Empathy-first design, accessibility, all 5 states, platform conventions

Stack-specific rules (installed via /setup)

Rule Stack What It Enforces
rails Rails N+1 prevention, strong params, migration safety, callback patterns
gemfile Rails Pessimistic version constraints, bundle audit
react React Component patterns, hooks rules, TypeScript conventions
package-json React Caret constraints, npm audit, no * or latest
python Python Virtual env, type hints, ruff/flake8 conventions
pyproject Python Version constraints, pip-audit
go Go Error handling, go vet, golangci-lint conventions
go-mod Go go mod tidy, govulncheck
elixir Elixir Context boundaries, OTP patterns, formatter/Credo
mix-deps Elixir Version constraints, hex audit

Common Workflows

Joining a project:

/shipkit:setup  →  /shipkit:onboard  →  /shipkit:explain-system

Building a feature (with TDD):

/shipkit:ui-ux design <feature>  →  /shipkit:tdd  →  /shipkit:qa  →  /shipkit:test

Adding a dependency:

/shipkit:use-library <name>  →  write code  →  /shipkit:test

Debugging a bug:

/shipkit:debug  →  /shipkit:tdd bugfix  →  /shipkit:test

Pre-PR checklist:

/shipkit:test  →  /shipkit:review-my-code  →  /shipkit:humanize (for docs/PR description)

Modernizing a legacy codebase:

/shipkit:legacy-audit  →  /shipkit:migration-plan <dep> <old> <new>  →  execute  →  /shipkit:test

Leaving shipkit:

/shipkit:unsetup  →  /plugin uninstall shipkit@shipkit

Tips

  1. Skills pause at checkpoints. Multi-phase skills like /shipkit:onboard and /shipkit:qa stop between phases for your input. Don't skip these.

  2. Use /clear between skills. Each skill works best with a fresh context window.

  3. Skills adapt to your stack. You don't need to specify your test framework or language — skills detect it automatically.

  4. Arguments are optional. Every skill has sensible defaults. Add arguments only to narrow scope.

  5. Path-scoped rules are automatic. You don't invoke them — they load when you edit matching files.

  6. Stack-specific content needs /setup. Base skills and rules work instantly. Stack-specific skills (like /new-feature for Rails) require running /shipkit:setup first.