Skip to content

AGENTS.md

Latest commit

 

History

History
218 lines (172 loc) · 6.79 KB

AGENTS.md

File metadata and controls

218 lines (172 loc) · 6.79 KB

AGENTS.md

Purpose

This repository contains Local Userscript Builder, a local browser-based tool for building one final Tampermonkey userscript from many smaller source files.

The project is intentionally small, dependency-free, and practical.

Core Goal

  • Keep the builder simple and directly usable.
  • Preserve local/offline operation.
  • Build reliable single-file Tampermonkey outputs from structured source folders.
  • Avoid unnecessary tooling such as Node.js, bundlers, package managers, servers, or frameworks.

Current State

  • Main builder workflow works.
  • Folder loading works.
  • File loading works.
  • Drag-and-drop loading works.
  • Recursive file discovery works.
  • project.toml builds work.
  • Output editor, copy, and download work.
  • Manifest generation helper exists.
  • Remove file action exists.
  • Standard non-source folder exclusions exist.

Key Files

  • Local-Userscript-Builder-v0.1.2.txt = main local builder tool
  • README.md = public GitHub documentation
  • AGENTS.md = AI and agent workflow rules
  • changelog/ = version changelogs
  • docs/ = supporting project documentation
  • assets/img/ = screenshots and README images

Requirements

  • Browser-only HTML and JavaScript.
  • No Node.js.
  • No Python.
  • No build framework.
  • No external runtime.
  • No server.
  • No package manager.
  • No browser extension API dependency.
  • Output remains .txt by default.

Project Style

  • Single-file local tool.
  • Plain HTML, CSS, and JavaScript.
  • Dark technical UI.
  • Wide desktop-friendly layout.
  • Clear status/log output.
  • Functional UI before decorative UI.
  • Keep the tool easy to inspect and modify.

Code Rules

  • Use plain JavaScript.
  • Use const and let.
  • Keep one central state object where practical.
  • Keep one central options/config object where practical.
  • Keep DOM references cached where useful.
  • Keep functions readable and explicit.
  • Do not add dependencies.
  • Do not add a framework.
  • Do not split this builder into many tiny files unless explicitly requested.
  • Do not silently change the output file format.
  • Do not remove existing working input methods.

JavaScript Rules

  • Code and code comments must be English.
  • UI labels should be English.
  • Prefer early returns.
  • Prefer simple helpers over abstract classes.
  • Avoid speculative abstractions.
  • Avoid hidden magic.
  • Do not use localStorage unless explicitly requested.
  • Do not use browser APIs that break local-file use without a fallback.

Build Model

The builder creates userscript output from a loaded project folder.

Preferred project format:

Project-Build/
   project.toml
   src/
      00-userscript-header.txt
      01-wrapper-start.js
      10-constants.js
      20-route-detection.js
      90-utils.js
      99-wrapper-end.js
   dist/
   docs/
   changelog/

Rules:

  • project.toml is the reproducible build source of truth.
  • src/ contains source files.
  • dist/ contains generated output and must not be included automatically.
  • docs/ contains documentation and must not be included automatically.
  • changelog/ contains changelogs and must not be included automatically.
  • README*, AGENTS.md, and PROJECT-MAP* are documentation, not source.

Manifest Rules

project.toml controls the build order.

Do not replace manifest-based builds with alphabetical guessing.

The generated manifest feature is only a helper for starting a project. A human or AI should review the generated manifest before using it as the stable build definition.

Output Rules

  • Keep .txt as the default generated output format.
  • Preserve line breaks as LF where possible.
  • Keep include markers readable.
  • Do not minify by default.
  • Do not remove comments by default.
  • Do not directly modify Tampermonkey scripts.
  • The final workflow is copy or download, then manual paste into Tampermonkey.

UI / UX Rules

  • Keep the main actions visible.
  • Keep file list, build log, and output editor easy to scan.
  • Preserve the output editor and copy button.
  • Preserve download output.
  • Do not add modal-heavy workflows.
  • Do not add destructive actions without visible confirmation or clear reversibility.
  • Keep default exclusions visible and predictable.

Documentation Rules

  • Keep README short and scannable.
  • Put public user-facing information in README.md.
  • Put agent/coding rules in AGENTS.md.
  • Put split instructions and AI project-splitting guidance in docs/.
  • Do not duplicate large explanations across README and AGENTS.
  • Keep changelog entries factual and versioned.

Release Rules

  • Public releases should remain small and working.
  • Include the main .txt tool file.
  • Include README, AGENTS, LICENSE, changelog, and screenshots when available.
  • Do not ship experimental rewrites as the main version.
  • Do not publish broken or half-migrated UI changes.

Safety Rules

  • Never delete user files.
  • Never overwrite local project files.
  • Never write directly into a loaded folder.
  • Generate downloadable text only.
  • Treat file loading as read-only.
  • Keep generated output inspectable before use.
  • Recommend testing generated userscripts in a separate Tampermonkey test entry.

Performance Rules

  • Handle hundreds of files without heavy UI delay.
  • Avoid repeated full rebuilds while typing.
  • Keep file scanning simple and predictable.
  • Do not add expensive validation unless it is explicitly triggered.
  • Large output should remain editable and copyable.

Change Policy

  • Prefer small changes.
  • Preserve working behavior.
  • Do not refactor stable logic unless explicitly requested.
  • Do not reformat unrelated code.
  • Do not remove fallback input methods.
  • Do not introduce package-based tooling.
  • Keep the public workflow simple.

Agent Workflow Rules

  • ALWAYS inspect the current main tool file before changing behavior.

  • ALWAYS preserve folder loading, file loading, and drag-and-drop loading.

  • ALWAYS keep project.toml as the reproducible build source.

  • ALWAYS keep .txt output available.

  • ALWAYS update the changelog for functional changes.

  • ALWAYS keep README and AGENTS consistent with released behavior.

  • ALWAYS keep browser-only operation.

  • DO NOT add Node.js, npm, Vite, Webpack, Rollup, or similar tooling.

  • DO NOT convert the project into a server application.

  • DO NOT make dist/, docs/, or changelog/ build sources.

  • DO NOT make direct Tampermonkey write integration the default workflow.

  • DO NOT remove include markers.

  • DO NOT minify output by default.

  • DO NOT hide errors that affect the build.

  • DO NOT add speculative features without clear workflow value.

What To Avoid

  • unnecessary rewrites
  • dependency creep
  • over-abstracted architecture
  • too many tiny internal files
  • hidden browser-specific behavior
  • silent build-order guessing
  • UI clutter
  • destructive defaults
  • direct modification of user scripts
  • output formats that are harder to inspect than plain text