Skip to content

AGENTS.md

Latest commit

 

History

History
128 lines (93 loc) · 6.02 KB

AGENTS.md

File metadata and controls

128 lines (93 loc) · 6.02 KB
Raw

AGENTS.md

Purpose

This file provides curated, minimal guidance for AI agents working in this repo. Rules are prioritized (MUST > SHOULD) so agents know what to enforce vs. what to prefer. Detailed workflows live in playbooks loaded on demand — not inlined here.

Surprise Handling

If something behaves unexpectedly (a test fails for unclear reasons, a build breaks in a surprising way, a dependency does something unusual):

  1. Stop — do not retry in a loop or force your way through.
  2. Investigate — read error output, check recent commits, look at related code.
  3. Document — if you discover a non-obvious gotcha, tell the user so it can be captured.

Project Overview

bitsocial-cli is an oclif-based CLI + daemon for the BitSocial protocol (built on top of pkc-js). It manages communities, challenges, IPFS nodes, and web UIs from the command line.

Instruction Priority

Level Meaning
MUST Non-negotiable. Breaking these causes failures or bad releases.
SHOULD Strong default. Override only with good reason.

Task Router

Quick lookup — find your situation, follow the required actions:

Situation Do this
First time / fresh clone nvm use → npm ci → npm run build
Changed any .ts file npm run build && npm run build:test
Running tests npm run test:cli
Added feature or fixed bug Write a test → build → run tests
Installing a dependency nvm use first, then npm install ...
Routine node/community config Perform the requested live operation → verify → summarize; no GitHub issue unless explicitly requested
Before committing Build passes, all tests pass

Stack

Layer Technology
Runtime Node 22 (nvm use reads .nvmrc)
Language TypeScript (ESM, "type": "module")
CLI framework oclif
Test runner Vitest
Package mgr npm (not yarn, not pnpm)
Build tsc with configs in config/

Project Structure

src/
├── cli/
│   ├── commands/        # oclif command implementations
│   │   ├── challenge/   # challenge-related subcommands
│   │   └── community/   # community-related subcommands
│   └── hooks/           # oclif lifecycle hooks (init, prerun)
├── challenge-packages/  # challenge package logic
├── common-utils/        # shared utilities
├── ipfs/                # IPFS/Kubo node management
├── webui/               # web UI download & serving
├── util.ts              # top-level utility helpers
└── index.ts             # package entry point

GitHub Issues

When the user gives a prompt to implement a feature or bug fix in this repository's codebase:

  1. MUST create a GitHub issue for the feature before starting work (gh issue create).
  2. MUST keep the issue updated with the current plan and progress as work proceeds.
  3. MUST put Closes #N in the PR body so the issue auto-closes when the PR merges. Closing keywords go in the PR body only, never in commit messages.
  4. MUST ask the user before closing an issue manually (gh issue close); auto-close via PR merge needs no ask.

Routine live operations are not repository feature work:

  • MUST NOT create GitHub issues for routine live-node operations, community/board configuration changes, data updates, support tasks, or private infrastructure administration unless the user explicitly asks for one.
  • MUST ask before creating any public GitHub artifact when a task could be interpreted as either repository work or live operations.
  • MUST NOT include private infrastructure details, secrets, API keys, or user-specific operational data in GitHub issues, comments, PRs, or commit messages.

Core MUST Rules

Environment Setup

  • MUST run nvm use before any npm command (npm ci, npm install, npm run, etc.).
  • MUST use npm, never yarn or pnpm.

Build & Test

  • MUST verify build passes after any code change: npm run build && npm run build:test.
  • MUST run tests with npm run test:cli (not vitest directly — the script downloads web UIs first).
  • MUST ensure all tests pass before committing.

Code Organization

  • MUST add a test when you add a feature or fix a bug.

Core SHOULD Rules

  • SHOULD keep changes focused — avoid unrelated refactors in the same commit.
  • SHOULD prefer editing existing files over creating new ones.
  • SHOULD check config/ for tsconfig and vitest settings before assuming defaults.

Common Commands

nvm use                              # switch to project's Node version
npm ci                               # clean install dependencies
npm run build                        # compile TypeScript → dist/
npm run build:test                   # compile test TypeScript
npm run build && npm run build:test  # full build check
npm run test:cli                     # run all tests (downloads web UIs first)
npm run build:watch                  # watch mode for main build
npm run build:test:watch             # watch mode for test build

Playbooks (Load On Demand)

No playbooks yet. As recurring workflows emerge (e.g., release process, adding a new command, upgrading pkc-js), create them as separate files and reference them here.