agentleFS
oleg-vasilyevoleg-vasilyev/FoolProof/.claude/skills/add-a-feature/SKILL.md

add-a-feature

Skill2 starsChanged 52 days agoMITView on GitHub

Add a new feature folder to FoolProof — the layers, the feature contract (commands, listen, resume), the two places a feature is named, the lint zone that fences it off, and the hazards the installer exists to prevent. Stage 1 work, before a line is written — use when adding a command or a screen that is not part of an existing feature, or when changing what a feature declares to the installer.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are 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.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before sketching a new poster or screen, open the committed PNGs in docs/posters/ and look at them.

    line 122
  2. Very specific:

    Every file gets a spec beside it, and everything it imports is mocked.

    line 140
  3. Very specific:

    Every user-readable string lives in copy.en.ts and copy.ru.ts and nowhere else, and a copy function interpolates rather than decides — …

    line 142

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Adding a feature

Stage 1 of how a change becomes a release.

A feature is a folder you can delete. Removing features/scoresheet/ must leave the rest compiling and passing, and adding one must not require editing another. Outside the folder it costs package.json, src/main.ts and the one spec that is supposed to know the roster — and every step below serves that.

Name the folder after what the player gets, not after an internal noun: live-game/ is the game running right now on a card of buttons, merge-names/ is the screen that makes two names one player. A folder called players/ or handlers/ is a bucket, and the next feature will be dumped in it.

1. The layers, and imports point downward only

features/<name>/
  <name>-feature.ts   the entry point: builds the parts and declares the commands
  <name>-drawings.ts  only if it draws: what the tools may draw of it, and the
                      tools it lends them — #shared/drawings/drawings-contract.ts
  copy.en.ts          every string this feature shows a user
  domain/             the pure core — no framework, no I/O, no rendering
  render/             state in, message text and SVG out; still pure
  samples/            only if it draws: the states worth drawing at
  bot/                the impure edge: grammY handlers, debouncing, rasterizing

bot may reach render and domain; render and samples may reach domain; domain reaches nothing. A feature that draws nothing has neither "only if" file, and one that does may still not be imported from scripts/: the tooling asks through the contract and finds the module by its name at run time, which is what keeps the folder deletable. Skip a layer with nothing in it rather than leaving it empty — diagnostics/ has no domain/ because it decides nothing.

The entry point sits at the feature root, not inside a layer. It is the feature's composition root, the same job src/main.ts does one level up, so opening the folder shows what the feature is before how it works.

Two ways to name that subfolder wrong, both paid for here. A bucket — helpers/, common/, a second shared/ inside a feature — is the vagueness the file names were cured of. A process name is worse than it looks: bot/opening/ reads fine to whoever has just split the folder and tells everybody else nothing, because opening is not something the player ends up holding. Name it after the thing they do hold — a picture, a screen, an entity the commands are about.

check-docs fails a layer root above nine files, which is unambiguous crowding rather than a real limit — the fix is always a named subfolder, never a bigger number. It is a late alarm on purpose: seven fired on a folder that needed no split, so the question is the rule and the count only makes somebody ask it.

2. What the feature declares

A feature does not get the Bot. It returns a Feature (shared/telegram/feature-contract.ts):

  • commands — each with menuDescription and help, both read from copyIn(locale). /help and the / menu are generated from this one list, so they cannot drift from what is installed. hidden: true keeps a command out of both while still registering it, which is how the installer filters twice from a single list.
  • listen — optional, receives a narrow Listeners with only onText and onTap.
  • resume — optional, called once after the commands are installed and before polling starts: the seam for catching up on whatever the previous run left behind. It may never be the reason the bot fails to start — a resume that throws is logged and skipped.
  • stop — optional, for a timer or a pending edit that must be flushed.

Two hazards this contract exists to prevent, both of which have already happened here:

  • Commands must be registered before any bot.on("message:text") filter, or a text handler that returns without calling next() silently swallows every command below it. The installer registers commands first, then listeners, and calls next() after each text listener — which is what lets a second feature hear text at all; a scenario replying to the other feature's question proves it.
  • onTap takes the pattern the feature owns, not just a handler: listeners.onTap(MERGE_TAPS, handler). A bare bot.on("callback_query:data") per feature meant the first feature registered saw every tap and answered "Card updated" for data that was never its own — the second feature's buttons were dead before they were written. Export the pattern from the feature's own codec and make sure it cannot match another screen's data. A tap matching nothing is answered by the installer itself.

3. Name it in exactly two places

  • package.json imports: "#<name>/*": "./src/features/<name>/*". These are Node's own subpath imports, the only aliasing that survives having no build step, and one declaration serves the compiler, Node, Vitest and Stryker's sandbox.
  • src/main.ts: build it and put it in the features array. main.spec.ts is the one spec that is supposed to know the roster, so it changes too.

There are no relative imports in src/ — not even for a sibling file. The value of the rule is that every import line reads the same way.

4. Fence it off, and prove the fence

Nothing to add: eslint.config.js reads src/features/ from disk, so the folder you just made already has its zones — domain/, render/ and samples/ may not import a framework or reach upward, and none may reach into another feature or #app/.

A zone is not finished until a deliberate violation has been shown to fail the lint. Write a throwaway file in each new zone that imports something banned, run the lint gate on it, see it fail, delete it. Zones have shipped here that never fired, every one of them silently:

  • a later flat-config block replaces an earlier one for a file matched by both, so purity and independence have to be one pattern list per zone;
  • minimatch reads a leading # as a comment, so #live-game/** matches nothing — alias bans are compiled to regex patterns instead;
  • no-restricted-imports reads only a static import, so every file loading its subject with await import("…") — almost every spec here — passed every zone. The bans compile into no-restricted-syntax too, so a static-only probe proves half.

5. If the feature draws anything, open the drawings first

Before sketching a new poster or screen, open the committed PNGs in docs/posters/ and look at them. Not the renderer, not the palette module — the pictures. The visual language here is carried by things no source file states: sheets run past two thousand pixels tall, sections are dense, a row is a numbered index plus a coloured spine plus a title plus a muted reason, and the headline bad news is a full-width red plate.

A mockup drawn from reading palette.ts and card-metrics.ts came back from the owner twice, and the fix both times was already sitting in docs/posters/awards-en.png. Two Read calls would have skipped both rounds.

Then draw the mockup with the real renderer as soon as one exists, and look at the rasterized PNG yourself before asking anybody else to. The two defects that survived into review — an axis with a single label, and a sheet 36px past IMAGE_MAX_HEIGHT — were both visible in the picture and invisible in the code.

6. Tests, copy, and how big the phase is

  • Every file gets a spec beside it, and everything it imports is mocked. Load the write-a-spec skill before writing them.
  • Every user-readable string lives in copy.en.ts and copy.ru.ts and nowhere else, and a copy function interpolates rather than decides — CLAUDE.md has why.
  • Freeze a refusal union against the copy lines it will be spoken with: every argument a refusal's line interpolates is a field of that union member, not something the handler digs up afterwards.
  • A keyboard whose buttons carry callback_data gets e2e scenarios; see e2e/README.md. A URL button does not earn one on its own — nothing routes back to the bot, so there is no dispatch to prove.
  • A new feature that adds a repository method or a screen with states is a contract-changing phase: it owes a PLAN.md section. The finish-phase skill has the table and the gates.

Judging a folder you did not add

The feature's defining property is mechanical, so test it rather than reading for it. Ask in this order — the first is worth the other five:

  1. Delete the folder and run node scripts/gates/gate-runner.ts typecheck. Anything that stops compiling outside src/main.ts and src/main.spec.ts is the finding, and its path names the coupling. Restore afterwards; the probe is the point, not the deletion.
  2. Does the folder name say what the player gets, or an internal noun?
  3. Does commands list one entry per thing the feature gives the player, so /help and the / menu cannot drift from what is installed?
  4. Was a deliberate violation shown to fail the lint for each new zone? A zone that never fires looks exactly like one with nothing to report.
  5. Can the pattern passed to onTap match another screen's callback_data?
  6. Does anything in scripts/ now import this feature? It may not — the tooling asks what features offer and finds them at run time; naming its folder is allowed.

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.