fix: agent hygiene P0/P1 — gitignore, DATABASE_URL, CI lint, docs

.github/workflows/ci.yml

@@ -1,20 +1,22 @@
-name: CI
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v1
-      - run: bun install
-      - run: bun test
-      - run: bun run build
-
-  docker:
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v4
-      - uses: docker/setup-buildx-action@v3
-      - name: Build Docker image
-        run: docker build -t agentswarm/agentswarm:latest .
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun lint
+      - run: bun format --check
+      - run: bun test
+      - run: bun run build
+
+  docker:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Build Docker image
+        run: docker build -t agentswarm/agentswarm:latest .

.gitignore

@@ -1 +1,37 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.next/
+.svelte-kit/
+build/
+
+# Environment — never commit secrets
+.env
+.env.local
+.env.*.local
+
+# Database files
+*.db
+*.db-shm
+*.db-wal
+data/
+
+# Logs
+*.log
+npm-debug.log*
+bun-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Vercel
 .vercel

AGENTS-IMPROVEMENT-SPEC.md

@@ -0,0 +1,165 @@
+# AGENTS.md Improvement Spec
+
+This document records the audit findings and the concrete changes made or required to bring agent guidance up to a useful standard.
+
+---
+
+## Audit Summary
+
+### What exists
+
+| Artifact | Location | Quality |
+|----------|----------|---------|
+| `AGENTS.md` | — | **Missing** (created in this session) |
+| Agent skill files (`.ona/skills/`, `.cursor/rules/`) | — | **Missing** |
+| `CONTRIBUTING.md` | `/CONTRIBUTING.md` | Good baseline; lacks agent-specific detail |
+| `README.md` | `/README.md` | Good user-facing overview; not agent-oriented |
+| `swarm-core.md` | `/swarm-core.md` | Phase 2 code reference dump; not structured guidance |
+| `docs/` | `/docs/` | Two useful docs (`how-it-works.md`, `tools.md`); no index |
+| `.devcontainer/devcontainer.json` | `/.devcontainer/` | Uses heavy universal image; no Bun feature pinned |
+| `.gitignore` | `/.gitignore` | Only contains `.vercel` — critically incomplete |
+| CI (`ci.yml`) | `.github/workflows/` | Functional but no lint step |
+| PR template | `.github/PULL_REQUEST_TEMPLATE.md` | Good |
+
+---
+
+## What Is Good
+
+- **CONTRIBUTING.md** covers setup, code style, PR process, and community links clearly.
+- **PR template** is well-structured with a type-of-change checklist and a 512 MB RAM reminder.
+- **Issue templates** (bug + feature) are thorough and include environment fields.
+- **docs/how-it-works.md** explains the ReAct loop with a clear ASCII diagram.
+- **docs/tools.md** lists all 14 tools with required env vars — useful for agents adding integrations.
+- **CI** runs install + test + build on every push/PR, and builds Docker on `main`.
+- **`.env.example`** documents all env vars with comments.
+
+---
+
+## What Is Missing
+
+### 1. `AGENTS.md` — created in this session
+No file existed to orient AI coding agents. Created at `/AGENTS.md` covering:
+- Repo structure map
+- Tech stack table
+- Dev commands
+- Code conventions
+- Architecture constraints (memory budget, step limit, sandbox)
+- Step-by-step guide for adding a new tool
+- PR checklist
+- CI expectations
+- File ownership table
+
+### 2. `.gitignore` is nearly empty
+Only `.vercel` is listed. The repo uses Bun, Node, TypeScript, and Docker. Without proper ignore rules, `node_modules/`, `dist/`, `.env`, `*.db`, and build artifacts will be committed accidentally.
+
+**Required additions:**
+```
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.next/
+.svelte-kit/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Database files
+*.db
+*.db-shm
+*.db-wal
+data/
+
+# Logs
+*.log
+npm-debug.log*
+bun-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+```
+
+### 3. No lint step in CI
+`ci.yml` runs `bun test` and `bun build` but not `bun lint`. Code style violations pass CI undetected.
+
+**Required change** — add to the `test` job in `.github/workflows/ci.yml`:
+```yaml
+- run: bun lint
+- run: bun format --check
+```
+
+### 4. Dev container uses a 10 GB universal image with no Bun feature
+`devcontainer.json` uses `mcr.microsoft.com/devcontainers/universal:4.0.1-noble`. This is slow to pull and does not pin Bun. A Bun-specific or Node image with the Bun devcontainer feature is faster and more reproducible.
+
+**Recommended change:**
+```json
+{
+  "name": "AgentSwarp",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
+  "features": {
+    "ghcr.io/devcontainers/features/bun:1": { "version": "1" }
+  },
+  "postCreateCommand": "bun install",
+  "forwardPorts": [3000, 3001]
+}
+```
+
+### 5. `swarm-core.md` is a raw code dump, not structured guidance
+The file contains 26 source files pasted inline. It is not useful as documentation and will confuse agents that read it as authoritative. It should either be deleted or replaced with a structured Phase 2 migration guide.
+
+### 6. No `docs/` index
+`docs/` has two good files but no index or README. Agents and contributors cannot discover what is documented.
+
+**Required:** add `docs/README.md` listing available docs and their purpose.
+
+### 7. `src/main.ts` diverges from the documented architecture
+README and `AGENTS.md` describe `apps/server/` as the API layer, but `src/main.ts` contains live route handlers and direct SQLite calls. This creates two competing entry points. The minimal `src/main.ts` should either be removed or reduced to a thin bootstrap that delegates to `apps/server/`.
+
+---
+
+## What Is Wrong
+
+### Critical: `.gitignore` is dangerously incomplete
+`node_modules/`, `.env`, `*.db`, and `dist/` are not ignored. Any `git add .` will stage secrets and large dependency trees. This must be fixed before any new contributor runs `bun install`.
+
+### Inconsistency: `package.json` version vs roadmap
+`package.json` declares `"version": "2.0.0"` but the README roadmap shows v0.2 as "In progress" and v1.0 as "Planned". The version field should match the public release state.
+
+### Inconsistency: `DATABASE_URL` vs hardcoded path
+`.env.example` sets `DATABASE_URL=./data/agentswarm.db` but `src/main.ts` opens `new Database("agentswarp.db")` ignoring the env var. The env var is documented but not respected.
+
+---
+
+## Improvement Priority
+
+| Priority | Item | Effort |
+|----------|------|--------|
+| P0 | Fix `.gitignore` | 5 min |
+| P0 | Respect `DATABASE_URL` in `src/main.ts` | 10 min |
+| P1 | Add lint + format-check to CI | 5 min |
+| P1 | Replace `swarm-core.md` with a structured migration guide or delete it | 30 min |
+| P2 | Switch devcontainer to a lighter image with pinned Bun | 15 min |
+| P2 | Add `docs/README.md` index | 10 min |
+| P3 | Reconcile `src/main.ts` with `apps/server/` architecture | 1–2 h |
+| P3 | Align `package.json` version with public roadmap | 5 min |
+
+---
+
+## Changes Made in This Session
+
+| File | Action |
+|------|--------|
+| `AGENTS.md` | Created |
+| `AGENTS-IMPROVEMENT-SPEC.md` | Created (this file) |
+
+All remaining items above are **not yet implemented** and require explicit follow-up.

AGENTS.md

@@ -0,0 +1,140 @@
+# AGENTS.md — AgentSwarp
+
+Guidance for AI coding agents working in this repository.
+
+---
+
+## Repository Overview
+
+AgentSwarp is a self-hosted, no-code AI agent platform built with Bun, Hono, SvelteKit, and SQLite. It is designed to run on low RAM (512 MB minimum).
+
+```
+agentswarp/
+├── src/main.ts              Entry point (Hono server, SQLite setup)
+├── apps/
+│   ├── web/                 SvelteKit frontend (port 3000)
+│   └── server/              Bun + Hono API server (port 3001)
+├── packages/
+│   ├── core/                Agent runner, LLM abstraction, memory, scheduler
+│   └── tools/               Built-in tool implementations (14 tools)
+├── docs/                    Architecture and tool reference docs
+├── public/                  Static assets served by Hono
+├── .devcontainer/           Dev container config
+└── .github/                 CI, PR template, issue templates
+```
+
+---
+
+## Tech Stack
+
+| Layer      | Technology                          |
+|------------|-------------------------------------|
+| Runtime    | Bun 1.0+                            |
+| Backend    | Hono (HTTP + WebSocket)             |
+| Frontend   | SvelteKit                           |
+| Database   | SQLite via `better-sqlite3`         |
+| Language   | TypeScript (strict, no `any`)       |
+| Container  | Docker / Docker Compose             |
+
+---
+
+## Development Commands
+
+```bash
+bun install          # Install dependencies
+bun dev              # Start dev server with file watching (port 3000)
+bun start            # Start production server
+bun build            # Build to ./dist
+bun test             # Run tests
+bun lint             # ESLint
+bun format           # Prettier
+```
+
+---
+
+## Code Conventions
+
+- **TypeScript everywhere** — no `any` unless unavoidable; document why if used.
+- **Prettier + ESLint** — run `bun format` and `bun lint` before committing.
+- **Small, named functions** — prefer composition over inheritance.
+- **Comments explain why**, not what.
+- **No placeholders or TODOs** in committed code — implement fully or open an issue.
+- SQLite access goes through `packages/core/` — do not add raw DB calls in route handlers.
+- New tools belong in `packages/tools/src/` and must be registered in `packages/core/src/tool-registry.ts`.
+- New API routes belong in `apps/server/` (not `src/main.ts`, which is the minimal entry point).
+
+---
+
+## Architecture Constraints
+
+- **Memory budget**: keep the runtime footprint under 512 MB. Avoid loading large assets or models into process memory.
+- **Step limit**: agent runs are capped at 15 steps to prevent infinite loops. Do not raise this without a corresponding safety review.
+- **Code execution sandbox**: `execute_code` tool runs in a sandboxed context — do not widen its permissions.
+- **WAL mode**: SQLite is opened with `journal_mode = WAL`. Maintain this for concurrent read performance.
+
+---
+
+## Environment Variables
+
+Copy `.env.example` to `.env` before running locally. Key variables:
+
+| Variable              | Purpose                                      |
+|-----------------------|----------------------------------------------|
+| `PORT`                | Server port (default `3000`)                 |
+| `SECRET_KEY`          | Session/auth secret — change before deploy   |
+| `DATABASE_URL`        | SQLite file path                             |
+| `DEFAULT_LLM_PROVIDER`| `ollama` (default), `openai`, `groq`, etc.   |
+| `DEFAULT_MODEL`       | Model name for the default provider          |
+| `OLLAMA_BASE_URL`     | Ollama endpoint (default `localhost:11434`)  |
+
+Never commit `.env` or any file containing real secrets.
+
+---
+
+## Adding a New Tool
+
+1. Create `packages/tools/src/<tool-name>.ts` implementing the `Tool` interface from `packages/core/src/types.ts`.
+2. Export it from `packages/tools/src/index.ts`.
+3. Register it in `packages/core/src/tool-registry.ts`.
+4. Add the required env vars to `.env.example` with empty values.
+5. Document the tool in `docs/tools.md`.
+6. Add a test in `packages/tools/src/__tests__/`.
+
+---
+
+## Pull Request Checklist
+
+Before opening a PR, verify:
+
+- [ ] `bun test` passes
+- [ ] `bun lint` passes with no errors
+- [ ] `bun format` applied
+- [ ] No `any` types introduced without justification
+- [ ] `.env.example` updated if new env vars were added
+- [ ] `docs/` updated if behaviour or architecture changed
+- [ ] Tested under constrained memory if the change touches the agent runner or tools
+
+---
+
+## CI
+
+GitHub Actions runs on every push and PR:
+
+- `bun install && bun test && bun run build` — must pass on all PRs.
+- Docker image build runs on `main` only.
+
+Do not merge if CI is red.
+
+---
+
+## File Ownership
+
+| Area                        | Primary location                        |
+|-----------------------------|-----------------------------------------|
+| Agent execution logic       | `packages/core/src/agent-runner.ts`     |
+| LLM provider abstraction    | `packages/core/src/llm-client.ts`       |
+| Memory (KV + vector)        | `packages/core/src/memory.ts`, `vector-store.ts` |
+| Tool implementations        | `packages/tools/src/`                  |
+| Frontend UI                 | `apps/web/src/`                         |
+| API routes                  | `apps/server/`                          |
+| Static entry point          | `src/main.ts`                           |