The previous contract described the commercial release: tiers, Stripe, KVARK, the Windows Solo qualification gate and the hive-mind mirror sync. It told agents to preserve monetization, which the community edition removes. The new contract states the scope status of every package, the conversion rules, the build and verification commands and the working rules. CLAUDE.md now only adds Claude-specific notes.
311 lines
14 KiB
Markdown
311 lines
14 KiB
Markdown
# 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 in `docs/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:
|
|
1. The agreed scope ("Waggle OSS Agreed Scope Annex", held by the project owner).
|
|
2. The decision records in [`docs/oss/adr/`](docs/oss/adr/README.md).
|
|
3. 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 ===
|
|
1. **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.
|
|
2. **Memory goes through the contract.** New code must not import `@waggle/hive-mind-*`,
|
|
`memory-mcp` or `wiki-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.
|
|
3. **Team mode is frozen.** Do not add features to team routes, WaggleDance or the worker.
|
|
4. **Self-learning is out.** Do not extend evolution, improvement signals, correction
|
|
learning, judge or eval loops, or `optimizer`. Cost tracking stays.
|
|
5. **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 by
|
|
`whatsapp-web.js` (ADR-0005). State the license of a new dependency in the commit message.
|
|
6. **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.
|
|
7. **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.
|
|
8. **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).
|
|
9. **Upstream defects.** When you find or fix a defect that also exists in the commercial
|
|
product, log it in [`docs/oss/upstream-fixes.md`](docs/oss/upstream-fixes.md) in 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
|
|
|
|
```bash
|
|
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/static`
|
|
with `wildcard: false`), so assets from a later build return 404. Restart the sidecar after
|
|
`npm 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")
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
- Playwright e2e reuses any server already listening on :3333 and its data directory. For an
|
|
isolated run set `WAGGLE_E2E_REUSE_EXISTING_SERVER=0` and a free `WAGGLE_E2E_PORT`. Its web
|
|
server step runs `npm run build:all`, which rewrites the root `dist/`.
|
|
- [`docs/oss/baseline.md`](docs/oss/baseline.md) records 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.ts` holds the canonical `PERSONAS` array (pure data);
|
|
`personas.ts` holds the `AgentPersona` interface 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 in `overlays/onboarding/constants.ts`.
|
|
|
|
```typescript
|
|
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)
|
|
|
|
1. **Secrets** belong in the secret store (`packages/core/src/vault.ts` until P1.2 replaces
|
|
it with a `SecretStore` interface) or an untracked local `.env`. Never in git. `.env.example`
|
|
holds placeholders only.
|
|
2. **Injection defense.** Call `scanForInjection()` from `injection-scanner.ts` on all
|
|
connector and external input.
|
|
3. **No eval and no dynamic require.**
|
|
4. **Tauri IPC allowlist** stays explicit in `app/src-tauri/capabilities/`.
|
|
5. **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`) |
|