Repo Preparation

The prep command (shipwright prep) analyzes your repository and generates the configuration files needed for effective agent team development. It creates .claude/ configs, architecture documentation, agent role definitions, quality gate hooks, and a GitHub issue template — all tailored to your project.

Quick Start

# Full analysis + generation
shipwright prep

# Audit existing prep quality (dry run)
shipwright prep --check

# Refresh auto-generated sections without overwriting user edits
shipwright prep --update

# Regenerate everything (overwrite existing)
shipwright prep --force

# Deep analysis using Claude Code (slower, richer output)
shipwright prep --with-claude

What It Generates

`.claude/` Directory

File	Purpose
`CLAUDE.md`	Project-specific instructions for Claude — conventions, architecture, key files
`settings.json`	Claude Code settings with permission allowlists and sensible defaults
`ARCHITECTURE.md`	System architecture overview — layers, data flow, key abstractions
`CODING-STANDARDS.md`	Coding conventions — style, naming, patterns, anti-patterns
`DEFINITION-OF-DONE.md`	Completion checklist — what “done” means for this project
`agents/*.md`	Agent role definitions for team-based development
`hooks/*.sh`	Pre/post action hooks — quality gates, notifications

GitHub Issue Template

File	Purpose
`.github/ISSUE_TEMPLATE/agent-task.md`	Structured issue template for agent-processable tasks

`CLAUDE.md` Content

The generated CLAUDE.md includes:

Project structure — directory layout, entry points, build system
Conventions — coding standards, naming patterns, import style
Key files — the most important files agents should know about
Test commands — how to run tests, lint, typecheck
Architecture notes — high-level system organization

How Analysis Works

Prep scans your repository to detect:

Language and framework — TypeScript, Python, Go, Rust, Java, etc.
Package manager — npm, pnpm, yarn, pip, cargo, go modules
Test framework — Jest, Vitest, pytest, go test, cargo test
Linter — ESLint, Ruff, golangci-lint
Build system — Webpack, Vite, esbuild, Make
CI/CD — GitHub Actions, Jenkins, GitLab CI

The generated configuration adapts to what it finds. A TypeScript/React project gets different hooks and CLAUDE.md content than a Python/FastAPI project.

Modes

Default (`shipwright prep`)

Runs full analysis and generates all files. Skips files that already exist (use --force to overwrite).

Check (`shipwright prep --check`)

Audits an existing prep without modifying any files. Reports on:

Missing or outdated generated files
Configuration quality and completeness
Hook health and permissions

Update (`shipwright prep --update`)

Refreshes auto-generated sections (architecture analysis, detected commands) while preserving any manual edits you’ve made to CLAUDE.md or other files.

Deep Analysis (`shipwright prep --with-claude`)

Uses Claude Code for richer analysis — better architecture descriptions, more accurate convention detection, and higher-quality agent role definitions. Slower but produces significantly better output for complex codebases.

Customization

After running shipwright prep, review and customize the generated files:

Edit .claude/CLAUDE.md — Add project-specific context that automated analysis might miss (domain terminology, architectural decisions, team conventions)
Tune hook scripts — Adjust quality gate thresholds or add project-specific checks
Update settings.json — Configure model preferences, auto-compact thresholds, and enabled plugins
Review agent roles — Customize agent definitions in agents/*.md for your team structure

Flags

Flag	Description
`--force`	Overwrite existing configuration files
`--check`	Audit existing prep quality (dry run, no writes)
`--update`	Refresh auto-generated sections only
`--with-claude`	Deep analysis using Claude Code (slower, richer)