Development - m4bwav/everwrite GitHub Wiki

The repository's rules for contributors and agents are in AGENTS.md. This page collects the commands and where things live.

Layout

  • skills/everwrite/SKILL.md: the skill itself.
  • skills/everwrite/references/patterns.md: before and after examples, read in edit and detect mode.
  • skills/everwrite/scripts/tells.py: the checker; test_tells.py beside it is its self-test.
  • skills/everwrite/evals/: the eval cases (evals.json) and two fixtures.
  • skills/everwrite/ evergreen files: evergreen.json (state and schedule), RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md, MAINTENANCE.md.
  • .claude-plugin/: plugin.json, marketplace.json and the directory icon.
  • ai-docs/: notes left by past work sessions (INDEX.md, HANDOFF.md, log.md, decisions).

Checks

The self-test is a plain unittest file with no dependencies:

$ python skills/everwrite/scripts/test_tells.py
............................
----------------------------------------------------------------------
Ran 28 tests in 0.967s

OK

The run time varies; 28 tests passed on Python 3.14.6 and 3.9.25 on 2026-10-03.

The repository's own prose must pass its checker. Weak hits are allowed; the exit code must be 0:

$ python skills/everwrite/scripts/tells.py README.md AGENTS.md skills/everwrite/SKILL.md skills/everwrite/references

On 2026-10-03 it ended with tells: 0 strong, 8 weak, 1583 words, 4 file(s) and exit code 0.

CI

.github/workflows/tests.yml runs both checks on every push to master and every pull request. The matrix is Ubuntu, macOS and Windows, each with Python 3.9 and 3.13, six jobs in all.

Rules for changes

From AGENTS.md:

  • tells.py stays standard-library only, compatible with Python 3.9 and cross-platform, reading and writing UTF-8.
  • Every rule change gets a case in test_tells.py. A new strong rule is first tried on a few human-written documents, so it does not flag good prose (the skill's L-003).
  • Every regular expression gets a test with a pathological input that must finish quickly (L-004).
  • Quoted examples of tells go between <!-- tells: off --> and <!-- tells: on --> lines.
  • Every edit to SKILL.md or the checker gets a CHANGELOG.md entry with its reason, and the eval suite runs again after SKILL.md changes.
  • No AI attribution in commits or files, and no personal names beyond the author credit.

The eval suite

evals/evals.json holds eight cases: three triggers, two decoys that must not load the skill, two action cases and an outcome case. The last run (T-20260925-4, 2026-09-25) passed the 7 cases that existed then; action-2 was added later and has not run. The runs were headless Claude Code sessions (claude -p with stream-json output, a fresh folder per run, hooks off). The skill's LEARNINGS.md (L-005) has the exact command. A run costs about 0.2 to 0.3 USD per case.

Releasing

There is no release process yet: changes go to master, and plugin users get them from there. The version in .claude-plugin/plugin.json has stayed at 1.0.0 since the first release (see Versions and upgrading).