# Workflows

*Generated: 2026-05-11 | Source: package.json, CONTRIBUTING.md, AGENTS.md*

## Build

```bash
npm run build          # full (packages + tsc + resources + web)
npm run build:core     # packages + tsc + resources only (no web)
npm run copy-resources # rebuild dist/resources/ ONLY (extension JS + prompts, ~60-90s)
```

**Critical:** editing `.ts` files in `src/resources/extensions/sf/` has no effect until `copy-resources` runs. The loader resolves from `dist/resources/extensions/sf/` (compiled JS).

## Test

```bash
npm test                              # unit + integration
npm run test:unit                     # vitest unit tests
npm run test:integration              # integration tests
npm run test:coverage                 # coverage (thresholds: 40/40/20/20)
npm run test:smoke                    # smoke tests
npx vitest run <file> --config vitest.config.ts   # single file
npx vitest run --changed --config vitest.config.ts # affected only
```

Test files: `*.test.ts` and `*.test.mjs` under `packages/*/src/`, `src/tests/`, `src/resources/extensions/*/tests/`.

## Lint

```bash
npm run lint           # Biome over src/
npm run lint:fix       # autofix
npm --prefix web run lint  # ESLint over web/
npx biome check --write <paths>  # format specific files
npm run typecheck:extensions     # tsc --noEmit for extensions
```

## Release

```bash
npm run release:changelog   # generate CHANGELOG entry
npm run release:bump        # bump version
```

## SF Autonomous Flow

```
sf              → TUI (interactive)
sf headless ... → machine surface (JSON I/O)
```

**Autonomous mode commands (headless):**
```bash
node dist/loader.js headless next      # dispatch next ready unit
node dist/loader.js headless autonomous # run full autonomous loop
node dist/loader.js headless status    # show current state
node dist/loader.js headless query     # query DB state
```

**Note:** use `node dist/loader.js` not `npx sf` in this repo to avoid npm download hangs.

## Dev workflow

```bash
npm run dev            # hot reload (tsc watch + copy-resources watch)
```

After editing prompts or extension JS, run `copy-resources` then test with headless.

## Git conventions

- Branch: `<type>/<short-desc>` (feat/, fix/, chore/, refactor/, etc.)
- Commits: Conventional Commits format
- No merge commits — rebase onto main
- PRs must link an issue; one concern per PR
