Relies on BDK foundation (STARTUP_INSTRUCTIONS.md). Assumes environment discovery has already run (language, test runner, build tool are known).

BDK Setup

Initializes .bdk/settings.json for this project. Probes project files to detect languages, test commands, lint commands, and build commands, then confirms with the user before writing.

Workflow

Phase 1: Check existing config

If .bdk/settings.json already exists and --force was not passed:

• Read the file and show current values
• Ask user: "Settings already exist. Overwrite?" — if no, stop

Phase 2: Probe project files

Read the following files if they exist and extract command/tool hints:

Command resolution priority — always prefer running tools via the package manager over direct binary invocation:

• package.json scripts → npm run <script> / yarn <script> / pnpm <script> (detect manager by lockfile: package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm)
• Python with pyproject.toml → poetry run <tool> if poetry.lock exists, else direct
• Ruby → bundle exec <tool> always
• Direct binary only as last resort (no package manager detected)

JavaScript/TypeScript (package.json):

• Scan scripts for keys: test, test:unit, test:e2e, test:integration, lint, lint:fix, build, typecheck, compile
• Emit as npm run <key> (or yarn/pnpm equivalent per lockfile)
• Check devDependencies/dependencies for: vitest, jest, @playwright/test, cypress, eslint, prettier, typescript — only as fallback if no matching script key found
• Presence of next.config.* → add next to languages
• Presence of react in deps → add react to languages

Python (pyproject.toml, setup.py, requirements*.txt):

• Detect pytest, ruff, mypy, black, flake8
• If poetry.lock present → poetry run pytest, poetry run ruff, etc.
• Else direct: pytest, ruff, etc.
• Language: python

Go (go.mod):

• Test: go test ./...
• Check for .golangci.yml or .golangci.toml → lint: golangci-lint run
• Else lint: go vet ./...
• Language: go

Rust (Cargo.toml):

• Test: cargo test
• Lint: cargo clippy
• Build: cargo build
• Language: rust

Java (pom.xml or build.gradle):

• Maven: mvn test, mvn package
• Gradle: ./gradlew test, ./gradlew build
• Language: java

PHP (composer.json):

• Check scripts for test key; else detect phpunit or artisan test
• Check for phpcs or pint for lint
• Language: php

Ruby (Gemfile):

• Test: bundle exec rspec (if rspec in Gemfile) or bundle exec rake test
• Lint: bundle exec rubocop
• Language: ruby

C# (*.csproj or *.sln):

• Test: dotnet test
• Build: dotnet build
• Language: csharp

Dart/Flutter (pubspec.yaml):

• Test: flutter test (if flutter sdk) or dart test
• Language: dart

Phase 2b: Fill in tier and scoping forms

The full command is the least useful thing about a tool entry. BDK runs scoped checks throughout a plan and the full suite exactly once, at the end — so every entry needs a tier and, wherever the tool supports it, the narrower forms. Getting these right here is what stops every later agent from guessing at npm run test:unit -- <path> versus vitest related.

Set tier on every test-tools entry (fast | e2e) and every lint-tools entry (lint | format | typecheck). Never leave it out: BDK infers a missing tier from the tool name, and an inferred fast on an e2e runner means a slow suite runs at every group boundary.

{files} is a literal placeholder in these templates — callers substitute a path list. Derive per runner:

Rules for anything not in the table:

• Package-manager script wrapping a runner that takes paths → <script> -- {files} (npm run test:unit -- {files}). The -- is required or the paths reach npm, not the runner.
• A tool that takes no path list (most typecheckers, some build-mode linters) → omit scoped; give an incremental form if the tool has a cache flag.
• Not sure a form exists → omit it. A wrong template is worse than a missing one: BDK falls back cleanly from a missing form, and silently runs the wrong thing with a broken one.
• scoped and related must contain {files}; the config hook rejects settings where they do not, because such a command ignores the file list and quietly runs everything.

Phase 3: Confirm settings via AskUserQuestion

Use the AskUserQuestion tool with up to 4 questions in a single call:

1. Test commands — multiSelect: true, options: each detected command as its own option + "None". User can add unlisted commands via "Other".
2. Lint commands — multiSelect: true, same pattern

Confirm the full commands only. Tiers and scoped forms are derived from Phase 2b for whatever the user confirms — they are mechanical consequences of the runner, not preferences worth a question. Show them in the completion summary instead so a wrong derivation is visible. 3. Features - single select, question: "Use caveman mode (terse replies)?", options: "On" (writes "caveman": true), "Off" (writes "caveman": false). 4. Build command — only include if a build tool was detected or the language typically has one (e.g. TypeScript, Java, Rust); skip otherwise to stay under 4 questions

If more than 4 confirmation categories exist, prioritize: test → lint → features → build. Handle remaining categories with a follow-up AskUserQuestion call after writing.

"Other" is automatically appended by the UI — user can type any custom command there.

Phase 4: Write .bdk/settings.json

Create directory and file:

.bdk/
├── settings.json
├── plans/
└── design/

Write settings.json with confirmed values plus the tier/scoping forms from Phase 2b:

{
  "$schema": "https://raw.githubusercontent.com/broneq/bdk/main/hooks/check-bdk-config/settings.schema.json",
  "languages": ["typescript", "react"],
  "test-tools": [
    {
      "type": "vitest",
      "tier": "fast",
      "command": "npm run test:unit",
      "scoped": "npx vitest run {files}",
      "related": "npx vitest related --run {files}",
      "failed": "npx vitest run --changed"
    },
    {
      "type": "playwright",
      "tier": "e2e",
      "command": "npm run test:e2e",
      "scoped": "npx playwright test {files}",
      "failed": "npx playwright test --last-failed"
    }
  ],
  "lint-tools": [
    {"type": "eslint", "tier": "lint", "command": "npm run lint", "scoped": "npx eslint {files}"},
    {"type": "tsc", "tier": "typecheck", "command": "npm run typecheck", "incremental": "npx tsc -b --incremental"}
  ],
  "build-tools": [{"type": "tsc", "command": "npm run build"}],
  "features": {
    "caveman": true
  }
}

type names the runner or framework (vitest, playwright, pytest, eslint, tsc), not the package manager — BDK reads it to infer a missing tier. Omit empty arrays (e.g. no build-tools key if none detected/provided), and omit any per-entry form the tool does not support. build-tools need no tier.

Phase 5: Git guidance

Recommend:

• Commit .bdk/settings.json (shared with team — consistent commands for all contributors)
• Add to .gitignore: .bdk/plans/ and .bdk/design/ (personal artifacts)

Show the gitignore lines to add:

.bdk/plans/
.bdk/design/

Ask: "Add these to .gitignore now? [y/n]"

Completion

Print:

[setup] .bdk/settings.json created.
[setup] Test tiers: {tier}={command} (scoped: {scoped|none}) …
[setup] Lint tiers: {tier}={command} (scoped: {scoped|none}) …
[setup] Directories created: .bdk/plans/, .bdk/design/
[setup] Restart your Claude Code session — BDK will inject project settings on startup.

The tier lines exist so a wrong derivation is caught now, by the one person who knows the project, rather than showing up later as a slow suite running at every group boundary.