stario-create

The project tool and agent guidance for building apps with Stario. This repo tracks Stario 5. The framework itself lives at bobowski/stario.

Two things ship from here:

• The stario-create CLI (uvx stario-create, or uv tool install stario-create). It scaffolds apps and keeps their guide and skills in sync.
• The files it installs: AGENTS.md (the always-on guide an app keeps at its root) and skills/<name>/SKILL.md (on-demand procedures an agent loads when the task matches).

New app

uvx stario-create new my-app
cd my-app
just dev     # http://127.0.0.1:8000, reloads on change
just check   # lint, format, types, tests — run before done

new gives you a tested, runnable app:

• A uv project on Python 3.14 with stario>=5.1,<6 and the dev tools.
• The feature-folder layout with one static home screen.
• static/js/datastar.js vendored.
• AGENTS.md at the app root (Claude Code reads it directly).
• The four skills installed into .agents/skills/ and linked from .claude/skills/.
• A justfile (dev, serve, check, fix, test). Without just, the recipes are plain commands — run them directly.
• The app's own tests, run once so the scaffold starts green (--no-verify skips that).

new takes --dir to pick the parent directory, --force to write into a non-empty one, and --orjson to add orjson and set it as the stario.json codec.

Syncing an app

Run this at the app root:

stario-create sync           # refresh AGENTS.md and the skills
stario-create sync --check   # exit 1 when the guide or a skill is stale

sync rewrites AGENTS.md to the bundled guide and keeps your ## This app notes at the end. It overwrites each .agents/skills/<name>/SKILL.md and relinks .claude/skills/<name>. It prints one line per file changed, or "up to date".

Without the CLI

To build an app by hand, the pyproject.toml needs these blocks:

[tool.ruff]
target-version = "py314"
line-length = 100
src = ["app", "tests"]
extend-exclude = [".agents", ".claude", ".cursor"]

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]

[tool.ruff.lint.isort]
known-first-party = ["app"]

[tool.pyright]
pythonVersion = "3.14"
include = ["app", "tests"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["."]
asyncio_mode = "auto"

Stario does not read .env. Configure with environment variables; serve reads STARIO_* through ServerConfig.from_env(). STARIO_PORT changes the port.

The guide and the skills are also at https://stario.dev/AGENTS.md and via npx skills add bobowski/stario-create.

Skills

npx skills add bobowski/stario-create also works — it reads the skills/ tree at this repo root.

Served copies

stario.dev serves these files: /AGENTS.md, /llms.txt, /llms-full.txt (the guide and the skills in one file), /skills/, and /skills/<name>/SKILL.md.

Repo layout

AGENTS.md, llms.txt, and skills/ sit at the root. npx skills, stario.dev, and repo browsing all read them there. The wheel embeds copies under stario_create/_data/ (hatchling force-include), so uvx works without a checkout. In a checkout the CLI reads the root files directly, so each file has one canonical copy.

Changing the guide

The guide is checked against real code: examples/chat-room in the stario repo follows it. When a rule changes here, change the example there and run its tests. A snippet in AGENTS.md must run as written — the package tests scaffold a project and compile every generated file, and stario-create new runs the new app's tests.