From b11bdb802995e7d88bace502042d35dac0a90dd5 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Wed, 4 Nov 2026 10:41:40 +0100 Subject: [PATCH] docs: make CONTRIBUTING the single contributor guide --- .github/PULL_REQUEST_TEMPLATE.md | 4 +- .gitignore | 3 +- AGENTS.md | 328 ------------------------------- CONTRIBUTING.md | 17 +- docs/ARCHITECTURE.md | 3 +- 5 files changed, 11 insertions(+), 344 deletions(-) delete mode 100644 AGENTS.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 00b7681..7fcf096 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,6 @@ ## What & why diff --git a/.gitignore b/.gitignore index fa29074..2fadefa 100644 --- a/.gitignore +++ b/.gitignore @@ -84,6 +84,7 @@ app/src-tauri/resources/service.js *.sw? .claude/ CLAUDE.md +AGENTS.md .playwright-mcp/ .superpowers/ ~$* @@ -123,7 +124,7 @@ tests/vision/artifacts/ /EVAL-RESULTS-V5.md /PLAN.md -# npm is the canonical package manager (AGENTS.md); bun.lock removed to avoid a +# npm is the canonical package manager (CONTRIBUTING.md); bun.lock removed to avoid a # divergent dependency graph from a stray `bun install`. bun.lock diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 027901f..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,328 +0,0 @@ -# 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. Memory runs on local mem0 through the memory contract (P1.5); -team mode stays in postponed packages, and the excluded packages left the repository in P2.2. -Work packages remove or replace the rest 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: `waggle.db` for Waggle's own data, and mem0's store for memory | -| Memory | `MemoryStore` from `@waggle/memory-contract`, implemented on local mem0 by `@waggle/memory-mem0` (ADR-0007) | -| 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`, `marketplace`, `cli`, `launcher` | Keep. | -| `packages/memory-contract`, `packages/memory-mem0` | Keep. The memory contract and its mem0 implementation (ADR-0007). | -| `packages/team-server`, `packages/waggle-dance`, `packages/worker` | Postponed: team mode stays in the repo, is not built or shipped (ADR-0003). | -| `packages/hive-mind-*`, `memory-mcp`, `wiki-compiler`, `admin-web`, `apps/www` | Excluded; removed in P2.2. The old memory engine is maintained separately by the owner. | -| `apps/browser-ext` | Not decided. Do not extend it. | -| `docs/` | `docs/oss/` holds the community-edition records. The remaining guides, reference, architecture, getting-started and contributing pages predate this edition and are rewritten in P2.4. Internal history (`sidecar/`, `benchmarks/`, `judging/`, internal docs) was removed in P2.2. | - -### 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, waggle-db (Waggle's own data: cron, notifications, - # cost tracking, profile, awareness), embeddings, vault, logger -packages/shared/src/ # shared types, Zod schemas, MCP catalog -``` - -Already removed: tiers and Stripe (P0.1); KVARK, enterprise packs, the compliance -subsystem, self-learning and `packages/optimizer` (P1.4, P1.6, ADR-0004); the team and -WaggleDance routes in the sidecar and `team-sync` in core, with the team server moved to -`packages/team-server` (P1.1); the single-mind to multi-mind migration in core (P1.2); -Waggle Room tasks for external coding agents (`POST /api/tools/run`, the headless task contract -in tool manifests, run tokens and the hook settings a launch used to set) and the router's -external executors. The Tool Launcher keeps detect, launch, live output and stop; the Room canvas -(`/room`) still shows Waggle agents, groups and launched tools. -The install audit trail moved from core to the server (`packages/server/src/local/install-audit.ts`, -P1.2); other packages write to it through `InstallAuditRecorder` from `@waggle/shared`. - ---- - -## 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 reaches memory through `MemoryStore` - (`@waggle/memory-contract`), must not import `@waggle/hive-mind-*`, `memory-mcp` or - `wiki-compiler`, and must not run SQL against a memory database (ADR-0007). Until P1.5 moves - the existing callers, keep changes to the old memory code minimal. The knowledge graph is - not in v1. -3. **Team mode is frozen.** Do not add features to `packages/team-server`, 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 # 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/ -``` - -- Workspace packages export their TypeScript source under the `source` condition, which - tsx, Vitest, Vite and the sidecar bundle resolve (P2.1). No `build:packages` is needed - before running or testing; it builds the `dist/` entries for publishing. -- The desktop app (`app/`) has its own dependencies outside the npm workspaces: run - `npm ci` in `app/` once, then `npm run tauri:build:mac:arm64` (or `tauri:build:mac:x64`, - `tauri:build:win`, `tauri:build:linux`). It needs a current Rust toolchain. Releases are - built and smoke-tested on all targets by `.github/workflows/release.yml`. Set `CI=true` when the build runs without - access to Finder, or the DMG step fails while styling the disk image window. The Windows - installer must be built on Windows: see [docs/oss/build-windows.md](docs/oss/build-windows.md). -- 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 -npm run build:packages # tsc -b over tsconfig.build.json: every in-scope package -npx tsc --noEmit --project app/tsconfig.json -npm run typecheck:tests # test suites; advisory until the existing errors are fixed -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; 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=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 — `. -- 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 (the `SecretStore` interface in - `packages/core/src/secret-store.ts`, implemented by `VaultStore` in `vault.ts`) 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 | `MemoryStore` in `@waggle/memory-contract`: how Waggle remembers, searches, lists, updates and forgets memories (ADR-0007) | -| 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`) | -| 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`) | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 190f27e..778910a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,8 @@ Thank you for helping. This page covers the setup, the checks and how to propose a change. -**Read [AGENTS.md](AGENTS.md) before you change code.** It is the operating contract for this -repository, for people and coding agents alike: what is in scope, the rules that must not be -broken, and the commands that verify a change. The decisions behind it are in -[docs/oss/adr/](docs/oss/adr/README.md). [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains -how the parts fit together. +[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains how the parts fit together. The rules +below are the ones reviews check first. ## Prerequisites @@ -45,7 +42,7 @@ Other entry points: ```bash npm run dev -w @waggle/cli # terminal REPL on the same memory and waggle.db -(cd app && npm ci && npm run tauri:build:mac:arm64) # desktop app; see AGENTS.md section 4 +(cd app && npm ci && npm run tauri:build:mac:arm64) # desktop app; also tauri:build:mac:x64, :win, :linux ``` ## Checks @@ -77,7 +74,6 @@ root `tests/`. New behavior needs a test; a bug fix needs a test that fails with ## Rules that reviews check first -The full list is in [AGENTS.md](AGENTS.md), section 3. In short: - No monetization: no tiers, trials, payments, license checks or upsell. - Memory goes through `MemoryStore` from `@waggle/memory-contract`. No SQL against a memory @@ -89,8 +85,8 @@ The full list is in [AGENTS.md](AGENTS.md), section 3. In short: - Analytics stay opt-in. Never commit a PostHog key or any other secret. - Platform-specific code needs Windows, macOS and Linux paths. End users must not need Python, Docker, a compiler or a developer Node.js install. -- Security constraints (secrets in the vault, the injection scanner on external input, no - `eval`, an explicit Tauri IPC allowlist, parameterized SQL) are in AGENTS.md, section 8. +- Security: secrets live in the vault, external input goes through the injection scanner, no + `eval`, the Tauri IPC allowlist stays explicit, and SQL is parameterized. ## Code style @@ -98,8 +94,7 @@ The full list is in [AGENTS.md](AGENTS.md), section 3. In short: `import type` for types. - File names in `kebab-case.ts`; React components in `PascalCase.tsx`. - Match the style of the file you change. Do not reformat code you do not otherwise touch. -- Search before you add a file: [AGENTS.md](AGENTS.md), section 9, lists modules that already - exist. +- Search before you add a file: the module you need may already exist. - Code, comments, commit messages and documentation are in English. Write plainly. ## Commits and pull requests diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0c42cd1..57cd6f5 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,8 +2,7 @@ How the community edition of Waggle is put together: the parts, how a chat turn flows through them, where data lives and how a release is built. The decisions behind it are in -[`docs/oss/adr/`](oss/adr/README.md); [`AGENTS.md`](../AGENTS.md) lists the status of every -package. +[`docs/oss/adr/`](oss/adr/README.md). ## Overview