shipworthy CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Shipworthy

What This Is

Shipworthy is an open-source Claude Code plugin that guides AI coding sessions toward production engineering practices. All checks are advisory by default — they suggest, never block. Every rule is configurable via .shipworthy/config.json. v1.5.0 with 64 skills, 6 hooks, 6 agents, 8 templates, 5 adapters, 3 presets, 7 commands.

Repository Structure

skills/              64 engineering skills as SKILL.md files (YAML frontmatter + Markdown)
  core/              Master router, architecture awareness, intent-to-spec
  planning/          Brainstorming, writing-plans, executing-plans, design-documents, decision-frameworks
  quality/           TDD, quality-gates, verification, error-handling, code-complexity, response-schema-validation, feedback-driven-adaptation, confidence-based-strictness
  security/          14 skills: adaptive-security, secrets, supply-chain, PII, compliance, bias-detection, vendor-risk-assessment, etc.
  architecture/      API design, database, performance, observability, resilience, 12-factor
  collaboration/     Subagent-driven-dev, parallel agents, code review
  operations/        15 skills: CI/CD, git worktrees, migrations, feature flags, incident response, context-manager, guardrail-audit-log, scope-creep-detection
  frontend/          Accessibility, frontend standards
  debugging/         Systematic debugging
  documentation/     Documentation as code
  meta/              Writing skills, retrospective
hooks/               6 bash hook scripts + shared library
  lib.sh             Shared utilities: JSON parsing, escaping, debug logging, transparency, config helpers
  session-start      SessionStart hook — tier detection, arch spec loading, transparency banner
  pre-tool-use       PreToolUse (Write|Edit) — secrets, eval, console.log suggestions (config-gated)
  pre-tool-use-bash  PreToolUse (Bash) — destructive command heads-up (config-gated)
  pre-push-validate  PreToolUse (Bash) — advisory pre-push check (blocks only in plugin repo or if user opts in)
  post-tool-use      PostToolUse (Bash) — commit, dependency, migration suggestions (config-gated)
  post-tool-use-write PostToolUse (Write|Edit) — :any, test location, route validation suggestions (config-gated)
commands/            7 slash commands (Markdown): /audit, /context, /diagnose, /health, /retro, /scaffold, /validate
agents/              6 agent personas (Markdown): code-reviewer, architecture-analyzer, security-auditor, test-strategist, project-doctor, pre-push-validator
templates/           8 architecture templates: nextjs, express, fastapi, go-service, react-spa, generic-typescript, generic-python, monorepo
adapters/            5 multi-agent adapters: cursor, copilot, codex, windsurf, gemini
presets/             3 config presets: startup.json, agency.json, enterprise.json
extensions/          Domain-specific extensions: e-commerce, fintech, healthcare
bin/shipworthy.cjs   CLI entry point (npx shipworthy init)
tests/               Test suites (14 suites, all passing)
  hooks/             Hook tests: test-session-start, test-pre-tool-use, test-post-tool-use, test-transparency
  skills/            Skill tests: test-skill-frontmatter, test-cso-format, test-cross-references, test-skill-routing, test-skill-quality, test-transparency-instructions
  security/          Security audit: test-security-audit (12 static analysis checks)
  run-all-tests.sh   Master test runner (auto-discovers test-*.sh files)
  validate-all.sh    Pre-push validation (8 checks, called by pre-push-validate hook)
site/                Landing page (GitHub Pages): index.html, og-image.html
docs/                Documentation site: getting-started/, guides/, reference/, blog/
benchmarks/          Reproducible benchmark suite with scoring scripts