
shipwithai-starter
Set up a standardized Claude Code harness for any project. One guided interview configures CLAUDE.md, permissions, hooks, MCP servers, agents, and SSOT docs. Three tiers: Essential (5 min), Standard (15 min), Full (30 min).
- version
- 1.0.0
- GitHub stars
- 9
Install
/plugin install shipwithai-starter@shipwithaiRun it inside Claude Code after adding the marketplace with /plugin marketplace add ShipWithAI/shipwithai-plugins.
Contents
Discovered from sourceSkills 13
/init
Mandatory entry point for the plugin. Do not run any other skill before init completes.
Instructions
Step 1 — State Detection
Before any other detection, check for an empty directory:
Scan for: package.json, pom.xml, build.gradle, go.mod, Cargo.toml,
pyproject.toml, Gemfile, composer.json, mix.exs
If NONE of these files are found:
"This looks like an empty project. Handing you off to
/shipwithai-starter:new-project for a better setup experience."
→ invoke /shipwithai-starter:new-project
→ stop
If stack files are found, continue with normal state detection:
Before asking anything, read the project state:
CLAUDE.md → populated / has [PLACEHOLDER] / missing
.claude/settings.json → exists / missing
.mcp.json → exists / missing
.claude/agents/ → exists / missing
docs/architecture.md → exists / missing
Auto-detect tech stack:
package.json → Node/TypeScript
pyproject.toml → Python
go.mod → Go
Cargo.toml → Rust
pom.xml / build.gradle → Java
Gemfile → Ruby
Detect existing tools:
.eslintrc* / eslint.config.* → ESLint
prettier.config* / .prettierrc → Prettier
jest.config* → Jest
pytest.ini / conftest.py → pytest
Makefile → make
docker-compose.yml → Docker Compose
If --update is provided: skip to Update Mode below — do not run the full interview.
If CLAUDE.md is already populated and --redo is not set and --update is not set: "Harness is already set up. Want to redo? (use --redo) or answer new questions only? (use --update)"
If --tier argument is provided, skip the tier selection prompt in Step 2 and use the given value directly.
Update Mode (--update)
Run when review detects schema is outdated, or user runs init --update directly.
Step 1: Read .claude/starter-context.json
→ Not found: "No context found. Run /shipwithai-starter:init for full setup."
→ Found: continue
Step 2: Compare existing fields against current schema (v1.4)
→ Find all fields that are null or absent
Step 3: For each missing field, ask the corresponding interview question only
→ Same wording as full interview
→ Skip all fields that already have answers
Step 4: Update starter-context.json
→ Merge new answers in
→ Set version to "1.4"
Step 5: Invoke setup-memory (merge mode)
→ Adds/updates only sections with new data
→ Existing sections preserved
Current schema fields by version:
v1.0: stack, project, architecture, conventions (formatter/branch_strategy/commit_format/coverage_target), permissions, hooks_selected, mcp_selected, agents_selected, ssot
v1.1: + conventions.workflow_gates
v1.2: + observability.enabled
v1.3: + skills_selected
v1.4: + stack_plugins_selected
Step 2 — Fork-First Preamble
Show immediately after state detection, before asking anything:
shipwithai-starter sets up a standard Claude Code harness for your project.
Tier 1 — Essential (5 min): CLAUDE.md with tech stack + conventions + architecture,
docs/architecture.md,.claude/settings.jsonwith stack-appropriate permissions. Ready to use immediately.Tier 2 — Standard (15 min): Adds auto-format/lint hooks,
.mcp.jsonfor external services.Tier 3 — Full (30 min): Adds specialized agents, ADR structure, CODEMAPS for codebase navigation.
Which tier? (Upgrade any time with
/shipwithai-starter:review)
→ Wait for tier selection before asking anything else.
Step 3 — Interview Flow
Part 0: Stack Confirmation (all tiers)
"I detected: [list detected stack + tools]. Anything wrong?"
If nothing detected → ask:
- Primary language?
- Primary framework?
- Build tool?
- Test framework?
- Package manager?
Part 1: Project Identity (all tiers)
Ask once, grouped:
- Project name + type (web app / API / CLI / lib / monorepo)?
- Team size?
- Stage (greenfield / active / maintenance / legacy)?
Part 2: Architecture (all tiers)
- Architecture style (monolith / microservices / modular monolith / event-driven)?
- Key layers and their corresponding directories?
- Entry points?
- External dependencies (DB, queue, cache, external APIs)?
"Paste tree -L 3 or I'll scan the codebase myself."
→ Read output, extract key directories automatically.
Gotchas (highest value — do not skip):
- Which directories/files must NOT be edited manually? (generated code)
- Build order dependencies? (codegen → compile)
- What does test isolation require? (Docker? env vars? seeds?)
- Which areas of code need extra care? (auth, payments, migrations)
Part 3: Conventions (all tiers)
If eslint/prettier/black/gofmt detected → confirm, do not re-ask. If not detected → ask:
- Code style tool?
- Branch strategy (trunk-based / gitflow)?
- Commit format (conventional / custom / none)?
- Test coverage target?
"Which workflow gates should Claude follow when working on tasks?" (Select all that apply — choosing None deselects all others)
→ [ ] Plan/design before coding
Claude must create a plan or design doc before writing code for any task > 30 min
→ [ ] TDD — write tests first
Claude writes failing tests before implementation
→ [ ] Code review gate
Claude runs code-reviewer agent after every significant change
→ [ ] Security review for sensitive areas
Claude runs security-reviewer before committing to sensitive areas
→ [ ] None — let Claude decide
Part 4: Permissions (all tiers)
Load preset from ./setup-permissions/settings-presets.json by detected stack.
"Based on your stack, I suggest this permission profile: [show preset with explanation per rule] Want to customize?"
Also ask:
- Which tools should Claude NOT use? → disallowedTools
- Which paths are read-only? → read-only paths
Part 5: Hooks (Tier 2+)
Detect available tools → suggest from ./setup-hooks/hooks-catalog.json:
ESLint detected → "Enable eslint --fix hook after Claude edits .ts/.js?"
Prettier detected → "Enable prettier --write hook after Edit tool?"
pytest detected → "Enable pytest hook after Claude edits *_test.py?"
Jest detected → "Enable jest hook after Claude edits *.test.*?"
gofmt detected → "Enable gofmt -w hook after Edit tool on .go files?"
One hook at a time. Show preview before confirming.
Part 6: MCP Servers (Tier 2+)
"Which external services does this project interact with?"
→ Show list from ./setup-mcp/mcp-registry.json.
For each selected service:
- Show config preview.
- Attempt test connection → report ✓ tested / ⚪ configured-not-verified / ✗ not-found.
- Never report ✓ without actually testing.
- Confirm before adding.
Part 6.5: Project Skills (Tier 2+)
Load ./setup-skills/skills-catalog.json → suggest installable project skills.
git-workflow is alwaysInclude — offer it by default (every project has git).
Show preview with the resolved commit/branch variant → confirm.
Part 6.6: Stack Plugins (Tier 2+)
Load ./stack-recipes.json → for each recipe whose detect matches the project
(a files entry exists AND, if content is set, one of those strings appears in it),
surface the recommended ShipWithAI plugin:
"Detected [recipe.label]. ShipWithAI has a dedicated plugin for this stack: [recommendPlugin] — [reason]. Set it up?"
- On yes, record
recommendPlugininstack_plugins_selected. If the plugin is already enabled (itssetupCommandresolves), invoke that command in Step 5. - If the plugin is not enabled, tell the user how to add it (enable the
[marketplace]marketplace), then it wires on the nextinit/--updaterun. Never claim it is installed when it is not.
Only recommend; never force-install. starter cannot enable a plugin the user has not added — that is the user's action. A user who declines is fine; do not re-ask.
Part 7: Agents (Tier 3+)
Load ./setup-agents/agents-catalog.json → suggest agents by project type/team size.
Always include drift-monitor for Tier 3.
Show preview per agent → confirm.
Part 8: SSOT (Tier 3+)
- "Set up ADR structure?" → Yes: create
docs/adr/+ADR-0001-initial-architecture.md. - "Create CODEMAPS?" → Yes: create
docs/CODEMAPS/structure guide.
Step 4 — Preview & Confirm
After the interview, generate a preview of all files to be written:
Here is what I will create/update:
┌──────────────────────────────────────┬──────────┬───────┐
│ File │ Action │ Tier │
├──────────────────────────────────────┼──────────┼───────┤
│ CLAUDE.md │ CREATE │ 1 │
│ docs/architecture.md │ CREATE │ 1 │
│ .claude/settings.json (permissions) │ CREATE │ 1 │
│ .claude/settings.json (hooks) │ UPDATE │ 2 │
│ .mcp.json │ CREATE │ 2 │
│ .claude/skills/git-workflow/SKILL.md │ CREATE │ 2 │
│ .claude/agents/drift-monitor.md │ CREATE │ 3 │
│ .claude/hooks/observe.py │ CREATE │ 3 │
│ .claude/logs/ (.gitignore entry) │ UPDATE │ 3 │
└──────────────────────────────────────┴──────────┴───────┘
Confirm?
For existing files: "File [X] already exists. Overwrite / Merge / Skip?"
Step 4.5 — Write Context File
Immediately after the user confirms the preview, before invoking any pillar skill,
write .claude/starter-context.json with all interview answers:
{
"version": "1.4",
"tier": "essential|standard|full",
"stack": {
"language": "...",
"framework": "...",
"build_tool": "...",
"test_framework": "...",
"package_manager": "...",
"detected_tools": ["eslint", "prettier", "..."]
},
"project": {
"name": "...",
"type": "web-app|api|cli|lib|monorepo",
"team_size": 3,
"stage": "greenfield|active|maintenance|legacy"
},
"architecture": {
"style": "monolith|microservices|modular-monolith|event-driven",
"key_layers": [{ "name": "API", "dir": "src/routes/", "responsibility": "..." }],
"entry_points": ["src/index.ts"],
"external_deps": [{ "service": "PostgreSQL", "purpose": "...", "env_var": "DATABASE_URL" }],
"gotchas": ["src/generated/ — do not edit manually"],
"build_order": ["codegen before tsc"],
"test_isolation": ["requires Docker Compose"],
"sensitive_areas": ["auth/", "payments/"]
},
"conventions": {
"formatter": "prettier",
"branch_strategy": "trunk-based",
"commit_format": "conventional",
"coverage_target": "80%",
"workflow_gates": ["plan-before-code", "tdd", "code-review"]
},
"permissions": {
"preset": "nodejs",
"disallowed_tools": [],
"readonly_paths": []
},
"hooks_selected": ["prettier", "eslint"],
"mcp_selected": ["github", "linear"],
"agents_selected": ["drift-monitor"],
"skills_selected": ["git-workflow"],
"stack_plugins_selected": ["shipwithai-java-backend-toolkit"],
"ssot": {
"adr": true,
"codemaps": false
},
"observability": {
"enabled": false
},
"collected_at": "ISO8601 timestamp"
}
This file is the source of truth for all pillar skills — both when called from init and standalone.
Commit this file alongside .claude/ so the team shares context.
Step 5 — Orchestrate Pillar Skills
User approves → invoke each pillar skill by tier, reading context from .claude/starter-context.json:
Tier 1: /shipwithai-starter:setup-memory (reads: project, stack, architecture, conventions)
→ writes CLAUDE.md at every tier; when tier=full,
also installs the .claude/memory/ lifecycle
(store + SessionStart/Stop hooks + /save-memory)
/shipwithai-starter:setup-permissions (reads: stack, permissions)
/shipwithai-starter:setup-ssot --architecture-only (reads: architecture)
Tier 2: /shipwithai-starter:setup-hooks (reads: stack.detected_tools, hooks_selected)
/shipwithai-starter:setup-mcp (reads: mcp_selected)
/shipwithai-starter:setup-skills (reads: skills_selected, conventions)
For each entry in stack_plugins_selected whose plugin is enabled:
invoke its setupCommand from stack-recipes.json (reads: stack_plugins_selected)
e.g. /shipwithai-java-backend-toolkit:setup
(if not enabled, skip and remind the user to enable it, then re-run)
Tier 3: /shipwithai-starter:setup-agents (reads: agents_selected, project)
/shipwithai-starter:setup-ssot --adr --codemaps (reads: ssot)
/shipwithai-starter:setup-observability (reads: observability) — only if observability.enabled == true
Step 6 — After-Write
- Summary table: files created / updated / skipped.
- "Commit
.claude/andCLAUDE.mdto the repo so the team shares the harness." - Upgrade note: "Currently at Tier [N]. Upgrade with
/shipwithai-starter:review."
Failure Modes
Don't guess stack if ambiguous → ask
Don't write hooks for tools not detected in the project
Don't add MCP server without actually verifying the connection
Don't overwrite existing files without asking
Don't skip the gotchas section — it's the highest-value part
Don't proceed if the user has not confirmed the preview
/new-project
Greenfield entry point. Guides from an empty directory to a scaffolded project with a configured Claude harness.
Prerequisite Check
Scan for stack indicator files before anything else:
package.json pom.xml build.gradle go.mod Cargo.toml
pyproject.toml Gemfile composer.json mix.exs
If any found:
"This directory already has a project. Use
/shipwithai-starter:initinstead." → stop
Overview
3 phases, each ending with a confirmed artifact. User can redirect at any checkpoint.
Phase 1 → confirm tech stack
Phase 2 → confirm architecture + folder structure
Phase 3 → confirm conventions → final preview → execute
Phase 1 — Project Goals
Ask 5 questions, one per message. Do not bundle questions.
Q0: What's the project name? (used for scaffold command and CLAUDE.md)
"What should we call this project? (e.g. my-app, acme-api)"
Q1: What are you building?
"What type of project is this?"
- Web app
- REST API
- Mobile backend
- CLI tool
- Library
Q2: Who will use it?
"Who's the primary audience for this project?"
- Just me (personal / internal tool)
- Small team or customers (< 1k users)
- Product with real growth targets
Q3: Any hard constraints? (free text, or "none")
"Any constraints I should know? e.g. must use a specific language, existing database to integrate with, specific hosting (Vercel, AWS, self-hosted)."
Q4: One-line description of what the project does. (free text)
After Q4, generate and show a tech stack recommendation:
Based on your answers, I recommend:
Project: [name]
Type: [web app / REST API / mobile backend / CLI / library]
Language: [language]
Framework: [framework + version]
Database: [database]
Hosting: [hosting]
Why: [2-3 sentence reasoning grounded in their specific answers]
Use this stack? (yes / swap one thing / different direction)
| Response | Action |
|---|---|
yes | Proceed to Phase 2 with confirmed stack |
swap one thing | "What would you like to swap?" → regenerate recommendation |
different direction | Return to Q1 |
Phase 2 — Technical Decisions
Generate 4-5 questions dynamically based on confirmed stack. Ask only questions relevant to the stack. One per message. Always include "Let me decide" for decisions that have a sensible default.
When "Let me decide" is chosen: pick an opinionated default and record it in
starter-context.json under the relevant field. In CLAUDE.md, add a comment
inline next to the value: # default — revisit before production.
Required question categories (adapt wording to stack):
- Database access / ORM
- Authentication approach
- API style
- Email service (if web app or API with users)
- Payments (if growth-stage product)
- Base package (if Java or Kotlin stack only)
"What's your base package? (e.g. com.example, io.acme.myapp)" → Used to generate exact package paths in folder tree:
src/main/java/com/example/myapp/
Example — Next.js + PostgreSQL:
| Question | Options |
|---|---|
| ORM / database access? | Drizzle / Prisma / Raw SQL (postgres.js) / Let me decide |
| Authentication? | Better Auth / Clerk / NextAuth.js / None yet / Let me decide |
| API style? | Server Actions / REST API routes / tRPC / Let me decide |
| Email? | Resend / SendGrid / None yet |
| Payments? | Stripe / Lemon Squeezy / None yet |
Example — Spring Boot + PostgreSQL:
| Question | Options |
|---|---|
| ORM? | JPA/Hibernate / jOOQ / JDBC Template / Let me decide |
| Auth? | Spring Security + JWT / OAuth2 Resource Server / Keycloak / Let me decide |
| API? | REST / GraphQL / gRPC / Let me decide |
| Async messaging? | Kafka / RabbitMQ / None yet |
| Email? | Spring Mail + SendGrid / Resend / None yet |
| Payments? | Stripe Java SDK / None yet |
After the last technical question, generate and show an architecture recommendation:
Here's your architecture:
Pattern: [pattern name]
[project-name]/
├── src/
│ ├── features/ ← business domains (auth, billing, dashboard)
│ │ └── <feature>/
│ │ ├── components/
│ │ ├── actions/ ← Server Actions or route handlers
│ │ └── types.ts
│ ├── components/ ← shared UI components
│ ├── db/
│ │ ├── schema.ts ← Drizzle schema definitions
│ │ └── index.ts ← database client
│ └── lib/ ← shared utilities and configs
└── [framework-specific root files]
Key decisions:
- [decision 1 + one-line rationale]
- [decision 2 + one-line rationale]
- [decision 3 + one-line rationale]
Does this architecture look right?
(yes / adjust folders / different pattern)
Generate the actual folder tree based on the confirmed stack and technical decisions — the example above is for Next.js + Drizzle. Adapt structure for other stacks (e.g. Spring Boot → src/main/java/.../controller|service|repository, Go → flat package layout).
| Response | Action |
|---|---|
yes | Phase 3 |
adjust folders | "What would you change?" → regenerate folder tree only → re-confirm |
different pattern | Show 2 alternative patterns with tradeoffs → user picks → confirm |
Phase 3 — Conventions
Ask 3 questions, one per message:
Q1: Workflow gates — what should Claude follow? (multi-select)
→ [ ] Plan before coding
Claude creates a plan before writing code for any task > 30 min
→ [ ] TDD — write tests first
Claude writes failing tests before implementation
→ [ ] Code review after every significant change
Claude runs code-reviewer agent after each change
→ [ ] Security review for sensitive areas
Claude runs security-reviewer before committing to auth/payments areas
→ [ ] None — let Claude decide
Q2: Commit format?
- Conventional commits (feat/fix/chore/docs)
- Custom (ask for format)
- None
Q3: Test coverage target?
- 80% (recommended)
- 60%
- No target
After Q3, show the final preview before executing:
Here's everything I'll set up:
┌──────────────────────────────────────┬──────────────────────────────┐
│ Action │ Details │
├──────────────────────────────────────┼──────────────────────────────┤
│ Run scaffold │ [exact command] │
│ CLAUDE.md │ CREATE — full architecture │
│ docs/architecture.md │ CREATE │
│ .claude/settings.json │ CREATE — [stack] preset │
│ .claude/starter-context.json │ CREATE — committed to git │
└──────────────────────────────────────┴──────────────────────────────┘
Stack: [confirmed stack summary]
Architecture: [pattern name]
Gates: [selected gates, or "None"]
Commits: [format]
Ready to execute? (yes / go back to phase 1 / 2 / 3)
| Response | Action |
|---|---|
yes | Execute |
go back to phase N | Return to that phase, re-run from its first question |
Execute
Run in this exact order — do not reorder steps:
Step 1 — Run scaffold command
Run scaffold FIRST while the directory is still empty — writing files before scaffold can cause tools to refuse or warn about non-empty directories.
Show the exact command to the user before running it:
"I'll run:
[command]. This will scaffold the project in the current directory."
Scaffold commands by stack:
Next.js → npx create-next-app@latest .
Spring Boot → spring init --dependencies=[selected deps] --build=gradle .
Django → django-admin startproject [name] .
Go → go mod init [module-name]
Rust → cargo init .
Node.js API → npm init -y then install chosen framework
Other stack → ask user for the scaffold command
If scaffold fails:
"Scaffold failed: [error]. Please fix the issue above, then run
/new-projectagain." → stop, do not proceed to pillar skills
Step 2 — Write context file
After scaffold succeeds, write .claude/starter-context.json.
Use the v1.4 schema (same as init Step 4.5). Always set:
version→"1.4"project.stage→"greenfield"project.team_size→1architecture.gotchas→ include"Project is greenfield — structure does not exist yet, build toward it"tier→"essential"(default for new-project; user can upgrade via/shipwithai-starter:review)
Essential-tier defaults for the Tier 2+/3+ fields (greenfield starts minimal — upgrade later):
hooks_selected,mcp_selected,skills_selected,agents_selected,stack_plugins_selected→[]observability.enabled→false
(A greenfield Spring Boot project that later wants the guardrail toolkit gets flagged by
/shipwithai-starter:review stack-plugin coverage, or can run init --update.)
Step 3 — Invoke pillar skills
Each pillar skill auto-reads .claude/starter-context.json — do not pass parameters manually.
/shipwithai-starter:setup-memory → writes CLAUDE.md + .claude/memory/ structure
/shipwithai-starter:setup-permissions → writes .claude/settings.json
/shipwithai-starter:setup-ssot --architecture-only → writes docs/architecture.md
Step 4 — After-write summary
Done! Here's what was set up:
✓ Project scaffolded via [tool]
✓ CLAUDE.md architecture + conventions (greenfield intent)
✓ docs/architecture.md
✓ .claude/settings.json
✓ .claude/starter-context.json
Next steps:
1. git init && git add .claude/ CLAUDE.md docs/ && git commit -m "chore: add Claude harness"
2. Open Claude Code → harness is ready
3. Run /shipwithai-starter:review anytime to check harness health
Failure Modes
Don't run scaffold without showing the command first
Don't continue past a checkpoint without user confirmation
Don't write harness files before starter-context.json is written
Don't continue if scaffold command fails
Don't ask about team size — irrelevant to harness config
Don't hardcode architecture patterns — generate with LLM based on stack + type + answers
Don't skip "Let me decide" option in Phase 2 questions
/optimize-harness
Reads .claude/logs/*.jsonl (written by observe.py) and surfaces actionable
suggestions: hooks to add, workflow gates to enable — based on what you actually do.
Does NOT repeat static analysis from
/review. Hook binaries, MCP alignment, schema drift → run/shipwithai-starter:review. Runtime usage patterns (frequency, directories, commands) → run this skill.
Flag Handling
--verbose— include LOW confidence suggestions (hidden by default)--window N— analysis window in days, minimum 7 (default: 30)--json— output as JSON instead of markdown report--force— bypass the 7-day cooldown advisory without prompting
Step 1 — Guard Clauses
Evaluate in order. Stop on first failure and output the message below.
Guard 1 — Observability not enabled:
Check: .claude/logs/ exists AND .claude/hooks/observe.py exists
Fail output:
Observability not enabled. Run /shipwithai-starter:setup-observability
first. optimize-harness requires at least 7 days of log data.
Guard 2 — Not enough data:
Check: ≥7 distinct YYYY-MM-DD log filenames within window
AND ≥50 total parsed events
Fail output:
Not enough data yet.
Current: [N] days of logs, [T] tool calls
Required: 7 days AND 50 tool calls
Come back after [earliest_date + 7 days].
N = count of YYYY-MM-DD filenames within window. T = successfully parsed events.
Guard 3 — Cooldown (advisory only, not a hard block):
Check: starter-context.json → optimizer.last_run exists
AND today - last_run < 7 days
Warn: Last optimization was [N] days ago (last run: [date]).
Results may not reflect new patterns. Run anyway? [y/N]
Proceed if user says yes, passes --force, or optimizer.last_run is absent.
Step 2 — Parse & Aggregate
Parse:
- List
.claude/logs/*.jsonlsorted by filename date; filter to window - Read line by line — skip malformed lines silently (no error output)
- Discard:
toolabsent or not in{Edit, Write, Bash} - Discard:
tsabsent or unparseable
Log format (observe.py — no exit codes, no ms duration):
Edit/Write: {"ts":"2026-06-01T10:00:00Z","sid":"a3f2c8b1","event":"tool","tool":"Edit","file":"src/auth.ts"}
Bash: {"ts":"2026-06-01T10:00:05Z","sid":"a3f2c8b1","event":"tool","tool":"Bash","cmd":"npm"}
Aggregate (pure computation — no further file I/O):
| Metric | Definition |
|---|---|
bash_cmd_frequency | Map<cmd, count> — Bash events only, key on cmd |
file_edit_frequency | Map<file_path, count> — Edit+Write, skip empty file |
file_edit_by_dir | Map<first_path_component, count> — from Edit+Write file field |
ts_extension_edits | Map<lowercase_ext_with_dot, count> — from Edit+Write file field |
session_count | len(set(e.sid for e in events)) |
session_duration_minutes | Per sid ≥2 events: (last_ts - first_ts).total_seconds() / 60 |
daily_tool_calls | Map<YYYY-MM-DD, count> from ts field |
days_with_data | len(daily_tool_calls) |
Step 3 — Correlate & Evaluate Rules
Read .claude/starter-context.json:
hooks_selected— list of active hook IDs (default:[])workflow_gates— list of active gate IDs (default:[])architecture.sensitive_areas— list of path patterns (default:[])
Compute sensitive_area_edits: for each pattern, count Edit+Write events
where file starts with the pattern (strip leading ./ from file paths).
Load optimize-rules.json (same directory as this file) to get rule definitions.
Evaluate all 8 rules:
| Rule | Condition | Confidence |
|---|---|---|
| R1 | bash_cmd_frequency["npm"] ≥ 5 AND jest-on-stop not in hooks_selected | HIGH ≥20 / MEDIUM ≥5 |
| R2 | bash_cmd_frequency["pytest"] ≥ 5 AND pytest-on-stop not in hooks_selected | HIGH ≥20 / MEDIUM ≥5 |
| R3 | sum(.ts+.tsx+.js+.jsx edits) ≥ 20 AND prettier-on-edit not in hooks_selected | HIGH ≥50 / MEDIUM ≥20 |
| R4 | .py edits ≥ 20 AND neither black-on-edit nor ruff-on-edit in hooks_selected | HIGH ≥50 / MEDIUM ≥20 |
| R5 | any sensitive_area_edits[P] ≥ 10 AND security-review not in workflow_gates | HIGH |
| R6 | make ≥ 5 AND make-test-on-stop absent; OR cargo ≥ 5 AND cargo-test-on-stop absent | HIGH ≥20 / MEDIUM ≥5 |
| R7 | top file_edit_frequency entry ≥ 30 AND no test file found | LOW |
| R8 | ≥3 timed sessions AND median(session_duration_minutes) > 60 | LOW |
R5: Use the pattern with the highest sensitive_area_edits count for the evidence line.
R6: If both make and cargo trigger, emit one suggestion per tool (two results).
R7 — test file detection:
base = filename without extension (e.g. "auth" from "src/auth.ts")
find . -not -path "*/node_modules/*" -not -path "*/.git/*" \
\( -name "*${base}.test*" -o -name "*${base}.spec*" \
-o -name "test_${base}*" -o -name "${base}_test*" \) 2>/dev/null
Non-empty output → test file exists → R7 does NOT trigger.
Filter & rank:
- Keep triggered rules only
- Drop LOW confidence if
--verbosenot set - Sort: HIGH first, then MEDIUM, then LOW
- Deduplicate by rule ID (keep first)
- Truncate to top 5
Step 4 — Output
Normal report:
## Harness Optimization Report — [project name from CLAUDE.md]
Period: YYYY-MM-DD → YYYY-MM-DD ([N] days, [M] sessions, [T] tool calls)
### Usage Summary
Most edited files: [file1] ([N]), [file2] ([N]), [file3] ([N])
Most used commands: [cmd1] ([N]), [cmd2] ([N]), [cmd3] ([N])
Active directories: [dir1] ([N] edits), [dir2] ([N] edits), [dir3] ([N] edits)
Tool distribution: Edit [X]% / Write [Y]% / Bash [Z]%
### Suggestions
[HIGH] [title]
Evidence: [evidence string]
Action: [action label from rule definition]
[MEDIUM] ...
---
Data window: [N] days | Next optimization: [today + 7 days]
No suggestions — replace Suggestions section with:
### No issues detected
Your harness matches your usage patterns. Keep it up!
--json output schema:
{
"project": "string", "generated_at": "YYYY-MM-DD",
"period": {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD", "days": 30, "sessions": 12, "total_events": 347},
"summary": {
"top_files": [{"file": "src/auth.ts", "count": 42}],
"top_commands": [{"cmd": "npm", "count": 67}],
"top_dirs": [{"dir": "src", "count": 93}],
"tool_distribution": {"Edit": 54, "Write": 12, "Bash": 34}
},
"suggestions": [{"id": "R1", "confidence": "HIGH", "title": "...", "evidence": "...", "action": "..."}]
}
Step 5 — Update Cooldown
Read .claude/starter-context.json, merge optimizer.last_run = today_iso_date,
write back. Preserve all other fields.
Failure Modes
- Don't suggest hooks for tools not detected in logs
- Don't auto-apply any changes — every suggestion includes an action command, user runs manually
- Don't run analysis with <7 days data or <50 events — guard clause handles this
- Don't duplicate static analysis from
/review(hook binaries, MCP alignment, schema drift) - Don't crash on malformed log lines — skip silently
- Don't show LOW confidence suggestions unless
--verboseis set - Don't write cooldown timestamp if analysis was blocked by a guard clause
/review
Audit full harness health. Detect drift. Suggest next actions.
Flag Handling
--drift-only— skip component scoring (Step 1), run drift detection only (Step 2)--tier-check— skip drift detection (Step 2), show current tier and what is missing for the next tier upgrade
Step 1 — Score Components
Read and score each component:
starter-context.json → version current (1.4) ✅ / outdated ⚠️ / missing ❌
CLAUDE.md → populated ✅ / has-placeholder ⚠️ / missing ❌
CLAUDE.md workflow → present ✅ / opted-out ✅ / missing ⚠️
.claude/settings.json → configured ✅ / exists-empty ⚠️ / missing ❌
settings.json hooks → hooks configured ✅ / empty ⚠️ / missing ❌
.mcp.json → servers configured ✅ / exists-empty ⚠️ / missing ❌
.claude/agents/ → agents present ✅ / missing ❌
docs/architecture.md → exists ✅ / missing ❌
docs/adr/ → ADRs present ✅ / index-only ⚠️ / missing ❌
.claude/memory/ → lifecycle complete ✅ / legacy-layout ⚠️ / incomplete ⚠️ / missing ❌ (Tier 3)
✅ lifecycle: MEMORY.md + HANDOFF.md + decisions/ + conventions/ +
load-memory.sh & remind-save.sh hooks + .claude/skills/save-memory/
⚠️ legacy: project.md / team.md present (pre-2.4.0 static memory) → offer migration
⚠️ incomplete: .claude/memory/ exists but hooks or /save-memory missing
.claude/hooks/observe.py → present ✅ / missing (Tier 3 opt-in) ❌
.claude/logs/ in .gitignore → in gitignore ✅ / tracked by git ⚠️ / not applicable ✅
Schema version check:
Read .claude/starter-context.json:
→ not found → ❌ not initialized
→ version == "1.4" → ✅ current
→ version == "1.3" → ⚠️ outdated — run init --update (adds stack_plugins_selected field)
→ version == "1.2" → ⚠️ outdated — run init --update (adds skills_selected, stack_plugins_selected)
→ version < "1.2" or absent → ⚠️ outdated — run init --update
Workflow section check (smart opt-out):
starter-context.json exists:
→ workflow_gates absent → ⚠️ schema outdated — run init --update
→ workflow_gates == ["none"] or [] → ✅ explicitly opted out
→ workflow_gates has values → check CLAUDE.md has "Development workflow" section
present → ✅
missing → ⚠️ context set but CLAUDE.md not updated
starter-context.json not found:
→ check CLAUDE.md for "## Development workflow" section
present → ✅
missing → ⚠️ no workflow section found
Detect current tier from the Harness config section of CLAUDE.md.
If CLAUDE.md is missing: treat as Tier 0 (not configured).
If CLAUDE.md exists but tier is not specified: infer from what is present.
Step 2 — Detect Drift
CLAUDE.md tech stack ←→ package.json / pyproject.toml / go.mod
New dependency not mentioned in CLAUDE.md? → flag ⚠️ undocumented
Dependency removed but still listed in CLAUDE.md? → flag ⚠️ stale
Hooks in settings.json ←→ tools present in project
Hook references a tool no longer in devDependencies or PATH? → flag ⚠️ stale
.mcp.json servers ←→ services referenced in codebase (imports, env vars)
Service used in code but no MCP server configured? → flag ⚠️ missing
docs/architecture.md last modified ←→ git log
File not updated in 30+ days AND new directories added since? → flag ⚠️ outdated
docs/adr/ ←→ git log
Commits in past 30 days added/removed directories, changed framework,
or modified core config (package.json, pyproject.toml)?
AND no new ADR written? → flag ⚠️ decision not recorded
workflow_gates ←→ architecture.sensitive_areas
sensitive_areas present in starter-context.json
AND "security-review" not in workflow_gates?
→ flag ⚠️ "Sensitive areas detected but no security-review gate configured"
Step 2b — Static Analysis
Run for ALL tiers. No runtime logs required.
Hook binary check
For each hook command in .claude/settings.json:
- Extract effective binary:
npx <pkg>→ check<pkg>;python3 <script>→ checkpython3; otherwise check first token - Binary in
devDependencies/dependencies(package.json) ORwhich <binary>returns a path → ✅ - Neither found → flag ⚠️
Hook [hook-id] references [binary] but it's not installed
Hook pattern match check
For hook commands that filter by file extension (e.g. case "$CLAUDE_TOOL_INPUT_PATH" in *.ts|*.tsx):
- Extract file extensions from the command (patterns after
*.) find . -name "*.<ext>" -not -path "*/node_modules/*"returns results → ✅- No matching files in project → flag ⚠️
Hook [hook-id] matches [pattern] but no matching files found
MCP usage vs codebase
Compare .mcp.json servers vs actual imports/usage in source files. Check both directions:
| MCP server | Detect usage by looking for |
|---|---|
| github | @octokit/*, octokit (JS imports), gh CLI calls |
| linear | @linear/sdk import |
| slack | @slack/bolt, @slack/web-api import |
| sentry | @sentry/* import, sentry-sdk (Python) |
| postgres | pg, postgres (JS), psycopg2, sqlalchemy (Python) |
| notion | @notionhq/client import |
| jira | jira-client (JS), jira (Python) |
Configured but no usage found:
→ flag ⚠️ MCP [name] configured but no related usage found — consider removing
Usage found but no MCP configured:
→ flag ⚠️ Code imports [package] but no [service] MCP configured — consider adding
Project skills staleness
For each .claude/skills/<id>/SKILL.md that has a template_version in frontmatter:
- Compare against the matching entry's
versionin this plugin'ssetup-skills/skills-catalog.json template_version< catalogversion(compare as semver — numeric components, not lexically) → flag ⚠️[id] skill is v[X]; current template is v[Y] — re-run /shipwithai-starter:setup-skills to refresh- Skills without a
template_version(hand-written) → skip, do not flag
Stack plugin coverage
Read ../init/stack-recipes.json. Determine the project stack (from
starter-context.json.stack, else detect like init Step 1: pom.xml/build.gradle → Java).
For each recipe whose detect matches (a files entry exists AND, if content is set,
one of those strings appears in it):
verifyArtifact file exists (e.g. .claude/hooks/jpa-guardrail.py) → ✅ wired
artifact absent BUT stack_plugins_selected lists recommendPlugin → ⚠️ selected but not installed —
re-run [setupCommand]
artifact absent AND not selected → ⚠️ [label] detected —
[recommendPlugin] available but not set up
no recipe matches the stack → not applicable (no row)
Recommend only; do not claim the plugin is installed when its verifyArtifact is absent.
If the plugin is not enabled in the marketplace, note that the user must enable
[marketplace] first.
Step 3 — Health Report
## Harness Health — [project name]
Current tier: [Essential / Standard / Full]
Checked: YYYY-MM-DD
| Component | Status | Issue |
|----------------------|--------|--------------------------------------------|
| Schema version | ⚠️ | v1.0 → v1.1 available (workflow_gates) |
| CLAUDE.md | ✅ | — |
| CLAUDE.md workflow | ⚠️ | Schema outdated — run init --update |
| settings.json | ✅ | — |
| Hooks | ⚠️ | prettier hook but prettier not in project |
| .mcp.json | ❌ | Redis used in code, no MCP server |
| docs/architecture.md | ⚠️ | Not updated in 45 days |
| ADRs | ✅ | 3 ADRs present |
| .claude/memory/ | ⚠️ | Legacy project.md/team.md — migrate to lifecycle |
| Observability | ❌ | observe.py not installed (Tier 3 opt-in) |
| Hook binaries | ⚠️ | jest-on-stop: jest not in devDeps or PATH |
| Hook patterns | ✅ | — |
| MCP alignment | ⚠️ | GitHub MCP configured, no octokit imports |
| Project skills | ✅ | — |
| Stack plugin | ⚠️ | Spring Boot — java-backend-toolkit not set up |
Drift detected: [list of flagged items, or "None"]
Static analysis: [list of flagged items, or "None"]
Step 4 — Suggest Actions
Prioritize by severity: ❌ first, then ⚠️. Suggest one action at a time:
"Want to fix [highest priority issue] now?"
If user accepts: invoke the relevant skill directly:
- Schema outdated →
/shipwithai-starter:init --update("Plugin has new questions (v1.1). Run init --update to answer only new questions — existing answers are preserved.") - Workflow missing (schema current) →
/shipwithai-starter:init --update - Hooks issue →
/shipwithai-starter:setup-hooks - MCP issue →
/shipwithai-starter:setup-mcp - Agents issue →
/shipwithai-starter:setup-agents - SSOT/docs issue →
/shipwithai-starter:update-ssot - Observability missing (Tier 3) →
/shipwithai-starter:setup-observability - Memory legacy/incomplete/missing (Tier 3) →
/shipwithai-starter:setup-memory --memory-only(migrates legacyproject.md/team.mdwithout deleting them; adds missing hooks +/save-memory) - Stale project skill (template_version behind catalog) →
/shipwithai-starter:setup-skills - Stack plugin available but not set up → run the recipe's
setupCommand(e.g./shipwithai-java-backend-toolkit:setup); if not enabled, enable the recipe's marketplace first - Logs tracked by git → warn: run
git rm -r --cached .claude/logs/and add to .gitignore
Tier upgrade path:
- Tier 1 → list Standard tier items not yet configured
- Tier 2 → list Full tier items not yet configured
- To upgrade: run
/shipwithai-starter:init
If .claude/logs/ exists and contains log files spanning ≥7 calendar days:
For runtime-based suggestions (usage patterns, hook coverage):
/shipwithai-starter:optimize-harness
/setup-agents
Configures .claude/agents/ with specialized sub-agents for the project.
Mode Detection
Read .claude/starter-context.json if it exists
→ Exists: use fields agents_selected, project.type, project.team_size, project.tier — skip suggest
→ Does not exist (standalone): load catalog → detect context → suggest → confirm
Argument Handling
If an agent name is passed directly (e.g. /setup-agents pr-review): skip the suggestion
step and go straight to that agent's entry in the catalog.
Context Detection
Load agents-catalog.json. For each entry, evaluate suggestWhen:
- files: check whether any listed glob exists in the project root
- context: if
.claude/starter-context.jsonexists, evaluate conditions against its fieldsteamSize > N→ readproject.team_sizetier == N→ readproject.tier
- always: if
alwaysIncludeistrue, suggest unconditionally — present first
In standalone mode without starter-context.json: ask the user for context that cannot
be inferred from files (e.g. "How many people work on this project?").
For each suggested agent: show preview → confirm before writing.
How Sub-Agent Context Works
Sub-agents receive only two inputs when invoked:
- Their agent file content (system prompt)
- The prompt string passed by the main agent at invocation time
They do not inherit the main agent's conversation history or open files.
Two patterns handle this:
Autonomous agents — self-orient by reading project files on startup. No runtime input needed beyond a trigger phrase. Examples: drift-monitor, dependency-scanner, test-coverage.
Task-specific agents — require runtime context passed in the invocation prompt. The caller must include specific parameters (e.g. PR number, branch name). Examples: pr-review.
Use contextType in the catalog to identify which pattern each agent follows.
Agent File Format
Write to .claude/agents/[id].md using this structure:
---
name: [id]
description: >
[One sentence: what this agent does and when to invoke it.
Include trigger phrases, e.g. "check drift", "run health check".]
model: [sonnet|haiku]
tools: ["Read", "Bash", "Glob", "Grep"]
---
# [Agent Name]
## Purpose
[Why this agent exists. What problem it solves.]
## Context
**Reads on startup:**
- `CLAUDE.md` — project conventions and standards
- `[other files this agent always reads to orient itself]`
**Expects in prompt:** *(omit this block for autonomous agents)*
- `[PARAM_NAME]`: [what it is and how to pass it]
## Steps
### Step 1 — [Action]
[Description]
### Step 2 — [Action]
[Description]
## Boundaries
- Does not modify files directly
- Does not self-schedule
- [Other explicit limits for this agent]
Model selection:
haiku: read-only checks, simple scans, lightweight file inspectionsonnet: analysis requiring judgment, code review, multi-step reasoning
Tools selection: include only what the agent needs.
- Read/Glob/Grep — file inspection
- Bash — running commands or scripts
Write Rules
- Create
.claude/agents/directory if it does not exist - Write one file per agent:
.claude/agents/[id].md - Before writing: check if the file already exists — offer skip or overwrite, do not silently replace
- For autonomous agents: populate
Reads on startupfromselfDiscoversin the catalog - For task-specific agents: populate
Expects in promptfromexpectsin the catalog
Post-Write
If .claude/starter-context.json exists:
→ Update the agents_selected field with the list of agent id values that were written
/setup-hooks
Configures .claude/settings.json → hooks section.
Mode Detection
Read .claude/starter-context.json if it exists
→ Exists: use fields stack.detected_tools, hooks_selected — skip detect + confirm
→ Does not exist (standalone): detect tools → suggest from catalog → confirm
Argument Handling
If flags are provided, skip auto-detection and only suggest hooks for the specified tools:
--formatter <name>: only suggest hook for that formatter (e.g.--formatter black)--test <name>: only suggest hook for that test runner (e.g.--test pytest)
Flags can be combined: /setup-hooks --formatter prettier --test jest
Tool Detection
Load hooks-catalog.json. For each entry, detect presence in order:
- files: check whether any listed filename/glob exists in the project root
- packageJson: read
package.json, check key underdevDependenciesordependencies - binary: run
which <binary>— pass if exit code is 0
Only suggest a hook if the tool passes at least one of the three checks.
If no tools are detected: inform the user, suggest using flags to specify tools manually.
Suggest & Confirm
Suggest hooks one at a time. Show a preview before confirming:
PostToolUse hook:
"This hook will run
prettier --write $FILEevery time Claude uses the Edit tool on.js|ts|jsx|tsx|css|mdfiles. Enable it?"
Stop hook:
"This hook will run
npm testevery time Claude finishes a session. Enable it?"
If the user declines: record as skipped, continue to the next hook.
After all hooks are processed, show a summary:
"Enabled: prettier-on-edit, eslint-fix-on-edit. Skipped: jest-on-stop."
Output Format
If .claude/settings.json does not exist: create it with { "hooks": {} }.
Merge into .claude/settings.json — do not overwrite the permissions section:
{
"permissions": { "...existing..." },
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "case \"$CLAUDE_TOOL_INPUT_PATH\" in *.js|*.ts|*.jsx|*.tsx|*.css|*.md) npx prettier --write \"$CLAUDE_TOOL_INPUT_PATH\";; esac"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "npm test"
}
]
}
]
}
}
Write Rules
- If
settings.jsondoes not exist: create it with{ "hooks": {} } - Merge hooks into
settings.json— do not overwrite the entire file - Before writing: check
hook.idagainst existing hooks — skip if the id already exists (prevent duplicates) - Do not write a hook for a tool that was not detected (unless specified via flags)
- Confirm one hook at a time — do not batch-confirm all at once
Post-Write
If .claude/starter-context.json exists:
→ Update the hooks_selected field with the list of hook.id values the user confirmed
/setup-mcp
Configures .mcp.json with MCP servers for external services.
Mode Detection
Read .claude/starter-context.json if it exists
→ Exists: use field mcp_selected — skip asking, go straight to lookup + write
→ Does not exist (standalone): ask "Which external services does your project use?"
Argument Handling
If a service name is passed directly (e.g. /setup-mcp github): skip the service selection
prompt and go straight to lookup for that service.
Service Lookup
Load mcp-registry.json and show the available services:
GitHub → code search, PR management, issues
Linear → issue tracking, sprint planning
Slack → search messages, read channels
Sentry → error tracking, performance data
PostgreSQL → direct DB queries, schema inspection
Google Drive → search and read documents
Notion → read and search pages and databases
Jira → issue tracking, sprint management
For each selected service:
- Look up config in the registry.
- If
authRequiredis true: show auth requirement before writing:"This server requires [authNote]. Do you have credentials ready?" If no: offer to skip and add later.
- If service type is
stdio: ask for required runtime values (e.g. connection string) before writing — never write placeholder values literally. - Show config preview (see Output Format below).
- Attempt test connection after writing (see Verification below).
- Confirm before writing.
If the requested service is not in the registry: do not fabricate a config. Ask the user to paste an MCP URL if they have one, or skip for now.
Output Format
If .mcp.json does not exist: create it with { "mcpServers": {} }.
HTTP server:
{
"mcpServers": {
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"type": "http",
"description": "Search code, manage PRs and issues"
}
}
}
stdio server (e.g. PostgreSQL — ask user for connection string first):
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres", "postgresql://user:pass@host/db"],
"description": "Direct database queries and schema inspection"
}
}
}
Write Rules
- If
.mcp.jsondoes not exist: create it with{ "mcpServers": {} } - If
.mcp.jsonexists: read it, check if serveridalready inmcpServers— skip if duplicate - Never overwrite an existing server entry without asking the user first
- Never write placeholder values (e.g.
<connection-string>) — always resolve real values first
Verification
MCP servers load at Claude Code startup. Writing .mcp.json takes effect in the next session.
After writing, report status:
- ✓ tested — a tool call to this MCP server actually succeeded in the current session
- ⚪ configured, not verified — config written but connection not testable until next session
- ✗ not found — server unreachable; show auth/setup guidance
Never report ✓ based on .mcp.json declarations alone.
Post-Write
If .claude/starter-context.json exists:
→ Update the mcp_selected field with the list of server id values that were written
/setup-memory
Configures the Memory pillar: CLAUDE.md (project context, all tiers) and a self-sustaining
.claude/memory/ lifecycle — store + hooks + /save-memory skill (Tier 3 only).
Flags
Check flags first — they override Mode Detection behavior:
--claude-md-only— write CLAUDE.md only, skip.claude/memory/entirely--memory-only— create.claude/memory/only, skip CLAUDE.md entirely
Mode Detection
Read .claude/starter-context.json if it exists
→ Exists:
- Load all fields
- For each required field that is null or missing → ask for that field only
- Use tier field to determine whether to create .claude/memory/ (Tier 3 = full / standard ≠ Tier 3)
→ Not found (standalone):
- Read existing CLAUDE.md if present (extract what's already there)
- Ask for any missing fields
- Ask: "Should I also set up .claude/memory/? (Tier 3 feature)"
Required fields from starter-context.json:
tier, project.name, project.type, project.team_size, project.stage,
stack.language, stack.framework, stack.build_tool, stack.test_framework, stack.package_manager,
architecture.style, architecture.key_layers, architecture.entry_points, architecture.external_deps,
architecture.gotchas, conventions.formatter, conventions.branch_strategy, conventions.commit_format,
conventions.workflow_gates (optional — absent means no workflow section generated)
CLAUDE.md Structure
Write with actual values — no generic text, no leftover placeholders:
# [Project Name] — Claude Context
*Generated by /shipwithai-starter on [DATE].
Edit directly — every skill reads this before doing anything.*
---
## Project identity
**Name:** [name]
**Type:** [web app / API / CLI / lib / monorepo]
**Team size:** [N developers]
**Stage:** [greenfield / active / maintenance]
---
## Tech stack
**Language(s):** [...]
**Framework(s):** [...]
**Build tool:** [...]
**Test framework:** [...]
**Package manager:** [...]
**Runtime:** [Node 20 / Python 3.12 / Go 1.22 / etc.]
---
## Architecture overview
**Style:** [monolith / microservices / modular monolith]
[Only include the following block when project.stage is "greenfield":]
**Status:** Greenfield — build toward this structure
**Build order:**
[Derive from architecture.build_order if present in starter-context.json.
Otherwise generate a sensible 3-step order based on the stack and architecture:
- Step 1: foundation first (e.g., db/schema.ts → run initial migration)
- Step 2: authentication (e.g., features/auth/ — auth before any business domain)
- Step 3: core domain (e.g., features/<core-domain>/)]
[End greenfield block — omit entirely for non-greenfield projects]
**Key layers:**
- [e.g., API layer: src/routes/]
- [e.g., Service layer: src/services/]
- [e.g., Data layer: src/db/]
**Entry points:**
- [e.g., src/index.ts → main server]
**Key directories:**
[paste tree output or describe structure]
**External dependencies:**
- [databases, queues, caches, external APIs]
---
## Key conventions
**Code style:** [ESLint + Prettier / Black / gofmt / etc.]
**Branch strategy:** [trunk-based / gitflow]
**Commit format:** [conventional / custom / none]
**Test coverage target:** [e.g., 80%]
---
## What Claude should know before touching code
**Gotchas:**
- [e.g., "src/generated/ is auto-generated, never edit manually"]
- [e.g., "migrations/ only via npm run migrate:create"]
**Build order:**
- [e.g., "codegen must run before tsc"]
**Test isolation:**
- [e.g., "integration tests require Docker Compose up"]
**Sensitive areas (extra care):**
- [e.g., "auth/ and payments/ require security review before merge"]
---
## Development workflow
[Only include this section if conventions.workflow_gates is present and not ["none"] or []]
**When working on any task, Claude must follow these gates:**
[Generate one bullet per gate selected:]
- plan-before-code → **Plan first:** For any task > 30 min, create a plan and get approval before writing code.
- tdd → **TDD:** Write failing tests first. Never write implementation without a corresponding test.
- code-review → **Code review:** Run the code-reviewer agent after every significant change. Address all CRITICAL and HIGH findings.
- security-review + sensitive_areas present → **Security review:** Before committing to [list from architecture.sensitive_areas], run security-reviewer agent.
- security-review + sensitive_areas empty → **Security review:** Before committing to sensitive areas (auth, payments, migrations), run security-reviewer agent.
[If workflow_gates is ["none"] or [] → omit this section entirely]
---
## Harness config
**Tier:** [Essential / Standard / Full]
**Last updated:** [DATE]
Hooks: see `.claude/settings.json`
MCP servers: see `.mcp.json`
.claude/memory/ — lifecycle memory (Tier 3 only)
A self-sustaining cross-session memory that lives in the repo: load on session start →
work → nudge to save on stop → distill → handoff to the next session. Plain markdown, version-
controlled. Set up three things: the store, the hooks, and the /save-memory skill.
Token replacements for every template below:
{{PROJECT_NAME}}→project.name;{{DATE}}→ today;{{TEMPLATE_VERSION}}→ this plugin's version (fromplugin.json).
A. The store
Create this structure (directories + seed files from assets/memory/):
.claude/memory/
README.md ← from assets/memory/README.md.tmpl (how the system works)
MEMORY.md ← from assets/memory/MEMORY.md.tmpl (index, loaded every session)
HANDOFF.md ← from assets/memory/HANDOFF.md.tmpl (ephemeral WIP, overwritten each save)
decisions/ ← empty dir + .gitkeep (durable, append-only ADR-lite)
conventions/ ← empty dir + .gitkeep (durable conventions + gotchas)
sessions/ ← empty dir + .gitkeep (append per-day summaries)
Copy each .tmpl to its destination (drop the .tmpl suffix) and substitute tokens. Create
the three subdirectories, each with an empty .gitkeep so git tracks them.
Memory layers (durable vs ephemeral) — the user does not hand-maintain these; the
/save-memory skill writes them:
| Path | Lifetime | Holds |
|---|---|---|
MEMORY.md | updated continuously | one-line index of every memory |
decisions/NNNN-slug.md | durable, append-only | a decision + its rationale |
conventions/slug.md | durable | a convention or gotcha |
HANDOFF.md | ephemeral, overwritten | current WIP + "Context to Load" for next session |
sessions/YYYY-MM-DD.md | append per day | a short session summary |
B. The hooks (this skill installs them — Decision: setup-memory owns memory hooks)
Copy the two scripts from assets/hooks/ into the project's .claude/hooks/ (create the dir if
needed), then merge their registration into .claude/settings.json. Merge additively — never
overwrite an existing hooks object (e.g. formatter/lint hooks from /setup-hooks).
load-memory.sh→ SessionStart: injectsMEMORY.md+HANDOFF.md, tells Claude to read only the files under "Context to Load" (lazy load).remind-save.sh→ Stop: nudges/save-memoryonce per session, only on real work, loop- guarded. On by default at Tier 3 (opt-out = remove this Stop entry; see the seeded README).
Registration to merge into .claude/settings.json (paths use $CLAUDE_PROJECT_DIR):
{
"hooks": {
"SessionStart": [
{ "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/load-memory.sh\"" } ] }
],
"Stop": [
{ "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/remind-save.sh\"" } ] }
]
}
}
If a
Stoparray already exists (e.g. a test-on-stop hook), append this entry to it rather than replacing the array.
C. The /save-memory skill (installed into the user project)
Install assets/skills/save-memory.SKILL.md.tmpl to .claude/skills/save-memory/SKILL.md:
- Substitute
{{PROJECT_NAME}}and{{TEMPLATE_VERSION}}. - Collision-safe: if
.claude/skills/save-memory/SKILL.mdalready exists, do NOT overwrite — report it and skip. (template_versionin the frontmatter letsreviewdetect staleness later.) - It is a project asset — do NOT add it to this plugin's
manifest.json.
This skill is what distills each session into the store above. Without it, the Stop nudge has nothing to call.
Write Rules
- Check flags first (
--claude-md-only,--memory-only) before anything else - Check if file exists before writing → Overwrite / Merge / Skip?
- Merge strategy for CLAUDE.md:
- Known sections (update with new values): Project identity, Tech stack, Architecture overview, Key conventions, Development workflow, What Claude should know, Harness config
- Unknown sections (preserve as-is): anything else the user added
- Always update "Last updated" date on every write, including merges
.claude/memory/already exists:- Legacy layout (
project.md/team.mdpresent — the pre-2.4.0 static memory): do NOT delete. Offer to migrate: keep the old files, add the new structure (decisions/ conventions/ sessions/ HANDOFF.md README.md) + hooks +/save-memory, and fold any real facts fromproject.mdinto adecisions//conventions/entry. The user may also choose Skip. - New layout already present: Ask — Overwrite seeds / Add missing only / Skip.
"Add missing only" creates any file/dir not already present, leaves existing untouched.
Never overwrite
MEMORY.md,HANDOFF.md,decisions/,conventions/, orsessions/if they already contain real entries.
- Legacy layout (
- Hooks merge (settings.json): additive only — append SessionStart/Stop entries; never
clobber existing hooks (e.g.
/setup-hooksformatter/lint/test). Skip an entry whose command is already registered. /save-memoryskill: collision-safe — never overwrite an existing.claude/skills/save-memory/SKILL.md. Do not add it to the plugin manifest (project asset).- Use actual values — no generic text
- No leftover [PLACEHOLDER] or
{{TOKEN}}after writing
/setup-observability
Installs a lightweight logging hook that records tool call metadata. Logs feed future harness analysis tooling (coming in a later phase).
What gets logged
Only metadata — never content:
| Tool | Logged | NOT logged |
|---|---|---|
| Edit | Relative file path | File content, old/new string |
| Write | Relative file path | File content |
| Bash | Command name (argv[0] only) | Arguments, output, exit code |
One line per call: .claude/logs/YYYY-MM-DD.jsonl
Opt-out anytime: export DISABLE_OBSERVE=1 in terminal or shell profile.
Mode Detection
--disable flag → reverse setup (see --disable Flow below)
No args → run setup flow
Setup Steps
- Copy
observe.pyfrom plugin assets to.claude/hooks/observe.py - Merge PostToolUse hook into
.claude/settings.json— matcherEdit|Write|Bash - Merge Stop hook (log rotation) into
.claude/settings.json - Add
.claude/logs/to.gitignore(skip if already present) - Check
git ls-files .claude/logs— warn user if currently tracked - Update
starter-context.json→observability.enabled: true
Output Format
Preview before writing:
Observability setup:
.claude/hooks/observe.py CREATE
.claude/settings.json (hook) UPDATE — add PostToolUse + Stop entries
.gitignore UPDATE — add .claude/logs/
Logs will be written to: .claude/logs/YYYY-MM-DD.jsonl
Opt-out: export DISABLE_OBSERVE=1
Proceed?
After writing:
✅ Observability enabled.
Logs: .claude/logs/ (excluded from git)
Disable anytime: export DISABLE_OBSERVE=1
Logs will feed harness analysis tooling (coming in a future phase).
settings.json Hook Entries
PostToolUse entry to add:
{
"matcher": "Edit|Write|Bash",
"hooks": [{"type": "command", "command": "python3 .claude/hooks/observe.py"}]
}
Stop entry to add:
{
"hooks": [{"type": "command", "command": "find .claude/logs -name '*.jsonl' -mtime +30 -delete 2>/dev/null || true"}]
}
Write Rules
- Read
settings.jsonbefore writing — merge into existing structure, never overwrite - Check
hooks.PostToolUsefor matcherEdit|Write|Bash— skip if already present (idempotent) - Check
hooks.Stopfor rotation command — skip if already present (idempotent) - Check
.gitignorefor.claude/logs/— skip line if already present - Never proceed without user confirmation of the preview
--disable Flow
- Remove PostToolUse hook entry with matcher
Edit|Write|Bashfromsettings.json - Remove Stop hook rotation entry from
settings.json - Delete
.claude/hooks/observe.py - Update
starter-context.json→observability.enabled: false - Report: "Observability disabled. Existing logs at
.claude/logs/preserved — delete manually if not needed."
/setup-permissions
Configures .claude/settings.json → permissions.allow and permissions.deny.
Flags
Check flags first — they override Mode Detection behavior:
--stack <name>— skip auto-detection, use the provided stack preset directly--preset-only— apply the matched preset without asking customization questions
Mode Detection
If --stack flag is provided → skip detection, use that stack value directly
Otherwise:
Read .claude/starter-context.json if it exists
→ Exists:
- Use fields: stack, permissions.preset, permissions.disallowed_tools, permissions.readonly_paths
- For each field that is null or missing → ask for that field only
→ Not found (standalone):
- Auto-detect stack from project files
- If detection fails → default to "general" preset, inform user:
"Could not detect stack — using the general (read-only) preset. Pass --stack to override."
- Show preset → confirm or customize (unless --preset-only is set)
Load Preset
Read settings-presets.json, match by stack:
nodejs → allow: Read, Write, Edit, Grep, Glob, Bash(npm:*), Bash(npx:*), Bash(node:*), Bash(git:*)
python → allow: Read, Write, Edit, Grep, Glob, Bash(python:*), Bash(pip:*), Bash(pytest:*), Bash(git:*)
golang → allow: Read, Write, Edit, Grep, Glob, Bash(go:*), Bash(git:*)
java → allow: Read, Write, Edit, Grep, Glob, Bash(mvn:*), Bash(gradle:*), Bash(java:*), Bash(git:*)
rust → allow: Read, Write, Edit, Grep, Glob, Bash(cargo:*), Bash(git:*)
general → allow: Read, Grep, Glob (Write/Edit/Bash not allowed until user explicitly adds them)
Show the preset with a one-line explanation per rule. Then ask:
- "Any tools Claude should NOT use?" → add to
deny - "Any paths that should be read-only?" → add path-scoped deny rules (see Output Format)
Skip both questions if --preset-only is set.
Multi-stack projects (e.g., Node frontend + Python backend): apply the union of both presets. Ask: "I detected both Node and Python — should I allow tools for both stacks?"
Output Format
{
"permissions": {
"allow": [
"Read",
"Write",
"Edit",
"Grep",
"Glob",
"Bash(npm:*)",
"Bash(npx:*)",
"Bash(node:*)",
"Bash(git:*)"
],
"deny": [
"Write(src/generated/*)",
"Edit(src/generated/*)"
]
}
}
Readonly paths map to deny rules scoped to that path:
src/generated/read-only →deny: ["Write(src/generated/*)", "Edit(src/generated/*)"]migrations/read-only →deny: ["Write(migrations/*)", "Edit(migrations/*)"]
Write Rules
- Check
.claude/settings.jsonexists before writing → Overwrite / Merge / Skip? - Merge: update
permissionssection only, never touchhookssection if already present - Do not set permissions so restrictive that the team cannot do normal work
/setup-skills
Provisions reusable skills into .claude/skills/<id>/SKILL.md for the project.
Sibling of setup-agents — same install model, different artifact type.
Mode Detection
Read .claude/starter-context.json if it exists
→ Exists: use skills_selected + conventions + project.name — skip suggestion step
→ Does not exist (standalone): load catalog → detect context → suggest → confirm
Argument Handling
If a skill id is passed directly (e.g. /setup-skills git-workflow): skip the
suggestion step and go straight to that catalog entry.
Step 1 — Context Detection
Context mode (starter-context.json present): install exactly the ids listed
in skills_selected — skip the suggestion logic below. If skills_selected is
absent or empty, the user declined skills at init; do not re-suggest. The
suggestWhen / alwaysInclude evaluation applies to standalone mode only.
Load skills-catalog.json. For each entry, evaluate suggestWhen:
- files: check whether any listed glob exists in the project root
- context: if
starter-context.jsonexists, evaluate conditions against its fields - alwaysInclude: if
true, suggest unconditionally — present first
git-workflow is alwaysInclude: true — every project has git.
For each suggested skill: show preview (with resolved variants from Step 2) → confirm before writing.
Step 2 — Resolve Conventions
The template adapts to the conventions chosen at init. Resolve these values:
| Token | Source | Fallback |
|---|---|---|
COMMIT_BLOCK | conventions.commit_format (conventional/none/custom) | conventional |
BRANCH_BLOCK | conventions.branch_strategy (gitflow/trunk-based) | trunk-based |
PROTECTED_BRANCHES | derived from branch_strategy | from trunk-based |
PROJECT_NAME | project.name | "this project" |
TEMPLATE_VERSION | catalog entry version | (always present) |
Standalone mode (no starter-context.json): ask only the two convention
questions before injecting — same wording as init Part 3:
- "Branch strategy (trunk-based / gitflow)?"
- "Commit format (conventional / custom / none)?"
Never invent a convention silently — if unknown, ask or use the documented fallback.
Step 3 — Inject
For each skill to install:
1. Read template: <template> from catalog entry (e.g. templates/git-workflow.SKILL.md.tmpl)
2. Read variants: <variants> from catalog entry (e.g. templates/git-workflow.variants.json)
3. Pick blocks:
COMMIT_BLOCK = variants.commit[commit_format] (fallback: commit.conventional)
BRANCH_BLOCK = variants.branch[branch_strategy] (fallback: branch.trunk-based)
PROTECTED_BRANCHES = variants.protected_branches[branch_strategy] (fallback: trunk-based)
4. Substitute every {{TOKEN}} in the template. PROJECT_NAME and TEMPLATE_VERSION
come from Step 2, not the variants file. Treat PROJECT_NAME as a literal
single-line string: strip newlines and any YAML control characters
(`:`, leading `-`, `#`) that could break frontmatter; if it is empty or
unsafe, fall back to "this project".
5. Validate: no {{...}} tokens remain AND the frontmatter still parses as valid YAML.
Step 4 — Write Rules
- Create
.claude/skills/<id>/if it does not exist. - Collision: if
.claude/skills/<id>/SKILL.mdalready exists → do NOT replace silently. Show that it exists and offer Skip or Overwrite. - Write the injected content to
.claude/skills/<id>/SKILL.md. - The written frontmatter carries
template_version— this enablesreviewto detect staleness when the plugin template is later updated.
Step 5 — Post-Write
- If
starter-context.jsonexists → updateskills_selectedwith installed ids. - Print: "Installed
<id>. It loads when you say: [triggers from catalog]." - Remind: "Commit
.claude/skills/so teammates get this skill without the plugin."
Failure Modes
Don't install a git tutorial — git-workflow is project rules only
Don't overwrite an existing skill dir without asking (Skip / Overwrite)
Don't inject conventions you didn't read or confirm — ask in standalone mode
Don't leave any {{TOKEN}} unsubstituted in the written file
Don't widen triggers to bare "git" — keep the catalog's scoped triggers
Don't add the installed skill to the plugin's own manifest.json — it is a project asset
/setup-ssot
Configures SSOT documentation: docs/architecture.md, docs/adr/, docs/CODEMAPS/.
Mode Detection
Read .claude/starter-context.json if it exists:
- Exists: use
architecture,ssot.adr,ssot.codemapsfields — skip questions - Missing (standalone): ask which outputs to create, then gather architecture details
Flags
--architecture-only— writedocs/architecture.mdonly, skip ADR and CODEMAPS--adr— include ADR structure--codemaps— include CODEMAPS structure- Flags can be combined:
--adr --codemaps
Standalone Questions (when no context file)
Ask once, grouped:
Which outputs to create?
-
docs/architecture.md— architecture overview -
docs/adr/— ADR structure with ADR-0001 -
docs/CODEMAPS/— codebase navigation guide
For each selected output, gather:
- Project name and type (web app / API / CLI / lib)?
- Primary stack (language + framework)?
- Architecture style (monolith / microservices / modular monolith / event-driven)?
- Key layers and their directories?
- Entry points?
- External dependencies (DB, queue, cache, external APIs)?
- Directories/files that must NOT be edited manually?
- Sensitive areas requiring extra care?
Output 1: docs/architecture.md
Draft from starter-context.json.architecture (or standalone answers). Use actual paths, not generic placeholders:
# Architecture Overview
*Generated by /shipwithai-starter on [DATE]. Edit directly.*
## System overview
[Project name] is a [type] built with [stack].
Architecture style: [monolith / microservices / modular monolith / event-driven].
## Key layers
| Layer | Directory | Responsibility |
|-------|-----------|----------------|
| [API] | [src/routes/] | [HTTP handlers, validation] |
| [Service] | [src/services/] | [Business logic] |
| [Data] | [src/db/] | [Database access, ORM] |
## Entry points
- `[src/index.ts]` → [main server, port 3000]
- `[src/worker.ts]` → [background job processor]
## External dependencies
| Service | Purpose | Connection |
|---------|---------|------------|
| [PostgreSQL] | [Primary database] | [DATABASE_URL] |
| [Redis] | [Session cache] | [REDIS_URL] |
## Key directories
[paste tree output or scan result]
## What to know before touching code
[Gotchas: generated dirs, build order, sensitive areas]
Existing file behavior
If docs/architecture.md already exists, ask: Overwrite / Merge / Skip?
- Overwrite: replace entirely with new draft
- Merge: append new sections that don't exist, keep existing content unchanged
- Skip: leave untouched
Output 2: ADR Structure
docs/adr/
README.md ← index + how to create new ADRs
ADR-0001-initial-architecture.md
docs/adr/README.md template:
# Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for [Project name].
## What is an ADR?
An ADR documents a significant architectural decision: the context, the options
considered, and the rationale behind the choice.
## How to create a new ADR
1. Copy `adr-template.md` (ask Claude: "create a new ADR for [topic]")
2. Name it `ADR-XXXX-short-title.md` (increment the number)
3. Fill in all sections — do not leave placeholders
4. Update the index table below
## Index
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [ADR-0001](ADR-0001-initial-architecture.md) | Initial Architecture | Accepted | [DATE] |
ADR-0001 is drafted from architecture answers using the format in adr-template.md.
Output 3: docs/CODEMAPS/
docs/CODEMAPS/
README.md ← how to use CODEMAPS
overview.md ← high-level codebase map
docs/CODEMAPS/README.md template:
# CODEMAPS
Navigation guides for this codebase. Read the relevant map before touching code
in a new area.
## How to use
Before working in an unfamiliar part of this codebase:
1. Find the relevant map in this directory
2. Read the entry points, data flows, and gotchas
3. Update the map when you make significant structural changes
## Maps
| File | Covers |
|------|--------|
| [overview.md](overview.md) | Full codebase — start here |
docs/CODEMAPS/overview.md template:
# Codebase Overview
*Generated by /shipwithai-starter on [DATE]. Update when structure changes.*
## Entry points
| File | Purpose |
|------|---------|
| [src/index.ts] | [Main server — starts HTTP on port 3000] |
## Key directories
| Directory | Purpose |
|-----------|---------|
| [src/routes/] | [API route handlers] |
| [src/services/] | [Business logic] |
| [src/db/] | [Database access] |
## Data flow
[Request] → [src/routes/] → [src/services/] → [src/db/] → [Response]
## What NOT to edit manually
- [src/generated/] — auto-generated, overwritten on build
## Sensitive areas
- [auth/] — changes require security review
- [payments/] — changes require payment team sign-off
Write Rules
- Use actual directory paths from codebase scan — no generic placeholder text
- Check each output separately: user may select only
architecture.mdand skip ADR - Never silently overwrite existing files — always ask Overwrite / Merge / Skip
- If a selected output directory already exists with content, treat as existing and ask
/update-ssot
Sync SSOT docs with the actual codebase. Section by section, confirm each change.
Flag Handling
--section stack— diff and update tech stack section only--section architecture— diff and update architecture/directories sections only--section conventions— diff and update coding conventions section only--section hooks— diff.claude/settings.jsonhooks vs CLAUDE.md only--section mcp— diff.mcp.jsonvs CLAUDE.md only--section all— default: diff everything- Flags can be combined:
--section stack --section mcp
Pre-flight Check
Before diffing, check which SSOT files exist:
CLAUDE.mdnot found → inform user, suggest running/shipwithai-starter:setup-ssotfirst, offer to continue anywaydocs/architecture.mdfound → include in diff scopedocs/CODEMAPS/overview.mdfound → include directories in diff scope
Step 1 — Diff SSOT vs Codebase
Run only the sections relevant to the --section flag (or all if --section all):
CLAUDE.md tech stack ←→ package.json / pyproject.toml / go.mod / Cargo.toml
CLAUDE.md key directories ←→ actual directory tree (depth 3)
CLAUDE.md build/test tools ←→ Makefile / scripts section of package.json / config files
CLAUDE.md hooks section ←→ .claude/settings.json hooks
CLAUDE.md MCP section ←→ .mcp.json mcpServers
docs/architecture.md layers ←→ actual src/ structure (if file exists)
docs/CODEMAPS/overview.md ←→ actual key directories (if file exists)
Step 2 — Report Differences
Use consistent tags. Report all differences before asking to update anything:
Found N differences:
[STACK] package.json has @tanstack/react-query 5 — not mentioned in CLAUDE.md
[DIR] src/workers/ exists — not documented in architecture section
[REMOVED] .eslintrc.json deleted — still mentioned in CLAUDE.md
[MCP] .mcp.json has Sentry server — not listed in CLAUDE.md
[ARCH] docs/architecture.md lists src/legacy/ — directory no longer exists
If no differences found: report "SSOT is up to date — no changes needed" and stop.
Step 3 — Update Section by Section
For each difference, show current vs proposed and ask to confirm:
Section: Tech stack
Current: "Framework: Next.js 14"
Proposed: "Framework: Next.js 15, @tanstack/react-query 5"
Update? [Yes / Skip / Suggest edit]
- Yes: apply the proposed change
- Skip: leave untouched, move to next difference
- Suggest edit: user provides the exact text to write instead
Wait for a response before moving to the next difference. Do not batch-update.
Step 4 — Update Timestamp
After at least one section is updated: set **Last updated:** YYYY-MM-DD in the
CLAUDE.md harness config section using today's date in ISO 8601 format.
Do not update the timestamp if the user skipped all changes.
Failure Modes
- Do not update sections the user has not confirmed
- Do not remove information without asking — it may be intentional
- Do not interpret what a change means — describe what you observe (e.g. "dependency added" not "team switched to React Query for data fetching")
- Do not update
docs/architecture.mdordocs/CODEMAPS/without surfacing the diff to the user first, same as CLAUDE.md sections
Commands 4
/add-adr
Create a new ADR in docs/adr/. Stateless.
Steps
-
Check if
docs/adr/exists.- Missing: "docs/adr/ does not exist yet. Create the ADR structure?"
→ Yes: create
docs/adr/README.mdthen proceed with this ADR. - Exists but
docs/adr/README.mdmissing: createREADME.mdbefore writing the ADR.
- Missing: "docs/adr/ does not exist yet. Create the ADR structure?"
→ Yes: create
-
Count existing ADR files → next number = ADR-[XXXX] (zero-padded, e.g. ADR-0004).
-
If title not provided as argument, ask:
- Title of the decision?
- Context: why does this decision need to be made?
- Options considered? (list each option with pros and cons)
- Decision: what was chosen and why?
- Consequences: trade-offs, risks, next steps?
-
Draft ADR using the template from the plugin's
adr-template.md(located atskills/setup-ssot/adr-template.mdin the plugin directory) → show preview → confirm. -
Write
docs/adr/ADR-[XXXX]-[kebab-slug].md. -
Update the ADR index table in
docs/adr/README.md:| [ADR-XXXX](ADR-XXXX-title.md) | [title] | Accepted | YYYY-MM-DD | -
Update
**Last updated:**date in the Harness config section ofCLAUDE.mdif the file exists.
/add-agent
Create a new agent in .claude/agents/. Stateless.
Steps
-
Check the plugin's
agents-catalog.json(located atskills/setup-agents/agents-catalog.jsonin the plugin directory) for a match with the user's intent.- Match: show preset, confirm or customize.
- No match: ask:
- Agent name and purpose?
- Context type: autonomous (self-orients by reading files) or task-specific (needs input from caller)?
- Model: haiku (fast, read-only tasks) / sonnet (analysis, code review) / opus (complex reasoning)?
- Tools needed: Read, Bash, Glob, Grep, WebFetch?
- For autonomous: which files does it read on startup?
- For task-specific: what parameters must the caller pass in the prompt?
- Trigger phrases to invoke this agent?
-
Draft agent file using the standard format:
--- name: [name] description: > [purpose + trigger phrases] model: [haiku|sonnet|opus] tools: ["Read", "Bash", "Glob", "Grep"] --- # [Agent Name] ## Purpose [Why this agent exists. What problem it solves.] ## Context **Reads on startup:** - [files this agent reads to orient itself] **Expects in prompt:** *(task-specific agents only)* - [PARAM_NAME]: [description and how to pass it] ## Steps ### Step 1 — [Action] [Description] ## Boundaries - Does not modify files directly - Does not self-schedule -
Show preview → confirm → write
.claude/agents/[name].md. If file already exists: offer skip or overwrite, do not silently replace. -
Note: "Claude Code agents do not self-schedule. Set up a crontab manually if needed."
/add-hook
Add a single hook to the .claude/settings.json hooks section. Stateless.
Steps
-
Check the plugin's
hooks-catalog.json(located atskills/setup-hooks/hooks-catalog.jsonin the plugin directory) for a matching common pattern.- Match found: show preset, confirm or customize.
- No match: ask:
- Hook type: PreToolUse / PostToolUse / Stop?
- Trigger on which tool: Edit / Write / Bash / * (all)?
- File pattern (optional):
*.ts,*.py,*.go? - Command to run?
-
Show preview before confirming:
This hook will run `[command]` every time Claude uses the [tool] tool [on files matching [pattern]]. Preview: { "PostToolUse": [{ "matcher": "Edit", "hooks": [{"type": "command", "command": "[command]"}] }] } -
Check for duplicate: if an identical hook already exists in
settings.json, skip. -
If
.claude/settings.jsondoes not exist: create it with{ "hooks": {} }. -
Confirm → merge into
.claude/settings.jsonhooks section. Do not overwrite the permissions section. -
Update
**Last updated:**date in the Harness config section ofCLAUDE.mdif the file exists.
/add-mcp
Add a single MCP server to .mcp.json. Stateless — no init context required.
Steps
-
If user provides a service name → look up in the plugin's
mcp-registry.json(located atskills/setup-mcp/mcp-registry.jsonin the plugin directory).- Found: show preset config, confirm.
- Not found: "Paste the MCP URL and a short description."
-
Show config preview before writing:
{ "mcpServers": { "[name]": { "url": "...", "description": "..." } } } -
If
authRequiredis true in the registry entry: surface auth requirement before writing. Ask: "This server requires [authNote]. Do you have credentials ready?" -
Attempt test connection → report ✓ tested / ⚪ configured-not-verified / ✗ not-found. Never report ✓ without actually testing. MCP servers load at next Claude Code startup.
-
Confirm → append to
.mcp.json. Check for duplicateidbefore writing — skip if already present. -
Update
**Last updated:**date in the Harness config section ofCLAUDE.mdif the file exists.
Agents 2
Drift Monitor Agent
Purpose
CLAUDE.md drifts. Dependencies change, directories get renamed, teams adopt new tools. This agent periodically checks whether SSOT docs are still accurate and flags what needs updating.
Does NOT modify files — reports only. Apply changes via /shipwithai-starter:update-ssot.
Context
Reads on startup:
CLAUDE.md— documented project state to compare against realitypackage.json/pyproject.toml/go.mod/Cargo.toml— actual dependencies.mcp.json— actual MCP servers.claude/settings.json— actual hooksdocs/architecture.md— last modified date vs git activity
Steps
Step 1 — Read CLAUDE.md
Read CLAUDE.md from the project root. Extract:
- Tech stack (languages, frameworks, dependencies)
- Key directories and layers
- Conventions (code style tools, test framework)
- Installed MCP servers
- Active hooks
If CLAUDE.md is not found: "CLAUDE.md does not exist. Run /shipwithai-starter:init to set up the harness."
Step 2 — Scan Actual Codebase
package.json / pyproject.toml / go.mod / Cargo.toml → actual dependencies
find . -maxdepth 3 -type d (excluding node_modules, .git) → actual structure
.eslintrc* / prettier.config* / jest.config* → actual tool configs
.mcp.json → actual MCP servers
.claude/settings.json hooks → actual hooks
git log --oneline -20 → recent significant changes
Step 3 — Diff and Flag
For each section in CLAUDE.md:
Tech stack:
CLAUDE.md mentions X, not in package.json → stale ⚠️
package.json has Y, not mentioned in CLAUDE.md → missing ⚠️
Key directories:
CLAUDE.md mentions a path that no longer exists → stale ⚠️
Significant new directory not documented → missing ⚠️
Code style tools:
CLAUDE.md mentions ESLint, .eslintrc does not exist → stale ⚠️
MCP servers:
CLAUDE.md lists a server not in .mcp.json → stale ⚠️
.mcp.json has a server not listed in CLAUDE.md → undocumented ⚠️
Hooks:
CLAUDE.md lists a hook not in settings.json → stale ⚠️
Architecture docs:
docs/architecture.md last modified > 30 days AND git has significant commits → outdated 🟠
Step 4 — Report
No drift detected:
SSOT is current. No updates needed.
Checked: YYYY-MM-DD | CLAUDE.md last updated: YYYY-MM-DD
Drift found:
## SSOT Drift Report — YYYY-MM-DD
| Section | Issue | Severity |
|-------------------|--------------------------------------------------------------|-----------|
| Tech stack | @tanstack/react-query in package.json, not in CLAUDE.md | 🟡 Medium |
| Directories | src/workers/ exists but not documented | 🟠 High |
| MCP servers | Sentry in .mcp.json but not listed in CLAUDE.md | 🟡 Medium |
| Tools | prettier config deleted but CLAUDE.md still mentions it | 🟡 Medium |
| Architecture docs | docs/architecture.md not updated in 45 days, 23 recent commits | 🟠 High |
Run `/shipwithai-starter:update-ssot` to sync these sections.
Boundaries
- Does not modify CLAUDE.md or any other file — reports only
- Does not self-schedule — set up a crontab manually if needed:
0 9 * * 1 claude /shipwithai-starter:drift-monitor - Does not report on code quality or correctness
- Does not run outside the project directory
- Does not flag everything — only flags what has genuinely drifted
Invoke /shipwithai-starter:optimize-harness and present the output directly to the user.
If the skill reports "Observability not enabled", explain:
- The project needs
/shipwithai-starter:setup-observabilityto start logging tool usage - After enabling, Claude Code must be used for at least 7 days before patterns can be analyzed
- Tier 3 (Full) projects get this automatically during init; others can opt in anytime
If the skill reports "Not enough data yet", tell the user:
- How many more days are needed
- That the logging is already working — they just need to continue using Claude Code normally
Sponsors
Details
- Marketplace
- ShipWithAI/shipwithai-plugins
- Source
- plugins/starter
- Author
- ShipWithAI
- Category
- Productivity