Skip to content

Latest commit

 

History

History
194 lines (149 loc) · 9.52 KB

AGENTS.md

File metadata and controls

194 lines (149 loc) · 9.52 KB

AGENTS.md

Purpose

This file defines the always-on rules for AI agents working on 5chan. Use this as the default policy. Load linked playbooks only when their trigger condition applies.

Surprise Handling

The role of this file is to reduce recurring agent mistakes and confusion points in this repository. If you encounter something surprising or ambiguous while working, alert the developer immediately. After confirmation, add a concise entry to docs/agent-playbooks/known-surprises.md so future agents avoid the same issue. Only record items that are repo-specific, likely to recur, and have a concrete mitigation.

Project Overview

5chan is a serverless, adminless, decentralized imageboard built on the Bitsocial protocol.

Instruction Priority

  • MUST rules are mandatory.
  • SHOULD rules are strong defaults unless task context requires a different choice.
  • If guidance conflicts, prefer: user request > MUST > SHOULD > playbooks.

Task Router (Read First)

Situation Required action
React UI logic changed (src/components, src/views, src/hooks, UI stores) Follow React architecture rules below and run yarn doctor
package.json changed Run yarn install to keep yarn.lock in sync
Dependencies or import graph changed Run yarn knip as an advisory manifest/import audit
Translation key/value changed Use docs/agent-playbooks/translations.md
Bug report in a specific file/line Start with git history scan from docs/agent-playbooks/bug-investigation.md before editing
CHANGELOG.md or package version changed Run yarn blotter:check; if needed add a concise release one-liner
UI/visual behavior changed Verify in browser with playwright-cli; test desktop and mobile viewport
New reviewable feature/fix started while on master Create a short-lived feature/*, fix/*, docs/*, or chore/* branch from master before editing; use a separate worktree only for parallel tasks
Open PR needs feedback triage or merge readiness check Use the review-and-merge-pr skill to inspect bot/human feedback, fix valid findings, and merge only after verification
Repo AI workflow files changed (.codex/**, .cursor/**) Keep the Codex and Cursor copies aligned when they represent the same workflow; update AGENTS.md if the default agent policy changes
GitHub operation needed Use gh CLI, not GitHub MCP
User asks for commit/issue phrasing Use docs/agent-playbooks/commit-issue-format.md
Surprising/ambiguous repo behavior encountered Alert developer and, once confirmed, document in docs/agent-playbooks/known-surprises.md

Stack

  • React 19 + TypeScript
  • Zustand for shared state
  • React Router v6
  • Vite
  • bitsocial-react-hooks
  • i18next
  • yarn
  • oxlint
  • oxfmt
  • tsgo

Project Structure

src/
├── components/   # Reusable UI components
├── views/        # Page-level route views
├── hooks/        # Custom hooks
├── stores/       # Zustand stores
├── lib/          # Utilities/helpers
└── data/         # Static data

Core MUST Rules

Package and Dependency Rules

  • Use yarn, never npm.
  • Pin exact dependency versions (package@x.y.z), never ^ or ~.
  • Keep lockfile synchronized when dependency manifests change.

React Architecture Rules

  • Do not use useState for shared/global state. Use Zustand stores in src/stores/.
  • Do not use useEffect for data fetching. Use bitsocial-react-hooks.
  • Do not sync derived state with effects. Compute during render.
  • Avoid copy-paste logic across components. Extract custom hooks in src/hooks/.
  • Avoid boolean flag soup for complex flows; model state clearly in Zustand.
  • Use React Router for navigation; no manual history manipulation.

Code Organization Rules

  • Keep components focused; split large components.
  • Follow DRY: shared UI in src/components/, shared logic in src/hooks/.
  • Add comments for complex/non-obvious code; skip obvious comments.

Git Workflow Rules

  • Keep master releasable. Do not treat master as a scratch branch.
  • If the user asks for a reviewable feature/fix and the current branch is master, create a short-lived task branch before making code changes unless the user explicitly asks to work directly on master.
  • Name short-lived branches by intent: feature/*, fix/*, docs/*, chore/*.
  • Open PRs from task branches into master so review bots can run against the actual change.
  • Prefer short-lived task branches over a long-lived develop branch unless the user explicitly asks for a staging branch workflow.
  • Use worktrees only when parallel tasks need isolated checkouts. One active task branch per worktree.
  • After a reviewed branch is merged, prefer deleting it to keep branch drift and merge conflicts low.

Bug Investigation Rules

  • For bug reports tied to a specific file/line, check relevant git history before any fix.
  • Minimum sequence: git log --oneline or git blame first, then scoped git show for relevant commits.
  • Full workflow: docs/agent-playbooks/bug-investigation.md.

Verification Rules

  • Never mark work complete without verification.
  • After code changes, run: yarn build, yarn lint, yarn type-check.
  • After adding or changing tests, run yarn test.
  • Do not commit or force-add local rebuild output. build/ is the main generated build output in this repo; remove or restore generated output directories after local verification before committing.
  • After React UI logic changes, run: yarn doctor.
  • Treat React Doctor output as actionable guidance; prioritize error then warning.
  • For UI/visual changes, verify with playwright-cli on desktop and mobile viewport.
  • Use yarn test:coverage as an advisory check when expanding test coverage or auditing risky logic; do not invent a repo-wide coverage gate unless the user asks for one.
  • If verification fails, fix and re-run until passing.

Tooling Constraints

  • Use gh CLI for GitHub work (issues, PRs, actions, dependabot, projects, search).
  • Do not use GitHub MCP.
  • Do not use browser MCP servers (cursor-ide-browser, playwright-mcp, chrome MCP, etc.).
  • Use playwright-cli for browser automation.
  • If many MCP tools are present in context, warn user and suggest disabling unused MCPs.

AI Tooling Rules

  • Treat .codex/ and .cursor/ as repo-managed contributor tooling, not private scratch space.
  • Keep equivalent workflow files aligned across both toolchains when both directories contain the same skill, hook, or agent.
  • When changing shared agent behavior, update the relevant files in .codex/skills/, .cursor/skills/, .codex/agents/, .cursor/agents/, .codex/hooks/, .cursor/hooks/, and their hooks.json or config entry points as needed.
  • If AGENTS.md references a skill, agent, or hook, prefer a tracked file under .codex/ or .cursor/ rather than an untracked local-only instruction.
  • Review .codex/config.toml and .cursor/hooks.json before changing agent orchestration or hook behavior, because they are the entry points contributors will actually load.

Project Maintenance Rules

  • If CHANGELOG.md or package version changes, run yarn blotter:check.
  • If blotter check fails for missing release coverage, add a concise one-line release entry.
  • Ignore manual entries for release coverage logic.
  • Use yarn blotter / yarn blotter:manual for manual dev messages.

Security and Boundaries

  • Never commit secrets or API keys.
  • Never push to a remote unless the user explicitly asks.
  • Test responsive behavior on mobile viewport.

Core SHOULD Rules

  • Keep context lean: delegate heavy/verbose tasks to subprocesses when available.
  • For complex work, parallelize independent checks.
  • Add or update tests for bug fixes and non-trivial logic changes when the code is reasonably testable.
  • When touching already-covered code, prefer extending nearby tests so measured coverage does not regress without a clear reason.
  • Use yarn knip when adding/removing dependencies or introducing new direct imports; treat findings as advisory, but resolve real issues before finishing.
  • When proposing or implementing meaningful code changes, include both:
    • a Conventional Commit title suggestion
    • a short GitHub issue suggestion Use the format playbook: docs/agent-playbooks/commit-issue-format.md.
  • When stuck on a bug, search the web for recent fixes/workarounds.
  • After user corrections, identify root cause and apply the lesson in subsequent steps.

Local Development URLs

This project uses Portless for local dev. The dev server is available at http://5chan.localhost:1355 instead of a random port. Other Bitsocial projects use the same proxy (seedit, mintpass, bitsocial at .localhost:1355), so they can all run simultaneously without port conflicts.

To bypass Portless: PORTLESS=0 yarn start

Common Commands

yarn install
yarn start                # http://5chan.localhost:1355
yarn build
yarn test
yarn test:coverage
yarn knip
yarn knip:full
yarn prettier
yarn electron
yarn doctor
yarn doctor:score
yarn doctor:verbose

Playbooks (Load On Demand)

Use these only when relevant to the active task:

  • Hooks setup and scripts: docs/agent-playbooks/hooks-setup.md
  • Translations workflow: docs/agent-playbooks/translations.md
  • Commit/issue output format: docs/agent-playbooks/commit-issue-format.md
  • Skills/tools setup and MCP rationale: docs/agent-playbooks/skills-and-tools.md
  • Bug investigation workflow: docs/agent-playbooks/bug-investigation.md
  • Known surprises log: docs/agent-playbooks/known-surprises.md