shipwrights-init

/shipwrights-init — non-destructive project scaffold

Scaffold .shipwrights.yml + workflows + scripts + doc templates into a project. Never overwrites silently. Always lands as one git commit so undo is git revert HEAD.

Flags

• --dry-run — print the plan, write nothing.
• --non-interactive — use defaults; for any conflict, write the plugin's version as .example and leave the consumer's file alone.
• --force — answer "overwrite" to every conflict prompt. Still lands as one commit.

What you (the init command) do

1. Pre-checks

• Confirm the working tree is clean. Refuse if dirty (unless --force).
• Confirm the cwd is a git repository (git rev-parse --is-inside-work-tree).
• Read existing package.json / Cargo.toml / go.mod / pyproject.toml to detect ecosystem.
• Look for an existing .shipwrights.yml. If present, refuse — direct user to /shipwrights-upgrade.

2. Auto-discovery

Run lib/verify-discovery.mjs against the project root. It returns a recipe:

{
  ecosystem: "node-pnpm" | "node-npm" | "node-yarn" | "go" | "rust" | "python-poetry" | "python-uv" | ...,
  install:    "pnpm install" | ...,
  verify:     "pnpm verify" | "go test ./..." | ...,
  lint:       "pnpm lint" | "cargo clippy" | ...,
  typecheck:  "pnpm typecheck" | "tsc --noEmit" | ...,
  format_fix: "pnpm exec biome check --write" | "gofmt -w ." | ...
}

Detect:

• Languages present (file extensions sampled).
• Monorepo vs single-package (pnpm-workspace.yaml, lerna.json, turbo.json, Cargo.toml with workspace, go.work).
• Existing CI workflows under .github/workflows/.
• Existing branch protection (warn if main allows direct push).
• Existing scripts under scripts/architecture/ (if so, propose registering them as guards).

3. Ask the consumer

Show the discovered recipe + propose questions. Each question has a default the consumer can accept by hitting Enter:

Project name? [shop-app-v2]
Integration branch? [dev]
Release branch? [main]
Verify command? [pnpm verify]
Format-fix command? [pnpm exec biome check --write]
Backlog source? [files]   (other options will be available once @shipwrights/source-* packages installed)
Where do epic files live? [docs/backlog/epics]
Which roles to enable?
  [x] po
  [x] backend
  [x] frontend
  [x] qa
  [x] gatekeeper
  [ ] browser              (auto-checked if apps/web/-style dir detected)
For backend, scope paths? [apps/api/**, packages/contracts/**]
For frontend, scope paths? [apps/web/**, packages/contracts/**]
For qa, scope paths? [**/*.test.ts, **/*.spec.ts, **/test/**]
Contract surface (frozen after slice)? [packages/contracts/**]
Push scratch branches to remote? [no]
Default merge strategy? [rebase]
File-length defaults?
  TypeScript source: [250]    test: [350]
Hard rules (one per line, blank to finish):
> Public APIs expose slugs / reference numbers, never raw DB ids
> Append-only ledgers stay append-only
>