# AGENTS.md

Contributor and AI coding agent guidelines for Flisk.

Flisk runs a local development inner loop for microservices and multi-agent systems. Services that declare a `command` run as local processes with no Docker; container stacks run on Docker and Tilt. It discovers services from manifests, generates necessary local configurations (Vite, TSConfig, Compose), and orchestrates live-reloading environments. It is designed for fast local development; it does not emit Kubernetes manifests by default and does not replace production cluster orchestrators like Helm, Kustomize, Flux, or Argo.

## Repository Map

- `cli/`: TypeScript CLI implementation (`flisk`), Ink-based terminal UI, command handlers, and precompiled bundle (`dist/`).
- `runtime/engine/`: Tilt and Starlark topologies, generators, and infrastructure orchestration modules (`runtime/engine/topologies/`).
- `runtime/discovery/`: Starlark-based service discovery, multi-root manifest scanning, and registry generation.
- `runtime/ext/`: Tilt extensions, UI enhancements, and IDE components.
- `runtime/platform/`: Shared platform service definitions and topology templates (`runtime/platform/services/`).
- `docs/`: Architecture guides, tutorials, contributor documentation, and agent contracts (`docs/agents/`).
- `scripts/`: Shell, Node.js, and Python maintenance, verification, benchmark, and release scripts.
- `tests/`: End-to-end (e2e) tests, tilt-engine pytest suites, and test fixtures.

## Package-Level Guidelines

Before modifying specific subsystems, read their dedicated guidance files:

- Read `cli/AGENTS.md` before changing `cli/` for coding standards, naming conventions, export patterns, and `FliskError` usage.
- Read `runtime/engine/AGENTS.md` before changing `runtime/engine/` for topology architecture, manifest-driven generation, golden image layering, and Tilt conventions.
- Read `runtime/discovery/AGENTS.md` before changing `runtime/discovery/` for scan roots, manifest validation rules, and caching behavior.
- Subsystem directories under `runtime/engine/topologies/platform/` (such as `docker/`, `net/`, `security/`, and `state/`) contain additional targeted `AGENTS.md` files.

## Common Commands

Run checks from the repository root:

### CLI Verification

- Typecheck CLI: `npm --prefix cli run typecheck` (or `cd cli && npm run typecheck`)
- Lint CLI: `npm --prefix cli run lint` (autofix: `npm --prefix cli run lint:fix`)
- Test CLI: `npm --prefix cli test` (coverage: `npm --prefix cli run test:coverage`)
- Build CLI: `npm --prefix cli run build`
- Verify dist sync: `npm --prefix cli run check:dist`
- Quick one-liner (with Bun): `bun run typecheck && bun run lint && bun run test`

### Make Targets

Run `make help` to inspect all available targets:

- `make test`: Run TypeScript, Python, and shell checks.
- `make test-ts`: Run TypeScript CLI test suite.
- `make test-python`: Run Python test suite with pytest.
- `make test-shell`: Run Bash syntax checks on scripts and e2e suite definitions.
- `make test-e2e GROUP=<group> SUITE=<suite>`: Run a live-stack e2e test suite (requires Docker, Tilt, and built flisk).
- `make scores`: Print the deterministic scoreboard (`scripts/scores/README.md`). `make test-shell` fails when a gate or ratchet on it drops.

## Ground Rules

- Keep PRs focused: Address one specific issue or change per pull request. Avoid bundled refactors or unrelated formatting changes.
- Add tests for behavior changes: Every new feature, bug fix, or CLI behavior change must include automated tests in the same PR.
- Do not hand-edit generated files: Never edit `.flisk/`, `.flisk-out/`, `release-dist-*`, `**/*.autogenerated.*`, or `product_autogenerated_*`. Modify the source files (`service.json`, `package.json`, or templates) instead.
- Do not hand-write container manifests: Use the Flisk CLI to manage services:
  - Create services: `flisk resource <name> --type agent|backend|worker|mcp` or call the `resource_create` MCP tool
  - Start the stack: `flisk up [stack]` or call the `up` MCP tool
  - Inspect status: `flisk status --json` or call the `status` MCP tool
  - Inspect agent sessions: `flisk agent sessions <resource>` lists them (add `--watch` to refresh); `--session-id <id>` reads one checkpoint. The MCP tool `agent_sessions` takes an optional `sessionId` the same way
  - Restart services: `flisk restart <resource>` or call `resource_restart`
  - Check diagnostics: `flisk doctor --json`; check generated files with `flisk config verify --json` or the `config_verify` MCP tool
- Agent resource contracts: The `agent` resource type manages its own process contract (`/health` for liveness, `/ready` for checkpoint store reachable, `GET /sessions` lists stored sessions, session routing via `x-session-id`, checkpoints survive restarts).
- MCP integration: Use `flisk mcp` over stdio (`{ "command": "flisk", "args": ["mcp"] }`) for full MCP stack integration.
- Starter templates: Use `flisk project agent-stack` (MCP: `project_init` with `template: "agent-stack"`) to scaffold a complete multi-agent system with tools, database, and messaging.
- Local-only by default: Do not add Deployment or cluster manifest generators without an agreed export scope. Keep cluster deployment policy with the user's Kubernetes workflow. The one agreed export scope: `flisk export render`, `flisk export wrangler` and `flisk export compose` (opt-in) may generate `render.yaml`, `wrangler.toml` and a standalone `docker-compose.yml` (bring-your-own resources, runs without Flisk) from `service.json`. They write files only: they never deploy, never create DNS records, never call a cloud API, and write environment variable names, never values. Kubernetes manifests stay out of scope.
- Preserve diagnostics boundaries: Maintain the distinction between `flisk doctor` environment/service checks and `flisk config verify` generated-project consistency checks.
- Database migrations: New services, examples, and fixtures must run database migrations in an explicit `migrator` resource (`appType: migrator`), not from an API start script or entrypoint.
- Agent contracts location: Agent-facing contracts (`llms.txt`, `llms-full.txt`, and the AI agents guide) live in `docs/agents/`; keep them there, not in the repo root.
- The one-command demo is P1: `npx @flisk-sh/flisk demo` is the first thing a new user runs, so a regression in it outranks every other task. Its CI suite is `tests/e2e/journeys/demo` (check "🎬 Demo command, run twice"). It runs the demo twice, because the second run meets the first run's Docker volumes, and runs it with Docker not running (cases N1-N3), where the demo must fall back to the two-service app as local processes (`cli/src/utils/native-demo.ts`, `cli/templates/demo-native/`). Native Windows runs that fallback too (`tests/e2e/platforms/windows` W5). Keep it passing, and extend it when the demo's behaviour changes.
- Never commit secrets or `.env`: Keep credentials, API keys, and environment overrides out of version control.
- Sign off commits: All commits must be signed off (`git commit -s`) to comply with the Developer Certificate of Origin (DCO).

## Verification Gotchas and Traps

- Stale `cli/dist/`: The CLI is committed as compiled output in `cli/dist/`. When modifying `cli/src/`, always run `npm --prefix cli run build` (or `npm --prefix cli run check:dist`). Newly emitted files in `cli/dist/` are gitignored by default; force-stage them with `git add -f cli/dist`.
- Biome execution: Run Biome through `npm --prefix cli run lint` or `cd cli && ./node_modules/.bin/biome check .`. Do not run bare `npx biome` at the repository root, which executes an obsolete package that exits 0 without checking.
- Clean test artifacts before linting: Running tests with coverage creates cli/test-results/ and cli/coverage/, which cause Biome checks to fail. Remove these directories before running `biome check .`.
- Repository memory: Check `.claude/memory/MEMORY.md` before opening a PR for an up-to-date list of verification and CI traps observed across previous runs. Add a line when a task uncovers a new trap.