Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (57 loc) · 4.46 KB

AGENTS.md

File metadata and controls

63 lines (57 loc) · 4.46 KB

Repository Guidelines

Project Structure & Module Organization

ClawSec combines a Vite + React frontend with security skill packages and release tooling.

  • Frontend entrypoints: index.tsx, App.tsx
  • UI and routes: components/, pages/
  • Shared types/constants: types.ts, constants.ts
  • Wiki source docs: wiki/ (synced to GitHub Wiki by .github/workflows/wiki-sync.yml)
  • Generated wiki exports: public/wiki/ (llms.txt outputs; generated locally/CI and gitignored)
  • Skills: skills/<skill-name>/ (skill.json, SKILL.md, optional scripts/, test/)
  • Advisory feed: advisories/feed.json, advisories/feed.json.sig
  • Automation: scripts/, .github/workflows/
  • Python utilities: utils/validate_skill.py, utils/package_skill.py

Build, Test, and Development Commands

  • npm install: install dependencies.
  • npm run dev: run local Vite server.
  • npm run build: create production build (CI gate).
  • npm run preview: preview built app.
  • npm run gen:wiki-llms: generate wiki llms.txt exports from wiki/ into public/wiki/.
  • ./scripts/prepare-to-push.sh [--fix]: run lint, types, build, and security checks.
  • ./scripts/populate-local-wiki.sh: regenerate local wiki llms.txt exports for preview.
  • npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0: lint JS/TS.
  • npx tsc --noEmit: type-check TypeScript.
  • node skills/clawsec-suite/test/feed_verification.test.mjs: run a skill-local Node test.
  • python utils/validate_skill.py skills/<skill-name>: validate skill schema/metadata.

Coding Style & Naming Conventions

  • Use TypeScript/TSX for frontend code and ESM for scripts.
  • Follow eslint.config.js; prefix intentionally unused vars/args with _.
  • Python under utils/ follows pyproject.toml Ruff/Bandit rules (line length 120).
  • Name React files in PascalCase (for example, SkillCard.tsx), skill directories in kebab-case (for example, skills/clawsec-feed), and tests as *.test.mjs.

Testing Guidelines

There is no root npm test; tests are mostly skill-local.

  • Run changed tests directly: node skills/<skill>/test/<name>.test.mjs.
  • For frontend/config changes, run ESLint, npx tsc --noEmit, and npm run build.
  • For wiki rendering/export changes, run npm run gen:wiki-llms and npm run build.
  • For Python utility updates, run ruff check utils/ and bandit -r utils/ -ll.

Pull Request Guidelines

  • Follow Conventional Commits: feat(scope): ..., fix(scope): ..., chore(scope): ....
  • Use skill branches like skill/<name>-....
  • Keep PRs focused and include summary, security benefit, and testing performed.
  • Keep versions aligned between skills/<skill>/skill.json and skills/<skill>/SKILL.md.
  • Do not push release tags from PR branches; releases are tagged from main.
  • Do not commit generated public/wiki/ artifacts; edit wiki/ source files instead.

Agent Collaboration & Git Safety

  • Delete unused or obsolete files only when your changes make them irrelevant; revert files only when the change is yours or explicitly requested. If a git operation creates uncertainty about another agent’s in-flight work, stop and coordinate instead of deleting.
  • Before deleting any file to fix local type/lint failures, stop and ask the user.
  • Never edit .env or any environment variable files.
  • Coordinate with other agents before removing their in-progress edits; do not revert or delete work you did not author unless everyone agrees.
  • Moving, renaming, and restoring files is allowed when done safely.
  • Never run destructive git operations without explicit written instruction in this conversation: git reset --hard, rm, git checkout/git restore to older commits. Treat these as catastrophic; if unsure, stop and ask. In Cursor or Codex Web, use platform tooling as applicable.
  • Never use git restore (or similar revert commands) on files you did not author.
  • Always run git status before committing.
  • Keep commits atomic and commit only touched files with explicit paths.
  • For tracked files: git commit -m "<scoped message>" -- path/to/file1 path/to/file2.
  • For new files: git restore --staged :/ && git add "path/to/file1" "path/to/file2" && git commit -m "<scoped message>" -- path/to/file1 path/to/file2.
  • Quote any git path containing brackets or parentheses when staging/committing (for example, "src/app/[candidate]/**").
  • For rebases, avoid editors: GIT_EDITOR=: and GIT_SEQUENCE_EDITOR=: (or --no-edit).
  • Never amend commits without explicit written approval in this task thread.