Packages relied on npm hoisting for imports they never declared, so a package installed on its own fails (UF-024). - server: + @waggle/marketplace, @waggle/sdk, @waggle/weaver, zod (MIT), @anthropic-ai/sdk (MIT), @ax-llm/ax (Apache-2.0); - @waggle/hive-mind-shim-core and stripe (unused) - agent: + pdf-parse (Apache-2.0); playwright-core (Apache-2.0) as an optional peer, since it is loaded only when available - worker: + @waggle/waggle-dance; web: + @waggle/shared - launcher: + @waggle/server as a dev dependency (bundled by tsup); - stripe; cli: - @waggle/weaver (unused); root: - stripe scripts/check-workspace-deps.mjs (npm run check:deps) compares the imports in each community-edition package's src/ with its manifest and runs in CI. Two imports wait for P1.4 (optimizer, evolution wiring).
15 KiB
AGENTS.md — Waggle Community Edition
Operating contract for every agent and contributor on this branch
Read this file in full before changing code. On this branch it replaces the commercial-product contract. Where older documents under
docs/(audits, briefs, launch and production-readiness records) disagree with this file or with the decision records indocs/oss/adr/, this file and the ADRs win.
0. Where We Are
This branch turns the commercial Waggle OS codebase into an open-source community edition. The conversion is in progress: the code still contains tiers, Stripe, KVARK, team mode and the hive-mind memory substrate. Work packages remove or replace them one by one.
Sources of truth, in order:
- The agreed scope ("Waggle OSS Agreed Scope Annex", held by the project owner).
- The decision records in
docs/oss/adr/. - This file.
Work is split into work packages: 0.x preparation, P0 unblocking, P1 main scope,
P2 hygiene and publication. Name the work package in commit messages when it helps
(for example refactor(server): remove Stripe routes (P1.1)).
1. What the Community Edition Is
Waggle is a workspace-native AI agent platform with persistent memory: a web UI, a local Fastify sidecar, an agent runtime with personas, skills and connectors.
The community edition:
- runs locally on Windows, macOS and Linux (the exact platform list awaits owner confirmation);
- installs with a Node-based installer (
packages/launcher) and optional Tauri desktop packages, without Python, Docker or a compiler on the user's machine; - has no monetization: no tiers, trials, payments, license checks or upsell (ADR-0001);
- keeps memory on the user's machine through a memory contract backed by local mem0 (ADR-0002);
- sends analytics only after the user opts in (ADR-0006).
Stack (verified 2026-10-15)
| Layer | Stack |
|---|---|
| Web UI | React 19, TypeScript, Vite 6, Tailwind CSS 3.4, Radix UI primitives (apps/web) |
| Sidecar | Fastify on Node.js, run with tsx in development (packages/server) |
| Desktop shell | Tauri 2 (app/src-tauri), an optional wrapper around the sidecar and web UI |
| Database | SQLite via better-sqlite3 and sqlite-vec |
| Memory | Today the hive-mind substrate (packages/hive-mind-core); target is the memory contract plus local mem0 (P0.3, P1.5) |
| Local models | Waggle-managed Ollama runtime, or the user's own provider keys |
| Tests | Vitest (unit), Playwright (e2e and visual) |
npm workspaces with the root package-lock.json. Node ^20.19.0 || >=22.12.0.
2. Repository Map and Scope Status
| Path | Status in the community edition |
|---|---|
apps/web |
Keep. The main UI; all React code lives here. |
app/ |
Keep. Tauri shell only (there is no app/src/). |
packages/agent, core, server, shared, sdk, weaver, marketplace, cli, launcher |
Keep. |
packages/waggle-dance, packages/worker |
Postponed: team mode stays in the repo, is not built or shipped (ADR-0003). |
packages/optimizer |
Excluded: part of self-learning (ADR-0004). Removed in P1.4. |
packages/hive-mind-*, memory-mcp, wiki-compiler |
Excluded once P1.5 moves all memory access to the contract. |
packages/admin-web, apps/www |
Excluded. |
apps/browser-ext |
Not decided. Do not extend it. |
sidecar/, benchmarks/, judging/, most of docs/ |
Internal history of the commercial product, removed in P2.2. Community-edition docs live in docs/oss/. |
Where things live
apps/web/src/
├── components/os/apps/ # per-app UI shells
├── components/os/overlays/ # OnboardingWizard.tsx, PersonaSwitcher.tsx
├── components/ui/ # shared UI primitives
└── lib/ hooks/ providers/ pages/ test/
packages/agent/src/ # most active package; grep before creating anything
agent-loop.ts core execution loop
orchestrator.ts buildSystemPrompt(), recallMemory()
personas.ts, persona-data.ts, custom-personas.ts
behavioral-spec.ts BEHAVIORAL_SPEC rules
tool-filter.ts filterToolsForContext()
injection-scanner.ts scanForInjection()
cost-tracker.ts CostTracker and model pricing (stays, ADR-0004)
feature-flags.ts exists; do not recreate
commands/ connectors/ mcp/ providers/
packages/server/src/local/ # the local sidecar: index.ts, routes/, services/
packages/core/src/ # config, cron-store, file-store, vault, logger, telemetry
packages/shared/src/ # shared types, Zod schemas, MCP catalog
To be removed by work packages, so do not build on them: packages/shared/src/tiers.ts
(P0.1), packages/agent/src/kvark-tools.ts and the evolution / improvement / correction
modules (P1.4), packages/server/src/stripe/ and packages/server/src/kvark/ (P1.1),
packages/core/src/compliance/ and install-audit.ts (P1.2).
3. Conversion Rules
=== CRITICAL ===
- No monetization. Do not add tier checks, trials, prices, payment flows, license checks, or KVARK and Team upsell. When a work package touches such code, remove it. The word "tier" also means UserTier (UI complexity), ModelTier, persona tiers, CLI levels and memory health levels. Leave those alone and never mass-replace the word.
- Memory goes through the contract. New code must not import
@waggle/hive-mind-*,memory-mcporwiki-compiler, and must not run SQL against the memory database. Until the contract lands (P0.3), keep memory changes minimal. The knowledge graph is not in v1. - Team mode is frozen. Do not add features to team routes, WaggleDance or the worker.
- Self-learning is out. Do not extend evolution, improvement signals, correction
learning, judge or eval loops, or
optimizer. Cost tracking stays. - Licenses. Every new dependency must be compatible with MIT distribution. No GPL or
AGPL code in shipped artifacts: this is why Baileys (GPL
libsignal) is replaced bywhatsapp-web.js(ADR-0005). State the license of a new dependency in the commit message. - Analytics are opt-in. Nothing is sent before the user agrees. The PostHog key comes
only from the build environment (
VITE_POSTHOG_KEY) and is never committed. - Three operating systems. Every platform-specific branch needs Windows, macOS and Linux paths. End users must not need Python, Docker, a compiler or a developer Node install.
- Secrets and history. Never commit secrets. Never push this repository's history to a public remote: the public release is a fresh repository built from the cleaned tree (P2.6).
- Upstream defects. When you find or fix a defect that also exists in the commercial
product, log it in
docs/oss/upstream-fixes.mdin the same commit, in English, using the template at the top of that file. Scope removals (tiers, Stripe, KVARK, team mode) are not defects and are not logged. === END CRITICAL ===
4. Build, Run and Verify
Setup and run
npm ci
npm run build:packages # required: workspace packages export dist/, the sidecar fails without it
npm run build # typechecks apps/web, builds it into the root dist/ (emptied first)
npm run dev:server # sidecar on http://localhost:3333, serves the UI from the root dist/
- The sidecar registers routes for the files in
dist/when it starts (@fastify/staticwithwildcard: false), so assets from a later build return 404. Restart the sidecar afternpm run build. npm run dev:web(Vite) cannot authenticate against the sidecar today (UF-003). Use the UI served by the sidecar.
Verification (run these, do not claim "it compiles")
npx tsc --noEmit --project packages/agent/tsconfig.json
npx tsc --noEmit --project packages/server/tsconfig.json # the sidecar runs via tsx, so nothing else typechecks it
npx tsc --noEmit --project app/tsconfig.json
npm run test # root Vitest: packages, tests/, scripts/ (excludes apps/**)
(cd apps/web && npx vitest run) # web UI tests use their own config
npm run lint # root config; ignores apps/web
(cd apps/web && npx eslint .) # web config; 49 errors pre-exist (docs/oss/baseline.md)
npm run check:deps # every imported package is declared in its package.json
- Playwright e2e reuses any server already listening on :3333 and its data directory. For an
isolated run set
WAGGLE_E2E_REUSE_EXISTING_SERVER=0and a freeWAGGLE_E2E_PORT. Its web server step runsnpm run build:all, which rewrites the rootdist/. docs/oss/baseline.mdrecords the build, typecheck, lint and test results at the start of the conversion. Compare your results against it and do not let a green check turn red.
5. How to Work
5.1 Think before coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them; don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop, name what's confusing, and ask.
=== CRITICAL === The most expensive failure mode is making a wrong assumption and building 100+ lines on top of it. The fix costs ten times what the question would have cost. Stop. Ask. Then build. === END CRITICAL ===
5.2 Simplicity first
Minimum code that solves the problem. No features beyond the request, no abstractions for single-use code, no configurability nobody asked for, no error handling for impossible scenarios. If you write 200 lines and it could be 50, rewrite it.
5.3 Surgical changes
- Touch only what the task needs. Don't reformat or "improve" adjacent code.
- Match the existing style.
- If you notice unrelated dead code, mention it; don't delete it.
- Remove imports, variables and functions that your own change made unused.
Every changed line should trace to the request. Removals required by a work package are the request.
5.4 Goal-driven execution
Turn tasks into verifiable goals ("fix the bug" becomes "write a test that reproduces it, then make it pass"). For multi-step work, state a short plan with a check per step. A task is not done until verification passes.
5.5 Context discipline
- Re-read a file before editing it if the conversation has moved on. Do not trust memory.
- Read files over 500 lines in chunks; never assume you saw all of it.
- Tool output over ~50k characters is truncated. If results look sparse, narrow the query.
- On a rename or removal, grep for direct references, types, string literals, dynamic imports, barrel re-exports and tests. One grep is never enough.
5.6 Check before create
Grep before adding a file. If something might already exist, it probably does (see section 9).
5.7 Output discipline
- Long specs, plans and reports go into files under
docs/oss/, not into chat. - Implement large work in phases: commit per phase, report briefly, then continue.
- Never hide failures. Report failing tests and skipped checks with their output.
6. Pre-Work Protocol
- Before a structural refactor of a file over 300 lines, remove dead code in a separate
commit:
chore(scope): dead code removal — <file>. - Work in phases of at most five files: change, verify, then continue.
- If the architecture is flawed, state is duplicated, or patterns are inconsistent, say so and propose a fix. Standard: what would a senior engineer reject in review?
7. Personas and Onboarding
packages/agent/src/persona-data.tsholds the canonicalPERSONASarray (pure data);personas.tsholds theAgentPersonainterface and logic.- The PersonaSwitcher (
apps/web/src/components/os/overlays/PersonaSwitcher.tsx) groups personas into universal modes and template-scoped specialists (apps/web/src/lib/persona-tier.ts). - The OnboardingWizard (
apps/web/src/components/os/overlays/OnboardingWizard.tsx) runs first-launch → who-are-you → model-gate → memory-import → template → first-task. Templates and the template-to-persona mapping live inoverlays/onboarding/constants.ts.
interface AgentPersona {
id, name, description, icon, systemPrompt, modelPreference,
tools: string[], workspaceAffinity: string[],
suggestedCommands: string[], defaultWorkflow: string | null,
disallowedTools?: string[] // denylist, wins over tools[]
failurePatterns?: string[]
isReadOnly?: boolean // no write tools after persona tool filtering
tagline?: string
bestFor?: string[]
wontDo?: string
suggestedSkills?: string[]
suggestedConnectors?: string[]
suggestedMcpServers?: string[]
}
8. Security Constraints (Non-Negotiable)
- Secrets belong in the secret store (
packages/core/src/vault.tsuntil P1.2 replaces it with aSecretStoreinterface) or an untracked local.env. Never in git..env.exampleholds placeholders only. - Injection defense. Call
scanForInjection()frominjection-scanner.tson all connector and external input. - No eval and no dynamic require.
- Tauri IPC allowlist stays explicit in
app/src-tauri/capabilities/. - Parameterized SQL only. No string interpolation in queries.
9. Already Built — Do Not Recreate
| File | What it does |
|---|---|
packages/agent/src/injection-scanner.ts |
scanForInjection() |
packages/agent/src/cost-tracker.ts |
CostTracker and model pricing |
packages/agent/src/tool-filter.ts |
filterToolsForContext() |
packages/agent/src/skill-frontmatter.ts |
parseSkillFrontmatter() |
packages/agent/src/feature-flags.ts |
Feature flags |
packages/agent/src/capability-router.ts |
Per-capability routing |
packages/agent/src/loop-guard.ts |
Infinite-loop prevention |
packages/agent/src/contradiction-detector.ts |
Memory conflict detection |
packages/shared/src/mcp-catalog.ts |
MCP server catalog |
packages/core/src/telemetry.ts |
Local telemetry pipeline |
packages/server/src/local/persona-tool-filter.ts |
applyPersonaToolFilter, filterMcpToolsForPersona |
10. Glossary
| Term | Meaning |
|---|---|
| Sidecar | The local Fastify server (packages/server/src/local) that the UI talks to |
| Memory contract | The interface Waggle uses to remember, search, get, update and delete memories (P0.3) |
| mem0 | Open-source memory library (mem0ai, Apache-2.0) behind the contract, run locally |
| Hive DS | Waggle design system tokens (waggle-theme.css) |
| BEHAVIORAL_SPEC | Core agent rules (packages/agent/src/behavioral-spec.ts) |
| Weaver | Memory consolidation and session-skill extraction (packages/weaver) |
| WaggleDance | Multi-agent team coordination (packages/waggle-dance), postponed |
| Work package | A unit of the conversion plan: 0.x, P0.x, P1.x, P2.x |
| UF-NNN | An entry in the upstream fixes log (docs/oss/upstream-fixes.md) |