agentleFS
Hermione-Granger-1176Hermione-Granger-1176/artifacts/CLAUDE.md

artifacts

CLAUDE.md2 starsChanged 29 days agoMITView on GitHub

This repository contains interactive HTML artifacts built with AI tools and hosted on GitHub Pages. pyproject.toml defines the canonical site URL under [tool.artifacts]. AGENTS.md is a symlink to this file, so agents share one set of repository instructions. Each artifact has an apps/<slug>/index.html entry point. Metadata lives beside it in name.txt, description.txt, tags.txt, and tools.txt. The root index.html is the gallery, with searchable thumbnails, filters, theme persistence, and detail overlays. The main directories are: Workspace structure owns the full layout…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

17 rules. About 0 are common, 8 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

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

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

    Use make <target> for workspace tools and GitHub actions.

    line 7
  2. Very specific:

    If a target is missing, add it before using the tool.

    line 8
  3. Distinctive:

    Read the Makefile and existing code before proposing changes.

    line 9
  4. Distinctive:

    Keep each tool's scope in its owning configuration file.

    line 10
  5. Very specific:

    Run auto-fix commands only when the user asks.

    line 11
  6. Distinctive:

    Commit, push, open PRs, or merge PRs only when the user asks.

    line 12
  7. Distinctive:

    Before adding or modifying an artifact, verify its behavior or calculations at least once.

    line 13
  8. Distinctive:

    Use one of the two scaffold inputs:

    line 32
  9. Distinctive:

    After the scaffold, complete these steps:

    line 43
  10. Distinctive:

    Verify its behavior or calculations.

    line 46
  11. Very specific:

    Run make validate and the relevant checks in Operations.

    line 47
  12. Very specific:

    Use the make pr-*, make issue-*, and Git targets.

    line 69
  13. Very specific:

    Use kebab-case artifact directory names and index.html entry points.

    line 132
  14. Very specific:

    Use the tokens in css/src/01-tokens.css and the themed colors in css/src/01-theme-light.css and css/src/01-theme-dark.css, plus the …

    line 135
  15. Very specific:

    Keep app behavior in apps/<slug>/js/app.js and app-local modules.

    line 136
  16. Very specific:

    Use the shared bookmark-note palette.

    line 137
  17. Distinctive:

    Keep Markdown paragraphs on one line.

    line 138

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
CLAUDE.md

CLAUDE.md

This repository contains interactive HTML artifacts built with AI tools and hosted on GitHub Pages. pyproject.toml defines the canonical site URL under [tool.artifacts]. AGENTS.md is a symlink to this file, so agents share one set of repository instructions.

Required workflow

  1. Use make <target> for workspace tools and GitHub actions. Do not run .venv/bin/*, pytest, ruff, mypy, npm run, npx, tsc, playwright, gh, or git directly. make git lists Git targets. Run make help to find command groups, then make help-<group> to list a group's targets.
  2. If a target is missing, add it before using the tool. Put it in the mk/*.mk file for its make help group, and add ## description after the target name so generated help includes it.
  3. Read the Makefile and existing code before proposing changes. Reuse existing behavior and helpers.
  4. Keep each tool's scope in its owning configuration file. Use roots, globs, and exclusions so new files are discovered automatically. Do not duplicate source-file lists in targets, workflows, and configuration files. Configuration-file path references are allowed.
  5. Run auto-fix commands only when the user asks. These include make align-tables, make fmt, make format, and make fix.
  6. Commit, push, open PRs, or merge PRs only when the user asks. Otherwise, make and verify changes in the working tree. Keep small tooling and documentation changes on the current branch unless the user requests a separate branch or worktree.
  7. Before adding or modifying an artifact, verify its behavior or calculations at least once.

Repository structure

Each artifact has an apps/<slug>/index.html entry point. Metadata lives beside it in name.txt, description.txt, tags.txt, and tools.txt. The root index.html is the gallery, with searchable thumbnails, filters, theme persistence, and detail overlays.

The main directories are:

  • apps/: artifact implementations, metadata, and app documentation.
  • scripts/: Python tooling grouped under build, ci, gh, lib, lint, and setup. Tests enforce 100% line and branch coverage.
  • tests/: matching Python groups, Playwright suites under browser, and Node suites under js.
  • js/ and css/: gallery code, shared app modules, and styles.
  • config/: tool configuration, gallery metadata, the artifact contract, and audit policy.
  • docs/: workspace documentation and architecture decision records.

Workspace structure owns the full layout and file-ownership reference.

Add an artifact

Use one of the two scaffold inputs:

  1. For a new placeholder, run make new name=my-artifact.
  2. For an existing HTML file, run make new name=my-artifact src=path/to/file.html instead.

Both inputs create metadata files, css/app.css, js/app.js, a README, architecture and verification docs, decision notes, and tests/js/apps/<slug>/app.test.js.

The placeholder includes the shared stylesheets, app shell, and self-only CSP. It passes validation, lint, dead-code, type, and JS test-import checks without manual edits.

The import preserves supplied HTML. It adds the CSP and shared stylesheet links when absent and reports off-origin script or style references. Vendor or remove those references before the CSP check. Shared app-shell wiring is optional for a self-contained import. Keep the generated js/app.js and its test, or replace them with your own module and test.

After the scaffold, complete these steps:

  1. Build the artifact and fill in its metadata.
  2. Verify its behavior or calculations.
  3. Run make validate and the relevant checks in Operations.

For user-provided artifacts, prefer the src= import and metadata edits. Avoid unrelated refactors. CI generates thumbnails, so missing local thumbnails do not block the contribution. Push only when authorized.

Local commands

The Makefile generates help from target descriptions and section headers. make help-json exposes the same groups and commands as JSON.

The main entry points are:

  • make setup: install Python and Node dependencies without Chromium. Setup requires uv on PATH.
  • make setup-all: also install Chromium. Use it when browser work is required.
  • make setup-playwright-local: prepare Chromium and local libraries on Debian or Ubuntu without sudo. make setup-playwright-webkit-local adds WebKit. Browser targets use the prepared libraries with local_libs=1.
  • make ci: run the complete non-browser local gate.
  • make ci-fast: run parallel non-browser checks, followed by generated-file checks. This target omits per-file JS coverage floors. Run make coverage-js-floors afterward to check those floors.
  • make check: run the full local gate, including browsers, thumbnails, index generation, and site assembly. make check-web runs the browser and thumbnail checks.
  • make status: inspect Git state, dependencies, lockfiles, generated files, and the PR summary.

Operations describes command selection, CI behavior, browser setup, and recovery.

GitHub commands

Use the make pr-*, make issue-*, and Git targets. The PR number defaults to the current branch's PR. Override it with pr_num=N. Do not pass raw CLI flags such as --jq to Make targets.

make pr-review-comments prints thread=PRRT_... identifiers. Pass the identifier to the reply or resolution target.

The commands with less obvious argument patterns are:

TaskCommand
List review threadsmake pr-review-comments [pr_num=N]
Reply to a threadmake pr-reply thread=PRRT_... < reply.md
Reply and resolvemake pr-address thread=PRRT_... < reply.md
Resolve a threadmake pr-resolve thread=PRRT_...
Comment on a PRmake pr-comment [pr_num=N] < comment.md
Comment on an issuemake issue-comment issue=N < comment.md
Create an issue branchmake issue-develop issue=N
Create a stacked branchmake branch name=my-feature base=current-branch
Create a worktreemake worktree name=my-feature [base=branch]
Remove a worktreemake worktree-remove name=my-feature
Commit staged workmake commit < message.txt

Supply multiline messages on stdin through a heredoc or file redirect. Do not pass prose as Make arguments. For short fields, use environment variables such as TITLE='...', SEARCH='...', or COMMENT='...' with the relevant target.

Tool configuration

Each tool has one configuration file that owns its scope. The Makefile calls the tools.

ToolConfigurationScope
ruffpyproject.tomlPython lint and format rules
pytestpyproject.tomlTest paths and 100% coverage for scripts/
ESLintconfig/eslint.config.jsJS patterns, ignores, and rules
stylelintconfig/stylelint.config.jsCSS rules and ignores
yamllint.yamllint.ymlYAML rules and ignores
JS coveragepackage.jsonThresholds and exclusions
TypeScriptconfig/jsconfig.jsonStrict checks for authored JS
mypypyproject.tomlStrict checks for scripts/
Prettierconfig/prettierrc.jsonMetadata, workflows, and tooling format
Knipconfig/knip.jsonUnused JS files, exports, and dependencies
vulturepyproject.tomlUnused Python code
EditorConfig.editorconfigSettings by file type
pre-commit.pre-commit-config.yamlHook checks
esbuildpackage.jsonCSS and JS minification during site assembly

Python declarations and workspace metadata live in pyproject.toml. uv.lock and package-lock.json record the frozen dependency graphs. Change lint, test, and type scope in the owning tool configuration.

Generated files

Change the inputs or generator for these outputs. Do not edit the outputs by hand:

  • js/data.js and js/gallery-config.js, generated by scripts/build/generate_index.py.
  • css/style.css, generated from css/src/ by scripts/build/generate_styles.py.
  • apps/*/thumbnail.webp, generated by scripts/build/generate_thumbnails.py.
  • _site/, assembled by scripts/build/prepare_site.py.
  • Auto-managed marker sections in README.md.

Deployment

Pushes to main trigger the GitHub Actions deployment to GitHub Pages. Trusted PRs (same repository, excluding Dependabot) receive previews under gh-pages/pr-preview/pr-<number>/ and a preview-link comment on each push.

CI manages gh-pages. Do not edit it manually. Deployments use GitHub App tokens and verified GraphQL commits. Architecture describes the pipeline, token roles, and deployment records.

App conventions

  • Use kebab-case artifact directory names and index.html entry points.
  • Load css/style.css in the gallery. In mature apps, load ../../css/style.css before ./css/app.css.
  • Reuse js/app-theme.js, js/modules/app-shell.js, and the other shared modules in js/modules/, such as formatting.js, segmented.js, section-nav.js, and chart-theme.js.
  • Use the tokens in css/src/01-tokens.css and the themed colors in css/src/01-theme-light.css and css/src/01-theme-dark.css, plus the components in css/src/04-artifact-components.css before adding app-local CSS. Shared families include .control-field, .stat, .chip, .segmented, .meter, .app-callout, .section-kicker, and .section-nav.
  • Keep app behavior in apps/<slug>/js/app.js and app-local modules. Keep app-specific layout in apps/<slug>/css/app.css.
  • Use the shared bookmark-note palette. Derive app CSS colors from tokens through var() or color-mix(). Raw color values belong in the shared token definitions. make lint-app-css-tokens also checks radius, font-size, and letter-spacing values. Style guide documents allowed values and exceptions.
  • Keep Markdown paragraphs on one line. Use sentence case headings and direct instructions. Do not use em dashes or en dashes.

Documentation ownership

Workspace documentation links to the owning document for each concern: structure, architecture, frontend behavior, operations, maintenance, style, and architecture decisions. Link to those sources instead of repeating their policies.

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.