BWOC Handbook¶
The single entry point for everyone who uses, builds, operates, or indexes the BWOC framework — a backend-neutral framework for incarnating and orchestrating AI coding agents, driven by one CLI: bwoc.
🇹🇭 ฉบับภาษาไทย:
README.th.md· Framework repo:bemindlabs/BWOC-Framework· v2.24.0 · Canonical docs (EN/TH):docs/
This handbook is role-indexed and bilingual. English is primary (canonical); each page has a Thai counterpart (*.en.md ↔ *.th.md). Open your role, read one book, follow links into the framework docs only when you need the full treatment.
Find your handbook¶
| You are… | Read | One-liner |
|---|---|---|
| 🧭 Why BWOC — the design, the reasoning & the dhamma mapping | philosophy/HANDBOOK.en.md · TH |
Design pillars, where DDD/SOLID are thin, 22-framework mapping, why adopt it |
| 🧑💻 End user — run agents, chat, teams, tasks (no framework code) | end-user/HANDBOOK.en.md · TH |
Install, init a workspace, drive agents with bwoc |
| 🛠️ Developer — build on / contribute to the framework (Rust, CLI, harness) | developer/HANDBOOK.en.md · TH |
Crate map, build/test, hooks, versioning, release, PR gates |
| 🤖 Agent author / operator — incarnate, tune, run agents | agents/HANDBOOK.en.md · TH |
Agent layout, the AGENTS.md rule, slots, manifest, the arc, bwoc check |
| ✍️ Persona · Mindsets · Skills — write an agent's identity & capabilities | slots/HANDBOOK.en.md · TH |
WHO/HOW/WHAT slot files; frontmatter, principle//domain/ tags, maturity L1–L7 |
| 🌱 Self-improvement — how an agent learns, reflects & improves | self-improvement/HANDBOOK.en.md · TH |
Learning loop (study/reflect/practice), memory tiers, curation, maturity, metrics |
| 🔌 Backends — drive & configure agents via each CLI | backends/HANDBOOK.en.md · TH |
Claude/Codex/AGY/Kimi/Copilot/Ollama; prompt-driven config after init |
| 🔎 AI search / retrieval agent — ingest this corpus to answer questions | ai-search/HANDBOOK.en.md · TH + llms.txt |
Where canonical facts live, how to cite, what not to hallucinate |
| 🕷️ Web crawler / indexer | crawler/HANDBOOK.en.md · TH + robots.txt + sitemap.md |
Crawl policy, freshness signals, what to index vs skip |
🧩 Anyone mapping the family — every BWOC & bwoc-* project |
ecosystem/HANDBOOK.en.md · TH |
What each project is, its stack, and how it connects to the core |
More chapters:
| Topic | Read | One-liner |
|---|---|---|
| 🚀 Quickstart — first agent in ~10 min | quickstart/HANDBOOK.en.md · TH |
Guided end-to-end: install → init → new → run → team → retire |
| 🧍 Single-agent workspace — one focused agent, no fleet | single-agent/HANDBOOK.en.md · TH |
bwoc init --single-agent; when to use; grow to a fleet later |
| 🛡️ Security & the tianting team | security/HANDBOOK.en.md · TH |
Threat model, Sīla 5, signed trust, the 8-agent security team |
| 🌐 Cross-workspace & protocols | cross-workspace/HANDBOOK.en.md · TH |
bwoc peer, A2A protocol, MQTT — agents across machines |
| 🖥️ Self-hosting (Harness) | harness/HANDBOOK.en.md · TH |
Run on Ollama / OpenAI-compatible via bwoc-harness |
| 🛰️ Fleet operations | fleet-ops/HANDBOOK.en.md · TH |
Run many agents: fleet health, supervise, sessions, doctor |
| 🏛️ Council — structured fleet decisions | council/HANDBOOK.en.md · TH |
propose → discuss → vote → resolve; voting models; the decision record |
| ❓ FAQ & troubleshooting | faq/HANDBOOK.en.md · TH |
Common questions + symptom→cause→fix table |
| 🤖 Chat Connectors (Telegram & Discord) | connect/HANDBOOK.en.md · TH | นำเอเจนต์เข้า Telegram & Discord ผ่าน bwoc-connect |
| 🟢 Google Workspace | google-workspace/HANDBOOK.en.md · TH | เชื่อม Gmail/Drive/Calendar ผ่าน plugin gws |
| 📋 Jira & SCRUM | jira-scrum/HANDBOOK.en.md · TH | plugin jira-cloud-rest + skill scrum-via-jira (sprint sync) |
| 🛡️ ISO Standards Audit | iso-audit/HANDBOOK.en.md · TH | ตรวจ ISO 9001/27001/20000-1/29110 ด้วย audit plugins |
| 🎯 OKR Plugin | okr/HANDBOOK.en.md · TH | ตั้ง/ติดตาม OKR ด้วย plugin okr (local-file) |
| 🧩 Plugin Authoring | plugin-craft/HANDBOOK.en.md · TH | Build a plugin: kinds, manifest, lifecycle, schemas, the write gate |
Term lookup for any reader: glossary.en.md · TH
What BWOC is, in five sentences¶
- One folder, one agent. Each agent is a self-contained directory cloned from a template; its identity, mindsets, and skills live in slot folders.
- Backend-neutral. The same agent runs on Claude, Codex, Kimi, or a self-hosted model (Ollama / any OpenAI-compatible endpoint) via
bwoc-harness. No vendor is favored. - Designed on explicit principles. A few specialized terms exist, but every one maps to a real engineering concern (lifecycle, memory pruning, inter-agent trust, threat modeling) — you don't need to learn the terms to use it. See the glossary when curious.
- Persistent, prune-aware memory. Agents accumulate knowledge across sessions and deliberately drop stale entries (
MEMORY.md≤ 200 lines). - Multi-agent safe. Many agents share one workspace — shared task lists, teams, trust scoring — without collision.
The lifecycle every BWOC object follows¶
| Phase | Plain name | What happens | CLI |
|---|---|---|---|
| 1 | Birth | Identity created, manifest resolved, capabilities declared | bwoc new, bwoc init |
| 2 | Live / work | Agent operates; state and memory evolve under discipline | bwoc spawn, chat, run, supervise |
| 3 | Retire | Cleanup; branches released, memory pruned, task closed, agent retired | bwoc retire, stop |
The framework docs label these three phases with Pali terms (uppāda · ṭhiti · vaya). You can ignore the labels and just think "birth / live / retire."
Conventions used across this handbook¶
- Handbook vs source of truth. This handbook orients and summarizes. The source of truth is the framework repo
bemindlabs/BWOC-Framework: code incrates/, docs indocs/en+docs/th, the spec inmodules/agent-template/AGENTS.md. On conflict, the repo wins — and that means this handbook has a bug; please fix it. - Bilingual, English-primary. Every page is
*.en.md(canonical) with a*.th.mdcounterpart kept in parity. Edit both in the same change. - Plain language, minimal jargon. Specialized terms are explained on first use and link to the glossary.
- Commands target the
bwocCLI. For the live surface runbwoc help getting-startedorbwoc <cmd> --help. - Versions move. Pin claims to a version when it matters; check
VERSION.mdfor currentSoftware-Version/Document-Version. - Links never point into a private workspace. All references to framework source go to the public GitHub repo, never to a local path like
projects/bwoc-framework.
Fast paths¶
# Just use it
bwoc init ./my-workspace && cd my-workspace && bwoc list
# Make an agent (template auto-detected from the framework clone in cwd ancestors)
bwoc new sage --role "research assistant" --target agents/agent-sage
bwoc check agents/agent-sage
# Build the framework (from a clone of github.com/bemindlabs/BWOC-Framework)
git clone https://github.com/bemindlabs/BWOC-Framework && cd BWOC-Framework
cargo build && cargo test
# Index this corpus (machine)
cat llms.txt