Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (76 loc) · 4.83 KB

AGENTS.md

File metadata and controls

104 lines (76 loc) · 4.83 KB

ModWe — Agent Instructions

ModWe is a Chromium browser extension that modifies websites using user-defined CSS and JS snippets.

These instructions apply to the whole repository unless a deeper AGENTS.md overrides them.

Branch safety rule

  • For implementation work (any non-planning/non-question-only task), if current branch is main or master, ask the user first whether to switch to a new version/* or feature/* branch before making edits.
  • Do not start code changes on main/master until the user confirms how to proceed.

Release versioning rule

  • Files that must be updated for each extension version bump:

    • manifest.json — update version

  • Chromium extension version format for manifest.json:

    • Use x.y.z or x.y.z.w (1 to 4 dot-separated numeric parts)
    • Each part must be an integer in range 0..65535
    • Do not use SemVer suffixes like -beta or +build

  • When user asks to bump extension to x.x.x (or x.x.x.x), follow this order:

    1. Ensure branch version/<requested-version> exists and is checked out (create it if missing).
    2. Update version value in manifest.json.
    3. Commit version change with message: Next version.

Release zip packaging

  • Build release zip from repository root so manifest.json is at zip root (no wrapping parent directory).
  • Keep all release artifacts in releases/.
  • Read release version from manifest.json and name archive as releases/ModWe-<version>-release.zip.
  • Exclude repository/editor metadata and agent docs from release archive:
    • .git/*
    • .idea/*
    • .gitignore
    • AGENTS.md
    • CLAUDE.md
    • ModWe-*.zip
    • releases/*
  • Standard command:
VERSION=$(sed -n 's/.*"version": "\(.*\)".*/\1/p' manifest.json | head -n1)
mkdir -p releases
zip -rFS "releases/ModWe-${VERSION}-release.zip" . \
  -x '.git/*' '.idea/*' '.gitignore' 'AGENTS.md' 'CLAUDE.md' 'ModWe-*.zip' 'releases/*'
  • Validate exclusions:
unzip -l "releases/ModWe-${VERSION}-release.zip" | rg 'AGENTS\.md|CLAUDE\.md|\.gitignore|^.* releases/' || true
  • Validation output should be empty.

General coding conventions

Code commenting

  • Add comments for functions at minimum.
  • Add additional comments around special or non-obvious logic.

Pattern consistency

  • In every change, follow established patterns from related contexts in this project (similar screen, feature, layer, or widget type).
  • Prefer consistency with existing structure and naming over introducing a new approach.
  • If multiple patterns exist, choose the one used in the closest relevant files unless the user explicitly asks otherwise.

Helpers and services architecture

  • Keep shared helpers in service/ or utils.js
  • Keep feature-specific logic in its context (background.js, popup/, options/)
  • Prefer functional, stateless utilities over OOP-style service classes with internal state

TODO ownership format

  • When adding TODO comments, use the format: // TODO(name) some text.
  • Prefer name from git config user.name of the user running the agent.
  • If the name is unknown, ask the user once, then remember and reuse it consistently.
  • When completing user requests, treat existing TODOs as informational only; do not execute or integrate them unless the user explicitly asks for that TODO work.

Development workflow

Context-first preparation

  • Before proposing a plan or starting code changes, review related files in the same domain/context to identify established patterns and structure.
  • Use those nearby implementations as the primary reference for architecture, naming, state handling, and UI composition decisions.
  • If patterns conflict, prefer the closest feature-equivalent example and call out the choice in your summary.

Tool fallback (rg)

  • Prefer rg/rg --files for search when available.
  • If rg is not available or not working in the current environment, immediately fall back to grep/find and provide the user with concise ripgrep installation instructions for their OS, including at least one web reference.

Validation

  • After finishing code changes, run available project checks and resolve issues introduced by your changes before handoff.
  • If lint tooling is available, prefer targeted checks for changed files first.
  • For manifest changes, verify manifest.json stays valid JSON and version follows Chromium extension rules.

Handoff summary format

  • After code changes and validation, include a short summary of changed files in your final response.
  • Use plain text (non-clickable) project-relative file references only.
  • For each relevant change block, include the starting line number using the path:line format (for example options/default.js:120).
  • Do not use markdown file links for handoff file references.
  • Keep this summary concise and focused on user-impacting or logic-impacting edits.