553efcc146
Complete documentation rewrite to match the current codebase: - README: add benefits section (process consistency, token savings with estimates, project isolation, continuous planning, feedback loops, role-based prompts, atomic operations, audit trail), task workflow with state diagram, model-to-role mapping tables, installation guide - New TOOLS.md: complete reference for all 11 tools with parameters, behavior, and execution guards - New CONFIGURATION.md: full config reference for openclaw.json, projects.json, heartbeat, notifications, workspace layout - Fix tool names across all docs: task_pickup→work_start, task_complete→work_finish - Fix tier model: QA has reviewer/tester levels, not flat "qa" - Fix config schema: nested models.dev.*/models.qa.* structure - Fix prompt path: projects/roles/ not projects/prompts/ - Fix worker state: uses "level" field not "model"/"tier" - Fix MANAGEMENT.md: remove incorrect model references - Fix TESTING.md: update model config example to nested structure - Remove VERIFICATION.md (one-off checklist, no longer needed) - Add cross-references between all docs pages https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# DevClaw — Context Awareness
|
|
|
|
DevClaw adapts its behavior based on how you interact with it.
|
|
|
|
## Design Philosophy
|
|
|
|
**One Group = One Project = One Team**
|
|
|
|
DevClaw enforces strict boundaries between projects:
|
|
- Each Telegram/WhatsApp group represents a **single project**
|
|
- Each project has its **own dedicated dev/qa workers**
|
|
- Project work happens **inside that project's group**
|
|
- Setup and configuration happen **outside project groups**
|
|
|
|
This prevents:
|
|
- Cross-project contamination (workers picking up wrong project's tasks)
|
|
- Confusion about which project you're working on
|
|
- Accidental registration of wrong groups
|
|
- Setup discussions cluttering project work channels
|
|
|
|
This enables:
|
|
- Clear mental model: "This group = this project"
|
|
- Isolated work streams: Each project progresses independently
|
|
- Dedicated teams: Workers focus on one project at a time
|
|
- Clean separation: Setup vs. operational work
|
|
|
|
## Three Interaction Contexts
|
|
|
|
### 1. Via Another Agent (Setup Mode)
|
|
|
|
When you talk to your main agent about DevClaw:
|
|
- Use: `onboard`, `setup`
|
|
- Avoid: `work_start`, `status` (operational tools)
|
|
|
|
**Example:**
|
|
```
|
|
User → Main Agent: "Can you help me set up DevClaw?"
|
|
Main Agent → Calls onboard
|
|
```
|
|
|
|
### 2. Direct Message to DevClaw Agent
|
|
|
|
When you DM the DevClaw agent directly on Telegram/WhatsApp:
|
|
- Use: `status` (all projects), `health` (system overview)
|
|
- Avoid: `work_start` (project-specific work), setup tools
|
|
|
|
**Example:**
|
|
```
|
|
User → DevClaw DM: "Show me the status of all projects"
|
|
DevClaw → Calls status (shows all projects)
|
|
```
|
|
|
|
### 3. Project Group Chat
|
|
|
|
When you message in a Telegram/WhatsApp group bound to a project:
|
|
- Use: `work_start`, `work_finish`, `task_create`, `status` (auto-filtered)
|
|
- Avoid: Setup tools, system-wide queries
|
|
|
|
**Example:**
|
|
```
|
|
User → Project Group: "pick up issue #42"
|
|
DevClaw → Calls work_start (only works in groups)
|
|
```
|
|
|
|
## How It Works
|
|
|
|
### Context Detection
|
|
|
|
Each tool automatically detects:
|
|
- **Agent ID** — Is this the DevClaw agent or another agent?
|
|
- **Message Channel** — Telegram, WhatsApp, or CLI?
|
|
- **Session Key** — Is this a group chat or direct message?
|
|
- Format: `agent:{agentId}:{channel}:{type}:{id}`
|
|
- Telegram group: `agent:devclaw:telegram:group:-5266044536`
|
|
- WhatsApp group: `agent:devclaw:whatsapp:group:120363123@g.us`
|
|
- DM: `agent:devclaw:telegram:user:657120585`
|
|
- **Project Binding** — Which project is this group bound to?
|
|
|
|
### Guardrails
|
|
|
|
Tools include context-aware guidance in their responses:
|
|
```json
|
|
{
|
|
"contextGuidance": "Context: Project Group Chat (telegram)\n You're in a Telegram group for project 'my-webapp'.\n Use work_start, work_finish for project work.",
|
|
...
|
|
}
|
|
```
|
|
|
|
## Tool Context Requirements
|
|
|
|
| Tool | Group chat | Direct DM | Via agent |
|
|
|---|---|---|---|
|
|
| `onboard` | Blocked | Works | Works |
|
|
| `setup` | Works | Works | Works |
|
|
| `work_start` | Works | Blocked | Blocked |
|
|
| `work_finish` | Works | Works | Works |
|
|
| `task_create` | Works | Works | Works |
|
|
| `task_update` | Works | Works | Works |
|
|
| `task_comment` | Works | Works | Works |
|
|
| `status` | Auto-filtered | All projects | Suggests onboard |
|
|
| `health` | Auto-filtered | All projects | Works |
|
|
| `work_heartbeat` | Single project | All projects | Works |
|
|
| `project_register` | Works (required) | Blocked | Blocked |
|
|
|
|
**Why `project_register` requires group context:**
|
|
- Forces deliberate project registration from within the project's space
|
|
- You're physically in the group when binding it, making the connection explicit
|
|
- Impossible to accidentally register the wrong group
|
|
|
|
## WhatsApp Support
|
|
|
|
DevClaw fully supports WhatsApp groups with the same architecture as Telegram:
|
|
|
|
- WhatsApp group detection via `sessionKey.includes("@g.us")`
|
|
- Projects keyed by WhatsApp group ID (e.g., `"120363123@g.us"`)
|
|
- Context-aware tools work identically for both channels
|
|
- One project = one group (Telegram OR WhatsApp)
|
|
|
|
**To register a WhatsApp project:**
|
|
1. Go to the WhatsApp group chat
|
|
2. Call `project_register` from within the group
|
|
3. Group ID auto-detected from context
|
|
|
|
## Implementation
|
|
|
|
- **Module:** [`lib/context-guard.ts`](../lib/context-guard.ts)
|
|
- **Detection logic:** Checks agentId, messageChannel, sessionKey pattern matching
|
|
- **Configuration:** `devClawAgentIds` in plugin config lists which agents are DevClaw orchestrators
|
|
|
|
## Related
|
|
|
|
- [Configuration — devClawAgentIds](CONFIGURATION.md#devclaw-agent-ids)
|
|
- [Architecture — Scope boundaries](ARCHITECTURE.md#scope-boundaries)
|