# Init

> Set up flux in the current project: config, gate script for CI, workflows, CLAUDE.md contract, specs index, GitHub label. Use when the user asks to initialize/install flux in a project.

- Skill: `sbnet/init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sbnet/init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sbnet/init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sbnet (https://skillmd.com/u/sbnet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sbnet/init

---


# Skill: init

## Purpose

Scaffold everything a project needs to be flux-managed. Idempotent: on a
project that already has flux, refresh the managed files instead of
duplicating them.

The plugin root is two levels up from this skill's base directory; templates
live in `<plugin root>/templates/`.

## Steps

1. **Prerequisites.** Check `yq` (v4, mikefarah) and `gh` (≥ 2.20, authenticated)
   are available. Install or tell the user how before continuing.
2. **Detect the stack.** Look at the project (composer.json, package.json,
   pyproject.toml…) and derive the real commands for lint / static analysis /
   types / tests / build.
3. **`flux-config.yml`** at the project root. If it does not exist yet,
   create it from `templates/flux-config.yml` with the detected commands,
   asking the user only if a command cannot be inferred. If it already
   exists, do NOT regenerate it: diff its keys against the current
   template and add only the ones missing (new schema keys from a plugin
   update), at the template's default. Never touch a key already present,
   that is the user's customization to keep.
4. **Gate script for CI.** Copy `<plugin root>/hooks/flux-gate.sh` to
   `.claude/hooks/flux-gate.sh` (chmod +x), overwriting unconditionally:
   this file is not meant to be hand-edited, so there is nothing local to
   preserve. Do NOT add hooks to `.claude/settings.json`: the plugin
   already provides them, duplicating would run every gate twice.
5. **Workflows.** For each of `templates/ci.yml` and
   `templates/spec-lifecycle.yml`: if the target under
   `.github/workflows/` does not exist, copy it (adapting the Prepare/Build
   steps of ci.yml to the stack; the template is Laravel/Vite-flavored). If
   it already exists and differs from the template, these files are
   routinely hand-adapted (a custom build step), so do not overwrite
   silently: show a diff and ask the user whether to replace it, keep it,
   or merge by hand. Identical content needs no prompt. There is no
   review workflow to install: `/flux:review` runs locally, in a session,
   never in CI. If `.github/workflows/claude-review.yml` exists from an
   older flux version, tell the user it is no longer used (`/flux:review`
   replaced it) and ask whether to delete it; the repository secret it
   needed is no longer required either.
6. **`CLAUDE.md`** from `templates/CLAUDE.md`: create it, or append the flux
   sections if the project already has one (never overwrite existing content).
7. **Specs.** Create `<specs.dir>/README.md` index if missing.
8. **GitHub.** Create the labels from `github.labels` (via `gh label create`
   or the API). Enable automatic head-branch deletion:
   `gh api -X PATCH repos/<owner>/<repo> -f delete_branch_on_merge=true`.
9. **Report.** List what was created/updated, and what needs a session
   restart (plugin hooks, skills).