Development

Guide for contributing to the Robota SDK monorepo.

Setup

git clone https://github.com/woojubb/robota.git
cd robota
pnpm install
pnpm build
pnpm test

Requirements

• Node.js: 22.14.0 (managed by Volta)
• pnpm: 8.15.4
• Module system: ES modules only ("type": "module")

Commands

pnpm build              # Build the package workspace once from the repo root
pnpm test               # Run all tests
pnpm typecheck          # TypeScript strict check
pnpm lint               # ESLint
pnpm harness:scan       # Full harness verification

Per-Package

pnpm --filter @robota-sdk/<pkg> build
pnpm --filter @robota-sdk/<pkg> test

Monorepo Structure

packages/
├── agent-core/                 ← Foundation (zero deps)
├── agent-tools/                ← Tools + 8 built-in CLI tools
├── agent-session/              ← Session with permissions/hooks
├── agent-executor/             ← Background task and subagent lifecycle
├── agent-framework/            ← Assembly layer (InteractiveSession, createQuery)
├── agent-command/              ← All slash command modules in one package
├── agent-provider/             ← Consolidated AI provider (sub-paths: /anthropic, /openai, /gemini, /google, /gemma, /qwen, /deepseek, /bytedance)
├── agent-plugin/               ← Consolidated plugin package
├── agent-transport/            ← Protocol transports + TUI (sub-paths: /tui, /headless, /http, /ws, /mcp)
├── agent-interface-transport/  ← Transport type contracts (zero deps)
├── agent-interface-tui/        ← TUI interaction type contracts (zero deps)
├── agent-cli/                  ← Terminal AI coding assistant
├── agent-subagent-runner/      ← Opt-in child-process subagent runner
├── agent-team/                 ← Multi-agent task delegation (playground stack)
├── agent-remote-client/        ← HTTP client for remote agents
├── agent-web-ui/               ← Browser React component library
├── agent-tool-mcp/             ← MCP tool client adapter
└── agent-playground/           ← Playground executor, hooks, and components

apps/
├── agent-web/                  ← Next.js playground host
├── agent-server/               ← AI provider proxy + WebSocket server
├── docs/                       ← VitePress documentation site
└── blog/                       ← Blog

Key Rules

• TypeScript strict mode — any and {} prohibited in production code
• SPEC.md required — Every package must have docs/SPEC.md
• TDD — Red-green-refactor cycle
• Spec-first — Update SPEC before code changes
• No fallbacks — Single correct path, no silent alternatives
• One-way dependencies — No circular deps between packages
• Conventional commits — feat:, fix:, docs:, chore:, refactor:

See AGENTS.md for the complete rule set.

Publishing

Robota publishes every non-private package together with one coordinated version. The current beta package set publishes approved @robota-sdk/* packages; private app, plugin, and internal packages are not published by the beta script.

pnpm harness:verify:release
pnpm publish:beta

pnpm harness:verify:release uses the root monorepo build instead of rebuilding each package independently. pnpm publish:beta runs the npm authentication preflight first, performs one recursive dry-run, prompts for OTP only after the dry-run succeeds, publishes all non-private packages with pnpm publish -r, syncs the beta dist-tag to the same version, and verifies both latest and beta dist-tags. If npm authentication fails, run:

npm login --registry https://registry.npmjs.org/

Never publish individual packages with --filter. Always use pnpm publish:beta; it resolves workspace:* dependencies correctly, avoids sequential per-package publishes, and keeps the monorepo package set on one version.

Documentation Sync

When package behavior changes, update the package README, the package docs page, and the relevant robota.io source page in the same PR:

• packages/<pkg>/README.md — npm/GitHub package README
• packages/<pkg>/docs/README.md — copied to robota.io as /packages/<pkg>/
• packages/<pkg>/docs/SPEC.md — package contract truth
• content/README.md — robota.io home page
• content/guide/*.md and content/examples/*.md — user-facing guides and examples

After changing content/ or packages/*/docs/, run:

pnpm docs:build