AGENTS.md — Gadget Code Monorepo

Project Structure

gadget/
├── packages/ai/           @gadget/ai — AI API abstraction (source of truth)
├── gadget-code/            Web service + browser IDE
├── gadget-drone/           Worker process (agentic workflow loop)
└── pnpm-workspace.yaml     Monorepo workspace definition

Rules for AI Code

The ecosystem speaks one AI API language defined by @gadget/ai. All rules apply to every consumer:

No direct SDK imports. Never import { Ollama } from "ollama" or import OpenAI from "openai" outside packages/ai/src/.
No provider.sdk checks outside the factory. The factory in packages/ai/src/index.ts routes to the correct implementation. After createAiApi(), the caller holds an AiApi and never checks which SDK backs it.
All AI interfaces live in @gadget/ai. Do not re-declare IAiProvider, IAiChatResponse, etc. in consumer packages. Import them from @gadget/ai.
Adding a new provider means implementing AiApi in packages/ai/src/ and registering it in the factory. Nothing else changes.

Dev Commands

pnpm install              # Install all workspace packages
pnpm -r build             # Build all packages
pnpm --filter @gadget/ai build
pnpm --filter gadget-drone build
pnpm --filter gadget-code build:backend
pnpm --filter gadget-code dev
pnpm --filter gadget-drone dev

Key Conventions

All packages are ES modules ("type": "module").
@gadget/ai uses moduleResolution: NodeNext and emits to dist/.
gadget-drone uses moduleResolution: NodeNext.
gadget-code uses moduleResolution: bundler with @/* path aliases.
Dependency versions are pinned in package.json — no ranges. Use the workspace protocol (workspace:*) for internal package references.
pnpm version is enforced at the workspace root (packageManager field).

TypeScript Strictness

Package	Strictness
`@gadget/ai`	`strict: true`
gadget-drone	`strict: true`
gadget-code	`strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noUncheckedIndexedAccess`

Adding Code

When adding a new feature or service, determine its scope:

Shared concern (AI, logging, config schema) → goes in @gadget/ai
Drone-only (Bull queue, workspace file operations) → goes in gadget-drone
Web-only (Express routes, Mongoose models, session management) → goes in gadget-code

If code is needed by both consumer packages, it belongs in @gadget/ai. Do not copy-paste shared logic across packages.

2.5 KiB Raw Blame History