Flisk Contributing

---
name: flisk-contributing
description: Contribute to the flisk CLI repository (flisk-sh/flisk) itself - follow its root AGENTS.md and the nested AGENTS.md files, rebuild the committed `cli/dist`, run `make test` and the CLI checks, keep `.claude/skills` and `cli/templates/agent-skills` in sync with flisk-skills, and sign off commits. Use when changing the CLI, engine, discovery or docs inside a flisk checkout. Not for working in a Flisk project; for that, use the other flisk-* skills.
license: MIT
compatibility: Requires a flisk-sh/flisk checkout, Bun, Docker and Tilt. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Contributing to flisk

## Workflow

1. Read the rules: the root `AGENTS.md`, then the one next to what you change (`cli/AGENTS.md`, `runtime/engine/AGENTS.md`, `runtime/discovery/AGENTS.md`, and the subsystem files under `runtime/engine/topologies/platform/`). Human-facing process: `.github/CONTRIBUTING.md`. Known CI and verification traps: `.claude/memory/MEMORY.md`.
2. Make one focused change, with tests for any behaviour change.
3. If you changed `cli/src/`, rebuild the committed output: `npm --prefix cli run build`, then `git add -f cli/dist` for new files (`npm --prefix cli run check:dist` verifies it).
4. Run the checks for what you touched:
   ```bash
   npm --prefix cli run typecheck
   npm --prefix cli run lint
   npm --prefix cli test
   make test          # TypeScript, Python and shell checks
   ```
   Live-stack suites: `make test-e2e GROUP=<group> SUITE=<suite>`.
5. Commit with a sign-off (`git commit -s`) and open the PR against `main`.

## Skills in the flisk repo

- Skills listed in `.claude/skills/LOCAL` are authored in flisk. The others (such as `flisk-doctor`, `flisk-troubleshoot`, `layer-autoresearch`) come from flisk-sh/flisk-skills: change them there first, then sync with `scripts/sync-flisk-skills.sh` (it expects a `flisk-skills` checkout next to flisk, or `FLISK_SKILLS_REPO`).
- `cli/templates/agent-skills/<name>/SKILL.md` is what `flisk project` writes into new projects. It must stay identical to `.claude/skills/<name>/SKILL.md`; `cli/src/utils/__tests__/agent-skills.test.ts` fails otherwise.

## Guardrails

- Never hand-edit generated output (`.flisk/`, `.flisk-out/`, `**/*.autogenerated.*`); change the generator or template.
- Run Biome through `npm --prefix cli run lint`, not a bare `npx biome` at the repo root.
- Remove `cli/test-results/` and `cli/coverage/` before linting.
- Never commit secrets or `.env`. Pause any tool that auto-commits working-tree changes while you experiment.