Flisk candidate test: four labs

Goal: feel what a new user feels. This is the most important lab: the demo is the first thing a new user runs.

Do

npx @flisk-sh/flisk demo

1. Run the demo. Note how long until you see something working, and every moment of doubt.
2. Run it a second time. The second run meets the first run's data and volumes.
3. Stop Docker and run it again. The demo should fall back to running the two-service app as plain local processes.

Evidence

• Timings for run 1, run 2 and the no-Docker run, in LOG.md.
• Three things that confused you, each with a one-line fix you would make.

We check

Can you observe a product honestly? Do you separate "I made a mistake" from "the product misled me"?

Goal: create a multi-service system with Flisk, without hand-writing container files.

Do

flisk project agent-stack      # a starter with tools, a database and messaging
flisk resource my-api --type backend
flisk up
flisk status --json

1. Scaffold the agent stack. Add one extra resource of your own (type backend, worker, agent or mcp) that does something small but real.
2. Bring everything up and show that your new resource talks to another one.
3. If you need a database schema, use a separate migrator resource (appType: migrator), not your API's start script.

Rules

• Do not hand-write container manifests and do not edit generated folders such as .flisk/. Change service.json or the templates instead.
• Do not commit secrets or .env files.

Evidence

• Your repository, with a README that lets a stranger run it in under ten minutes.
• The output of flisk status --json with everything healthy.

We check

Can you build something that works, and explain it to someone who has never seen it?

Goal: debugging is most of the job. Show that you can find a fault using the tools Flisk gives you.

Do

flisk doctor --json            # environment and service checks
flisk config verify --json     # are the generated files consistent?
flisk logs                     # what the services say
flisk restart my-api

1. Break your system in three different ways. For example: a wrong port, a service that depends on one that is not up yet, and a missing environment variable.
2. For each: show the symptom, find it with doctor, config verify or logs, and fix it.
3. Write down which tool pointed at the cause fastest, and which message was unclear or wrong.

Evidence

• A table in LOG.md: fault, symptom, command that found it, fix, minutes spent.
• At least one error message you think Flisk should say better, with your proposed wording.

We check

Do you reason from evidence? Do you know the difference between an environment problem (doctor) and a generated-files problem (config verify)?

Goal: ship one improvement, or a clear plan for one. Pick one option.

Option A: Feature proposal and prototype

Propose one feature or fix that helps AI agents or developers. Give: why it matters, how it works (user experience and technical), acceptance criteria. Build a prototype, or a detailed design with code or pseudocode.

Option B: Integration

Connect Flisk to one AI or developer tool (for example Claude Code, Cursor, Windsurf, Continue, Aider) through the MCP server:

{ "command": "flisk", "args": ["mcp"] }

Show an agent starting the stack, checking status and restarting a service on its own. Record what worked and what the agent got wrong.

Option C: Companion tool

A small separate tool, agent or CLI wrapper that uses Flisk and adds value on top.

Evidence

• A pull request to flisk-sh/flisk is best. A fork or your own repository is fine.
• Tests for whatever you change. A change without a test is not finished.
• Commits signed off (git commit -s).

We check

Does the idea fit what Flisk is (a fast local inner loop, not a production cluster tool)? Is it small enough to merge, and clear enough to review?