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
- MortisDei/hermaeustheir own version, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- MortisDei/hermaeus★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-repository-methodSkill
- finish-phaseSkill
- fix-a-bugSkill
- refresh-the-picturesSkill
- retrospectiveSkill
- update-the-design-pageSkill
- write-a-commitSkill
- write-a-docSkill
- write-an-e2e-scenarioSkill
- write-a-specSkill
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
- Very specific: line 122
Before sketching a new poster or screen, open the committed PNGs in docs/posters/ and look at them.
- Very specific: line 140
Every file gets a spec beside it, and everything it imports is mocked.
- Very specific: line 142
Every user-readable string lives in copy.en.ts and copy.ru.ts and nowhere else, and a copy function interpolates rather than decides — …
≈ “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.
Files
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, rasterizingbot 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 withmenuDescriptionandhelp, both read fromcopyIn(locale)./helpand the/menu are generated from this one list, so they cannot drift from what is installed.hidden: truekeeps a command out of both while still registering it, which is how the installer filters twice from a single list.listen— optional, receives a narrowListenerswith onlyonTextandonTap.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 — aresumethat 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 callingnext()silently swallows every command below it. The installer registers commands first, then listeners, and callsnext()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. onTaptakes the pattern the feature owns, not just a handler:listeners.onTap(MERGE_TAPS, handler). A barebot.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.jsonimports:"#<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 thefeaturesarray.main.spec.tsis 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 toregexpatterns instead; no-restricted-importsreads only a staticimport, so every file loading its subject withawait import("…")— almost every spec here — passed every zone. The bans compile intono-restricted-syntaxtoo, 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-specskill before writing them. - Every user-readable string lives in
copy.en.tsandcopy.ru.tsand nowhere else, and a copy function interpolates rather than decides —CLAUDE.mdhas 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_datagets e2e scenarios; seee2e/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.mdsection. Thefinish-phaseskill 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:
- Delete the folder and run
node scripts/gates/gate-runner.ts typecheck. Anything that stops compiling outsidesrc/main.tsandsrc/main.spec.tsis the finding, and its path names the coupling. Restore afterwards; the probe is the point, not the deletion. - Does the folder name say what the player gets, or an internal noun?
- Does
commandslist one entry per thing the feature gives the player, so/helpand the/menu cannot drift from what is installed? - 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.
- Can the pattern passed to
onTapmatch another screen'scallback_data? - 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.
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
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.

