Skip to main content
fensu init sets up Fensu in a repository. It detects your layout, writes a fensu.toml with the complete default ruleset, runs an initial check to show the current drift, and installs agent skill files. The native initializer is non-interactive, so new initialization requires --yes.

​
What it does

  1. Detects your layout and analyzers. Python package roots come from pyproject.toml metadata (hatch, setuptools, poetry, flit, uv workspaces, the project name), ruff’s src setting, and a directory scan. Test paths come from pytest testpaths and tests/test directories; tooling from scripts, tools, bin, and tasks directories with Python files. If package metadata also names one of those conventional tooling directories, tooling classification wins so a path is never proposed in both scopes; an explicit --root overrides detection. Fensu also detects complete SvelteKit projects and can write both analyzers as named targets.
  2. Enables each complete policy. Python targets select FF; detected SvelteKit targets activate the sveltekit rule pack and select FPSK. An empty repository normally gets a scaffolded Python src/<name>/ package plus tests/.
  3. Writes fensu.toml and updates your .gitignore to cover Fensu’s cache directory.
  4. Measures current drift by running the starting ruleset once and printing the total fault and affected-file counts.
  5. Installs project-specific agent skill files (.claude/, .opencode/, .agents/) at the Git root by default under --yes; see fensu skills.

​
Options

--skills and --no-skills are mutually exclusive. --root, --tests, and --tooling only apply when a codebase is detected; --name only applies when none is.

​
SvelteKit detection

Repository-wide onboarding includes each confidently detected SvelteKit project. Detection requires a svelte.config.* file, package.json with @sveltejs/kit, tsconfig.json or jsconfig.json, and src/ in the same target directory. A mixed repository receives explicit Python and Svelte targets. Generic TypeScript files alone do not trigger automatic web policy. Use --exclude-target NAME when the onboarding request deliberately excludes a detected web project. See TypeScript and SvelteKit for manual configuration and gradual adoption.

​
An existing repository

On a repository with code, use the detected paths or supply explicit scope paths:
The command writes configuration, measures drift, and installs all three local skill targets without launching a second process:
Use repeatable --root, --tests, and --tooling arguments when detection is not the intended layout. No rule family is silently held back. For an existing repository, keep the target visible and roll it out with evaluation targeting or explicit rule exceptions; see Adopting Fensu.

​
An empty repository

With no Python code detected, fensu init scaffolds a fresh layout instead. The required explicit name is normalized into a Python package name:
The resulting project starts fully enforced from the first commit:

​
Gitignore handling

Fensu’s generated result cache lives under .fensu/cache/, which should not be committed. The rest of the .fensu/ namespace is not ignored automatically.
  • If a root .gitignore exists and does not already cover the cache path, fensu init appends a .fensu/cache/ entry to it.
  • An empty repository with no .gitignore gets one created from the standard GitHub Python template, plus the .fensu/cache/ entry.
  • An existing repository with no .gitignore gets one containing just the .fensu/cache/ entry.

​
Rerunning is safe

If the directory already has a fensu.toml or a [tool.fensu] table, fensu init changes nothing and exits 0:
If a parent directory’s configuration would apply here instead, init refuses with an error rather than shadowing it. Configuration and scaffold writes are transactional. Drift measurement and skill installation happen afterward. If skill installation fails, the initialized project is kept and the error is reported so you can rerun fensu skills.

​
Approval and automation

Initialization does not implement an interactive wizard. Pass --yes; otherwise the command fails without writing:
Add --no-skills only for explicit configuration-only automation. After normal initialization, require fensu skills --check to pass before onboarding is complete.

​
Exit codes

Quickstart

The manual version of what init automates.

Adopting Fensu

Rolling out full enforcement with explicit boundaries and exceptions.

Configuration

Every key in the file init writes.

fensu skills

The agent guidance init installs by default under --yes.