Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (90 loc) · 7.31 KB

AGENTS.md

File metadata and controls

133 lines (90 loc) · 7.31 KB

AGENTS.md

Purpose

This file defines the always-on rules for AI agents working on Bitsocial Spam Blocker. Use it as the default policy. Load linked playbooks only when their trigger condition applies.

Surprise Handling

If you encounter something ambiguous, surprising, or repo-specific that is not covered here, stop and ask the developer before proceeding. After confirmation, add a concise note to docs/agent-playbooks/known-surprises.md if the issue is likely to recur.

Project Overview

Public integration surface for the Bitsocial spam blocker. This repo contains the challenge package and shared schemas used by communities and by the hosted server implementation.

Instruction Priority

  1. User request
  2. MUST rules
  3. SHOULD rules
  4. Playbooks

Agent Operating Principles

  • Before editing, state important assumptions when the task is ambiguous. Ask instead of silently choosing between materially different interpretations.
  • Prefer the smallest implementation that solves the requested problem. Do not add speculative abstractions, configurability, or features.
  • Keep diffs surgical. Do not refactor, reformat, rename, or "improve" adjacent code unless it is necessary for the task.
  • Clean up only artifacts created by the current change, such as newly unused imports or dead helper code.
  • For non-trivial work, define success criteria and verify them with the narrowest reliable checks before marking the task complete.

LLM Knowledge Base Policy

Use compiled context for orientation, not as source of truth.

Source of truth:

  • Code, tests, package manifests, docs, and runtime/live evidence when relevant.

Compiled context:

  • AGENTS.md, directory-specific AGENTS.md files, CLAUDE.md, and repo-managed .codex/, .cursor/, and .claude/ workflow files.
  • docs/agent-playbooks/**, docs/agent-runs/**, docs/agent-playbooks/known-surprises.md, and tracked llms.txt / llms-full.txt files when present.

Agents may use compiled context to navigate quickly, but must verify against source files before making behavioral claims or edits. External code graph, RAG, MCP, or wiki tools are optional local accelerators unless the developer explicitly asks to make one part of the committed workflow.

Task Router

Situation Action
Bug reported Reproduce with a test first, then fix
package.json changed Run corepack yarn install to keep yarn.lock in sync
Code changed Run corepack yarn build for all packages
New feature added Add vitest coverage
Shared schema changed Keep it in packages/shared
README drifts from implementation Update README.md
Public docs or AI context changed Run corepack yarn llms:generate; inspect and commit any resulting changes to llms*.txt so LLM indexes stay current
Hidden AI workflow files change Keep the repo-managed AI workflow surfaces aligned
Long-running or multi-session task started Track state under docs/agent-runs/<slug>/ using the long-running workflow playbook
GitHub operation needed Use gh CLI, not GitHub MCP
User-facing UI text Use Bitsocial for product/network text, community instead of community, and PKC / pkc-js for protocol-core names

Stack

  • Runtime: Node.js v22+ / TypeScript / ESM
  • Workspace: Yarn 4 workspaces (challenge, shared)
  • Public packages: challenge integration / shared Zod schemas
  • Tooling: vitest / esbuild / Prettier / commitlint / husky

Project Structure

packages/
├── challenge/  # package for community owners
└── shared/     # shared types and Zod schemas

MUST Rules

Environment & Build

  • Node.js v22+ required for all packages.
  • Prefer Corepack-managed Yarn for install and verification commands.
  • Run corepack yarn build after coding and make sure it passes.
  • Run corepack yarn type-check and corepack yarn test after meaningful code changes, unless the task is docs-only.
  • The challenge package runs in Node.js only, never in the browser.
  • Prefer static imports; dynamic imports should not be needed.

Code Style

  • Function parameters should use a single object shape: {param1, param2}.
  • Everything should be properly typed. If you cannot type something, ask the user for help.
  • In user-facing UI text, use Bitsocial for product/network text, community instead of community, and PKC / pkc-js for protocol-core names.

Testing

  • Add vitest tests for every new feature.
  • Reproduce bugs with a test case first, then fix the code, then verify the test passes.

Dependencies & Types

  • Do not duplicate pkc-js schemas or types. Import them from @pkcprotocol/pkc-js.
  • community.address can be a domain. Resolve it with pkc-js to get the public key.

Shared Code

  • Schemas shared between the challenge package and the private hosted server belong in packages/shared.

Security & Trust

  • Author fields are user-provided and not trusted, except author.community, which is generated by the community and can be trusted.
  • Authors can spam with different signers; the protocol is pseudonymous.

Git Worktrees

  • Always give a new worktree a descriptive name that reflects the task (e.g. fix-challenge-timeout, not wt1, tmp, feature, or a numbered slug), so it can be identified at a glance in a long list of worktrees.

SHOULD Rules

  • Keep README.md in sync with implementation changes when committing.

Playbooks

Consult these only when the task touches their domain:

Topic Location
Hooks setup docs/agent-playbooks/hooks-setup.md
Skills and tools docs/agent-playbooks/skills-and-tools.md
Bug investigation workflow docs/agent-playbooks/bug-investigation.md
Long-running task handoff docs/agent-playbooks/long-running-agent-workflow.md
Known surprises log docs/agent-playbooks/known-surprises.md
Full API spec README.md