ainurdevainurdev/mystical-assistant/.claude/skills/bridge-feature-slice/SKILL.md

bridge-feature-slice

Skill7 starsChanged 7 days agoMITView on GitHub

Use when adding or changing a capability in this repo that users should reach — a new endpoint, panel, command, or piece of session data. Names every file the change has to touch across the bot, the Mini App and the dashboard, in order, so a surface doesn't get left behind. Use before writing code, not after.

Reads credentials

In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- accessibility-auditSkill
- algorithmic-artSkill
- api-docsSkill
- beautiful-shadowsSkill
- brainstormingSkill
- bridge-eyesSkill
- bridge-shipSkill
- bridge-worktreeSkill
- changelogSkill
- color-paletteSkill
- content-strategySkill
- design-firstSkill
- design-implementSkill
- design-reviewSkill
- design-tokensSkill
- emil-design-engSkill
- empty-statesSkill
- frontend-designSkill
- landing-pageSkill
- micro-interactionsSkill
- mystical-assistant-designSkill
- ogilvy-copywritingSkill
- onboarding-guideSkill
- typography-scaleSkill
- visual-style-presetsSkill
- writing-guidelinesSkill

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Two servers, one shape: If the dashboard and the Mini App return different JSON for the same concept, the next feature that reads it has to …
line 43

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Wiring a capability across the three surfaces

A feature here is never one file. The same capability has to reach a Telegram chat, a phone-sized Mini App and a desktop dashboard, each with its own server, its own client and its own auth. Leave one out and the product quietly disagrees with itself.

The slice, in order

Trace an existing feature before you start — attribution / "breakdown" is a clean, recent one to copy:

#	Layer	File	Rule
1	Logic	`bridge/<feature>.py`	Stdlib only. Module docstring says why, including what you chose not to build. Best-effort features swallow their own errors — nothing may raise into the turn lifecycle.
2	Storage	`bridge/store.py`	Only if it must outlive the process. SQLite; migrations live here too.
3	Dashboard route	`bridge/dashboard/server.py` → `_get_api()` / `do_POST`	`self._json(...)`. POST is gated on Host + Origin + `X-Dash-Token`.
4	Mini App route	`bridge/miniapp/server.py`	Same data, `/api/...` prefix, auth is a validated `X-Telegram-Init-Data`.
5	Dashboard client	`bridge/dashboard/web/src/api.ts`	Typed `req<T>`; export the interface.
6	Mini App client	`bridge/miniapp/web/src/lib/api.ts`	Typed `request<T>`.
7	Dashboard UI	`bridge/dashboard/web/src/components/hud/`	HUD panel — see the `mystical-assistant-design` skill.
8	Mini App UI	`bridge/miniapp/web/src/components/`	Sheet/tab, 390px-first.
9	Bot	`bridge/dispatch.py`	Only if it deserves a slash command. Add it to `HELP` in the same edit — an undocumented command doesn't exist.
10	Live updates	`bridge/pubsub.py`	Only if it changes mid-turn: `publish("session:<id>", …)`, consumed over SSE.
11	Tests	`tests/test_<feature>.py` + `tests/test_<feature>_endpoint.py`	Logic and route tested separately.

Skipping a row is fine when it genuinely doesn't apply — skipping it by forgetting is the failure. State which rows you're skipping and why.

Rules that only apply here

The client may be newer than the server. Users run a dashboard built from new code against a bridge process still running old code, so a brand-new route 404s. Both SpendPanel.tsx and SpendSheet.tsx handle exactly this — copy that pattern for any new endpoint, and say "restart the bridge" in the UI rather than rendering a broken panel.
Two servers, one shape. If the dashboard and the Mini App return different JSON for the same concept, the next feature that reads it has to special-case both. Reuse the function from bridge/<feature>.py in both routes; don't reshape in the route.
Config is frozen at import. bridge/config.py reads os.environ once. A new setting goes there (and in .env.example, which tests/test_env_example.py enforces), never read ad-hoc from os.environ at call time.
Route matching is manual string work — path == "/local/x" and path.startswith(...). Order matters: a startswith above a more specific path will swallow it. Put the specific case first, as /breakdown is.

Verify

python3 -m pytest tests/ -q — green.
Both routes answer: curl -s 127.0.0.1:8790/local/<x> (the Mini App needs forged init-data — see bridge-eyes).
Both UIs render it — bridge-eyes for the screenshots.
It's live at all: bridge-ship.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free