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@shipwithai

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ShipWithAI/shipwithai-plugins.

Contents

Discovered from source

Skills 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.json with stack-appropriate permissions. Ready to use immediately.

Tier 2 — Standard (15 min): Adds auto-format/lint hooks, .mcp.json for 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 recommendPlugin in stack_plugins_selected. If the plugin is already enabled (its setupCommand resolves), 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 next init/--update run. 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

  1. Summary table: files created / updated / skipped.
  2. "Commit .claude/ and CLAUDE.md to the repo so the team shares the harness."
  3. 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:init instead." → 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)
ResponseAction
yesProceed to Phase 2 with confirmed stack
swap one thing"What would you like to swap?" → regenerate recommendation
different directionReturn 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):

  1. Database access / ORM
  2. Authentication approach
  3. API style
  4. Email service (if web app or API with users)
  5. Payments (if growth-stage product)
  6. 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:

QuestionOptions
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:

QuestionOptions
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).

ResponseAction
yesPhase 3
adjust folders"What would you change?" → regenerate folder tree only → re-confirm
different patternShow 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)
ResponseAction
yesExecute
go back to phase NReturn 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-project again." → 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 → 1
  • architecture.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:

  1. List .claude/logs/*.jsonl sorted by filename date; filter to window
  2. Read line by line — skip malformed lines silently (no error output)
  3. Discard: tool absent or not in {Edit, Write, Bash}
  4. Discard: ts absent 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):

MetricDefinition
bash_cmd_frequencyMap<cmd, count> — Bash events only, key on cmd
file_edit_frequencyMap<file_path, count> — Edit+Write, skip empty file
file_edit_by_dirMap<first_path_component, count> — from Edit+Write file field
ts_extension_editsMap<lowercase_ext_with_dot, count> — from Edit+Write file field
session_countlen(set(e.sid for e in events))
session_duration_minutesPer sid ≥2 events: (last_ts - first_ts).total_seconds() / 60
daily_tool_callsMap<YYYY-MM-DD, count> from ts field
days_with_datalen(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:

RuleConditionConfidence
R1bash_cmd_frequency["npm"] ≥ 5 AND jest-on-stop not in hooks_selectedHIGH ≥20 / MEDIUM ≥5
R2bash_cmd_frequency["pytest"] ≥ 5 AND pytest-on-stop not in hooks_selectedHIGH ≥20 / MEDIUM ≥5
R3sum(.ts+.tsx+.js+.jsx edits) ≥ 20 AND prettier-on-edit not in hooks_selectedHIGH ≥50 / MEDIUM ≥20
R4.py edits ≥ 20 AND neither black-on-edit nor ruff-on-edit in hooks_selectedHIGH ≥50 / MEDIUM ≥20
R5any sensitive_area_edits[P] ≥ 10 AND security-review not in workflow_gatesHIGH
R6make ≥ 5 AND make-test-on-stop absent; OR cargo ≥ 5 AND cargo-test-on-stop absentHIGH ≥20 / MEDIUM ≥5
R7top file_edit_frequency entry ≥ 30 AND no test file foundLOW
R8≥3 timed sessions AND median(session_duration_minutes) > 60LOW

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:

  1. Keep triggered rules only
  2. Drop LOW confidence if --verbose not set
  3. Sort: HIGH first, then MEDIUM, then LOW
  4. Deduplicate by rule ID (keep first)
  5. 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 --verbose is 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> → check python3; otherwise check first token
  • Binary in devDependencies / dependencies (package.json) OR which <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 serverDetect 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)
postgrespg, postgres (JS), psycopg2, sqlalchemy (Python)
notion@notionhq/client import
jirajira-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 version in this plugin's setup-skills/skills-catalog.json
  • template_version < catalog version (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 legacy project.md/team.md without 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:

  1. files: check whether any listed glob exists in the project root
  2. context: if .claude/starter-context.json exists, evaluate conditions against its fields
    • teamSize > N → read project.team_size
    • tier == N → read project.tier
  3. always: if alwaysInclude is true, 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:

  1. Their agent file content (system prompt)
  2. 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 inspection
  • sonnet: 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 startup from selfDiscovers in the catalog
  • For task-specific agents: populate Expects in prompt from expects in 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:

  1. files: check whether any listed filename/glob exists in the project root
  2. packageJson: read package.json, check key under devDependencies or dependencies
  3. 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 $FILE every time Claude uses the Edit tool on .js|ts|jsx|tsx|css|md files. Enable it?"

Stop hook:

"This hook will run npm test every 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.json does not exist: create it with { "hooks": {} }
  • Merge hooks into settings.json — do not overwrite the entire file
  • Before writing: check hook.id against 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:

  1. Look up config in the registry.
  2. If authRequired is true: show auth requirement before writing:

    "This server requires [authNote]. Do you have credentials ready?" If no: offer to skip and add later.

  3. If service type is stdio: ask for required runtime values (e.g. connection string) before writing — never write placeholder values literally.
  4. Show config preview (see Output Format below).
  5. Attempt test connection after writing (see Verification below).
  6. 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.json does not exist: create it with { "mcpServers": {} }
  • If .mcp.json exists: read it, check if server id already in mcpServers — 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 (from plugin.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:

PathLifetimeHolds
MEMORY.mdupdated continuouslyone-line index of every memory
decisions/NNNN-slug.mddurable, append-onlya decision + its rationale
conventions/slug.mddurablea convention or gotcha
HANDOFF.mdephemeral, overwrittencurrent WIP + "Context to Load" for next session
sessions/YYYY-MM-DD.mdappend per daya 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: injects MEMORY.md + HANDOFF.md, tells Claude to read only the files under "Context to Load" (lazy load).
  • remind-save.sh → Stop: nudges /save-memory once 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 Stop array 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:

  1. Substitute {{PROJECT_NAME}} and {{TEMPLATE_VERSION}}.
  2. Collision-safe: if .claude/skills/save-memory/SKILL.md already exists, do NOT overwrite — report it and skip. (template_version in the frontmatter lets review detect staleness later.)
  3. 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.md present — 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 from project.md into a decisions//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/, or sessions/ if they already contain real entries.
  • Hooks merge (settings.json): additive only — append SessionStart/Stop entries; never clobber existing hooks (e.g. /setup-hooks formatter/lint/test). Skip an entry whose command is already registered.
  • /save-memory skill: 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:

ToolLoggedNOT logged
EditRelative file pathFile content, old/new string
WriteRelative file pathFile content
BashCommand 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

  1. Copy observe.py from plugin assets to .claude/hooks/observe.py
  2. Merge PostToolUse hook into .claude/settings.json — matcher Edit|Write|Bash
  3. Merge Stop hook (log rotation) into .claude/settings.json
  4. Add .claude/logs/ to .gitignore (skip if already present)
  5. Check git ls-files .claude/logs — warn user if currently tracked
  6. 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.json before writing — merge into existing structure, never overwrite
  • Check hooks.PostToolUse for matcher Edit|Write|Bash — skip if already present (idempotent)
  • Check hooks.Stop for rotation command — skip if already present (idempotent)
  • Check .gitignore for .claude/logs/ — skip line if already present
  • Never proceed without user confirmation of the preview

--disable Flow

  1. Remove PostToolUse hook entry with matcher Edit|Write|Bash from settings.json
  2. Remove Stop hook rotation entry from settings.json
  3. Delete .claude/hooks/observe.py
  4. Update starter-context.json → observability.enabled: false
  5. 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.json exists before writing → Overwrite / Merge / Skip?
  • Merge: update permissions section only, never touch hooks section 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:

  1. files: check whether any listed glob exists in the project root
  2. context: if starter-context.json exists, evaluate conditions against its fields
  3. 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:

TokenSourceFallback
COMMIT_BLOCKconventions.commit_format (conventional/none/custom)conventional
BRANCH_BLOCKconventions.branch_strategy (gitflow/trunk-based)trunk-based
PROTECTED_BRANCHESderived from branch_strategyfrom trunk-based
PROJECT_NAMEproject.name"this project"
TEMPLATE_VERSIONcatalog 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.md already 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 enables review to detect staleness when the plugin template is later updated.

Step 5 — Post-Write

  1. If starter-context.json exists → update skills_selected with installed ids.
  2. Print: "Installed <id>. It loads when you say: [triggers from catalog]."
  3. 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.codemaps fields — skip questions
  • Missing (standalone): ask which outputs to create, then gather architecture details

Flags

  • --architecture-only — write docs/architecture.md only, 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.md and 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.json hooks vs CLAUDE.md only
  • --section mcp — diff .mcp.json vs 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.md not found → inform user, suggest running /shipwithai-starter:setup-ssot first, offer to continue anyway
  • docs/architecture.md found → include in diff scope
  • docs/CODEMAPS/overview.md found → 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.md or docs/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

  1. Check if docs/adr/ exists.

    • Missing: "docs/adr/ does not exist yet. Create the ADR structure?" → Yes: create docs/adr/README.md then proceed with this ADR.
    • Exists but docs/adr/README.md missing: create README.md before writing the ADR.
  2. Count existing ADR files → next number = ADR-[XXXX] (zero-padded, e.g. ADR-0004).

  3. 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?
  4. Draft ADR using the template from the plugin's adr-template.md (located at skills/setup-ssot/adr-template.md in the plugin directory) → show preview → confirm.

  5. Write docs/adr/ADR-[XXXX]-[kebab-slug].md.

  6. Update the ADR index table in docs/adr/README.md:

    | [ADR-XXXX](ADR-XXXX-title.md) | [title] | Accepted | YYYY-MM-DD |
    
  7. Update **Last updated:** date in the Harness config section of CLAUDE.md if the file exists.

/add-agent

Create a new agent in .claude/agents/. Stateless.

Steps

  1. Check the plugin's agents-catalog.json (located at skills/setup-agents/agents-catalog.json in 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?
  2. 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
    
  3. Show preview → confirm → write .claude/agents/[name].md. If file already exists: offer skip or overwrite, do not silently replace.

  4. 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

  1. Check the plugin's hooks-catalog.json (located at skills/setup-hooks/hooks-catalog.json in 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?
  2. 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]"}]
      }]
    }
    
  3. Check for duplicate: if an identical hook already exists in settings.json, skip.

  4. If .claude/settings.json does not exist: create it with { "hooks": {} }.

  5. Confirm → merge into .claude/settings.json hooks section. Do not overwrite the permissions section.

  6. Update **Last updated:** date in the Harness config section of CLAUDE.md if the file exists.

/add-mcp

Add a single MCP server to .mcp.json. Stateless — no init context required.

Steps

  1. If user provides a service name → look up in the plugin's mcp-registry.json (located at skills/setup-mcp/mcp-registry.json in the plugin directory).

    • Found: show preset config, confirm.
    • Not found: "Paste the MCP URL and a short description."
  2. Show config preview before writing:

    {
      "mcpServers": {
        "[name]": {
          "url": "...",
          "description": "..."
        }
      }
    }
    
  3. If authRequired is true in the registry entry: surface auth requirement before writing. Ask: "This server requires [authNote]. Do you have credentials ready?"

  4. Attempt test connection → report ✓ tested / ⚪ configured-not-verified / ✗ not-found. Never report ✓ without actually testing. MCP servers load at next Claude Code startup.

  5. Confirm → append to .mcp.json. Check for duplicate id before writing — skip if already present.

  6. Update **Last updated:** date in the Harness config section of CLAUDE.md if 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 reality
  • package.json / pyproject.toml / go.mod / Cargo.toml — actual dependencies
  • .mcp.json — actual MCP servers
  • .claude/settings.json — actual hooks
  • docs/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-observability to 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

More from ShipWithAI/shipwithai-plugins

All 7