flisk-sh/flisk

Ground rules and the CLI-to-MCP command map for a coding agent (Claude Code, Cursor, Codex) working in a Flisk project - create services with flisk resource instead of hand-writing Dockerfiles, Compose files or manifests, keep the agent resource contract, and drive the stack with --json commands or the flisk mcp tools (doctor, up, status, logs, resource_restart, agent_list, agent_sessions, down). Use when about to write container config by hand or when you need the MCP tool for a CLI command. For building a whole app from a request, use flisk-build.

Turn a plain request such as "build me a small online shop", "a SaaS with login and billing", "an AI agent with MCP tools and a database" or "a blog with an admin API" into Flisk steps (flisk project, flisk resource ... --type ... --stack ..., flisk up), check that every URL is healthy, and tell the user where the app is. Use when the user asks you to build, scaffold or run a new app on their laptop with Flisk.

Convert any existing app (Node, Python, Go, Rust, Bun, a static site, a Docker Compose or Procfile project, a monorepo) to run with Flisk, so flisk up starts it locally. Picks the right path (local processes, bring-your-own container, or flisk import), writes the service.json files with the CLI, and checks every URL. Use when the user says "convert this app to Flisk", "run this with Flisk", "add Flisk to this repo" or "move my Compose setup to Flisk". For a new app from a plain request, use flisk-build.

Check or repair the local Flisk development environment and project configuration using flisk doctor (including --all, --json and --fix). Use when setting up a Flisk project, before running flisk up, or when Docker, Tilt, Bun, ports, Docker networks, generated files or service manifests may be misconfigured. For a stack that started and then failed, use flisk-troubleshoot instead.

Recipe for "build me an AI agent with MCP tools and a database" with Flisk - an agent service with sessions, an MCP tools server and a backend with a database in one stack, started with flisk up. Use with the flisk-build skill when the user asks for an AI agent, chatbot, assistant, MCP server or tools for an agent.

Recipe for "build me a blog with an admin API" with Flisk - a public blog site and a posts API with a database and token-protected admin routes, in one stack started with flisk up. Use with the flisk-build skill when the user asks for a blog, a CMS, a news site or any site with an editor.

Recipe for "build me a SaaS with login and billing" with Flisk - a web app, an accounts API with a database for sign-up and login, and a billing API, in one stack started with flisk up. Use with the flisk-build skill when the user asks for a SaaS, a members area, subscriptions, sign-up or payments.

Recipe for "build me a small online shop" with Flisk - a storefront website and an orders API with a database in one stack, started with flisk up and checked URL by URL. Use with the flisk-build skill when the user asks for a shop, store, catalogue or anything with products and orders.

Start from a ready-made Flisk starter app instead of an empty project when the request matches one - restaurant (reservations, kitchen, menu, floor), SaaS (dashboard, billing, checkout), online store, AI agent stack (agent, MCP tools, database), user management (admin, portal, audit), or a small orders example. Clones it with flisk project <template> and starts it. Use with the flisk-build skill.

Add one service to an existing Flisk project with flisk resource <name> --type frontend|backend|worker|agent|mcp --stack <stack>, or wrap an existing Dockerfile or image with --type bring-your-own. Use when the user asks to add a service, website, agent, MCP tools server, worker or backend. For a whole new app from a plain request, use flisk-build; to start it, use flisk-up.

Report the state of Flisk stacks and resources with flisk status --json, and list or read agent sessions with flisk agent sessions. Use when the user asks what is running, which URLs are healthy, or why a service is not responding. To start a stack, use flisk-up; to fix one that failed, use flisk-troubleshoot.

Diagnose a Flisk stack that fails after flisk up starts it - red or pending Tilt resources (golden image "pull access denied", run-only "No such image", missing shared-platform-engineering files, TS2688 bun types), Postgres crash loops, services that never turn healthy, "Docker daemon is not responding", flisk up or flisk down hanging, or a machine overloaded by many containers. Use when something in a running Flisk project is broken or slow. For setup checks before the first flisk up, use flisk-doctor; for measuring memory and scale, use flisk-benchmark.

Start a Flisk stack with flisk up, preview it first with flisk up <stack> --dry-run, and confirm the healthy URLs. Use when the user asks to run, start, or bring up their local services, or after changing service.json files. To check a stack that is already running, use flisk-status; when it fails, use flisk-troubleshoot.