refactor: remove context awareness documentation and related code; streamline tool registration and context detection
This commit is contained in:
Lauren ten Hoor
@@ -135,24 +135,6 @@ Control which lifecycle events send notifications:
|
||||
| `workerStart` | `true` | Announce when a worker picks up a task |
|
||||
| `workerComplete` | `true` | Announce when a worker finishes a task |
|
||||
|
||||
### DevClaw Agent IDs
|
||||
|
||||
List which agents are recognized as DevClaw orchestrators (used for context detection):
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"devclaw": {
|
||||
"config": {
|
||||
"devClawAgentIds": ["my-orchestrator"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Tool Permissions
|
||||
|
||||
Restrict DevClaw tools to your orchestrator agent:
|
||||
|
||||
@@ -1,133 +0,0 @@
|
||||
# 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)
|
||||
@@ -320,7 +320,7 @@ Conversational onboarding guide. Returns step-by-step instructions for the agent
|
||||
|
||||
**Source:** [`lib/tools/onboard.ts`](../lib/tools/onboard.ts)
|
||||
|
||||
**Context:** Works in DMs and via-agent. Blocks group chats (setup should not happen in project groups).
|
||||
**Note:** Call this before `setup` to get step-by-step guidance.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user