fallow 3.30.0 → 3.32.0

package/skills/fallow-setup/references/configure-and-install.md

@@ -0,0 +1,56 @@
+# Configure and install
+
+## Recommendation
+
+`fallow recommend --format json --quiet` inspects the project and changes nothing. It always exits 0. The envelope has `kind: "recommendation"` and these fields:
+
+| Field | Content |
+|---|---|
+| `detected` | The project facts: monorepo layout, TypeScript, test framework, UI framework, Storybook, package manager |
+| `proposed_config` | A safe starting config |
+| `decisions[]` | One entry per setting: `setting`, `value`, `rationale`, `kind`, `question` |
+| `config_schema_command` | The command that prints the config JSON Schema |
+
+Use `kind` to decide what to do with each decision:
+
+| `kind` | Meaning | Action |
+|---|---|---|
+| `auto` | Fallow decided the value from the detection | Apply it. |
+| `default` | A disclosed default that the user can change | Apply it and tell the user the `rationale` in one line. |
+| `taste` | A subjective choice | Keep the current value, or ask the user. `question` has a `header`, a `question`, and `options[]` with a `label` and a `description`. Show these options as they are. |
+
+When the project has no Fallow config, write `proposed_config` plus the answers to `.fallowrc.json`. When the project has a config, change only the settings that the user approved. Validate the keys with `fallow config-schema`. Check the loaded config with `fallow config --format json --quiet`.
+
+When the project has a Knip, jscpd, or stylelint config, preview the migration with `fallow migrate --dry-run`. Merge the result with the recommendation. Do not delete the old config in this step. The [parity check](tooling-detection.md#parity-check) decides when it can go.
+
+## Dev dependency
+
+Install Fallow as a dev dependency with the detected package manager:
+
+| Package manager | Command |
+|---|---|
+| npm | `npm install --save-dev fallow` |
+| pnpm | `pnpm add -D fallow` |
+| Yarn | `yarn add -D fallow` |
+| Bun | `bun add -d fallow` |
+
+A dev dependency pins one Fallow version for every developer, every agent, and CI. Add scripts to `package.json` when the project uses scripts for its other checks, for example `"fallow": "fallow"` and `"fallow:audit": "fallow audit"`.
+
+## Agent wiring
+
+`fallow agent install` wires Fallow into Claude Code, Codex, and Cursor in one pass. It detects the harnesses from the project, the home directory, and the session environment. `--harness` selects them explicitly.
+
+1. Run `fallow agent install --dry-run --format json --quiet`. Each entry in `steps[]` has a `step`, a `status`, and a `path`. Show the plan to the user.
+2. Run `fallow agent install`. Add `--without <step>` to skip a step. The steps are `guide`, `skill`, `mcp`, and `hooks`.
+3. Run `fallow agent status --format json --quiet`. Check only the entries of the harnesses that step 1 selected. Status also lists the other harnesses (for example `.cursor/mcp.json` in a Claude-only project) as `absent`, which is correct. Act on `next_actions[]` for a `stale` entry of a selected harness.
+
+The steps write these items:
+
+| Step | Result |
+|---|---|
+| `guide` | The task map in `AGENTS.md`, and an `@AGENTS.md` import in `CLAUDE.md` for Claude Code |
+| `skill` | The Fallow skills under `.claude/skills/` and `.agents/skills/` |
+| `mcp` | The MCP server registration for each harness |
+| `hooks` | The commit and push gate: a PreToolUse hook for Claude Code (`.claude/settings.json`) and for Codex (`.codex/hooks.json`), plus a routing block in `AGENTS.md` |
+
+Exit code 2 means that a step is `refused` or `failed`. Read the `reason` of that step. `skill_name_taken` means that a skill with the same name exists and Fallow did not write it. Do not pass `--force` without the approval of the user.

package/skills/fallow-setup/references/tooling-detection.md

@@ -0,0 +1,44 @@
+# Tooling detection
+
+Inspect the repository before you change it. Record what you find, because the later steps use it.
+
+## Files to inspect
+
+| Tool area | Signals |
+|---|---|
+| Package manager | `packageManager` in `package.json`; the lockfile: `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `bun.lockb`, `package-lock.json` |
+| Formatter | `.oxfmtrc.json`, `.prettierrc*`, `prettier.config.*`, `biome.json`, `biome.jsonc`, a `format` script in `package.json` |
+| Linter | `.oxlintrc.json`, `eslint.config.*`, `.eslintrc*`, `biome.json`, a `lint` script in `package.json` |
+| TypeScript | `tsconfig.json`, `tsconfig.*.json`, a `typecheck` script, `typescript` in `devDependencies` |
+| CI | `.github/workflows/*.yml`, `.gitlab-ci.yml`, other CI config files |
+| Existing analysis | `knip.json`, `knip.jsonc`, `.knip.json`, `.knip.jsonc`, a `knip` field in `package.json`; `.jscpd.json`; `.dependency-cruiser.*` |
+| Existing Fallow | `fallow config --path` prints the config path, or exits 3 when there is no config |
+| Agent harnesses | `CLAUDE.md`, `.claude/`, `.codex/`, `.cursor/` (`AGENTS.md` alone does not name a harness) |
+
+`fallow doctor --format json --quiet` checks the project root, the config, the workspaces, and the installed dependencies. It changes nothing. Run it when the project layout is not clear.
+
+## Responsibility split
+
+Give each tool one job. Do not configure two tools for the same job.
+
+| Job | Tool | Command |
+|---|---|---|
+| Formatting | Oxfmt | `oxfmt` |
+| Local lint rules | Oxlint | `oxlint` |
+| Type correctness | TypeScript | `tsc --noEmit` |
+| Repository and system analysis | Fallow | `fallow`, `fallow audit` |
+
+Repository and system analysis covers unused files, exports, types, and dependencies, duplication, complexity, circular dependencies, architecture boundaries, and changed-code risk.
+
+For a new project, use the tools in this table. For an existing project, keep the current formatter, linter, and type check. Add Fallow for the system analysis.
+
+## Parity check
+
+Do this check before you remove a tool whose job overlaps with Fallow, for example Knip, jscpd, or dependency-cruiser. When a step fails, keep the tool and tell the user why.
+
+1. Ask the user for approval to replace the tool.
+2. Migrate the config when Fallow can read it: `fallow migrate --dry-run` for Knip, jscpd, and stylelint. When the project has no Fallow config, review the preview, then run `fallow migrate`. When a Fallow config exists, `fallow migrate` refuses to write. Merge the settings from the preview into that config by hand. Fallow cannot migrate a dependency-cruiser config. Write the rules again as `boundaries` in the Fallow config (`fallow config-schema` gives the format).
+3. Run the old tool and Fallow on the same commit. Compare the findings by category.
+4. Explain each finding that only one tool reports. A finding that Fallow does not report must have a reason, for example a framework entry point that Fallow detects.
+5. Move each CI step and each `package.json` script of the old tool to Fallow.
+6. Remove the old tool and its config in a separate commit, so that the user can revert it.