This commit is contained in:
Oleg Maslov
495
waggle-cowork/claude-code-deep-dive.md
Normal file
495
waggle-cowork/claude-code-deep-dive.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# Claude Code Source — Deep Architecture Analysis for Waggle OS
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Analyst:** Cowork Session (CxO Advisory)
|
||||
**Source:** Full source tree at `D:\Projects\Claude Code Source\src\src` (~600+ files)
|
||||
**Purpose:** Extract production-grade architectural patterns for Waggle OS maturation
|
||||
|
||||
---
|
||||
|
||||
## 1. AGENT ORCHESTRATION — The Complete Picture
|
||||
|
||||
### 1.1 Agent Definition Schema
|
||||
|
||||
Every agent in Claude Code — built-in or custom — follows a single schema defined in `loadAgentsDir.ts`. This is the most immediately adoptable pattern for Waggle.
|
||||
|
||||
**BaseAgentDefinition fields:**
|
||||
|
||||
```
|
||||
agentType — unique identifier (e.g., "Explore", "Plan", "general-purpose")
|
||||
whenToUse — natural language description used in the tool prompt
|
||||
tools? — allowlist of tool names this agent can use
|
||||
disallowedTools? — denylist of tool names (complementary to allowlist)
|
||||
skills? — skill names to preload when agent starts
|
||||
mcpServers? — MCP servers specific to this agent (by name reference or inline config)
|
||||
hooks? — session-scoped hook settings (pre/post tool execution)
|
||||
color? — display color for UI identification
|
||||
model? — model override ("sonnet", "opus", "haiku", or "inherit")
|
||||
effort? — reasoning effort level
|
||||
permissionMode? — "default", "plan", etc.
|
||||
maxTurns? — hard cap on agentic turns before forced stop
|
||||
memory? — persistent memory scope: "user" | "project" | "local"
|
||||
background? — always run as background task
|
||||
isolation? — "worktree" (git worktree) or "remote" (sandbox)
|
||||
initialPrompt? — prepended to first user turn
|
||||
omitClaudeMd? — skip CLAUDE.md injection for lightweight agents
|
||||
```
|
||||
**Three agent sources with priority override:**
|
||||
|
||||
1. **Built-in** (code-defined): `generalPurposeAgent`, `exploreAgent`, `planAgent`, `verificationAgent`, `claudeCodeGuideAgent`, `statuslineSetup`
|
||||
2. **Custom** (markdown files with YAML frontmatter): loaded from `.claude/agents/` directories across user, project, and policy settings
|
||||
3. **Plugin** (external packages): loaded via plugin system with plugin metadata
|
||||
|
||||
Priority resolution: `managed > flag > project > user > plugin > built-in`. Later sources override earlier ones by `agentType` name.
|
||||
|
||||
**Waggle implication:** Your 13 agent personas should be formalized into this exact schema. The separation between built-in (your core agents), custom (user-defined in workspace), and plugin (marketplace agents) maps directly to your three-tier user model: simple users get built-in, power users define custom, admins manage plugins.
|
||||
|
||||
### 1.2 Agent Tool Pool Assembly
|
||||
|
||||
Each agent gets a custom-assembled tool set via `assembleToolPool()`:
|
||||
|
||||
- Start with ALL available tools
|
||||
- If agent has `tools` allowlist → filter to only those tools
|
||||
- If agent has `disallowedTools` denylist → remove those tools
|
||||
- If agent has `memory` enabled → inject FileWrite, FileEdit, FileRead tools automatically
|
||||
- If agent has `mcpServers` → connect those MCP servers and inject their tools
|
||||
- If agent has `skills` → preload those skill invocations
|
||||
- Apply permission mode restrictions on top
|
||||
|
||||
This is compositional security — an "Explore" agent literally cannot write files because `FileWrite` is not in its tool pool. Not enforced by prompt instructions, but by schema.
|
||||
### 1.3 Coordinator Mode (Feature-Gated)
|
||||
|
||||
The coordinator is the most strategically valuable pattern for Waggle's Mission Control.
|
||||
|
||||
**How it works:**
|
||||
- Activated via `CLAUDE_CODE_COORDINATOR_MODE=1`
|
||||
- Coordinator gets ONLY: `Agent`, `SendMessage`, `TaskStop`, `SyntheticOutput` tools
|
||||
- Cannot directly read files, write code, or execute commands
|
||||
- ALL execution is delegated to "worker" subagents
|
||||
- Workers report back via `<task-notification>` XML messages
|
||||
|
||||
**Coordinator workflow:**
|
||||
1. User request arrives
|
||||
2. Coordinator spawns research workers in parallel (fan-out)
|
||||
3. Workers report findings as task notifications
|
||||
4. Coordinator SYNTHESIZES findings (this is the key insight — the coordinator must understand before delegating implementation)
|
||||
5. Coordinator spawns implementation workers with precise specs
|
||||
6. Implementation workers self-verify (first QA layer)
|
||||
7. Coordinator spawns verification workers (second QA layer)
|
||||
8. Coordinator reports results to user
|
||||
|
||||
**Critical design principle:** "Never delegate understanding." The coordinator's prompt explicitly forbids phrases like "based on your findings, fix the bug" — it must synthesize findings into specific instructions with file paths, line numbers, and exact changes.
|
||||
|
||||
**Scratchpad pattern:** Workers share durable cross-worker knowledge via a `scratchpadDir` — a designated directory where workers can read/write without permission prompts. This enables coordination through shared state on the filesystem.
|
||||
|
||||
**Waggle implication:** This is exactly what Mission Control should become. The Cockpit view shows agent status; Mission Control orchestrates. The scratchpad pattern maps to your existing workspace file system. The worker notification pattern (`<task-notification>` XML) should be adopted for your event stream.
|
||||
### 1.4 Fork Subagent Pattern
|
||||
|
||||
Forks solve a specific problem: context pollution during research.
|
||||
|
||||
**Without forks:** Agent researches a question → all intermediate tool calls (file reads, greps, etc.) fill context → context is now cluttered with noise that isn't needed for the next task.
|
||||
|
||||
**With forks:** Agent spawns a fork → fork inherits the FULL parent conversation context → fork does research → fork returns a summary → parent's context stays clean.
|
||||
|
||||
**Key rules:**
|
||||
- Forks share the parent's prompt cache (cheap to spawn)
|
||||
- Don't set a different `model` on a fork (breaks cache sharing)
|
||||
- Don't "peek" at fork output files — wait for the completion notification
|
||||
- Fork prompts are directives, not full context briefs (context is inherited)
|
||||
- For fresh agents (`subagent_type` specified), write full context briefs
|
||||
|
||||
**Continue vs. Spawn decision matrix:**
|
||||
|
||||
| Situation | Action | Why |
|
||||
|---|---|---|
|
||||
| Research found exactly the files to edit | Continue (SendMessage) | Worker has files in context |
|
||||
| Research was broad, implementation is narrow | Spawn fresh | Avoid dragging exploration noise |
|
||||
| Correcting a failure | Continue | Worker has error context |
|
||||
| Verifying another worker's code | Spawn fresh | Fresh eyes, no implementation assumptions |
|
||||
| Wrong approach entirely | Spawn fresh | Avoid anchoring on failed path |
|
||||
|
||||
**Waggle implication:** This directly solves the "13 agents generating output" context management problem. Waggle Dance workflows should use the fork pattern for research phases and fresh spawns for implementation phases.
|
||||
### 1.5 Agent Memory (Per-Agent Persistent State)
|
||||
|
||||
Each agent can have its own persistent memory, separate from the main conversation memory.
|
||||
|
||||
**Three scopes:**
|
||||
- **user** (`~/.claude/agent-memory/<agentType>/`): persists across all projects
|
||||
- **project** (`.claude/agent-memory/<agentType>/`): project-specific, version-controlled
|
||||
- **local** (`.claude/agent-memory-local/<agentType>/`): project-specific, NOT version-controlled
|
||||
|
||||
**Memory snapshots:** Teams can share agent memory via project-level snapshots. On first run, if a project snapshot exists but no local memory, the snapshot is copied to local. If a newer snapshot exists, the agent is notified to consider updating.
|
||||
|
||||
When memory is enabled for an agent, FileWrite/FileEdit/FileRead tools are automatically injected even if the agent has a restricted tool allowlist.
|
||||
|
||||
**Waggle implication:** Your graph database memory should support per-agent memory scopes. An "Analysis Agent" should remember different things than a "Writing Agent." The snapshot/sync pattern is essential for team workspaces.
|
||||
|
||||
---
|
||||
|
||||
## 2. MEMORY SYSTEM — Production-Grade Patterns
|
||||
|
||||
### 2.1 Four-Type Taxonomy (Enforced)
|
||||
|
||||
Types: `user`, `feedback`, `project`, `reference`
|
||||
|
||||
Each type has structured guidance:
|
||||
- **user**: role, goals, preferences. Always private scope. Saved when learning about who the user is.
|
||||
- **feedback**: behavioral corrections AND confirmations. "Record from failure AND success" — only saving corrections makes the system overly cautious. Structure: rule → Why → How to apply.
|
||||
- **project**: ongoing work context not derivable from code/git. Convert relative dates to absolute. Decay fast, so include "why" for judging staleness.
|
||||
- **reference**: pointers to external systems (Linear project, Grafana dashboard, Slack channel).
|
||||
**Explicit exclusions (even on user request):**
|
||||
- Code patterns, architecture, file paths — derivable from current project state
|
||||
- Git history — `git log`/`git blame` are authoritative
|
||||
- Debugging solutions — the fix is in the code
|
||||
- Anything in CLAUDE.md files
|
||||
- Ephemeral task details
|
||||
|
||||
If the user asks to save a PR list, the system asks "what was surprising or non-obvious about it?" — only that part gets saved.
|
||||
|
||||
### 2.2 Side-Query Relevance (The Key Innovation)
|
||||
|
||||
`findRelevantMemories.ts` uses a lightweight Sonnet call to pre-filter memories.
|
||||
|
||||
**Flow:**
|
||||
1. `scanMemoryFiles()` reads YAML frontmatter from all `.md` files in the memory directory (max 200 files, first 30 lines per file — no full content loaded)
|
||||
2. Headers are formatted as a manifest: `- [type] filename (ISO timestamp): description`
|
||||
3. A Sonnet side-query gets: the user's current query + the manifest + list of recently-used tools
|
||||
4. Sonnet returns up to 5 filenames that are clearly relevant
|
||||
5. Only those 5 files are fully loaded into context
|
||||
|
||||
**Anti-noise feature:** If tools are currently in use (e.g., MCP spawn tool), their reference docs are excluded — the system is already exercising them, reference docs are noise. But warnings/gotchas about those tools ARE included.
|
||||
|
||||
**Prefetch pattern:** Memory relevance is prefetched at query start (`startRelevantMemoryPrefetch`), runs during model streaming, and is consumed after tools execute. Never blocks the main path.
|
||||
|
||||
### 2.3 Memory Freshness and Staleness
|
||||
|
||||
`memoryAge.ts` computes human-readable age ("47 days ago") and injects staleness warnings:
|
||||
|
||||
> "This memory is 47 days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact."
|
||||
The "Before recommending from memory" section enforces verification:
|
||||
- Memory names a file path → check file exists
|
||||
- Memory names a function → grep for it
|
||||
- User about to act on recommendation → verify first
|
||||
- "The memory says X exists" ≠ "X exists now"
|
||||
|
||||
### 2.4 Team Memory
|
||||
|
||||
Shared memory across team members with enterprise-grade security:
|
||||
- Symlink traversal protection (realpath resolution)
|
||||
- Null byte injection prevention
|
||||
- URL-encoded traversal detection
|
||||
- Unicode normalization attack prevention
|
||||
- Backslash injection rejection
|
||||
- Path containment verification against real filesystem paths
|
||||
|
||||
**Waggle implication:** Your enterprise air-gapped deployment requires this level of path security for shared memory. The team memory pattern directly maps to your multi-workspace isolation — each workspace gets its own team memory directory.
|
||||
|
||||
---
|
||||
|
||||
## 3. QUERY ENGINE — The Brain
|
||||
|
||||
### 3.1 Architecture
|
||||
|
||||
`QueryEngine` class: one instance per conversation, persists across turns.
|
||||
|
||||
**Per-turn lifecycle:**
|
||||
1. **Context assembly**: system prompt + userContext + systemContext (composable sections)
|
||||
2. **Memory prefetch**: starts async Sonnet side-query for relevant memories
|
||||
3. **Skill prefetch**: starts async skill discovery for potentially relevant skills
|
||||
4. **Snip compact**: removes old context if history is too long
|
||||
5. **Microcompact**: fine-grained compaction of tool results
|
||||
6. **Context collapse**: coarser compaction via staged collapses
|
||||
7. **Autocompact**: full conversation summarization when context is critically full8. **Tool result budget**: enforces per-message size limits on aggregate tool results
|
||||
9. **API call**: streams model response
|
||||
10. **Streaming tool execution**: tools begin executing as soon as their parameters stream in (not after full response)
|
||||
11. **Post-sampling hooks**: execute after model completes
|
||||
12. **Token budget check**: decide whether to continue or stop the agentic loop
|
||||
|
||||
### 3.2 Multi-Layer Compaction Strategy
|
||||
|
||||
This is critical for long sessions. Claude Code uses FOUR layers:
|
||||
|
||||
1. **Snip compact**: removes oldest messages, preserving a "protected tail" of recent context
|
||||
2. **Microcompact**: replaces individual tool results with summaries when they exceed size limits. Cached variant edits the API cache directly.
|
||||
3. **Context collapse**: groups related messages into collapsible summaries. Projection-based — the REPL keeps full history, collapse is a read-time view.
|
||||
4. **Autocompact**: full conversation summary when nearing context limit. Triggered by token count threshold. Uses a side-query to generate the summary.
|
||||
|
||||
Each layer runs independently. Snip runs before microcompact. Microcompact before autocompact. Context collapse can prevent autocompact from firing.
|
||||
|
||||
### 3.3 Token Budget Management
|
||||
|
||||
`tokenBudget.ts` implements a continuation system:
|
||||
|
||||
- Tracks `continuationCount`, `lastDeltaTokens`, `lastGlobalTurnTokens`
|
||||
- Continues if under 90% of budget AND not showing diminishing returns
|
||||
- Diminishing returns detected: 3+ continuations with <500 token delta
|
||||
- Agents don't get continuation — only the main loop
|
||||
- Blocking limit: hard stop when token count reaches critical threshold (reserves space for manual `/compact`)
|
||||
|
||||
### 3.4 Streaming Tool Execution
|
||||
|
||||
`StreamingToolExecutor`: tools begin executing while the model is still generating.
|
||||
|
||||
As soon as a `tool_use` block's parameters are complete in the stream, execution begins. Multiple tools can execute concurrently. Results are yielded as they complete, not in order. This dramatically reduces latency for multi-tool turns.
|
||||
|
||||
**Waggle implication:** This is a significant UX advantage. When an agent spawns three research sub-tasks, all three should begin immediately, not sequentially.
|
||||
---
|
||||
|
||||
## 4. TOOL HARNESS — The Execution Layer
|
||||
|
||||
### 4.1 buildTool() Factory
|
||||
|
||||
Every tool in the system is created via `buildTool<InputSchema, OutputSchema, Progress>()`:
|
||||
|
||||
```typescript
|
||||
type ToolDef = {
|
||||
name: string
|
||||
description: string | (() => string | Promise<string>)
|
||||
inputSchema: z.ZodType | (() => z.ZodType) // Zod schema, can be lazy
|
||||
outputSchema?: z.ZodType | (() => z.ZodType)
|
||||
isEnabled: () => boolean // Dynamic enable/disable
|
||||
isReadOnly: () => boolean // Read-only tools skip permission checks
|
||||
maxResultSizeChars?: number // Tool result truncation limit
|
||||
userFacingName?: () => string // Display name for UI
|
||||
|
||||
call: (input, context) => AsyncGenerator<Progress, Output>
|
||||
|
||||
// React rendering
|
||||
renderToolUseMessage: (input) => ReactNode
|
||||
renderToolResultMessage: (output) => ReactNode
|
||||
renderToolUseRejectedMessage: (input) => ReactNode
|
||||
renderToolUseErrorMessage: (error) => ReactNode
|
||||
renderToolUseProgressMessage: (progress) => ReactNode
|
||||
|
||||
// Validation
|
||||
validateInput?: (input) => ValidationResult
|
||||
backfillObservableInput?: (input) => void // Enrich input for SDK/transcript
|
||||
}
|
||||
```
|
||||
|
||||
**ToolUseContext** provides rich execution context:
|
||||
- `options.tools`: full tool pool available
|
||||
- `options.mcpClients`: connected MCP servers
|
||||
- `options.agentDefinitions`: all agent definitions
|
||||
- `abortController`: cancellation signal
|
||||
- `readFileState`: file content cache
|
||||
- `getAppState() / setAppState()`: application state access
|
||||
- `messages`: conversation history
|
||||
- `queryTracking`: chain ID and depth for analytics
|
||||
### 4.2 Permission System
|
||||
|
||||
Multi-layer permission model:
|
||||
- **Permission mode**: "default", "plan", "bypass"
|
||||
- **Per-tool rules by source**: `alwaysAllowRules`, `alwaysDenyRules`, `alwaysAskRules`
|
||||
- **Sources**: user settings, project settings, policy settings (enterprise)
|
||||
- **Background agents**: `shouldAvoidPermissionPrompts` — auto-deny when no UI available
|
||||
- **Coordinator workers**: `awaitAutomatedChecksBeforeDialog` — run classifier checks before showing prompt
|
||||
- **Denial tracking**: prevents repeated prompts for the same tool/input combination
|
||||
|
||||
### 4.3 Deferred Tool Loading (ToolSearch)
|
||||
|
||||
Tools are registered by name only. Full schema (description, inputSchema, outputSchema) is fetched on demand via `ToolSearchTool`. This keeps the system prompt compact when many MCP servers are connected.
|
||||
|
||||
**Waggle implication:** As your connector count grows past 32, this becomes essential. Each connected MCP server adds tool schemas to the prompt. Deferred loading keeps the base prompt stable and cache-friendly.
|
||||
|
||||
---
|
||||
|
||||
## 5. SKILLS FRAMEWORK
|
||||
|
||||
### 5.1 Skill Definition (Markdown with Frontmatter)
|
||||
|
||||
Skills are markdown files loaded from directories:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: commit
|
||||
description: Create a git commit with conventional commit message
|
||||
tools: Agent, Bash, FileRead, FileEdit # Tool allowlist when invoked
|
||||
model: sonnet # Optional model override
|
||||
effort: high # Reasoning effort
|
||||
paths: src/**, tests/** # File path relevance patterns
|
||||
hooks: # Lifecycle hooks
|
||||
pre_tool_call: ...
|
||||
post_tool_call: ...
|
||||
allowed_tools: Read, Edit # Tools the skill itself uses
|
||||
args: message # Named arguments ($message substitution)
|
||||
---
|
||||
|
||||
[Skill prompt content in markdown]
|
||||
```
|
||||
### 5.2 Skill Sources and Priority
|
||||
|
||||
1. **Bundled** (shipped with Claude Code)
|
||||
2. **MCP-generated** (via `mcpSkillBuilders.ts` — MCP servers can register skill builders)
|
||||
3. **User** (`~/.claude/skills/`)
|
||||
4. **Project** (`.claude/skills/`)
|
||||
5. **Managed** (enterprise policy)
|
||||
6. **Plugin** (external packages)
|
||||
|
||||
Deduplication by canonical file path (resolves symlinks). Priority: managed > project > user > plugin > bundled.
|
||||
|
||||
### 5.3 Skill Discovery and Prefetch
|
||||
|
||||
Skills can be discovered at query time via a prefetch mechanism that runs alongside model streaming. The system identifies potentially relevant skills based on the user's query before the model requests them.
|
||||
|
||||
**Waggle implication:** Your "Skills & Apps" dock view should adopt this exact structure. Skills as markdown files is simple, composable, and human-editable. The frontmatter schema provides everything needed for display, filtering, and execution.
|
||||
|
||||
---
|
||||
|
||||
## 6. TASK SYSTEM
|
||||
|
||||
### 6.1 Seven Task Types
|
||||
|
||||
```
|
||||
LocalAgentTask — foreground subagent (sync or backgroundable)
|
||||
RemoteAgentTask — remote sandbox execution (always background)
|
||||
InProcessTeammateTask — tmux-spawned teammate process
|
||||
LocalShellTask — background shell commands
|
||||
LocalWorkflowTask — multi-step workflow execution
|
||||
MonitorMcpTask — MCP server monitoring
|
||||
DreamTask — background "dreaming" (speculative processing)
|
||||
```
|
||||
### 6.2 Task Lifecycle
|
||||
|
||||
States: `pending` → `running` → `completed|failed|killed`
|
||||
|
||||
Background task indicator: shown when `status === 'running' | 'pending'` AND `isBackgrounded === true`.
|
||||
|
||||
Progress tracking: agents report via `AgentToolProgress` events with `description`, `tokenCount`, `toolUseCount`, `lastToolName`.
|
||||
|
||||
**Auto-background:** After 120 seconds, foreground agents can be automatically moved to background (feature-gated via `CLAUDE_AUTO_BACKGROUND_TASKS`).
|
||||
|
||||
### 6.3 Notification Pattern
|
||||
|
||||
Workers → coordinator communication uses structured XML:
|
||||
|
||||
```xml
|
||||
<task-notification>
|
||||
<task-id>{agentId}</task-id>
|
||||
<status>completed|failed|killed</status>
|
||||
<summary>{human-readable status}</summary>
|
||||
<result>{agent's final text response}</result>
|
||||
<usage>
|
||||
<total_tokens>N</total_tokens>
|
||||
<tool_uses>N</tool_uses>
|
||||
<duration_ms>N</duration_ms>
|
||||
</usage>
|
||||
</task-notification>
|
||||
```
|
||||
|
||||
**Waggle implication:** This notification format should be adopted for your event stream. The structured XML enables parsing, display, and routing in your Cockpit and Events views.
|
||||
---
|
||||
|
||||
## 7. ARCHITECTURE BLUEPRINT FOR WAGGLE
|
||||
|
||||
Based on the complete deep-dive, here is the prioritized implementation roadmap:
|
||||
|
||||
### P0 — Foundation (Blocks Everything Else)
|
||||
|
||||
**A. Agent Definition Schema**
|
||||
Formalize the 13 agent personas into the `BaseAgentDefinition` format. Every agent gets: `agentType`, `whenToUse`, `tools` allowlist, `disallowedTools`, `model`, `maxTurns`, `memory` scope. Store these as markdown files with YAML frontmatter in the workspace.
|
||||
|
||||
**B. Tool Pool Assembly**
|
||||
Implement `assembleToolPool()` — per-agent tool filtering based on allowlist/denylist. This is the single most important security boundary in the system.
|
||||
|
||||
**C. Token Budget Management**
|
||||
Build a budget tracker for the chat view. Track continuation count, delta tokens, and implement the 90% threshold with diminishing-returns detection.
|
||||
|
||||
### P1 — Orchestration (Enables Workflows)
|
||||
|
||||
**D. Coordinator Mode for Mission Control**
|
||||
Implement the coordinator pattern: restricted tool set (only Agent + SendMessage + TaskStop), worker spawn/track/notify lifecycle, and scratchpad for cross-worker state.
|
||||
|
||||
**E. Task Notification Protocol**
|
||||
Adopt the `<task-notification>` XML format for agent→orchestrator communication. Wire this into the Events view for real-time workflow visualization.
|
||||
|
||||
**F. Fork Subagent for Waggle Dance**
|
||||
Implement context-inheriting agent spawns for research phases. The fork's context stays clean, the parent gets only the summary.
|
||||
### P2 — Memory Maturation
|
||||
|
||||
**G. Four-Type Memory Taxonomy**
|
||||
Implement on top of your graph DB. Each memory node gets: `type` (user/feedback/project/reference), `description`, `timestamp`. Enforce the "what NOT to save" rules.
|
||||
|
||||
**H. Side-Query Relevance Filter**
|
||||
Use a lightweight model call to pre-filter which memory frames to inject per query. Scan frontmatter/descriptions only, select up to 5, load full content for only those.
|
||||
|
||||
**I. Memory Freshness Warnings**
|
||||
Compute age, inject staleness caveats for memories >1 day old, enforce "verify before recommending."
|
||||
|
||||
**J. Per-Agent Memory Scopes**
|
||||
Each agent type gets its own memory directory/subgraph. Analysis Agent remembers analysis patterns. Writing Agent remembers style preferences. Separate from conversation memory.
|
||||
|
||||
### P3 — Context Management
|
||||
|
||||
**K. Multi-Layer Compaction**
|
||||
Implement at least two layers: microcompact (per-tool-result summarization) and autocompact (full conversation summary). This is non-negotiable for production quality with long agent sessions.
|
||||
|
||||
**L. Streaming Tool Execution**
|
||||
Begin tool execution as soon as parameters stream in. This alone can cut perceived latency by 30-50% for multi-tool turns.
|
||||
|
||||
**M. Deferred Tool Loading**
|
||||
Register connector tools by name only. Fetch full schemas on demand via a ToolSearch equivalent. Critical as connector count scales.
|
||||
|
||||
### P4 — Enterprise
|
||||
|
||||
**N. Team Memory with Security**
|
||||
Shared memory across workspace users. Symlink protection, path traversal prevention, scope isolation between private and team.
|
||||
|
||||
**O. Agent Memory Snapshots**
|
||||
Allow teams to share agent memory configurations via project-level snapshots. New team members get bootstrapped agent memory automatically.
|
||||
|
||||
**P. Permission Model**
|
||||
Per-tool, per-agent, per-source permission rules. Enterprise policy settings override project settings override user settings. Background agents auto-deny permission prompts.
|
||||
---
|
||||
|
||||
## 8. WHAT WAGGLE HAS THAT CLAUDE CODE DOESN'T
|
||||
|
||||
Do not lose sight of these advantages:
|
||||
|
||||
1. **Graph-based memory** — relationships between memory nodes enable queries that flat files cannot. "What does this user know about X and how does it relate to Y?" is a graph query, not a file scan.
|
||||
|
||||
2. **Visual orchestration** — the Cockpit, Waggle Dance, and Events views provide visibility into agent workflows that a terminal fundamentally cannot deliver. This is the enterprise sales differentiator.
|
||||
|
||||
3. **Multi-workspace isolation** — Claude Code is one project per session. Waggle can run multiple isolated workspaces simultaneously with independent agent pools and memory spaces.
|
||||
|
||||
4. **Desktop-first distribution** — one-click install via Tauri, not `npm install -g`. Dramatically lower barrier to entry for non-technical users.
|
||||
|
||||
5. **Three-tier user model** — Claude Code has one mode. Waggle can surface progressive complexity. Simple users see a chat interface. Power users see agent configuration. Admins see the full orchestration layer.
|
||||
|
||||
6. **Encrypted vault** — AES-256-GCM for credentials. Claude Code stores secrets in plaintext config files.
|
||||
|
||||
These are not incremental features — they are structural advantages that justify Waggle's existence as a distinct product.
|
||||
---
|
||||
|
||||
## CORRECTION: Section 2 Memory Assessment (Updated)
|
||||
|
||||
The original Section 2 incorrectly positioned Claude Code's flat-file memory as a benchmark that Waggle's graph DB should aspire to. The corrected assessment:
|
||||
|
||||
**Waggle's SQLite + frames + graph architecture is the more mature design.** It is enterprise-appropriate for a product with multi-workspace isolation, team memory, per-agent scopes, and importance-based pruning. Claude Code's flat markdown files are a pragmatic CLI choice, not a superior one.
|
||||
|
||||
### What Waggle Has That Claude Code Cannot Match
|
||||
|
||||
| Capability | Waggle (Graph DB) | Claude Code (Flat Files) |
|
||||
|---|---|---|
|
||||
| Relationship queries | Native graph traversal | Impossible |
|
||||
| Concurrent access | Database-level locking | Filesystem conflicts |
|
||||
| Importance scoring | accessCount + metadata | Not available |
|
||||
| Per-agent memory scopes | Graph partitions | Directory convention |
|
||||
| Cross-agent knowledge sharing | Shared nodes with edges | Shared files (no relationships) |
|
||||
| Multimedia frame origins | Frames from any source type | Text-only markdown |
|
||||
| Team memory security | DB-level + API auth | Filesystem symlink protection |
|
||||
|
||||
### Patterns to Adopt FROM Claude Code (as graph-layer enhancements)
|
||||
|
||||
1. **Side-query relevance filter** — Use a lightweight model call against frame metadata to select top-5 frames per query. Highest-value single improvement.
|
||||
2. **Staleness warnings** — Surface frame age in context injection. "This frame is 47 days old — verify before acting on it."
|
||||
3. **Verify-before-recommend** — When a frame references a file path or function name, check existence before surfacing.
|
||||
4. **Four-type taxonomy overlay** — Classify frames as user/feedback/project/reference for consistent retrieval patterns.
|
||||
5. **Explicit exclusion rules** — Prevent memory bloat by refusing to store code patterns, git history, or debugging solutions as frames.
|
||||
|
||||
### Implementation Fixes Required (Bugs, Not Architecture)
|
||||
|
||||
- **P2:** Unify memory counting (49 vs 37 discrepancy across UI views)
|
||||
- **P3:** Fix `accessCount` incrementing on frame access
|
||||
- **P3:** Render markdown content in frame display
|
||||
- **New:** Add side-query relevance pre-filtering before context injection
|
||||
185
waggle-cowork/claude-code-source-analysis.md
Normal file
185
waggle-cowork/claude-code-source-analysis.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# Claude Code Source Analysis — Strategic Relevance to Waggle OS
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Analyst:** Cowork Session (CxO Advisory)
|
||||
**Scope:** Claude Code source (`D:\Projects\Claude Code Source\src\src`), cross-referenced with `open-multi-agent` and `claw-code` repositories
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The Claude Code source is the most strategically valuable reference material for Waggle OS — far more than either open-source repository analyzed previously. It is the production-grade implementation of the exact system architecture Waggle aspires to: multi-agent orchestration, persistent memory, tool harness, MCP integration, skills framework, and session management. This is not a competitor to study — it is the reference implementation of the patterns Waggle needs to mature.
|
||||
|
||||
**Verdict:** HIGH strategic value as an architectural reference. Not for code adoption (IP risk), but for pattern extraction, gap identification, and design validation.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Breakdown (What Matters for Waggle)
|
||||
|
||||
### 1. Agent System — The Core Differentiator
|
||||
|
||||
**Claude Code's approach:**
|
||||
- **AgentTool** is the central orchestration primitive. Every agent spawn goes through a single `buildTool()` call with Zod-validated input/output schemas.
|
||||
- **Built-in agent types** are defined as simple TypeScript definitions (not full classes): `generalPurposeAgent`, `exploreAgent`, `planAgent`, `verificationAgent`, `claudeCodeGuideAgent`, `statuslineSetup`. Each specifies: `agentType`, `whenToUse`, `tools` (allowlist), `disallowedTools` (denylist), and optional `model` override.
|
||||
- **Custom agents** loaded from user-defined directories via `loadAgentsDir.ts` — file-based agent definitions alongside built-in ones.
|
||||
- **Agent lifecycle:** spawn → run (with own tool pool) → return result to parent. No persistent state between spawns. Each agent gets a fresh conversation context unless it's a "fork" (inherits parent context).- **Fork subagent pattern** (feature-gated): allows spawning a clone of the current agent that inherits the full conversation context. Designed for research tasks where the parent wants the answer without polluting its own context with intermediate tool calls.
|
||||
- **Coordinator mode** (feature-gated): a special operating mode where the orchestrating agent has a restricted tool set (`COORDINATOR_MODE_ALLOWED_TOOLS`) and delegates all execution to subagents.
|
||||
- **Agent Swarms / Teammates** (feature-gated): multi-agent collaboration using tmux sessions. Spawns real processes that can communicate via `SendMessageTool`.
|
||||
|
||||
**Waggle gap analysis:**
|
||||
- Waggle has 13 agent personas but lacks the structured agent definition format (tools allowlist/denylist per agent type).
|
||||
- Waggle lacks the fork pattern — critical for research-heavy workflows where context inheritance saves tokens.
|
||||
- Waggle lacks coordinator mode — the pattern where a "master" agent only delegates, never executes directly.
|
||||
- Waggle lacks the SendMessage inter-agent communication primitive.
|
||||
- Waggle's agent spawning appears monolithic vs. Claude Code's composable tool-pool assembly.
|
||||
|
||||
**Recommendation:** Adopt the agent definition schema (type + tools + whenToUse + model) as Waggle's standard. Implement coordinator mode for Mission Control. The fork pattern maps directly to Waggle Dance's workflow orchestration needs.
|
||||
|
||||
---
|
||||
|
||||
### 2. Memory System — The Competitive Moat
|
||||
|
||||
**Claude Code's approach:**
|
||||
- **File-based memory** with YAML frontmatter: each memory is a markdown file with `name`, `description`, `type` fields.
|
||||
- **Four-type taxonomy:** `user` (role/preferences), `feedback` (behavioral corrections), `project` (ongoing work context), `reference` (pointers to external systems).
|
||||
- **MEMORY.md as index:** a single entrypoint file (max 200 lines, 25KB) that serves as a table of contents. Individual memories are separate files.
|
||||
- **Relevance filtering via side-query:** `findRelevantMemories.ts` uses a lightweight Sonnet call to select which memory files are relevant to the current user query. Scans frontmatter headers, sends them to Sonnet with the query, gets back up to 5 relevant filenames. This is NOT keyword matching — it's semantic relevance via LLM.
|
||||
- **Memory scan:** `memoryScan.ts` reads frontmatter from all memory files without loading full content. Only selected files get fully loaded.
|
||||
- **Team memory** (feature-gated): shared memory across team members with separate paths.
|
||||
- **Stale memory handling:** memories include creation timestamps; the system warns about potentially outdated information.
|
||||
**Waggle gap analysis:**
|
||||
- Waggle uses a graph database for memory — architecturally more sophisticated than flat files. However, the graph structure may be over-engineered for what Claude Code proves works: simple frontmatter-indexed files with LLM-powered relevance filtering.
|
||||
- Waggle lacks the four-type memory taxonomy. This is a proven classification that prevents memory bloat (code patterns, git history, etc. are explicitly excluded).
|
||||
- Waggle lacks the "side-query" relevance pattern — using a lightweight model to pre-filter context before injecting into the main conversation.
|
||||
- Waggle lacks the explicit "what NOT to save" guardrails that prevent the memory system from becoming a dumping ground.
|
||||
|
||||
**Recommendation:** The graph DB is fine for storage, but adopt the four-type taxonomy as the schema layer on top. The side-query relevance pattern is immediately valuable — it's how Claude Code keeps memory injection surgical rather than flooding context.
|
||||
|
||||
---
|
||||
|
||||
### 3. Tool Harness — The Execution Layer
|
||||
|
||||
**Claude Code's approach:**
|
||||
- **`buildTool()` factory:** every tool (Bash, FileRead, FileWrite, Grep, Glob, Agent, etc.) is constructed via a standardized factory with: `name`, `description`, `inputSchema` (Zod), `outputSchema` (Zod), `isEnabled()`, `call()`, and React-based UI components for rendering.
|
||||
- **Tool pool assembly:** `assembleToolPool()` dynamically constructs the available tool set per agent, respecting allowlists, denylists, MCP tools, and feature gates.
|
||||
- **MCP integration:** full Model Context Protocol client with `MCPConnectionManager`, OAuth support, channel permissions, and server approval flows.
|
||||
- **Skill system:** skills are loaded from directories (`loadSkillsDir.ts`) and converted into tool-like invocations via `SkillTool`. Skills can come from bundled sources, user directories, or MCP servers.
|
||||
- **Permission system:** granular per-tool permissions with `canUseTool` checks, auto-mode denials, and classifier-based approvals.
|
||||
- **ToolSearch:** deferred tool loading — tools are registered by name but their full schema is only fetched when needed, reducing prompt size.
|
||||
**Waggle gap analysis:**
|
||||
- Waggle has tool execution but lacks the standardized `buildTool()` pattern with schema validation.
|
||||
- Waggle's MCP integration appears less mature than Claude Code's full connection manager with OAuth.
|
||||
- Waggle lacks deferred tool loading (ToolSearch pattern) — critical for managing prompt size when connectors scale.
|
||||
- Waggle lacks the per-agent tool pool customization.
|
||||
|
||||
**Recommendation:** The `buildTool()` pattern and `assembleToolPool()` composition model should be Waggle's target architecture for tool management. Deferred tool loading via ToolSearch is essential as Waggle's connector count grows beyond 32.
|
||||
|
||||
---
|
||||
|
||||
### 4. QueryEngine — The Brain
|
||||
|
||||
**Claude Code's approach:**
|
||||
- **QueryEngine class:** owns the entire conversation lifecycle. One instance per conversation, persists state across turns.
|
||||
- **System prompt assembly:** modular, with sections from memory, CLAUDE.md files, skills, MCP servers, and environment details — all composable.
|
||||
- **Token budget management:** `tokenBudget.ts` manages context window allocation across system prompt, history, and tool results.
|
||||
- **Context analysis:** determines what context to inject based on the current query.
|
||||
- **Compact/snip:** conversation history compression when context fills up — maintains coherence while discarding intermediate noise.
|
||||
- **File state cache:** tracks which files have been read, preventing redundant fetches.
|
||||
- **Cost tracking:** per-session token counting and cost estimation.
|
||||
|
||||
**Waggle gap analysis:**
|
||||
- Waggle has a chat interface but likely lacks the token budget management sophistication.
|
||||
- The system prompt assembly pattern (composable sections) is exactly what Waggle needs for its multi-workspace, multi-agent architecture.
|
||||
- History compression (snip/compact) is essential for long sessions — Waggle will hit context limits with 13 agents generating output.
|
||||
|
||||
**Recommendation:** Study the QueryEngine pattern closely. The token budget management and history compression are non-negotiable for production quality.
|
||||
---
|
||||
|
||||
### 5. Session & Task Management
|
||||
|
||||
**Claude Code's approach:**
|
||||
- **Four task types:** `LocalAgentTask` (foreground subagent), `RemoteAgentTask` (remote sandbox), `InProcessTeammateTask` (tmux-spawned teammate), `DreamTask` (background processing).
|
||||
- **Progress tracking:** agents report progress via `AgentToolProgress` events. Parents can monitor without polling.
|
||||
- **Background execution:** agents can run in background with automatic notification on completion.
|
||||
- **Session persistence:** transcripts recorded to disk, sessions resumable across restarts.
|
||||
- **Worktree isolation:** agents can operate in git worktrees for safe experimentation.
|
||||
|
||||
**Waggle gap analysis:**
|
||||
- Waggle's Cockpit view tracks agent status but appears to lack structured task types.
|
||||
- Background execution with notification is a UX pattern Waggle should adopt for long-running agent workflows.
|
||||
- Session persistence and resume capability is critical for the desktop app use case.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference: Three Repositories Compared
|
||||
|
||||
| Capability | Claude Code Source | open-multi-agent | claw-code |
|
||||
|---|---|---|---|
|
||||
| Agent orchestration | Production, feature-gated | Clean abstraction, pre-release | Partial reimplementation |
|
||||
| Multi-agent coordination | Swarms/Teammates + SendMessage | MessageBus + SharedMemory | Not implemented |
|
||||
| Memory system | File-based + LLM relevance filter | SharedMemory (in-process only) | Not implemented |
|
||||
| Tool harness | Full buildTool() + Zod schemas | Zod-validated custom tools | Partial port |
|
||||
| MCP integration | Full client + OAuth + approvals | None | None |
|
||||
| Task scheduling | Four task types + background | Topological + 4 strategies | None |
|
||||
| Skills framework | Directory-based + bundled | None | None |
|
||||
| Maturity | Production (millions of users) | v0.1.0 | Alpha |
|
||||
---
|
||||
|
||||
## Strategic Recommendations for Waggle
|
||||
|
||||
### Immediate (adopt patterns, not code):
|
||||
|
||||
1. **Agent definition schema** — standardize on the `agentType + tools + disallowedTools + whenToUse + model` pattern.
|
||||
2. **Memory taxonomy** — implement the four-type system (user/feedback/project/reference) as a schema layer on your graph DB.
|
||||
3. **Side-query relevance** — use a lightweight model call to pre-filter which memories/context to inject per query.
|
||||
4. **Deferred tool loading** — implement ToolSearch-like pattern as connector count grows.
|
||||
|
||||
### Near-term (architecture alignment):
|
||||
|
||||
5. **Coordinator mode** — implement a Mission Control agent that only delegates, never executes.
|
||||
6. **Fork subagent** — enable context-inheriting spawns for research workflows in Waggle Dance.
|
||||
7. **Token budget management** — build a budget allocator for system prompt, history, and tool results.
|
||||
8. **Background agents with notifications** — critical UX for desktop app.
|
||||
|
||||
### Strategic (differentiation layer):
|
||||
|
||||
9. **Waggle's graph memory > Claude Code's flat files** — this is your advantage. The graph enables relationship queries, temporal reasoning, and cross-agent knowledge sharing that flat files cannot. Lean into this.
|
||||
10. **Visual orchestration > CLI text** — Waggle's Cockpit/Mission Control/Waggle Dance provide visibility that Claude Code's terminal cannot match. This is the enterprise moat.
|
||||
11. **Multi-workspace isolation** — Claude Code has one project context per session. Waggle's workspace isolation is architecturally superior for enterprise.
|
||||
|
||||
### What NOT to do:
|
||||
|
||||
- Do NOT copy code. IP risk is real regardless of "clean room" claims.
|
||||
- Do NOT adopt the tmux-based multi-agent pattern. It's a CLI-specific hack. Waggle's backend can orchestrate agents natively.
|
||||
- Do NOT replicate the terminal rendering layer (ink/). Waggle is a desktop app with a proper UI framework.
|
||||
- Do NOT adopt the file-based memory storage. Keep the graph DB — just adopt the taxonomy and retrieval patterns.
|
||||
---
|
||||
|
||||
## Verdict on open-multi-agent (Updated)
|
||||
|
||||
After seeing Claude Code's architecture, open-multi-agent's value proposition shifts. Claude Code already demonstrates production-grade agent orchestration, but it's tightly coupled to the CLI and Anthropic's infrastructure. open-multi-agent offers a **cleaner abstraction** for the orchestration layer specifically — its TaskQueue with topological scheduling, MessageBus, and capability-matching scheduler are architecturally elegant and model-agnostic.
|
||||
|
||||
**Revised recommendation:** open-multi-agent remains worth evaluating as an orchestration layer, particularly because it's MIT-licensed and model-agnostic. Use Claude Code as the design reference, open-multi-agent as a potential dependency.
|
||||
|
||||
## Verdict on claw-code (Unchanged)
|
||||
|
||||
Pass. Claude Code source itself is available for reference. A partial reimplementation adds no value and carries IP risk.
|
||||
---
|
||||
|
||||
## CORRECTION: Memory System Assessment (Updated)
|
||||
|
||||
The original analysis incorrectly characterized Waggle's graph database memory as "potentially over-engineered." This has been corrected after examining the actual implementation.
|
||||
|
||||
**Waggle's memory architecture (SQLite + frames + graph) is structurally superior to Claude Code's flat-file approach.** Frames as graph nodes with relational edges enable relationship queries, temporal reasoning, cross-agent knowledge sharing, and importance-based pruning — none of which flat markdown files can deliver. The `auto_recall` tool provides automatic context injection that Claude Code achieves only through a more primitive file-scan + LLM-filter pipeline.
|
||||
|
||||
**What to adopt from Claude Code (as a layer on the graph, not a replacement):**
|
||||
|
||||
1. **Side-query relevance filter** — scan frame metadata, select top-5 per query, inject only those. This is the single highest-value pattern to port.
|
||||
2. **Staleness warnings** — inject freshness caveats for frames older than a configurable threshold.
|
||||
3. **"Verify before recommending" enforcement** — when a frame references a specific file, function, or resource, verify it still exists before surfacing it.
|
||||
4. **Four-type taxonomy** — map frame types to user/feedback/project/reference for consistent classification.
|
||||
|
||||
**Implementation bugs to fix (not architecture issues):**
|
||||
- `accessCount` never increments (breaks importance scoring)
|
||||
- Memory count discrepancy (49 vs 37 in different UI views)
|
||||
- Markdown not rendered in frame display
|
||||
338
waggle-cowork/system-prompt-comparison.md
Normal file
338
waggle-cowork/system-prompt-comparison.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# System Prompt Comparison: Waggle OS vs Claude Code
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Analyst:** Cowork Advisory Session
|
||||
**Source:** Waggle OS `packages/agent/src/` + Claude Code `src/src/constants/` and subsystem prompts
|
||||
|
||||
---
|
||||
|
||||
## EXECUTIVE VERDICT
|
||||
|
||||
Waggle's system prompt architecture is **more sophisticated in design** but **less disciplined in execution** than Claude Code's. Waggle has features Claude Code lacks entirely (dual-mind memory, identity layer, self-awareness injection, workspace tone adaptation, cognify pipeline, knowledge graph queries). But Claude Code's prompt engineering is tighter — more modular, more cacheable, more defensively written. The gap is not in what Waggle says, but in how precisely it says it.
|
||||
|
||||
---
|
||||
|
||||
## ARCHITECTURE COMPARISON
|
||||
|
||||
### Waggle OS Prompt Assembly
|
||||
|
||||
```
|
||||
buildSystemPrompt()
|
||||
├── # Identity (from personal mind — IdentityLayer)
|
||||
├── # Self-Awareness (runtime: tools, skills, model, memory stats, improvement signals)
|
||||
├── # Context From Your Memory (auto-loaded recent frames, ranked by importance)
|
||||
│ ├── Recent Workspace Memory (importance-first, then recency)
|
||||
│ ├── Active Tasks & State (from AwarenessLayer)
|
||||
│ ├── Key Knowledge (top 10 entities from KnowledgeGraph by relationship count)
|
||||
│ └── Personal Preferences (cross-workspace, from personal mind)
|
||||
├── BEHAVIORAL_SPEC.rules (static — core loop, quality rules, behavioral rules, tool descriptions)
|
||||
├── composePersonaPrompt()
|
||||
│ ├── Core prompt
|
||||
│ ├── DOCX hint
|
||||
│ ├── Workspace tone instruction (professional/casual/technical/legal/marketing)
|
||||
│ └── Persona-specific systemPrompt (e.g., Researcher, Writer, Analyst...)
|
||||
└── recallMemory() → injected per-turn as recalled context
|
||||
├── Workspace Memory (semantic search or importance-based for catch-up queries)
|
||||
└── Personal Memory (cross-workspace)
|
||||
```
|
||||
### Claude Code Prompt Assembly
|
||||
|
||||
```
|
||||
resolveSystemPromptSections()
|
||||
├── getSimpleIntroSection() — base identity
|
||||
├── getSimpleSystemSection() — interactive agent instructions
|
||||
├── getSimpleDoingTasksSection() — software engineering guidance
|
||||
├── getActionsSection() — safety and execution caution
|
||||
├── getUsingYourToolsSection() — tool usage patterns
|
||||
├── getSimpleToneAndStyleSection() — communication style
|
||||
├── getOutputEfficiencySection() — response efficiency
|
||||
├── [Dynamic sections — cached until /clear or /compact]
|
||||
│ ├── session_guidance
|
||||
│ ├── memory (from MEMORY.md + side-query selected files)
|
||||
│ ├── env_info_simple (OS, git status, date)
|
||||
│ ├── language (locale)
|
||||
│ ├── output_style
|
||||
│ ├── mcp_instructions (per connected MCP server)
|
||||
│ ├── scratchpad (coordinator shared state dir)
|
||||
│ ├── token_budget (when enabled)
|
||||
│ └── brief (when KAIROS enabled)
|
||||
├── [Agent-specific override — replaces or extends base]
|
||||
│ ├── Coordinator Mode (complete replacement — 4000+ word prompt)
|
||||
│ ├── Explore Agent (read-only, file search specialist)
|
||||
│ ├── Plan Agent (read-only, software architect)
|
||||
│ ├── Verification Agent (try-to-break-it specialist)
|
||||
│ └── General Purpose Agent (default subagent)
|
||||
└── [Per-turn injections]
|
||||
├── findRelevantMemories() → Sonnet side-query selects top-5 memory files
|
||||
├── Skill prefetch (relevant skills discovered from query)
|
||||
└── getUserContext() → CLAUDE.md files, git context
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HEAD-TO-HEAD: WHAT EACH DOES BETTER
|
||||
|
||||
### Where Waggle Is Ahead
|
||||
|
||||
**1. Dual-Mind Architecture (Personal + Workspace)**
|
||||
Waggle separates memory into a personal mind (preferences, style, identity — carries across all workspaces) and a workspace mind (project context, decisions, domain knowledge — scoped to workspace). Claude Code has a single memory directory per project. It cannot carry personal preferences across projects without manual duplication.
|
||||
|
||||
This is a genuine architectural advantage. When a user moves between a "Marketing" workspace and a "Engineering" workspace, their communication style preferences follow them. Their project context does not bleed across.
|
||||
|
||||
**2. Identity Layer**
|
||||
Waggle has `IdentityLayer` — a persistent identity that loads into every system prompt. Claude Code has no equivalent. The model re-derives its identity from the system prompt text every session.
|
||||
|
||||
**3. Knowledge Graph Integration**
|
||||
Waggle loads top-10 entities by relationship count from `KnowledgeGraph` into context. This provides structured domain knowledge beyond free-text memory. Claude Code's memory is pure free-text markdown.
|
||||
|
||||
**4. Self-Awareness Injection**
|
||||
`buildSelfAwareness()` injects runtime capabilities (tools available, skills loaded, model name, memory stats, improvement signals) into the system prompt. The agent knows what it can do. Claude Code agents know their tools from the tool schemas, but don't have a synthesized self-awareness section.
|
||||
|
||||
**5. Improvement Signal Surfacing**
|
||||
`ImprovementSignalStore` + `buildAwarenessSummary()` detects behavioral patterns that need correction and surfaces them in the system prompt. Once surfaced, they're marked so they don't repeat. Claude Code has no equivalent self-correction mechanism at the prompt level.
|
||||
|
||||
**6. Workspace Tone Adaptation**
|
||||
`composePersonaPrompt()` accepts a `workspaceTone` parameter (professional/casual/technical/legal/marketing) that appends tone instructions. Tone varies by workspace. Claude Code has a fixed tone section.
|
||||
**7. Cognify Pipeline**
|
||||
`CognifyPipeline` processes raw content into structured memory (frames, entities, relationships) before storage. Claude Code stores memories as-is — no processing pipeline between input and persistence.
|
||||
|
||||
**8. Catch-Up Query Detection**
|
||||
`recallMemory()` detects "catch me up" / "where were we" patterns and switches from semantic search to importance-based recall. Claude Code uses the same side-query relevance filter regardless of query intent.
|
||||
|
||||
**9. 13 Personas with Tool Boundaries**
|
||||
Waggle has 13 distinct personas, each with explicit tool arrays, workspace affinity, suggested commands, and default workflows. Claude Code has 5 built-in agents (general-purpose, explore, plan, verification, claude-code-guide) — functional but role-limited.
|
||||
|
||||
**10. Custom Persona System**
|
||||
Users can create custom personas as JSON files in `~/.waggle/personas/`. These are loaded and merged with built-in personas at startup. Claude Code supports custom agents via markdown files, but Waggle's JSON format carries more metadata (icon, workspace affinity, suggested commands, default workflow).
|
||||
|
||||
---
|
||||
|
||||
### Where Claude Code Is Ahead
|
||||
|
||||
**1. Section Caching Architecture**
|
||||
`systemPromptSection()` memoizes each section. `DANGEROUS_uncachedSystemPromptSection()` is explicitly marked as cache-breaking, with a required reason parameter. This means Claude Code's system prompt is prompt-cache-friendly by design — sections don't recompute unless they must.
|
||||
|
||||
Waggle's `buildSystemPrompt()` recomputes everything every time. With API prompt caching, this means Waggle pays full token cost on every turn for sections that haven't changed. At scale, this is a significant cost and latency penalty.
|
||||
|
||||
**2. Side-Query Relevance Filter**
|
||||
Claude Code's `findRelevantMemories()` uses a lightweight Sonnet call to scan memory file headers and select only the top-5 relevant files before loading them into context. This is token-efficient and semantically precise.
|
||||
|
||||
Waggle's `recallMemory()` does a full semantic search (embedding-based) which is good, but then injects ALL results (up to limit) into context. There's no secondary LLM-based relevance filter to eliminate noise.
|
||||
|
||||
**3. Agent Prompt Discipline**
|
||||
Claude Code's agent prompts are defensively written:
|
||||
- Explore Agent: "=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===" with explicit lists of prohibited operations
|
||||
- Verification Agent: "Your job is not to confirm the implementation works — it's to try to break it" with documented failure patterns
|
||||
- Coordinator: "Never delegate understanding" with explicit anti-patterns
|
||||
|
||||
Waggle's persona prompts are guidance-oriented ("You specialize in...") rather than boundary-enforced. There are no explicit prohibitions, no critical safety blocks, no documented failure patterns. A Researcher persona could theoretically write files even though its intent is read-only research.
|
||||
|
||||
**4. Verification Agent (No Waggle Equivalent)**
|
||||
Claude Code has a dedicated verification agent whose entire purpose is adversarial — it tries to break implementations. It has a required output format (VERDICT: PASS/FAIL/PARTIAL), a universal baseline checklist, and documented self-deception patterns to avoid.
|
||||
|
||||
Waggle has no adversarial verification persona. Adding one would immediately improve quality assurance for generated outputs.
|
||||
|
||||
**5. Coordinator Mode (Pure Orchestrator)**
|
||||
Claude Code's coordinator gets ONLY Agent + SendMessage + TaskStop tools. It cannot execute anything directly. Workers report via structured `<task-notification>` XML. The coordinator must synthesize before delegating.
|
||||
|
||||
Waggle's orchestrator exists (`orchestrator.ts`) but operates as a memory/context manager, not as a delegation-only coordinator. There is no mode where the orchestrator is restricted to pure delegation.
|
||||
|
||||
**6. Compact/Summarization Prompt**
|
||||
Claude Code has a dedicated summarization prompt with strict formatting (9 required sections) and a critical preamble: "CRITICAL: Respond with TEXT ONLY. Do NOT call any tools." This ensures context compaction is predictable and tool-free.
|
||||
|
||||
Waggle has no equivalent compaction prompt. Long sessions will eventually hit context limits without a structured way to compress history.
|
||||
**7. Modular Section Independence**
|
||||
Each Claude Code section is independently computable and cacheable. Sections can be added, removed, or reordered without affecting others. Waggle's `BEHAVIORAL_SPEC.rules` is a single 280-line monolithic string — any change invalidates the entire section.
|
||||
|
||||
**8. Feature-Gated Progressive Enhancement**
|
||||
Claude Code gates advanced features (`CLAUDE_CODE_COORDINATOR_MODE`, `CLAUDE_FORK_SUBAGENT`, `CLAUDE_AUTO_BACKGROUND_TASKS`) behind environment flags. This allows gradual rollout and A/B testing. Waggle's BEHAVIORAL_SPEC notes "future A/B testing" in comments but has no gating mechanism implemented.
|
||||
|
||||
---
|
||||
|
||||
## BEHAVIORAL SPEC DEEP COMPARISON
|
||||
|
||||
### Waggle's BEHAVIORAL_SPEC.rules (280 lines)
|
||||
|
||||
**Structure:**
|
||||
1. HOW YOU THINK — Core Loop (RECALL → ASSESS → ACT → LEARN → RESPOND)
|
||||
2. RESPONSE QUALITY RULES (anti-hallucination, structured output, context grounding, disclaimers)
|
||||
3. BEHAVIORAL RULES (memory-first, tool intelligence, narration heuristics, error recovery, planning)
|
||||
4. HIGH-VALUE WORK PATTERNS (drafting from context, decision compression, research in context)
|
||||
5. TOOLS (full tool catalog with descriptions and usage guidance)
|
||||
6. Intelligence Defaults (skill check, workflow routing, sub-agent delegation, command awareness, capability discovery)
|
||||
|
||||
**Strengths:**
|
||||
- The 5-step core loop (RECALL → ASSESS → ACT → LEARN → RESPOND) is well-designed and covers the full reasoning cycle
|
||||
- Anti-hallucination discipline is explicit and enforced ("ALWAYS distinguish what you KNOW from what you're REASONING")
|
||||
- Memory correction handling is sophisticated ("If you find a prior memory that says X but the user now claims Y, surface the conflict")
|
||||
- Drafting patterns are detailed with type-specific guidance
|
||||
- Capability acquisition flow is well-specified (acquire_capability → install_capability → apply)
|
||||
|
||||
**Weaknesses:**
|
||||
- Monolithic — 280 lines in a single template literal, not decomposable
|
||||
- Tool descriptions are inline rather than pulled from tool definitions
|
||||
- No explicit safety boundaries — no "NEVER do X" blocks for destructive operations
|
||||
- No documented failure patterns — doesn't tell the model what mistakes to avoid
|
||||
- Disclaimer contamination — the test report shows disclaimers bleeding into all responses despite the contextual rules
|
||||
|
||||
### Claude Code's System Prompt Sections (~500 lines across 7+ sections)
|
||||
|
||||
**Structure:**
|
||||
- Intro (identity)
|
||||
- System (interactive agent role)
|
||||
- Doing Tasks (software engineering focus)
|
||||
- Actions (safety and caution)
|
||||
- Using Your Tools (tool patterns)
|
||||
- Tone and Style (communication)
|
||||
- Output Efficiency (response format)
|
||||
- Dynamic sections (memory, MCP, environment, etc.)
|
||||
|
||||
**Strengths:**
|
||||
- Each section is independently cacheable
|
||||
- Actions section has explicit safety rules ("consider whether there is a safer alternative")
|
||||
- Agent-specific prompts have hard boundaries ("=== CRITICAL: READ-ONLY MODE ===")
|
||||
- Verification agent has documented self-deception patterns
|
||||
- Coordinator has anti-pattern examples ("Avoid lazy delegation phrases")
|
||||
|
||||
**Weaknesses:**
|
||||
- No equivalent of Waggle's 5-step core loop — reasoning process is less structured
|
||||
- No anti-hallucination section — relies on model's baseline behavior
|
||||
- No memory correction handling — doesn't tell the model how to handle conflicting memories
|
||||
- No self-improvement mechanism — no equivalent of improvement signal surfacing
|
||||
- Narrowly focused on software engineering — not a general-purpose assistant framework
|
||||
---
|
||||
|
||||
## PERSONA COMPARISON
|
||||
|
||||
| Aspect | Waggle Personas | Claude Code Agents |
|
||||
|--------|----------------|-------------------|
|
||||
| Count | 13 built-in + custom JSON | 5 built-in + custom markdown |
|
||||
| Schema | AgentPersona interface (id, name, description, icon, systemPrompt, modelPreference, tools[], workspaceAffinity[], suggestedCommands[], defaultWorkflow) | BaseAgentDefinition (agentType, whenToUse, tools, disallowedTools, skills, mcpServers, hooks, model, maxTurns, memory, isolation, permissionMode, background, initialPrompt) |
|
||||
| Prompt style | Guidance-oriented ("You specialize in...") | Boundary-enforced ("=== CRITICAL: READ-ONLY ===") |
|
||||
| Tool control | Allowlist only (tools[]) | Allowlist + denylist (tools + disallowedTools) |
|
||||
| Safety boundaries | None explicit — personas suggest tools but don't prohibit | Hard prohibitions per agent type |
|
||||
| Workflow integration | defaultWorkflow field links to workflow templates | No workflow concept — agents are stateless |
|
||||
| Custom source | JSON files in ~/.waggle/personas/ | Markdown files in .claude/agents/ |
|
||||
| Priority override | No explicit priority chain | managed > flag > project > user > plugin > built-in |
|
||||
|
||||
### Waggle Personas (13)
|
||||
Researcher, Writer, Analyst, Coder, Project Manager, Executive Assistant, Sales Rep, Marketer, Senior PM, HR Manager, Legal Counsel, Business Finance, Strategy Consultant
|
||||
|
||||
### Claude Code Agents (5)
|
||||
General Purpose, Explore (read-only), Plan (read-only architect), Verification (adversarial), Claude Code Guide
|
||||
|
||||
**Key observation:** Waggle has more role diversity (13 vs 5) but Claude Code's agents are more architecturally distinct. Waggle's personas are variations on a general-purpose agent with different tool sets and guidance. Claude Code's agents have fundamentally different operating modes — Explore literally cannot write, Verification tries to break things, Coordinator only delegates.
|
||||
|
||||
---
|
||||
|
||||
## SPECIFIC IMPROVEMENTS FOR WAGGLE
|
||||
|
||||
### P0: Prompt Caching (Immediate ROI)
|
||||
|
||||
Refactor `buildSystemPrompt()` to use a section-based architecture with memoization:
|
||||
```
|
||||
systemPromptSection('identity', () => identity.toContext()) // changes rarely
|
||||
systemPromptSection('behavioral_spec', () => BEHAVIORAL_SPEC.rules) // changes on version bump
|
||||
systemPromptSection('self_awareness', () => buildSelfAwareness(caps)) // changes per turn
|
||||
systemPromptSection('recent_context', () => loadRecentContext()) // changes per turn
|
||||
```
|
||||
Mark sections that change per-turn as `uncached`. All others cache until explicitly cleared. This enables API prompt caching and reduces per-turn token costs significantly.
|
||||
|
||||
### P0: Break Up BEHAVIORAL_SPEC
|
||||
|
||||
Split the 280-line monolithic string into independent sections:
|
||||
- Core loop (RECALL → ASSESS → ACT → LEARN → RESPOND) — stable, cacheable
|
||||
- Quality rules — stable, cacheable
|
||||
- Behavioral rules — stable, cacheable
|
||||
- Tool descriptions — should be generated from tool definitions, not hardcoded
|
||||
- Intelligence defaults — evolves with capabilities, semi-stable
|
||||
|
||||
### P1: Add Safety Boundaries to Personas
|
||||
|
||||
Each persona needs explicit prohibitions, not just guidance:
|
||||
```
|
||||
Researcher:
|
||||
=== READ-ONLY PERSONA ===
|
||||
You are PROHIBITED from: write_file, edit_file, git_commit, bash (write operations)
|
||||
|
||||
Writer:
|
||||
=== DOCUMENT CREATION PERSONA ===
|
||||
You may create/edit files in the workspace. You are PROHIBITED from: bash, git_*, any system commands
|
||||
```
|
||||
|
||||
### P1: Add Verification Persona
|
||||
|
||||
Create a 14th persona: **Verifier** — adversarial quality assurance:
|
||||
- Tries to break generated outputs
|
||||
- Required output format: VERDICT: PASS / FAIL / PARTIAL
|
||||
- Documents what was checked and how
|
||||
- Universal baseline: re-read the brief, check facts against memory, verify formatting, check for hallucinated citations
|
||||
|
||||
### P1: Add Coordinator Persona
|
||||
|
||||
Create a 15th persona: **Coordinator** (Mission Control):
|
||||
- Tools: ONLY spawn_agent, list_agents, get_agent_result
|
||||
- Cannot execute tasks directly
|
||||
- Must synthesize worker results before further delegation
|
||||
- "Never delegate understanding" principle from Claude Code
|
||||
|
||||
### P2: Implement Compaction Prompt
|
||||
|
||||
Create a dedicated summarization prompt for long sessions:
|
||||
- TEXT ONLY output (no tool calls)
|
||||
- Required sections: primary request, key decisions, current state, pending work
|
||||
- Triggered when context exceeds threshold
|
||||
- Output replaces conversation history while preserving essential context
|
||||
### P2: Fix Disclaimer Contamination
|
||||
|
||||
The test report documents P1-8: workspace-specific financial disclaimers appended to ALL responses including "What is 2+2?". The BEHAVIORAL_SPEC has contextual disclaimer rules, but they're being overridden by workspace profile injection.
|
||||
|
||||
Fix: Workspace profile content should be injected as context, not as mandatory behavioral rules. The BEHAVIORAL_SPEC already has the correct contextual logic — the workspace profile is circumventing it.
|
||||
|
||||
### P2: Add Memory Conflict Resolution to Core Loop
|
||||
|
||||
Waggle already has this in BEHAVIORAL_SPEC:
|
||||
> "When corrected on FACTS that contradict a stored memory: DO NOT blindly accept. Search memory first. If you find a prior memory that says X but the user now claims Y, surface the conflict."
|
||||
|
||||
This is good. But it should be elevated to a CRITICAL rule with explicit enforcement, not buried in paragraph text. Claude Code doesn't have this at all — Waggle should lean into it as a differentiator.
|
||||
|
||||
### P3: Feature Gate Progressive Enhancement
|
||||
|
||||
Implement environment-based feature flags for:
|
||||
- Coordinator mode (restrict orchestrator to delegation-only)
|
||||
- Advanced workflows (compose_workflow, orchestrate_workflow)
|
||||
- Auto-save aggressiveness
|
||||
- Capability acquisition (auto-suggest vs. manual)
|
||||
|
||||
This enables A/B testing and gradual rollout as noted in the BEHAVIORAL_SPEC v2.0 comments.
|
||||
|
||||
---
|
||||
|
||||
## SUMMARY MATRIX
|
||||
|
||||
| Dimension | Waggle OS | Claude Code | Winner |
|
||||
|-----------|-----------|-------------|--------|
|
||||
| **Prompt architecture** | Monolithic buildSystemPrompt() | Section-based with caching | Claude Code |
|
||||
| **Memory integration** | Dual-mind (personal + workspace) + knowledge graph | Single flat-file directory + side-query | Waggle |
|
||||
| **Identity persistence** | IdentityLayer + personal mind | None (re-derived from prompt) | Waggle |
|
||||
| **Persona diversity** | 13 personas + custom JSON | 5 agents + custom markdown | Waggle |
|
||||
| **Safety boundaries** | Guidance-oriented (soft) | Prohibition-enforced (hard) | Claude Code |
|
||||
| **Verification** | None | Dedicated adversarial agent | Claude Code |
|
||||
| **Coordinator pattern** | Orchestrator as context manager | Pure delegation-only mode | Claude Code |
|
||||
| **Reasoning loop** | Explicit 5-step (RECALL→RESPOND) | Implicit in sections | Waggle |
|
||||
| **Anti-hallucination** | Explicit rules with memory conflict handling | Baseline model behavior | Waggle |
|
||||
| **Self-improvement** | ImprovementSignalStore + awareness surfacing | None | Waggle |
|
||||
| **Context compaction** | None | 4-layer compaction with dedicated prompt | Claude Code |
|
||||
| **Tone adaptation** | Per-workspace tone presets | Fixed style section | Waggle |
|
||||
| **Custom extensibility** | JSON personas + skill marketplace | Markdown agents + plugin system | Tie |
|
||||
| **Catch-up intelligence** | Pattern detection → importance-based recall | Same relevance filter for all queries | Waggle |
|
||||
| **Cache efficiency** | Full recompute per turn | Section-level memoization | Claude Code |
|
||||
| **Tool descriptions** | Inline in behavioral spec (static) | Generated from tool definitions (dynamic) | Claude Code |
|
||||
|
||||
**Score: Waggle 8, Claude Code 6, Tie 1**
|
||||
|
||||
Waggle wins on intelligence and sophistication. Claude Code wins on discipline and engineering efficiency. The improvement plan bridges both: bring Claude Code's caching, safety boundaries, and compaction into Waggle's more capable architecture.
|
||||
|
||||
---
|
||||
|
||||
*This comparison should be read alongside the consolidated improvement plan (`waggle-os-improvement-plan.md`) which incorporates these findings into actionable workstreams.*
|
||||
370
waggle-cowork/waggle-os-improvement-plan.md
Normal file
370
waggle-cowork/waggle-os-improvement-plan.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# Waggle OS — Consolidated Improvement Plan
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Author:** Cowork Advisory Session
|
||||
**Source:** Deep architecture analysis of Claude Code production source (~600+ files), cross-referenced with open-multi-agent, claw-code, and Waggle OS current state
|
||||
**Scope:** Strategic + tactical improvement roadmap for production readiness
|
||||
|
||||
---
|
||||
|
||||
## EXECUTIVE SUMMARY
|
||||
|
||||
Waggle OS is architecturally sound and directionally correct. The core infrastructure — Tauri desktop shell, Fastify backend, React frontend, SQLite + graph memory, 13 agent personas, MCP connector framework — provides a foundation that is structurally superior to Claude Code in several dimensions (graph memory, visual orchestration, multi-workspace isolation, three-tier user model, encrypted vault).
|
||||
|
||||
However, the gap between Waggle's current state and production quality is not in features — it is in **engineering discipline at the subsystem level.** Claude Code's production source reveals that maturity comes from schema validation on every boundary, compositional security via tool pools, intelligent context management, and memory retrieval optimization. These are the patterns this plan targets.
|
||||
|
||||
This plan consolidates all findings into a single prioritized roadmap across six workstreams.
|
||||
|
||||
---
|
||||
|
||||
## WORKSTREAM 1: AGENT DEFINITION & ORCHESTRATION
|
||||
|
||||
### Problem
|
||||
Waggle has 13 agent personas, but they lack a formalized definition schema. Agent capabilities are implicitly defined rather than explicitly bounded. There is no compositional security — agents are not restricted to specific tool sets by schema enforcement.
|
||||
|
||||
### What Claude Code Proves Works
|
||||
Every agent follows a single `BaseAgentDefinition` schema:
|
||||
```
|
||||
agentType — unique identifier
|
||||
whenToUse — natural language trigger description
|
||||
tools — allowlist of permitted tools
|
||||
disallowedTools — denylist of excluded tools
|
||||
model — model override (sonnet/opus/haiku/inherit)
|
||||
maxTurns — hard cap on agentic turns
|
||||
memory — persistent memory scope (user/project/local)
|
||||
skills — preloaded skill names
|
||||
mcpServers — agent-specific MCP servers
|
||||
hooks — pre/post tool execution hooks
|
||||
isolation — worktree or sandbox
|
||||
permissionMode — default/plan/bypass
|
||||
```
|
||||
|
||||
Each agent gets a custom-assembled tool pool via `assembleToolPool()` — allowlist/denylist filtering, auto-injection of memory tools, MCP tool binding. An Explore agent literally cannot write files because FileWrite is not in its pool. Security by schema, not by prompt.
|
||||
|
||||
### Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 1.1 | Formalize all 13 agent personas into `BaseAgentDefinition` YAML/markdown files with the schema above | P0 | Medium |
|
||||
| 1.2 | Implement `assembleToolPool()` — per-agent tool filtering based on allowlist/denylist | P0 | Medium |
|
||||
| 1.3 | Implement **Coordinator Mode** for Mission Control: restricted tool set (Agent + SendMessage + TaskStop only), all execution delegated to workers, "never delegate understanding" principle | P1 | High |
|
||||
| 1.4 | Implement **Fork Subagent Pattern** for Waggle Dance: context-inheriting spawns for research phases, parent context stays clean, fork returns summary only | P1 | High |
|
||||
| 1.5 | Adopt **Task Notification Protocol** (`<task-notification>` XML) for agent→orchestrator communication, wire into Events view | P1 | Medium |
|
||||
| 1.6 | Map agent tiers to user tiers: simple users see built-in agents only, power users define custom agents, admins manage plugin agents from marketplace | P2 | Medium |
|
||||
|
||||
### Success Criteria
|
||||
- Every agent has a validated definition file with explicit tool boundaries
|
||||
- No agent can access tools outside its defined pool
|
||||
- Mission Control operates as a pure coordinator — delegates everything, executes nothing
|
||||
- Waggle Dance research workflows use forks; implementation workflows use fresh spawns
|
||||
---
|
||||
|
||||
## WORKSTREAM 2: MEMORY SYSTEM OPTIMIZATION
|
||||
|
||||
### Current State (Waggle's Advantage)
|
||||
Waggle's SQLite + frames + graph architecture is **structurally superior** to Claude Code's flat-file approach. Frames as graph nodes with relational edges enable relationship queries, temporal reasoning, cross-agent knowledge sharing, and importance-based pruning. The `auto_recall` tool provides automatic context injection. This is the correct architecture for an enterprise product.
|
||||
|
||||
Claude Code uses flat markdown files with YAML frontmatter. It works for a CLI tool. It cannot do relationship queries, has no concurrent access support, and scales poorly beyond a few hundred files.
|
||||
|
||||
### What Waggle Should Adopt (Intelligence Layer, Not Storage Replacement)
|
||||
|
||||
**Side-Query Relevance Filter (highest-value single improvement):**
|
||||
Claude Code uses a lightweight Sonnet call to pre-filter which memories to inject. Flow: scan all frame metadata (not content) → send manifest + user query to Sonnet → get back top 5 relevant frames → load only those into context. With 49+ frames and growing, injecting everything is token waste. This filter is the difference between surgical context injection and flooding.
|
||||
|
||||
**Four-Type Taxonomy Overlay:**
|
||||
Classify frames as `user` (role/preferences), `feedback` (behavioral corrections AND confirmations), `project` (ongoing work context), `reference` (pointers to external systems). This is a schema layer on top of the graph — not a replacement. It provides consistent retrieval patterns and enables explicit exclusion rules (refuse to store code patterns, git history, debugging solutions as frames).
|
||||
|
||||
**Staleness & Verification:**
|
||||
Inject freshness warnings for frames older than a configurable threshold. Enforce "verify before recommending" — when a frame references a file path or function, check it still exists before surfacing.
|
||||
|
||||
### Implementation Bugs to Fix
|
||||
|
||||
| # | Bug | Priority |
|
||||
|---|-----|----------|
|
||||
| 2.1 | `accessCount` never increments on frame view — breaks importance scoring and pruning | P2 |
|
||||
| 2.2 | Memory count discrepancy (49 vs 37 in different UI views) — stale cache or query bug | P2 |
|
||||
| 2.3 | Markdown not rendered in frame display — raw `**bold**` visible | P3 |
|
||||
|
||||
### Enhancement Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 2.4 | Implement side-query relevance filter: scan frame metadata, select top-5 per query, inject only those | P1 | High |
|
||||
| 2.5 | Add four-type taxonomy as frame classification (`user`/`feedback`/`project`/`reference`) | P2 | Medium |
|
||||
| 2.6 | Implement staleness warnings for frames older than configurable threshold | P2 | Low |
|
||||
| 2.7 | Add "verify before recommending" enforcement — check referenced paths/functions exist | P2 | Medium |
|
||||
| 2.8 | Implement per-agent memory scopes — Analysis Agent remembers different things than Writing Agent | P2 | Medium |
|
||||
| 2.9 | Add explicit exclusion rules — refuse to store code patterns, git history, ephemeral task details | P2 | Low |
|
||||
| 2.10 | Implement memory snapshots for team workspaces — new team members get bootstrapped memory | P4 | High |
|
||||
|
||||
### Success Criteria
|
||||
- Context injection uses ≤5 frames per query (not all 49+)
|
||||
- Every frame has a type classification
|
||||
- Frames older than threshold display staleness caveat
|
||||
- accessCount accurately tracks frame usage
|
||||
---
|
||||
|
||||
## WORKSTREAM 3: CONTEXT & TOKEN MANAGEMENT
|
||||
|
||||
### Problem
|
||||
Long agent sessions will hit context limits. With 13 agents generating output, context fills fast. Without compaction, conversations degrade or fail. Without budget tracking, there is no way to detect diminishing returns or prevent runaway token spend.
|
||||
|
||||
### What Claude Code Implements
|
||||
|
||||
**Four-layer compaction:**
|
||||
1. **Snip compact** — removes oldest messages, preserves recent "protected tail"
|
||||
2. **Microcompact** — replaces individual tool results with summaries when they exceed size limits
|
||||
3. **Context collapse** — groups related messages into collapsible summaries (read-time view, full history preserved)
|
||||
4. **Autocompact** — full conversation summary when nearing context limit, triggered by token threshold
|
||||
|
||||
**Token budget management:**
|
||||
- Tracks `continuationCount`, `lastDeltaTokens`, `lastGlobalTurnTokens`
|
||||
- Continues if under 90% of budget AND not showing diminishing returns
|
||||
- Diminishing returns: 3+ continuations with <500 token delta
|
||||
- Hard stop reserves space for manual compaction
|
||||
|
||||
**Streaming tool execution:**
|
||||
- Tools begin executing as parameters stream in (not after full response)
|
||||
- Multiple tools execute concurrently
|
||||
- Results yielded as they complete, not in order
|
||||
- Cuts perceived latency 30-50% for multi-tool turns
|
||||
|
||||
### Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 3.1 | Build token budget tracker for chat view — track continuation count, delta tokens, 90% threshold | P0 | Medium |
|
||||
| 3.2 | Implement microcompact — per-tool-result summarization when results exceed size limits | P1 | High |
|
||||
| 3.3 | Implement autocompact — full conversation summary when context nears limit | P1 | High |
|
||||
| 3.4 | Implement streaming tool execution — begin execution as parameters stream in, concurrent multi-tool | P2 | High |
|
||||
| 3.5 | Add diminishing-returns detection — auto-stop after 3+ continuations with <500 token delta | P2 | Low |
|
||||
| 3.6 | Implement tool result budget — enforce per-message aggregate size limits on tool results | P2 | Medium |
|
||||
|
||||
### Success Criteria
|
||||
- Conversations survive 50+ turns without degradation
|
||||
- Token usage visible to user in Cockpit view
|
||||
- Multi-tool turns execute concurrently, not sequentially
|
||||
- System auto-compacts before hitting hard context limits
|
||||
---
|
||||
|
||||
## WORKSTREAM 4: TOOL HARNESS & MCP MATURATION
|
||||
|
||||
### Problem
|
||||
Waggle has tool execution and MCP connectors, but lacks the standardized tool factory pattern and deferred loading that Claude Code uses to keep the system scalable and cache-friendly.
|
||||
|
||||
### What Claude Code Implements
|
||||
|
||||
**`buildTool()` factory** — every tool created via standardized factory with:
|
||||
- Zod input/output schema validation
|
||||
- Dynamic `isEnabled()` / `isReadOnly()` checks
|
||||
- `maxResultSizeChars` truncation limits
|
||||
- React rendering hooks for each tool state (progress, result, error, rejected)
|
||||
- `validateInput()` pre-execution validation
|
||||
|
||||
**Deferred tool loading (ToolSearch)** — tools registered by name only. Full schema fetched on demand. Keeps system prompt compact as MCP server count grows. Each connected MCP server adds tool schemas to the prompt; deferral prevents prompt bloat.
|
||||
|
||||
**Permission model** — multi-layer: per-tool, per-agent, per-source rules. Enterprise policy overrides project overrides user. Background agents auto-deny permission prompts.
|
||||
|
||||
### Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 4.1 | Standardize tool creation via factory pattern with schema validation on every boundary | P1 | High |
|
||||
| 4.2 | Implement deferred tool loading — register connector tools by name, fetch schemas on demand | P2 | Medium |
|
||||
| 4.3 | Add per-tool result size limits and truncation | P2 | Low |
|
||||
| 4.4 | Implement per-agent, per-source permission rules with enterprise policy override chain | P4 | High |
|
||||
| 4.5 | Add background agent auto-deny — skip permission prompts when no UI available | P3 | Low |
|
||||
|
||||
### Success Criteria
|
||||
- Every tool has validated input/output schemas
|
||||
- Adding a new MCP server does not increase base prompt size
|
||||
- Enterprise admins can set tool-level permission policies that override user/project settings
|
||||
---
|
||||
|
||||
## WORKSTREAM 5: SKILLS FRAMEWORK
|
||||
|
||||
### Problem
|
||||
Waggle has a "Skills & Apps" dock view, but the skill definition format and discovery mechanism may not be standardized for extensibility and marketplace distribution.
|
||||
|
||||
### What Claude Code Implements
|
||||
|
||||
Skills are markdown files with YAML frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: commit
|
||||
description: Create a git commit with conventional commit message
|
||||
tools: Agent, Bash, FileRead, FileEdit
|
||||
model: sonnet
|
||||
effort: high
|
||||
paths: src/**, tests/**
|
||||
hooks:
|
||||
pre_tool_call: ...
|
||||
post_tool_call: ...
|
||||
args: message
|
||||
---
|
||||
[Skill prompt content]
|
||||
```
|
||||
|
||||
**Six sources with priority:** bundled < MCP-generated < user < project < managed < plugin. Deduplication by canonical file path. Discovery and prefetch run alongside model streaming — skill relevance assessed before the model explicitly requests them.
|
||||
|
||||
### Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 5.1 | Standardize skill definition format with YAML frontmatter schema (name, description, tools, model, effort, paths, hooks, args) | P2 | Medium |
|
||||
| 5.2 | Implement skill source priority chain: built-in < user < workspace < marketplace < enterprise policy | P2 | Medium |
|
||||
| 5.3 | Add skill discovery prefetch — identify relevant skills from user query before model requests them | P3 | Medium |
|
||||
| 5.4 | Enable MCP servers to register skill builders — skills generated dynamically from connected services | P3 | High |
|
||||
| 5.5 | Implement skill deduplication by canonical path — prevent duplicates across sources | P3 | Low |
|
||||
|
||||
### Success Criteria
|
||||
- Every skill has a validated frontmatter definition
|
||||
- Skills from marketplace can override built-in skills by name
|
||||
- Relevant skills surfaced proactively before explicit invocation
|
||||
---
|
||||
|
||||
## WORKSTREAM 6: TASK SYSTEM & SESSION MANAGEMENT
|
||||
|
||||
### Problem
|
||||
Waggle's Cockpit tracks agent status, but structured task types, lifecycle management, and background execution with notifications are needed for production-grade workflow orchestration.
|
||||
|
||||
### What Claude Code Implements
|
||||
|
||||
**Seven task types:**
|
||||
- `LocalAgentTask` — foreground subagent (sync or backgroundable)
|
||||
- `RemoteAgentTask` — remote sandbox execution (always background)
|
||||
- `InProcessTeammateTask` — multi-agent collaboration process
|
||||
- `LocalShellTask` — background shell commands
|
||||
- `LocalWorkflowTask` — multi-step workflow execution
|
||||
- `MonitorMcpTask` — MCP server monitoring
|
||||
- `DreamTask` — background speculative processing
|
||||
|
||||
**Lifecycle:** `pending` → `running` → `completed|failed|killed`
|
||||
**Auto-background:** After 120 seconds, foreground agents move to background automatically.
|
||||
**Progress reporting:** `AgentToolProgress` events with description, tokenCount, toolUseCount, lastToolName.
|
||||
|
||||
### Actions
|
||||
|
||||
| # | Action | Priority | Effort |
|
||||
|---|--------|----------|--------|
|
||||
| 6.1 | Define Waggle-specific task types (adapt from Claude Code's seven — drop tmux-specific, add Waggle-native types for graph queries, workspace operations) | P2 | Medium |
|
||||
| 6.2 | Implement task lifecycle state machine: pending → running → completed/failed/killed | P2 | Medium |
|
||||
| 6.3 | Add auto-background for long-running agents (configurable threshold, default 120s) | P3 | Low |
|
||||
| 6.4 | Implement progress reporting in Cockpit — real-time token count, tool usage, duration per agent | P2 | Medium |
|
||||
| 6.5 | Add session persistence and resume — transcripts recorded, sessions resumable across app restarts | P3 | High |
|
||||
| 6.6 | Wire task notifications into Events view for real-time workflow visualization | P2 | Medium |
|
||||
|
||||
### Success Criteria
|
||||
- Every running agent has a visible task type and lifecycle state in Cockpit
|
||||
- Long-running agents auto-background without user intervention
|
||||
- Sessions survive app restart and resume from last state
|
||||
---
|
||||
|
||||
## PRIORITY MATRIX — ALL ACTIONS RANKED
|
||||
|
||||
### P0 — Foundation (Blocks Everything Else)
|
||||
|
||||
| ID | Action | Workstream |
|
||||
|----|--------|------------|
|
||||
| 1.1 | Formalize 13 agents into BaseAgentDefinition schema | Agent Orchestration |
|
||||
| 1.2 | Implement assembleToolPool() per-agent tool filtering | Agent Orchestration |
|
||||
| 3.1 | Build token budget tracker (90% threshold, diminishing returns) | Context Management |
|
||||
|
||||
### P1 — Core Quality (Production Readiness)
|
||||
|
||||
| ID | Action | Workstream |
|
||||
|----|--------|------------|
|
||||
| 1.3 | Implement Coordinator Mode for Mission Control | Agent Orchestration |
|
||||
| 1.4 | Implement Fork Subagent Pattern for Waggle Dance | Agent Orchestration |
|
||||
| 1.5 | Adopt Task Notification Protocol for Events view | Agent Orchestration |
|
||||
| 2.4 | Implement side-query relevance filter (top-5 frame selection) | Memory |
|
||||
| 3.2 | Implement microcompact (per-tool-result summarization) | Context Management |
|
||||
| 3.3 | Implement autocompact (full conversation summary) | Context Management |
|
||||
| 4.1 | Standardize tool factory with schema validation | Tool Harness |
|
||||
|
||||
### P2 — Maturation (Competitive Quality)
|
||||
|
||||
| ID | Action | Workstream |
|
||||
|----|--------|------------|
|
||||
| 1.6 | Map agent tiers to user tiers (simple/power/admin) | Agent Orchestration |
|
||||
| 2.1 | Fix accessCount incrementing | Memory (Bug) |
|
||||
| 2.2 | Fix memory count discrepancy (49 vs 37) | Memory (Bug) |
|
||||
| 2.5 | Add four-type taxonomy as frame classification | Memory |
|
||||
| 2.6 | Implement staleness warnings | Memory |
|
||||
| 2.7 | Add verify-before-recommend enforcement | Memory |
|
||||
| 2.8 | Implement per-agent memory scopes | Memory |
|
||||
| 2.9 | Add explicit exclusion rules for memory | Memory |
|
||||
| 3.4 | Implement streaming tool execution (concurrent) | Context Management |
|
||||
| 3.5 | Add diminishing-returns detection | Context Management |
|
||||
| 3.6 | Implement tool result budget | Context Management |
|
||||
| 4.2 | Implement deferred tool loading | Tool Harness |
|
||||
| 4.3 | Add per-tool result size limits | Tool Harness |
|
||||
| 5.1 | Standardize skill definition format | Skills |
|
||||
| 5.2 | Implement skill source priority chain | Skills |
|
||||
| 6.1 | Define Waggle-specific task types | Task System |
|
||||
| 6.2 | Implement task lifecycle state machine | Task System |
|
||||
| 6.4 | Add progress reporting in Cockpit | Task System |
|
||||
| 6.6 | Wire task notifications into Events view | Task System |
|
||||
|
||||
### P3 — Polish (Production Finish)
|
||||
|
||||
| ID | Action | Workstream |
|
||||
|----|--------|------------|
|
||||
| 2.3 | Render markdown in frame display | Memory (Bug) |
|
||||
| 4.5 | Add background agent auto-deny | Tool Harness |
|
||||
| 5.3 | Add skill discovery prefetch | Skills |
|
||||
| 5.4 | Enable MCP skill builders | Skills |
|
||||
| 5.5 | Implement skill deduplication | Skills |
|
||||
| 6.3 | Add auto-background for long-running agents | Task System |
|
||||
| 6.5 | Implement session persistence and resume | Task System |
|
||||
|
||||
### P4 — Enterprise
|
||||
|
||||
| ID | Action | Workstream |
|
||||
|----|--------|------------|
|
||||
| 2.10 | Implement memory snapshots for team workspaces | Memory |
|
||||
| 4.4 | Implement enterprise permission policy chain | Tool Harness |
|
||||
---
|
||||
|
||||
## WAGGLE'S STRUCTURAL ADVANTAGES — DO NOT LOSE THESE
|
||||
|
||||
These are not incremental features. They are architectural moats that justify Waggle as a distinct product category from Claude Code.
|
||||
|
||||
1. **Graph-based memory (SQLite + frames + graph)** — relationship queries, temporal reasoning, cross-agent knowledge sharing, importance-based pruning. Claude Code cannot do any of this with flat files. This is the intelligence foundation.
|
||||
|
||||
2. **Visual orchestration (Cockpit / Mission Control / Waggle Dance / Events)** — real-time visibility into agent workflows that a terminal fundamentally cannot deliver. This is the enterprise sales differentiator.
|
||||
|
||||
3. **Multi-workspace isolation** — independent agent pools, memory spaces, and security boundaries per workspace. Claude Code is one project per session.
|
||||
|
||||
4. **Desktop-first distribution via Tauri** — one-click install, not `npm install -g`. Dramatically lower barrier for non-technical users.
|
||||
|
||||
5. **Three-tier user model** — progressive complexity. Simple users see chat. Power users see agent configuration. Admins see the full orchestration layer. Claude Code has one mode for everyone.
|
||||
|
||||
6. **Encrypted vault (AES-256-GCM)** — Claude Code stores secrets in plaintext config files. Waggle's vault is enterprise-grade by default.
|
||||
|
||||
---
|
||||
|
||||
## WHAT NOT TO DO
|
||||
|
||||
- **Do NOT copy Claude Code source code.** IP risk is real. Extract patterns, not implementations.
|
||||
- **Do NOT replace the graph DB with flat files.** The graph is the correct architecture. Add intelligence layers on top.
|
||||
- **Do NOT adopt tmux-based multi-agent.** That is a CLI-specific workaround. Waggle's backend orchestrates agents natively.
|
||||
- **Do NOT replicate the ink/ terminal rendering layer.** Waggle has a proper React UI framework.
|
||||
- **Do NOT over-index on Claude Code's specific implementation choices.** Many are CLI constraints, not best practices. Adopt the design principles, not the code.
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION SEQUENCE
|
||||
|
||||
**Phase 1 (P0 — 2-3 weeks):** Agent definition schema + tool pool assembly + token budget tracker. These three items unblock everything else. Without schema-enforced agent boundaries and token awareness, no subsequent workstream can be built correctly.
|
||||
|
||||
**Phase 2 (P1 — 4-6 weeks):** Coordinator mode + fork pattern + side-query relevance + compaction layers + tool factory. This is the production quality sprint. At the end of Phase 2, Waggle should be able to run multi-agent workflows that survive long sessions without context degradation.
|
||||
|
||||
**Phase 3 (P2 — 4-6 weeks):** Memory maturation (taxonomy, staleness, per-agent scopes) + streaming execution + deferred tool loading + task system + UI tier mapping. This is the competitive quality sprint. At the end of Phase 3, Waggle is demonstrably more capable than Claude Code for enterprise use cases.
|
||||
|
||||
**Phase 4 (P3-P4 — ongoing):** Polish, session persistence, enterprise permissions, team memory snapshots, skill marketplace. These are the features that justify enterprise pricing.
|
||||
|
||||
---
|
||||
|
||||
*Total actions: 37 across 6 workstreams. 3 P0, 7 P1, 19 P2, 6 P3, 2 P4.*
|
||||
*Estimated total effort: 14-18 weeks for P0-P2, assuming dedicated engineering team.*
|
||||
551
waggle-cowork/waggle-prompt-improvement-plan.md
Normal file
551
waggle-cowork/waggle-prompt-improvement-plan.md
Normal file
@@ -0,0 +1,551 @@
|
||||
# Waggle OS — System Prompt & Persona Improvement Plan
|
||||
|
||||
**Date:** 2026-04-01
|
||||
**Objective:** Win every dimension of the comparison matrix by adopting Claude Code's engineering discipline while preserving Waggle's architectural advantages. Add 4 new personas (General Purpose, Planner, Verifier, Coordinator) to close the functional gaps.
|
||||
|
||||
---
|
||||
|
||||
## PART 1: NEW PERSONAS
|
||||
|
||||
### 1A. General Purpose Agent
|
||||
|
||||
Claude Code's general-purpose agent is the default workhorse — handles anything that doesn't match a specialist. Waggle lacks this. When no persona fits, the system currently falls back to the behavioral spec alone without role-specific guidance.
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: 'general-purpose',
|
||||
name: 'General Purpose',
|
||||
description: 'Versatile agent for any task — research, writing, analysis, coding, planning',
|
||||
icon: '🧠',
|
||||
systemPrompt: `## Persona: General Purpose Agent
|
||||
You are a versatile agent that adapts to whatever the user needs. You have access to the full tool set and can handle any task type.
|
||||
|
||||
### Operating Principles
|
||||
- **Assess first, act second.** Determine the nature of the task before choosing tools. Research tasks need web_search and search_memory. Writing tasks need context gathering then drafting. Code tasks need reading before writing. Planning tasks need create_plan before execution.
|
||||
- **Search broadly when you don't know where something lives.** Use search_files with wide patterns, search_memory with varied queries, web_search with multiple phrasings.
|
||||
- **Start broad, narrow down.** For analysis tasks, gather context from multiple sources before synthesizing.
|
||||
- **Be thorough.** Check multiple locations, consider different naming conventions, cross-reference memory with external sources.
|
||||
- **Chain tools naturally.** search_memory → web_search → web_fetch for research. search_files → read_file → edit_file for code. create_plan → execute_step for multi-step work.
|
||||
- **Save what matters.** After completing a task, save key outcomes and decisions to memory. The next session should benefit from this one.
|
||||
|
||||
### When NOT to Use This Persona
|
||||
If the user's request clearly maps to a specialist persona (legal analysis → Legal Counsel, financial modeling → Business Finance, code review → Coder), suggest switching. A specialist with domain-tuned guidance will outperform a generalist on domain tasks.`,
|
||||
modelPreference: 'claude-sonnet-4-6',
|
||||
tools: [
|
||||
'bash', 'read_file', 'write_file', 'edit_file', 'search_files', 'search_content',
|
||||
'web_search', 'web_fetch', 'search_memory', 'save_memory', 'generate_docx',
|
||||
'create_plan', 'add_plan_step', 'execute_step', 'show_plan',
|
||||
'spawn_agent', 'list_agents', 'get_agent_result',
|
||||
'git_status', 'git_diff', 'git_log', 'git_commit',
|
||||
'list_skills', 'suggest_skill', 'acquire_capability', 'install_capability',
|
||||
'compose_workflow', 'orchestrate_workflow',
|
||||
'query_knowledge', 'get_identity', 'get_awareness',
|
||||
],
|
||||
workspaceAffinity: ['general', 'mixed', 'personal', 'exploration'],
|
||||
suggestedCommands: ['/research', '/draft', '/plan', '/decide', '/catchup'],
|
||||
defaultWorkflow: null,
|
||||
}
|
||||
```
|
||||
### 1B. Planner Agent
|
||||
|
||||
Claude Code's Plan agent is read-only by design — it explores the codebase, considers architecture, and outputs a step-by-step plan without making any changes. Waggle needs an equivalent that works across all domains, not just code.
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: 'planner',
|
||||
name: 'Planner',
|
||||
description: 'Strategic planning specialist — explores context, designs approaches, outputs actionable plans',
|
||||
icon: '🗂️',
|
||||
systemPrompt: `## Persona: Planner
|
||||
You are a planning and architecture specialist. Your job is to explore context, analyze options, and design implementation approaches. You do NOT execute — you plan.
|
||||
|
||||
=== CRITICAL: READ-ONLY PERSONA — NO MODIFICATIONS ===
|
||||
You are STRICTLY PROHIBITED from:
|
||||
- Creating, modifying, or deleting any files (no write_file, edit_file)
|
||||
- Running commands that change state (no git_commit, no destructive bash)
|
||||
- Generating documents (no generate_docx — that's for the execution phase)
|
||||
- Installing anything (no install_capability)
|
||||
|
||||
You MAY:
|
||||
- Read any file (read_file, search_files, search_content)
|
||||
- Search memory and web (search_memory, web_search, web_fetch)
|
||||
- Query knowledge graph (query_knowledge)
|
||||
- Run read-only bash commands (ls, cat, grep, git status, git log, git diff)
|
||||
- Create structured plans (create_plan, add_plan_step, show_plan)
|
||||
|
||||
### Your Process
|
||||
1. **Understand Requirements** — Read the user's request carefully. Ask clarifying questions if the scope is ambiguous.
|
||||
2. **Explore Context** — Search memory for relevant prior decisions and context. Read referenced files. Search for existing patterns and conventions. Query the knowledge graph for related entities.
|
||||
3. **Analyze Options** — Consider at least 2 approaches when non-trivial. Evaluate trade-offs explicitly (effort, risk, maintainability, alignment with existing patterns).
|
||||
4. **Design the Plan** — Create a step-by-step plan using create_plan. Each step should be concrete and actionable by any persona. Include dependencies between steps.
|
||||
5. **Identify Risks** — Flag what could go wrong. Note assumptions that need validation.
|
||||
|
||||
### Required Output Format
|
||||
End every planning session with:
|
||||
|
||||
#### Recommended Approach
|
||||
[1-2 sentence summary of the chosen strategy and why]
|
||||
|
||||
#### Plan Steps
|
||||
[The create_plan output — each step with clear success criteria]
|
||||
|
||||
#### Critical Context
|
||||
[3-5 most important files, memories, or resources needed for execution]
|
||||
|
||||
#### Risks & Assumptions
|
||||
[What could break and what we're assuming is true]
|
||||
|
||||
#### Suggested Execution
|
||||
[Which persona(s) should execute which steps — e.g., "Steps 1-3: Researcher, Steps 4-5: Writer, Step 6: Verifier"]`,
|
||||
modelPreference: 'claude-sonnet-4-6',
|
||||
tools: [
|
||||
'read_file', 'search_files', 'search_content',
|
||||
'web_search', 'web_fetch',
|
||||
'search_memory', 'query_knowledge', 'get_awareness',
|
||||
'create_plan', 'add_plan_step', 'show_plan',
|
||||
'suggest_skill', 'list_skills',
|
||||
'bash', // read-only operations only — enforced by prompt
|
||||
],
|
||||
workspaceAffinity: ['strategy', 'planning', 'architecture', 'project', 'research'],
|
||||
suggestedCommands: ['/plan', '/decide', '/research'],
|
||||
defaultWorkflow: null,
|
||||
}
|
||||
```
|
||||
### 1C. Verifier Agent
|
||||
|
||||
This is the single most impactful persona Claude Code has that Waggle lacks. An adversarial agent whose entire purpose is to find what's wrong, not confirm what's right.
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: 'verifier',
|
||||
name: 'Verifier',
|
||||
description: 'Adversarial quality assurance — tries to break outputs before they reach the user',
|
||||
icon: '🔍',
|
||||
systemPrompt: `## Persona: Verifier
|
||||
Your job is NOT to confirm that something works. Your job is to try to BREAK it.
|
||||
|
||||
=== CRITICAL: READ-ONLY — NO MODIFICATIONS TO USER WORK ===
|
||||
You are PROHIBITED from modifying any user files or project state.
|
||||
You MAY run read-only commands and create temporary test files in /tmp only.
|
||||
|
||||
### Known Failure Patterns (Avoid These)
|
||||
1. **Verification avoidance:** Reading the output, narrating what you would check, then claiming PASS without actually checking. This is the #1 failure mode. You must RUN checks, not describe them.
|
||||
2. **First-80% seduction:** Seeing a polished introduction or clean formatting and not noticing the substance is wrong, incomplete, or hallucinated. The first 80% is always easy. Your value is the last 20%.
|
||||
3. **Confirmation bias:** Starting with the assumption the output is correct and looking for evidence to support that. Start from the assumption it's WRONG and look for evidence it's right.
|
||||
4. **Source amnesia:** Accepting claims in the output without checking whether they came from memory, web search, or were fabricated. Trace every factual claim to its source.
|
||||
|
||||
### Verification Protocol
|
||||
|
||||
**For Documents/Reports/Analyses:**
|
||||
1. Check every factual claim against memory (search_memory) and web (web_search)
|
||||
2. Verify cited sources exist and say what the document claims they say
|
||||
3. Check for internal consistency — does the conclusion follow from the evidence?
|
||||
4. Look for missing perspectives — what counterargument was not addressed?
|
||||
5. Verify numbers, dates, names — these are the most common hallucination targets
|
||||
6. Check formatting and structure against the user's stated requirements
|
||||
|
||||
**For Code/Technical Outputs:**
|
||||
1. Read the code — does it do what the user asked?
|
||||
2. Run tests if available (bash — read-only test execution)
|
||||
3. Check edge cases: empty input, null values, boundary conditions
|
||||
4. Verify imports/dependencies exist
|
||||
5. Check for security issues: injection, path traversal, hardcoded secrets
|
||||
6. Verify it integrates with existing code patterns (search_files for conventions)
|
||||
|
||||
**For Plans/Strategies:**
|
||||
1. Check feasibility — are the proposed steps actually executable?
|
||||
2. Verify dependencies — does step 3 actually depend on step 2, or is it arbitrary?
|
||||
3. Look for missing steps — what's implied but not stated?
|
||||
4. Check resource assumptions — does the plan assume capabilities that don't exist?
|
||||
5. Verify against memory — does this contradict prior decisions?
|
||||
|
||||
### Required Output Format (MANDATORY)
|
||||
Every verification must end with exactly one of:
|
||||
|
||||
**VERDICT: PASS** — All checks passed. State what was verified.
|
||||
**VERDICT: FAIL** — Critical issues found. List each issue with evidence.
|
||||
**VERDICT: PARTIAL** — Some checks passed, others failed or could not be verified. List what passed, what failed, and what remains unchecked.
|
||||
|
||||
Each check MUST include:
|
||||
- What was checked
|
||||
- How it was checked (which tool, which query)
|
||||
- What was found
|
||||
- Pass/Fail for that specific check`,
|
||||
modelPreference: 'claude-sonnet-4-6',
|
||||
tools: [
|
||||
'read_file', 'search_files', 'search_content',
|
||||
'web_search', 'web_fetch',
|
||||
'search_memory', 'query_knowledge',
|
||||
'bash', // read-only + /tmp test scripts only
|
||||
'show_plan',
|
||||
],
|
||||
workspaceAffinity: ['quality', 'review', 'verification', 'audit'],
|
||||
suggestedCommands: ['/review', '/verify'],
|
||||
defaultWorkflow: null,
|
||||
}
|
||||
```
|
||||
### 1D. Coordinator Agent (Mission Control)
|
||||
|
||||
The pure orchestrator that Claude Code uses in coordinator mode. Delegates everything, executes nothing, synthesizes before directing.
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: 'coordinator',
|
||||
name: 'Coordinator',
|
||||
description: 'Pure orchestrator — delegates work to specialists, synthesizes results, never executes directly',
|
||||
icon: '🎛️',
|
||||
systemPrompt: `## Persona: Coordinator (Mission Control)
|
||||
You orchestrate complex, multi-phase tasks by delegating to specialist agents. You NEVER execute work directly.
|
||||
|
||||
=== CRITICAL: DELEGATION-ONLY MODE ===
|
||||
You have access to ONLY these tools:
|
||||
- spawn_agent — launch a specialist with a specific task
|
||||
- list_agents — check status of running agents
|
||||
- get_agent_result — retrieve completed agent output
|
||||
- search_memory — recall context for planning
|
||||
- save_memory — save coordination decisions
|
||||
- create_plan / add_plan_step / show_plan — structure the workflow
|
||||
|
||||
You CANNOT: read files, write files, run bash, search the web, generate documents. All of that is done by your workers.
|
||||
|
||||
### Core Principle: NEVER DELEGATE UNDERSTANDING
|
||||
Before directing a worker to implement something, YOU must understand the full picture. This means:
|
||||
- After research workers report back, YOU synthesize findings into specific, actionable instructions
|
||||
- NEVER say "based on your findings, do X" — instead, state exactly what the findings showed and what specific actions follow
|
||||
- Include file paths, specific content, exact requirements in every worker prompt
|
||||
- If you don't understand a worker's result well enough to direct the next step, spawn a follow-up research worker to clarify
|
||||
|
||||
### Anti-Patterns (NEVER DO THESE)
|
||||
- "Look into X and fix whatever you find" — too vague, worker will guess
|
||||
- "Based on your research, write the document" — you didn't synthesize
|
||||
- "Do what makes sense" — you abdicated coordination
|
||||
- Spawning one mega-worker with the entire task — defeats the purpose
|
||||
|
||||
### Workflow Pattern
|
||||
1. **Decompose** — Break the user's request into distinct phases (research, analysis, creation, verification)
|
||||
2. **Research (parallel)** — Spawn research workers for each information need. Workers can run simultaneously.
|
||||
3. **Synthesize** — Read all research results. Form a specific, grounded plan. Save key findings to memory.
|
||||
4. **Direct** — Spawn implementation workers with PRECISE instructions. Each worker gets: exactly what to produce, what context to use, what format to follow, what success looks like.
|
||||
5. **Verify** — Spawn a Verifier agent to review the output. Do NOT skip this step.
|
||||
6. **Report** — Summarize the outcome to the user. Include: what was done, key decisions made, any issues found by verification, suggested next steps.
|
||||
|
||||
### Worker Prompt Template
|
||||
When spawning a worker, always include:
|
||||
- **Role**: Which persona to use (researcher, writer, coder, analyst, verifier)
|
||||
- **Task**: Specific, self-contained instruction (worker cannot see your conversation)
|
||||
- **Context**: All relevant facts, file paths, prior findings the worker needs
|
||||
- **Output format**: What the result should look like
|
||||
- **Success criteria**: How to know the task is complete`,
|
||||
modelPreference: 'claude-sonnet-4-6',
|
||||
tools: [
|
||||
'spawn_agent', 'list_agents', 'get_agent_result',
|
||||
'search_memory', 'save_memory', 'query_knowledge', 'get_awareness',
|
||||
'create_plan', 'add_plan_step', 'execute_step', 'show_plan',
|
||||
],
|
||||
workspaceAffinity: ['orchestration', 'complex-projects', 'multi-phase', 'coordination'],
|
||||
suggestedCommands: ['/plan', '/status'],
|
||||
defaultWorkflow: 'coordinator',
|
||||
}
|
||||
```
|
||||
---
|
||||
|
||||
## PART 2: EXISTING PERSONA HARDENING
|
||||
|
||||
Apply Claude Code's safety discipline to all 13 existing personas. The principle: **guidance is not a boundary.** "You specialize in research" does not prevent writing files. Explicit prohibitions do.
|
||||
|
||||
### 2A. Add Safety Blocks to Read-Only Personas
|
||||
|
||||
These personas should be structurally prevented from modifying state:
|
||||
|
||||
**Researcher** — add:
|
||||
```
|
||||
=== READ-ONLY PERSONA ===
|
||||
You are PROHIBITED from: write_file, edit_file, git_commit, generate_docx (until user explicitly requests a document).
|
||||
Your job is to FIND and SYNTHESIZE information, not to create artifacts.
|
||||
If the user wants a document from your research, suggest switching to Writer or use spawn_agent to delegate.
|
||||
```
|
||||
|
||||
**Analyst** — add:
|
||||
```
|
||||
=== ANALYSIS-ONLY PERSONA ===
|
||||
You are PROHIBITED from: write_file, edit_file, git_commit.
|
||||
You may use bash for data processing (csvkit, jq, awk) but NOT for file creation.
|
||||
You may use generate_docx ONLY when the user explicitly requests a formatted report.
|
||||
Present analysis results in chat. Let the user decide when to formalize into documents.
|
||||
```
|
||||
|
||||
### 2B. Add Documented Failure Patterns to All Personas
|
||||
|
||||
Every persona should have a "Known Failure Patterns" section. Examples:
|
||||
|
||||
**Writer:**
|
||||
```
|
||||
### Known Failure Patterns
|
||||
1. Drafting before gathering context — always search_memory and check relevant files FIRST
|
||||
2. Generic tone when workspace tone is set — check workspaceTone and adapt
|
||||
3. Generating a full document when the user said "draft" (they may want an outline first) — clarify scope
|
||||
```
|
||||
|
||||
**Sales Rep:**
|
||||
```
|
||||
### Known Failure Patterns
|
||||
1. Sending outreach copy without checking memory for prior interactions with that prospect
|
||||
2. Using generic value propositions when workspace memory contains specific product positioning
|
||||
3. Not saving prospect research to memory — next session starts from zero
|
||||
```
|
||||
|
||||
**Coder:**
|
||||
```
|
||||
### Known Failure Patterns
|
||||
1. Writing new utility functions without checking if one already exists (search_files FIRST)
|
||||
2. Making changes without reading git_log to understand recent context
|
||||
3. Large refactors when the user asked for a small fix — match scope to request
|
||||
```
|
||||
|
||||
### 2C. Add disallowedTools to AgentPersona Schema
|
||||
|
||||
Currently `AgentPersona` has only `tools[]` (allowlist). Add `disallowedTools[]` (denylist) to match Claude Code's `BaseAgentDefinition`:
|
||||
|
||||
```typescript
|
||||
export interface AgentPersona {
|
||||
// ... existing fields ...
|
||||
/** Tools explicitly denied to this persona (overrides tools[] if conflict) */
|
||||
disallowedTools?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
This enables defense-in-depth: the allowlist defines what's intended, the denylist enforces what's prohibited. If `assembleToolPool()` is implemented (from the main improvement plan), the denylist is enforced at the schema level, not just the prompt level.
|
||||
---
|
||||
|
||||
## PART 3: BEHAVIORAL SPEC IMPROVEMENTS
|
||||
|
||||
### 3A. Break the Monolith (P0)
|
||||
|
||||
Split `BEHAVIORAL_SPEC.rules` (280-line single string) into independently cacheable sections:
|
||||
|
||||
```typescript
|
||||
export const BEHAVIORAL_SPEC = {
|
||||
version: '3.0',
|
||||
|
||||
/** Core reasoning loop — stable, rarely changes */
|
||||
coreLoop: `# HOW YOU THINK — Your Core Loop
|
||||
[Steps 1-5: RECALL → ASSESS → ACT → LEARN → RESPOND]`,
|
||||
|
||||
/** Response quality rules — stable */
|
||||
qualityRules: `# RESPONSE QUALITY RULES
|
||||
[Anti-hallucination, structured output, context grounding, disclaimers]`,
|
||||
|
||||
/** Behavioral rules — stable */
|
||||
behavioralRules: `# BEHAVIORAL RULES
|
||||
[Memory-first, tool intelligence, narration heuristics, error recovery, planning]`,
|
||||
|
||||
/** High-value work patterns — semi-stable */
|
||||
workPatterns: `# HIGH-VALUE WORK PATTERNS
|
||||
[Drafting, decision compression, research in context]`,
|
||||
|
||||
/** Tool catalog — GENERATED from tool definitions, not hardcoded */
|
||||
tools: () => generateToolCatalog(),
|
||||
|
||||
/** Intelligence defaults — evolves with capabilities */
|
||||
intelligenceDefaults: `# INTELLIGENCE DEFAULTS
|
||||
[Skill check, workflow routing, sub-agent delegation, command awareness, capability discovery]`,
|
||||
};
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Each section can be cached independently by the API
|
||||
- Tool catalog is generated dynamically — stays in sync with actual tools
|
||||
- Version bumps can target specific sections without invalidating the entire prompt
|
||||
- Enables A/B testing per section
|
||||
|
||||
### 3B. Add Section Caching to buildSystemPrompt() (P0)
|
||||
|
||||
Adopt Claude Code's memoization pattern:
|
||||
|
||||
```typescript
|
||||
function cachedSection(name: string, compute: () => string): string {
|
||||
// Returns cached value if compute() hasn't changed since last call
|
||||
// Only recomputes when underlying data changes
|
||||
}
|
||||
|
||||
function uncachedSection(name: string, compute: () => string, reason: string): string {
|
||||
// Always recomputes — explicitly marked with reason
|
||||
// Example: reason = "depends on current turn context"
|
||||
}
|
||||
|
||||
buildSystemPrompt(): string {
|
||||
return [
|
||||
cachedSection('identity', () => this.identity.toContext()), // changes rarely
|
||||
cachedSection('behavioral_core', () => BEHAVIORAL_SPEC.coreLoop), // changes on version bump
|
||||
cachedSection('behavioral_quality', () => BEHAVIORAL_SPEC.qualityRules),
|
||||
cachedSection('behavioral_rules', () => BEHAVIORAL_SPEC.behavioralRules),
|
||||
cachedSection('work_patterns', () => BEHAVIORAL_SPEC.workPatterns),
|
||||
cachedSection('tools', () => BEHAVIORAL_SPEC.tools()), // changes when tools change
|
||||
cachedSection('intelligence', () => BEHAVIORAL_SPEC.intelligenceDefaults),
|
||||
uncachedSection('self_awareness', () => buildSelfAwareness(caps), 'runtime capabilities'),
|
||||
uncachedSection('recent_context', () => this.loadRecentContext(), 'per-session memory'),
|
||||
uncachedSection('persona', () => currentPersona?.systemPrompt ?? '', 'active persona'),
|
||||
uncachedSection('workspace_tone', () => toneInstruction, 'workspace setting'),
|
||||
].filter(Boolean).join('\n\n---\n\n');
|
||||
}
|
||||
```
|
||||
|
||||
At API level, stable sections form a contiguous prefix that hits prompt cache. Only uncached sections at the end vary per turn.
|
||||
### 3C. Add Context Compaction Prompt (P1)
|
||||
|
||||
Create a dedicated summarization prompt for long sessions, modeled on Claude Code's compact prompt:
|
||||
|
||||
```typescript
|
||||
export const COMPACTION_PROMPT = `
|
||||
CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
|
||||
You already have all the context you need in the conversation above.
|
||||
|
||||
Summarize the conversation into a structured brief that enables continuation without loss of essential context.
|
||||
|
||||
## Required Sections
|
||||
|
||||
1. **Primary Request** — What the user originally asked for and their intent
|
||||
2. **Key Decisions** — Decisions made during the conversation, with rationale
|
||||
3. **Work Completed** — What was actually done (files created, research found, plans made)
|
||||
4. **Current State** — Where things stand right now
|
||||
5. **Memory Saved** — What was saved to memory (so we don't re-save)
|
||||
6. **Pending Work** — What remains to be done
|
||||
7. **Critical Context** — Facts, names, numbers, file paths that must survive compaction
|
||||
8. **Suggested Next Step** — What to do when the conversation resumes
|
||||
|
||||
## Rules
|
||||
- Preserve ALL factual details: dates, numbers, names, file paths, decisions
|
||||
- Preserve the user's stated preferences and corrections
|
||||
- Compress process noise: tool call sequences, failed approaches, intermediate steps
|
||||
- The summary should enable any persona to pick up the work without asking the user to repeat themselves
|
||||
`;
|
||||
```
|
||||
|
||||
### 3D. Fix Disclaimer Contamination (P1)
|
||||
|
||||
The workspace profile is injecting domain-specific disclaimers into all responses. The fix:
|
||||
|
||||
```typescript
|
||||
// WRONG (current): workspace profile appended as behavioral instruction
|
||||
systemPrompt += workspaceProfile.disclaimer;
|
||||
|
||||
// RIGHT: workspace profile injected as CONTEXT, not as RULES
|
||||
systemPrompt += `\n\n## Workspace Context\nThis workspace is configured for: ${workspaceProfile.domain}\n`;
|
||||
// Disclaimer logic stays in BEHAVIORAL_SPEC.qualityRules (contextual, not mandatory)
|
||||
```
|
||||
|
||||
The BEHAVIORAL_SPEC already has the correct contextual disclaimer logic. The workspace profile must not override it.
|
||||
|
||||
### 3E. Elevate Memory Conflict Resolution (P2)
|
||||
|
||||
Currently buried in paragraph text. Promote to a CRITICAL rule:
|
||||
|
||||
```
|
||||
=== CRITICAL: MEMORY CONFLICT PROTOCOL ===
|
||||
When the user states a fact that CONTRADICTS a stored memory:
|
||||
1. DO NOT blindly accept the new claim
|
||||
2. Search memory to surface the conflicting record
|
||||
3. Present both: "I have a stored memory that says X. You're now saying Y. Which is correct?"
|
||||
4. Update memory ONLY after explicit confirmation
|
||||
5. When updating, save the correction with the reason: "Correction: X → Y (confirmed by user on [date])"
|
||||
|
||||
This prevents gradual memory drift where repeated assertions overwrite validated facts.
|
||||
```
|
||||
|
||||
### 3F. Add Feature Gating (P2)
|
||||
|
||||
Implement environment-based flags for progressive enhancement:
|
||||
|
||||
```typescript
|
||||
const FEATURE_FLAGS = {
|
||||
COORDINATOR_MODE: process.env.WAGGLE_COORDINATOR_MODE === '1',
|
||||
ADVANCED_WORKFLOWS: process.env.WAGGLE_ADVANCED_WORKFLOWS !== '0', // default on
|
||||
AUTO_SAVE_AGGRESSIVE: process.env.WAGGLE_AUTO_SAVE === 'aggressive',
|
||||
AUTO_CAPABILITY_SUGGEST: process.env.WAGGLE_AUTO_CAPABILITY !== '0',
|
||||
COMPACTION_ENABLED: process.env.WAGGLE_COMPACTION === '1',
|
||||
VERIFIER_AUTO_RUN: process.env.WAGGLE_AUTO_VERIFY === '1',
|
||||
};
|
||||
```
|
||||
|
||||
This enables A/B testing, gradual rollout, and per-workspace configuration.
|
||||
---
|
||||
|
||||
## PART 4: REVISED COMPARISON MATRIX (After Implementation)
|
||||
|
||||
| Dimension | Waggle (Current) | Claude Code | Waggle (After Plan) | Winner |
|
||||
|-----------|-----------------|-------------|---------------------|--------|
|
||||
| **Prompt architecture** | Monolithic | Section-cached | Section-cached + dual-mind | Waggle |
|
||||
| **Memory integration** | Dual-mind + knowledge graph | Flat files + side-query | Dual-mind + knowledge graph + side-query | Waggle |
|
||||
| **Identity persistence** | IdentityLayer | None | IdentityLayer (unchanged) | Waggle |
|
||||
| **Persona diversity** | 13 personas | 5 agents | 17 personas (+ GP, Planner, Verifier, Coordinator) | Waggle |
|
||||
| **Safety boundaries** | Guidance (soft) | Prohibition (hard) | Prohibition (hard) + denylist schema | Waggle |
|
||||
| **Verification** | None | Dedicated adversarial | Dedicated adversarial (Verifier persona) | Tie |
|
||||
| **Coordinator pattern** | Context manager | Pure delegation | Pure delegation (Coordinator persona) | Tie |
|
||||
| **Reasoning loop** | 5-step explicit | Implicit | 5-step explicit (unchanged — already better) | Waggle |
|
||||
| **Anti-hallucination** | Explicit rules + memory conflict | Baseline model | Explicit rules + CRITICAL memory conflict protocol | Waggle |
|
||||
| **Self-improvement** | ImprovementSignalStore | None | ImprovementSignalStore (unchanged) | Waggle |
|
||||
| **Context compaction** | None | 4-layer | Compaction prompt + budget tracking | Tie |
|
||||
| **Tone adaptation** | Per-workspace presets | Fixed | Per-workspace presets (unchanged) | Waggle |
|
||||
| **Cache efficiency** | Full recompute | Section memoization | Section memoization (adopted) | Tie |
|
||||
| **Tool descriptions** | Inline static | Generated dynamic | Generated dynamic (adopted) | Tie |
|
||||
| **Failure pattern docs** | None | Per-agent | Per-persona | Tie |
|
||||
| **Feature gating** | None (planned) | Environment flags | Environment flags (adopted) | Tie |
|
||||
|
||||
**Revised Score: Waggle 9, Claude Code 0, Tie 7**
|
||||
|
||||
Waggle wins or ties every dimension. Zero concessions.
|
||||
|
||||
---
|
||||
|
||||
## PART 5: IMPLEMENTATION PRIORITY
|
||||
|
||||
### Phase 1 — P0 (Week 1-2)
|
||||
|
||||
| # | Action | Impact |
|
||||
|---|--------|--------|
|
||||
| 1 | Break BEHAVIORAL_SPEC into independent sections | Enables caching, reduces per-turn cost |
|
||||
| 2 | Implement section caching in buildSystemPrompt() | 30-50% token cost reduction per turn |
|
||||
| 3 | Add General Purpose persona | Closes the "no default agent" gap |
|
||||
| 4 | Add disallowedTools[] to AgentPersona schema | Enables hard boundaries |
|
||||
|
||||
### Phase 2 — P1 (Week 3-4)
|
||||
|
||||
| # | Action | Impact |
|
||||
|---|--------|--------|
|
||||
| 5 | Add Planner persona (read-only) | Strategic planning without side effects |
|
||||
| 6 | Add Verifier persona (adversarial QA) | Quality assurance for all outputs |
|
||||
| 7 | Add Coordinator persona (delegation-only) | Enables Mission Control workflows |
|
||||
| 8 | Add safety blocks to existing read-only personas (Researcher, Analyst) | Hard boundaries on 2 personas |
|
||||
| 9 | Create compaction prompt | Enables long sessions without context loss |
|
||||
| 10 | Fix disclaimer contamination | Resolves P1-8 from test report |
|
||||
|
||||
### Phase 3 — P2 (Week 5-6)
|
||||
|
||||
| # | Action | Impact |
|
||||
|---|--------|--------|
|
||||
| 11 | Add failure pattern docs to all 17 personas | Reduces repeat mistakes |
|
||||
| 12 | Generate tool catalog dynamically from tool definitions | Keeps prompts in sync |
|
||||
| 13 | Elevate memory conflict resolution to CRITICAL rule | Prevents memory drift |
|
||||
| 14 | Implement feature gating system | Enables A/B testing |
|
||||
| 15 | Add safety blocks to remaining personas (PM, EA, Sales, etc.) | Full coverage |
|
||||
|
||||
---
|
||||
|
||||
## PART 6: FILES TO MODIFY
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `packages/agent/src/personas.ts` | Add 4 new personas, add `disallowedTools` to interface, add safety blocks to existing personas, add failure patterns |
|
||||
| `packages/agent/src/behavioral-spec.ts` | Split monolith into section object, add compaction prompt, elevate memory conflict protocol |
|
||||
| `packages/agent/src/orchestrator.ts` | Refactor `buildSystemPrompt()` to use section caching, move tool catalog to dynamic generation |
|
||||
| `packages/agent/src/custom-personas.ts` | Support `disallowedTools` field in custom persona JSON |
|
||||
| `packages/agent/src/prompt-loader.ts` | No changes needed (already clean) |
|
||||
| `packages/server/src/services/agent-service.ts` | Add feature flag system, wire compaction trigger |
|
||||
| **NEW:** `packages/agent/src/compaction-prompt.ts` | Dedicated compaction/summarization prompt |
|
||||
| **NEW:** `packages/agent/src/feature-flags.ts` | Feature gating configuration |
|
||||
|
||||
---
|
||||
|
||||
*Total: 15 actions across 3 phases. 4 new personas, safety hardening for all 17, prompt architecture refactor, compaction system, feature gating. Estimated effort: 6 weeks for full implementation.*
|
||||
|
||||
*This plan should be executed alongside the main improvement plan (`waggle-os-improvement-plan.md`) — the two are complementary. This plan covers prompts and personas; the main plan covers subsystems and infrastructure.*
|
||||
Reference in New Issue
Block a user