Contributing

Thank you for contributing to GrokBot Society!

Quick Start

Fork the repository, create a branch, make changes following the invariants below, run verification, submit a PR.

Setup
git clone https://github.com/M4G3LL4N0/grokbot-society.git
cd grokbot-society
pnpm install
Verify
pnpm typecheck
pnpm test

Architectural Invariants (Must Preserve)

These are non-negotiable. Any PR violating them will be rejected.

No Provider Bypass

All model calls go through IntelligenceGateway. Direct provider calls throw ProviderCallOutsideGatewayError.

One Call Per Event

maxCallsPerEvent = 1 enforced by BudgetGovernor.

Zero Background Inference

backgroundModelCalls = 0 by default. Scheduled work = $0.

No Person = Agent

Persons are durable state. Actors are ephemeral per-scene. Roles create zero agents.

No Group-Call Fan-Out

Hard max 3 speakers per scene (hardMaxSpeakers = 3).

No Unbounded Context

ContextCompiler enforces section/token caps. context_explosion breaker is hard.

No Uncontrolled Retries

maxRetries = 0, recursionDepth = 0. Fail closed, deterministic fallback.

Provider-Neutral Identity

Switching routes never touches Person state.

Code Style

  • TypeScript strict mode — strict: true, noUncheckedIndexedAccess: true
  • No any — use proper types
  • Immutable by default — prefer readonly, const, pure functions
  • Explicit over implicit — no magic, no hidden side effects
  • Error types over strings — domain errors extend SocietyError with codes
  • 2 spaces, trailing commas, semicolons — consistent with existing code

Test Requirements

  • All tests must pass: pnpm test
  • Typecheck must pass: pnpm typecheck
  • New features need tests: Add to tests/ following existing patterns
  • Deterministic tests: Use SimulatedClock and rng: () => 1 (serendipity off)
Test Structure
tests/
  helpers.ts           # makeKernel, sceneMessages, selectedIds
  01.mass-zero-cost.test.ts
  02.idle-dormant.test.ts
  03.scenes.test.ts
  04.identity-switching.test.ts
  05.guards.test.ts
  06.architectural-block.test.ts
  07.end-to-end.test.ts
  08.society-mvp.test.ts

Adding a New Feature

  1. Identify the domain (people, roles, relationships, circles, events, memory, runtime, intelligence, providers, budget, cache, telemetry, sessions, seed)
  2. Add types in src/god/types.ts or domain-specific types file
  3. Implement service in src/<domain>/
  4. Wire in GodKernel if needed
  5. Add tests in tests/
  6. Update docs in docs/
  7. Run verification: pnpm typecheck && pnpm test && pnpm dev

Dependency Policy

  • Minimize dependencies — prefer stdlib or tiny deps
  • No runtime deps — all deps are devDependencies
  • Pin major versions in package.json
  • Audit before adding — pnpm audit on new deps

Documentation

  • Update README.md for user-facing changes
  • Update docs/ for architectural changes
  • Update docs/ROADMAP.md for new features
  • Keep ARCHITECTURE.md current

Release Process (Maintainers Only)

  1. Update version in package.json
  2. Update CHANGELOG.md (if exists)
  3. Tag release: git tag v0.x.y
  4. Publish to npm (if applicable)

Questions?

Open an issue or start a discussion. We are happy to help.