Skip to content

AGENTS.md

Latest commit

 

History

History
40 lines (29 loc) · 3.77 KB

AGENTS.md

File metadata and controls

40 lines (29 loc) · 3.77 KB

Repository Guidelines

Project Structure & Module Organization

index.ts is the plugin entrypoint and registers commands, services, and interactive handlers. Core implementation lives in src/: controller flow in controller.ts, API/client integration in client.ts, configuration in config.ts, state and thread helpers in state.ts, thread-picker.ts, and thread-selection.ts, and user-facing text formatting in format.ts. Tests are colocated with source files as src/*.test.ts. Plugin metadata lives in openclaw.plugin.json; package and TypeScript settings are in package.json and tsconfig.json.

Design notes and upstream behavior captures live under docs/specs/. Before changing approval, trust, sandbox, file-edit, or media-handling behavior, review docs/specs/PERMISSIONS.md and docs/specs/MEDIA.md.

Project Management

Use the repo-local project-manager skill for GitHub issue and project-board work in this repository.

  • Repo/project config: .agents/project-manager.config.json
  • Project board: https://github.com/orgs/pwrdrvr/projects/7
  • Canonical local tracker: .local/work-items.yaml (derived; refresh with pnpm project:sync)
  • Canonical local issue drafts: .local/issue-drafts/
  • Do not create parallel scratch trackers or alternate temp directories for issue workups.

Build, Test, and Development Commands

Use pnpm for local work.

  • After committed package.json changes, run pnpm install so pnpm-lock.yaml stays in sync. If a peer range points past the newest npm release, do not commit that unresolved peer bump yet; keep registry-facing compatibility in openclaw.compat / openclaw.build until the matching package version exists.
  • pnpm test: run the Vitest suite once.
  • pnpm typecheck: run strict TypeScript checking with tsc --noEmit.
  • pnpm openclaw plugins install --link /path/to/openclaw-codex-app-server: link this package into a local OpenClaw checkout for manual integration testing.

There is no separate build step in this repository; correctness is gated by tests and typechecking.

Coding Style & Naming Conventions

Write TypeScript targeting Node ESM ("module": "NodeNext"). Match the existing style: 2-space indentation, double quotes, semicolons, and small focused helpers. Use PascalCase for classes and types, camelCase for functions and variables, and SCREAMING_SNAKE_CASE for shared constants such as command lists or namespace identifiers. Keep command and plugin-facing strings explicit and near the registration code when possible.

Testing Guidelines

Tests use Vitest and should stay next to the code they cover, named *.test.ts. Prefer narrow unit tests over broad fixtures; most existing tests assert exact payloads and formatting behavior. Run pnpm test and pnpm typecheck before opening a PR. Add or update tests for any command handling, thread-selection logic, formatting branch, or protocol-shape change.

Commit & Pull Request Guidelines

Follow the repository’s existing commit style: short imperative subjects, often with a Plugin: prefix, for example Plugin: restore Codex interactive workflows. Keep commits scoped to one behavior change. PRs should include a concise summary, linked issue or context, and the exact validation performed (pnpm test, pnpm typecheck, manual OpenClaw plugin exercise). Include screenshots or message transcripts when changing interactive Telegram or Discord flows.

Command Help Text

Every /cas_* command has structured help metadata in src/help.ts. When adding, removing, or changing a command's flags, arguments, or behavior, update the corresponding entry in COMMAND_HELP and the README command reference table to keep them in sync.