# flaker New Project Onboarding Checklist
[日本語版](new-project-checklist.ja.md)
The checklist for introducing flaker to a new repository and getting value from it across the first day, first week, and first month. Assumes `0.7.0+`.
Day 1 converges in five steps: `init -> doctor -> plan -> apply -> status`. If you follow it in order, initial setup takes about 30 minutes, your measurement baseline is in place within a week, and the repository is ready to promote CI gating in 2-4 weeks.
---
## Day 0: Preconditions (5 minutes)
```bash
node --version # >= 24
pnpm --version # >= 10
git remote -v # origin should point at GitHub
gh auth status # logged in (needed for flaker apply when pulling CI history)
```
Repositories with no GitHub Actions history are still fine. `flaker apply` detects an empty history and picks the cold-start path (self-seed from a local run). Real CI history accumulates naturally after Day 1.
You do not need `moon` (MoonBit). flaker ships a bundled `dist/moonbit/flaker.js`, and falls back to TypeScript (`src/cli/core/loader.ts`) when needed.
---
## Day 1: Install through convergence (15 minutes)
Day 1 is a single five-step flow. `flaker apply` handles collect / calibrate / quarantine sequencing internally, so you do not have to memorize the order.
### 1. Install
```bash
pnpm add -D @mizchi/flaker
```
### 2. Generate `flaker.toml`
Choose the adapter and runner at init time:
```bash
# vitest project
pnpm flaker init --adapter vitest --runner vitest
# playwright e2e
pnpm flaker init --adapter playwright --runner playwright
# jest
pnpm flaker init --adapter jest --runner jest
# actrun wrapping a GitHub Actions workflow for playwright
pnpm flaker init --adapter playwright --runner actrun
```
`owner` and `name` are auto-detected from the git remote. Override with `--owner` / `--name` if needed.
`flaker init` also writes default `[gate.release]` / `[gate.merge]` / `[gate.iteration]` blocks so that gates resolve immediately.
### 3. Check the environment with doctor
```bash
pnpm flaker doctor
```
Expected output looks like:
```text
OK config flaker.toml is readable
OK config ranges all values within expected ranges
OK duckdb DuckDB initialized successfully
OK moonbit MoonBit JS build detected (or fallback)
Doctor checks passed.
```
If DuckDB fails to initialize, the most likely cause is `node --version < 24`.
### 4. Configure the affected resolver
To make `flaker run --gate iteration` and the `hybrid` strategy useful, you need an affected resolver. Edit `[affected]` in `flaker.toml` based on the repository shape:
```toml
# pnpm workspaces / npm workspaces monorepo
[affected]
resolver = "workspace"
config = ""
# glob rules with a separate flaker.affected.toml
[affected]
resolver = "glob"
config = "flaker.affected.toml"
# bitflow repository
[affected]
resolver = "bitflow"
config = ""
```
If you do not configure a resolver, `hybrid` still works through `weighted` fallback, but you lose the best change-aware behavior. Start with `workspace` if possible.
### 5. Preview with `flaker plan`
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker plan
```
`flaker plan` reads `flaker.toml` as desired state and reports what the DB is currently missing. An empty-history repository usually plans `collect_ci` + `cold_start_run`; if `[quarantine].auto = true`, a `quarantine_apply` action shows up too.
### 6. Converge with `flaker apply`
```bash
pnpm flaker apply
```
`flaker apply` is idempotent and runs `collect` / `calibrate` / `quarantine apply` on demand based on current state. It is safe to re-run from cron or nightly — repeated executions do not break anything.
### 7. Inspect with `flaker status`
```bash
pnpm flaker status
```
A one-screen summary dashboard. On Day 1 you usually see `data confidence: insufficient`, which is expected. After a week of `flaker apply`, it lifts to `moderate` naturally.
---
## Day 2-3: Keep applying
Because `flaker apply` is idempotent, "run it once a day" is the whole Day 2 story. You do not have to call `collect` or `calibrate` manually.
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker apply
pnpm flaker status # daily dashboard
pnpm flaker status --detail # KPI view (formerly analyze kpi)
```
Drilling down into the individual steps
`flaker apply` internally invokes the commands below on demand. They remain callable directly if you want to inspect one stage in isolation, but `flaker apply` is canonical.
**Collect CI history:**
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker import --ci --days 30
```
**Calibrate:**
```bash
pnpm flaker calibrate
```
This writes the recommended strategy and sampling percentage into `[sampling]` in `flaker.toml`. Add `--dry-run` if you want to preview without writing.
If data is still thin (`commits < 20`), you may get `confidence: insufficient` or `low`. That is acceptable at this stage; `flaker apply` will recalibrate itself as history grows over the next week.