Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (56 loc) · 6.09 KB

AGENTS.md

File metadata and controls

96 lines (56 loc) · 6.09 KB
Raw

Repository Guidelines

ExecPlans

When writing complex features or significant refactors, use an ExecPlan as described in PLANS.md.

Create new ExecPlan files under plans/ with a two-digit ordering prefix and a short kebab-case name, for example plans/00-first-monitor-cli.md or plans/01-local-ocr-analyzer.md. Use the next unused number after the highest existing prefixed plan.

The first implementation should continue from plans/00-first-monitor-cli.md.

Product Direction

Monitor is an internal prototype CLI utility for Ubuntu running inside Windows 11 WSL. It is intended to capture periodic Windows desktop screenshots, analyze them with Codex CLI image input, maintain local text summaries of visible activity over time, and show transparent live terminal progress while it runs.

Do not implement direct OpenAI Platform API calls for the first version. The planned analyzer is Codex CLI, not an OPENAI_API_KEY integration.

Treat screenshots and summaries as sensitive local artifacts. Keep run output under .monitor/, and keep .monitor/ ignored by git.

Planning and Change Intake

Treat requested changes as suggested directions until scope, tradeoffs, and long-term consequences are understood. If a requested change would create unclear privacy behavior, direct API billing, hidden background monitoring, or unnecessary architecture, explain the concern before proceeding.

When creating or revising a plan, gather enough project and repository information to understand feature scope, expected workflows, future extension points, privacy risks, maintainability costs, and how easy the resulting system will be for future contributors to understand.

Agent Browser and Visual Review

Use the repo-local agent-browser skill whenever a task requires browser interaction, screenshots, video recordings, form automation, scraping, exploratory testing, UI review, or web-app quality checks.

Monitor currently has no browser or Electron UI. For CLI-only changes, state that browser visual review is not applicable and use terminal output, generated text files, tests, and repository checks instead. If a future UI is added, follow the visual evidence workflow in DESIGN.md and PLANS.md.

For Windows 11 host-desktop evidence, use scripts/win-screenshot [output.png] when a screenshot needs to show the whole host desktop.

Core Documents

Treat root documentation files as durable project control documents:

  • README.md explains what the project is, how to set it up, and how to validate changes.
  • PRODUCT.md captures current user-visible product state, workflows, capability boundaries, and important limitations.
  • ROADMAP.md captures intended product direction, planned capabilities, strategic priorities, and explicit non-priorities.
  • PLANS.md defines how ExecPlans must be written and maintained.
  • CODESTYLE.md defines source formatting, naming, documentation style, and commenting standards.
  • DESIGN.md captures terminal UX rules and future UI review expectations.
  • ARCHITECTURE.md captures the high-level codemap, architectural boundaries, and invariants.

When a change materially affects current user-visible capabilities, workflows, scope boundaries, or important product limitations, update PRODUCT.md in the same change. When a change materially affects product vision, intended audience, strategic priorities, planned capabilities, sequencing assumptions, or explicit non-priorities, update ROADMAP.md in the same change. When a change materially affects source conventions or commenting standards, update CODESTYLE.md in the same change. When a change materially affects terminal UX or future design language, update DESIGN.md in the same change. When a change materially affects structure, ownership, or system boundaries, update ARCHITECTURE.md in the same change.

If you introduce a new root-level ALLCAPS.md file, treat it as a new control document by default. Define its purpose inside the file and update this section plus PLANS.md if future ExecPlans must read or maintain it.

Code Style and Commenting Requirements

Follow CODESTYLE.md. For the planned Bash CLI, keep scripts strict, quote expansions, validate external commands before use, and comment meaningful functions and side effects.

Project Structure & Module Organization

Keep runtime code in src/, mirror tests in tests/, keep static assets in assets/ only if they become needed, portable contributor utilities in scripts/, ordered ExecPlans in plans/, and durable documentation in the repository root.

Keep project-scoped Codex configuration in .codex/config.toml. The current default model is gpt-5.5 for contributor sessions. Do not use .codex/config.toml as Monitor runtime configuration.

Keep repo-local agent workflows in .agents/skills/.

Build, Test, and Development Commands

Run the checked-in CLI validation first:

bash -n scripts/win-screenshot src/monitor.sh tests/monitor_cli_test.sh
tests/monitor_cli_test.sh

Use lightweight repo checks before review:

rg --files --hidden -g '!.git/**'
git diff --check
git status --short

The screenshot helper can be smoke-tested on Windows 11 WSL with:

scripts/win-screenshot /tmp/monitor-smoke.png

Live smoke tests with bash src/monitor.sh --once require codex login and consume Codex plan usage or credits. A successful one-shot run makes one image-analysis Codex call and one text-summary Codex call.

Testing Guidelines

New behavior should ship with tests. Mirror source layout inside tests/.

For the first CLI, prefer fake capture and fake analyzer commands in tests so most validation does not require a live Windows desktop or real Codex usage. Live Codex smoke tests should be explicit because they consume Codex plan usage or credits.

Commit & Pull Request Guidelines

The current history starts with a short imperative commit message: Initial commit. Follow that pattern: concise subject line, imperative mood, no trailing period.

Pull requests should explain what changed, why it changed, and how it was validated. Include screenshots only when the change affects rendered output or documentation presentation.