mirror of
https://github.com/instructkr/claw-code.git
synced 2026-10-14 00:00:19 +08:00
Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Bellman
|
089abe753b | ||
 clawdbot
|
e54d832dfc |
@@ -0,0 +1,799 @@
|
||||
# GJC Compatibility Gap Matrix
|
||||
|
||||
**Document Status**: Phase 1 Analysis (2026-10-13)
|
||||
**Scope**: SDK wire protocol, session lifecycle, tools, skills, settings, hooks, commands, and AGENTS.md rules
|
||||
**Target**: Rust fork-in-spirit of gajae-code (GJC) SDK-compatible and capability-compatible
|
||||
|
||||
---
|
||||
|
||||
## 1. EXECUTIVE SUMMARY
|
||||
|
||||
This matrix maps GJC capabilities (from gajae-code) against claw-code's current Rust implementation, identifying gaps and proposing crate/module ownership for each slice.
|
||||
|
||||
### Key Findings
|
||||
|
||||
| Area | Status | Priority |
|
||||
|------|--------|----------|
|
||||
| **SDK Wire Protocol** | Missing | P0 (Foundation) |
|
||||
| **Session Lifecycle** | Partial (no SDK) | P0 (Foundation) |
|
||||
| **Tool Catalog (55 tools)** | Partial (35/55) | P1 (Core) |
|
||||
| **Skill Discovery** | Partial (basic) | P1 (Core) |
|
||||
| **Settings & Config** | Partial | P2 (Enhancing) |
|
||||
| **Hooks & Plugins** | Existing | P3 (Polish) |
|
||||
| **AGENTS.md Rules** | Existing | P3 (Polish) |
|
||||
| **Slash Commands (120+)** | Partial (40/120+) | P2 (Core) |
|
||||
| **Subagent Delegation** | Existing | P2 (Core) |
|
||||
|
||||
---
|
||||
|
||||
## 2. SDK WIRE PROTOCOL
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/sdk/client/client.ts`, `sdk/host/session-runtime.ts`
|
||||
|
||||
GJC uses a **WebSocket-based JSON-RPC-like protocol** with:
|
||||
- **Transport**: WebSocket over TCP
|
||||
- **Frame Format**: JSON object with typed fields
|
||||
- **Correlation**: Request/response matched by `frame.id` (UUID)
|
||||
- **Operations**: 65+ operation types (Q1-Q32, C01-C06, reverse ops)
|
||||
- **Error Handling**: Typed `SdkErrorCode` with `uncertain_after_send` recovery
|
||||
- **Reconnect**: Exponential backoff with deadline management
|
||||
- **Request Timeout**: 10s default (`DEFAULT_SDK_REQUEST_TIMEOUT_MS`), per-request override
|
||||
- **Handshake**: `client.hello` with capabilities advertised; `server.hello` response
|
||||
|
||||
**Operations** (sample):
|
||||
- **Control**: `turn.create`, `turn.prompt`, `turn.steer`, `turn.abort_and_prompt`
|
||||
- **Queries**: `turn.list`, `turn.get_one`, `turn.message_list`, `skill.source`, `artifact.content`
|
||||
- **Reverse**: `ask.answer`, `tool.dispatch`, `tool.fetch_capability`
|
||||
|
||||
**Event Schema**:
|
||||
```json
|
||||
{
|
||||
"id": "uuid-string",
|
||||
"operation": "turn.create",
|
||||
"input": { ... },
|
||||
"connectionId": "optional",
|
||||
"settings": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Missing entirely. claw-code has no SDK wire protocol or external session API.
|
||||
|
||||
**Files**: None
|
||||
**Lines**: 0
|
||||
|
||||
**Reality**:
|
||||
- claw-code operates as a local CLI only (stdin/stdout/stderr).
|
||||
- Sessions are file-based (`.claw/sessions/`).
|
||||
- No remote access or external SDK clients.
|
||||
- No WebSocket transport.
|
||||
- No frame correlation or reconnect logic.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| WebSocket Transport | 1500 LOC | — | 100% | High |
|
||||
| Frame Correlation | 800 LOC | — | 100% | Medium |
|
||||
| Operation Registry | 400 LOC | 0 | 100% | Medium |
|
||||
| Error Handling & Recovery | 600 LOC | — | 100% | High |
|
||||
| Handshake & Negotiation | 200 LOC | — | 100% | Low |
|
||||
| **Total** | **3,500 LOC** | **0** | **3,500 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `sdk` (new)
|
||||
|
||||
**Module Structure**:
|
||||
```
|
||||
rust/crates/sdk/
|
||||
├── Cargo.toml
|
||||
└── src/
|
||||
├── lib.rs (exports + top-level API)
|
||||
├── client/
|
||||
│ ├── mod.rs (SdkClient, WebSocket transport)
|
||||
│ ├── correlation.rs (frame ID tracking, reconnect)
|
||||
│ └── errors.rs (SdkErrorCode, recovery)
|
||||
├── protocol/
|
||||
│ ├── mod.rs (Operation registry)
|
||||
│ ├── operations.rs (operation definitions)
|
||||
│ └── schema.rs (JSON schemas, frame validation)
|
||||
├── session/
|
||||
│ ├── mod.rs (session lifecycle over SDK)
|
||||
│ ├── router.rs (session routing, durable state)
|
||||
│ └── reconciliation.rs (uncertain outcome recovery)
|
||||
└── tests/
|
||||
├── mod.rs
|
||||
└── fixtures/ (mock server scenarios)
|
||||
```
|
||||
|
||||
**Size Estimate**: 4,500 LOC (Rust + test fixtures)
|
||||
|
||||
**Dependencies**:
|
||||
- `tokio` (async I/O, WebSocket)
|
||||
- `tungstenite` (WebSocket protocol)
|
||||
- `serde_json` (frame serialization)
|
||||
- `uuid` (correlation IDs)
|
||||
- `runtime` crate (session persistence bridge)
|
||||
|
||||
---
|
||||
|
||||
## 3. SESSION LIFECYCLE
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/sdk/host/session-runtime.ts`, `sdk/client/`, `sdk/lifecycle/`
|
||||
|
||||
GJC sessions have **three entry points**:
|
||||
1. **Native SDK** (via WebSocket): typed `SdkClient` with `session.create`, `session.prompt`, etc.
|
||||
2. **Browser ACP** (via iframe): same protocol, browser sandbox isolate
|
||||
3. **CLI Daemon** (stdio): JSON-RPC over stdio for local CLI access
|
||||
|
||||
**Session Operations**:
|
||||
- **create**: `turn.create(model, input)` → returns `sessionId`, persistent state written to broker DB
|
||||
- **prompt**: `turn.prompt(request, tools, settings)` → streams events: `agent_begin`, `tool_use`, `tool_result`, `agent_end`
|
||||
- **steer**: `turn.steer(overrides)` → mid-flight direction change (model, settings, system prompt)
|
||||
- **abort**: `turn.abort_and_prompt()` → terminal failure + new prompt in one operation
|
||||
- **list**: `turn.list(filters)` → paginated session history
|
||||
- **get_one**: `turn.get_one(sessionId, turnId)` → single turn with full details
|
||||
|
||||
**State Persistence**:
|
||||
- Invocation record (prompt request, outcome, correlation)
|
||||
- Message buffer (system, assistant, tool results, agent events)
|
||||
- Reconciliation store (uncertain → durable mapping)
|
||||
- Terminal scope (last session per correlation key)
|
||||
|
||||
**Lifecycle Events**:
|
||||
1. `turn_accepted` (immediate, transient)
|
||||
2. `agent_begin` (before first model call)
|
||||
3. `tool_use` + `tool_result` (interleaved)
|
||||
4. `agent_end` (final model output)
|
||||
5. `turn_ended` (durable, terminal outcome recorded)
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. Local session lifecycle exists but no SDK transport or remote access.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/session.rs` (1,961 LOC)
|
||||
- `rust/crates/runtime/src/conversation.rs` (1,878 LOC)
|
||||
- `rust/crates/runtime/src/session_control.rs` (file ops, migration)
|
||||
- `rust/crates/runtime/src/lib.rs` (re-exports `Session`, `SessionStore`, `ConversationRuntime`)
|
||||
|
||||
**Lines**: ~3,900 LOC (session + conversation)
|
||||
|
||||
**Reality**:
|
||||
- `Session` struct holds in-memory state (messages, usage, context).
|
||||
- `SessionStore` reads/writes `.claw/sessions/{id}/` directory.
|
||||
- `ConversationRuntime` drives the local agent loop (sync).
|
||||
- No WebSocket or remote access.
|
||||
- No invocation reconciliation or uncertain outcome recovery.
|
||||
- No terminal scope tracking (per-session-per-correlation).
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Remote Session Router | 2,500 LOC | — | 100% | High |
|
||||
| Invocation Reconciliation | 1,200 LOC | — | 100% | High |
|
||||
| Terminal Scope Tracking | 600 LOC | — | 100% | Medium |
|
||||
| Async Event Streaming | 800 LOC | Partial | 60% | Medium |
|
||||
| Uncertain Outcome Recovery | 1,000 LOC | — | 100% | High |
|
||||
| **Total** | **6,100 LOC** | **3,900** | **2,200 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `sdk` (new, or extend `runtime`)
|
||||
|
||||
**Module Structure** (add to `sdk/session/`):
|
||||
```
|
||||
sdk/session/
|
||||
├── router.rs (session routing, durable lookup)
|
||||
├── reconciliation.rs (uncertain → terminal recovery)
|
||||
├── terminal_scope.rs (per-correlation state retention)
|
||||
└── events.rs (event publishing, reconciliation)
|
||||
```
|
||||
|
||||
**Integration Points**:
|
||||
- Bridge `runtime::Session` into `sdk::Session` wrapper
|
||||
- Add `runtime::SessionStore` extensions for reconciliation data
|
||||
- Extend `ConversationRuntime` with event emission
|
||||
|
||||
**Size Estimate**: 2,500 LOC (Rust, new + modifications)
|
||||
|
||||
---
|
||||
|
||||
## 4. TOOL CATALOG (55 Tools)
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/` (55 tool files + shared harness)
|
||||
|
||||
GJC implements **55 distinct tools** across multiple domains:
|
||||
- **File I/O**: `read`, `write`, `edit`, `search`, `find`
|
||||
- **Shell**: `bash`, `sleep`
|
||||
- **Task Delegation**: `task` (subagent spawning)
|
||||
- **Workflow**: `skill`, `skill_discovery`, `goal`, `ask`
|
||||
- **Search**: `search_tool_bm25` (semantic search discovery)
|
||||
- **Image**: `image_gen` (DALL-E), `image_tag_scan`
|
||||
- **Integration**: `web_fetch`, `web_search`, `custom_tool_fetch`
|
||||
- **Developer**: `notebook_edit`, `command_repl`, `shell_repl`, `powershell`
|
||||
- **Config**: `config_read`, `config_write` (settings, modes)
|
||||
- **Structured**: `model_registry`, `cost_calculator`, `settings_apply`
|
||||
- **Workflow Gates**: `workflow_gate_answer`, `workflow_plan_approve`
|
||||
- **Move**: `move_cwd`, `move_session`
|
||||
|
||||
**Tool Execution Model**:
|
||||
1. Input deserialized from JSON schema
|
||||
2. Permission check (read-only vs. destructive)
|
||||
3. Tool invocation with typed inputs
|
||||
4. Structured output or error
|
||||
5. Result published to agent loop
|
||||
|
||||
**Permission Gating**: Every tool has a `required_permission` (read-only, approve, unsafe).
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. 35 tools implemented, 20 missing or incomplete.
|
||||
|
||||
**Files**: `rust/crates/tools/src/lib.rs` (10,892 LOC, single file with all 55 spec + implementations)
|
||||
|
||||
**Implemented Tools** (~35):
|
||||
- `read`, `write`, `edit`, `search`, `find`
|
||||
- `bash`, `sleep`
|
||||
- `task` (subagent spawning)
|
||||
- `skill`, `skill_discovery` (basic)
|
||||
- `bash_list_*, bash_check_*` (validation helpers)
|
||||
- `web_fetch`, `search_bm25` (basic)
|
||||
- `config_*` (read/write settings)
|
||||
- `notebooks` (edit, execute)
|
||||
- `goal` (basic ledger)
|
||||
- `move_*` (cwd, session)
|
||||
- Various validation and utility tools
|
||||
|
||||
**Missing / Incomplete Tools** (~20):
|
||||
- `image_gen` (DALL-E)
|
||||
- `image_tag_scan`
|
||||
- `custom_tool_fetch`
|
||||
- `command_repl`, `shell_repl`, `powershell`
|
||||
- `model_registry`, `cost_calculator`
|
||||
- `workflow_gate_answer`, `workflow_plan_approve`
|
||||
- `ask` (interactive prompt)
|
||||
- `irc` (live coordination)
|
||||
- Search/discovery integration tools
|
||||
- Advanced structured output handling
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Tool Registry | 400 LOC | 400 LOC | 0% | — |
|
||||
| Spec Table (55 entries) | 1,800 LOC | 1,800 LOC | 0% | — |
|
||||
| image_gen | 600 LOC | — | 100% | High |
|
||||
| command_repl, shell_repl | 900 LOC | — | 100% | Medium |
|
||||
| workflow_gate_* | 800 LOC | — | 100% | Medium |
|
||||
| custom_tool_fetch | 400 LOC | — | 100% | Low |
|
||||
| ask (interactive) | 1,200 LOC | Stub | 80% | High |
|
||||
| cost_calculator | 300 LOC | — | 100% | Low |
|
||||
| **Total** | **11,500 LOC** | **8,000** | **3,500 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `tools` (expand existing)
|
||||
|
||||
**New Modules**:
|
||||
```
|
||||
rust/crates/tools/src/
|
||||
├── tools/
|
||||
│ ├── image_gen.rs (DALL-E integration)
|
||||
│ ├── ask_interactive.rs (blocking user prompts)
|
||||
│ ├── workflow_gates.rs (plan approval, gate answer)
|
||||
│ ├── repl/*.rs (command_repl, shell_repl, powershell)
|
||||
│ └── cost_calc.rs (pricing lookup)
|
||||
└── vendors/
|
||||
├── dalle.rs (image generation API)
|
||||
└── integrations.rs (custom tool fetch)
|
||||
```
|
||||
|
||||
**Size Estimate**: 3,500 LOC (new tools + vendor integration)
|
||||
|
||||
**Dependencies**:
|
||||
- `reqwest` (image generation API calls)
|
||||
- `api` crate (provider client reuse)
|
||||
- Existing: `runtime`, `commands`, `serde_json`
|
||||
|
||||
---
|
||||
|
||||
## 5. SKILL DISCOVERY & INVOCATION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/skill-discovery.ts`, `packages/coding-agent/src/tools/skill.ts`, `packages/coding-agent/src/sdk-skills/`
|
||||
|
||||
GJC supports **dynamic skill loading** with:
|
||||
- **Discovery**: `skill_discovery` tool scans `.gjc/skills/`, project `.gjc/skills/`, bundled skills
|
||||
- **Frontmatter Parsing**: YAML headers in `SKILL.md` define metadata (name, description, use conditions)
|
||||
- **Invocation**: `skill` tool loads and executes a named skill (skill name + args)
|
||||
- **Skill Execution**: Skill = subprocess call to `gjc /skill:<name>` with args
|
||||
- **Bundled Skills**: `autoresearch`, `deep-interview`, `ralplan`, `ultragoal`
|
||||
- **Project Skills**: Discoverable from `.gjc/skills/*/SKILL.md`
|
||||
- **User Skills**: Discoverable from `~/.gjc/skills/*/SKILL.md`
|
||||
|
||||
**Skill Metadata**:
|
||||
```yaml
|
||||
# /skill:my-skill
|
||||
# description: What this skill does
|
||||
# scope: project | user | bundled
|
||||
# requires: List of capabilities
|
||||
```
|
||||
|
||||
**Skill Discovery Result**:
|
||||
```json
|
||||
{
|
||||
"name": "skill-name",
|
||||
"description": "...",
|
||||
"path": "...",
|
||||
"bundled": true | false,
|
||||
"scope": "project" | "user" | "bundled"
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Basic. Skill discovery exists but limited to filesystem scanning.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/tools/src/lib.rs` (skill_discovery + skill dispatch, ~200 LOC)
|
||||
- `rust/crates/runtime/src/prompt.rs` (skill loading in prompts, ~100 LOC)
|
||||
|
||||
**Implementation**:
|
||||
- Scans `.claw/skills/` directory for `SKILL.md` files
|
||||
- Parses frontmatter (basic YAML)
|
||||
- Returns discovery results as JSON
|
||||
- `skill` tool invokes skill as subprocess
|
||||
|
||||
**Missing**:
|
||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
||||
- Project + user skill discovery hierarchy
|
||||
- Frontmatter validation and standardization
|
||||
- Skill chaining (`skill()` tool to invoke another skill from within a skill)
|
||||
- Skill state persistence (workflow handoff)
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Bundled Skill Registry | 200 LOC | — | 100% | Low |
|
||||
| Frontmatter Parser | 150 LOC | 100 LOC | 30% | Low |
|
||||
| Project + User Discovery | 300 LOC | Basic | 70% | Low |
|
||||
| Skill Chaining | 250 LOC | — | 100% | Medium |
|
||||
| Workflow State Handoff | 400 LOC | — | 100% | Medium |
|
||||
| Skill Execution Harness | 200 LOC | Partial | 40% | Low |
|
||||
| **Total** | **1,500 LOC** | **100** | **1,400 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `tools` (expand existing) or `skills` (new, lightweight)
|
||||
|
||||
**Module Structure**:
|
||||
```
|
||||
rust/crates/tools/src/
|
||||
├── skill_discovery.rs (enhanced parsing, project/user/bundled hierarchy)
|
||||
├── skill_execution.rs (subprocess dispatch, state handoff)
|
||||
├── bundled_skills.rs (registry of autoresearch, deep-interview, ralplan, ultragoal)
|
||||
└── skill_state.rs (workflow handoff serialization)
|
||||
```
|
||||
|
||||
**Size Estimate**: 1,400 LOC (Rust)
|
||||
|
||||
**Integration**:
|
||||
- Extend `skill_discovery` tool to search three scopes (bundled, project, user)
|
||||
- Add `skill` tool support for chaining (returning another skill invocation)
|
||||
- Store workflow state in durable files for handoff
|
||||
|
||||
---
|
||||
|
||||
## 6. SETTINGS & CONFIGURATION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/config.ts`, `packages/coding-agent/src/sdk/host/session-runtime.ts`
|
||||
|
||||
GJC supports **settings override** at multiple levels:
|
||||
1. **Global Settings**: `~/.gjc/config.json` (user defaults)
|
||||
2. **Session Settings**: per-session override via `turn.create` or `turn.prompt` input
|
||||
3. **Runtime Override**: `settings` field in SDK request frames
|
||||
4. **Setting Categories**:
|
||||
- **Model**: `modelName`, `modelTemperature`, `modelMaxTokens`
|
||||
- **Behavior**: `allowance`, `permissions.*`, `features.*`
|
||||
- **UX**: `theme`, `shell`, `notification*`
|
||||
- **Advanced**: `memory.context`, `memory.compression`, `cost.*`
|
||||
|
||||
**Config Schema**: Typed with JSON schema validation per setting
|
||||
|
||||
**Permission Modes**:
|
||||
- `read_only` (no execution)
|
||||
- `approve` (interactive approval)
|
||||
- `unsafe` (no gates)
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. Config exists but no session-level override or setting propagation.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/config.rs` (3,894 LOC, largest file in runtime)
|
||||
- `rust/crates/runtime/src/config_validate.rs` (validation helpers)
|
||||
|
||||
**Implementation**:
|
||||
- Reads `.claw/config.json` at startup
|
||||
- Stores global settings (model, permissions, plugins, features)
|
||||
- No session-level override
|
||||
- No setting propagation through tool execution
|
||||
- No typed setting validation against schema
|
||||
|
||||
**Missing**:
|
||||
- Per-session setting override (session-specific model, permissions)
|
||||
- Setting propagation to all tool invocations
|
||||
- Dynamic setting application (e.g., changing model mid-session)
|
||||
- Setting schema validation
|
||||
- Config hotreload (changes without restart)
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Setting Schema Definition | 300 LOC | — | 100% | Low |
|
||||
| Session-Level Override | 400 LOC | — | 100% | Medium |
|
||||
| Setting Propagation | 300 LOC | — | 100% | Low |
|
||||
| Dynamic Application | 200 LOC | — | 100% | Medium |
|
||||
| Config Hotreload | 150 LOC | — | 100% | Low |
|
||||
| **Total** | **1,350 LOC** | **3,894** | **-2,544 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `runtime` (enhance existing `config.rs`)
|
||||
|
||||
**Additions to config.rs**:
|
||||
- Setting schema registry
|
||||
- Session setting override struct
|
||||
- Setting applicator (merge global + session + override)
|
||||
- Hotreload support (watch config file, signal on change)
|
||||
|
||||
**Size Estimate**: 500 LOC (new code, mostly schema + applicators)
|
||||
|
||||
---
|
||||
|
||||
## 7. HOOKS & PLUGINS
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/hooks.ts`, `packages/coding-agent/src/plugin_lifecycle.ts`
|
||||
|
||||
GJC provides **5 hook points**:
|
||||
- `on_session_created`: After session starts
|
||||
- `on_prompt_received`: Before agent loop begins
|
||||
- `on_tool_use`: Before tool invocation
|
||||
- `on_tool_result`: After tool completes
|
||||
- `on_session_ended`: Before session cleanup
|
||||
|
||||
**Plugin System**:
|
||||
- Plugins are shell scripts or binaries in `.claw/plugins/`
|
||||
- Each plugin implements hook handlers (exit code + JSON output)
|
||||
- Plugin registry stored in config
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and comprehensive.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/hooks.rs` (L155)
|
||||
- `rust/crates/runtime/src/plugin_lifecycle.rs`
|
||||
- `rust/crates/plugins/src/` (plugin manager)
|
||||
|
||||
**Implementation**: Hooks fully implemented; plugin system working.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Hook Points | 5 | 5 | 0% |
|
||||
| Plugin Registry | ✓ | ✓ | 0% |
|
||||
| Plugin Execution | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No gaps**. Hooks and plugins are fully compatible.
|
||||
|
||||
---
|
||||
|
||||
## 8. AGENTS.MD RULES & CONTEXT
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: gajae-code root + `docs/` (AGENTS.md files at multiple levels)
|
||||
|
||||
GJC loads **directory-specific rules** from `AGENTS.md` files:
|
||||
- **Root AGENTS.md**: Project-level knowledge base
|
||||
- **Directory AGENTS.md**: Directory-specific rules override parent
|
||||
- **Rules Loaded**: Automatically prepended to system prompt during agent reasoning
|
||||
- **Hierarchy**: Deepest (most specific) rules override higher level
|
||||
|
||||
**Rule Content**:
|
||||
- Code organization and conventions
|
||||
- Tool restrictions (never use X in Y context)
|
||||
- Testing requirements
|
||||
- Deployment/safety gates
|
||||
- Architecture decisions
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and matching GJC.
|
||||
|
||||
**Files**:
|
||||
- Root: `AGENTS.md`
|
||||
- Crate-level: `rust/crates/*/AGENTS.md`
|
||||
- Implementation: `rust/crates/runtime/src/` (loads rules)
|
||||
|
||||
**Implementation**: Rules loaded and applied to prompts.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Rule Loading | ✓ | ✓ | 0% |
|
||||
| Hierarchy | ✓ | ✓ | 0% |
|
||||
| Prompt Integration | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No gaps**. AGENTS.md system is compatible.
|
||||
|
||||
---
|
||||
|
||||
## 9. SLASH COMMANDS (120+ Commands)
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/commands/lib.ts` (7,200 LOC with 120+ command specs)
|
||||
|
||||
GJC implements **120+ slash commands** for REPL interaction:
|
||||
- **Session**: `/session list`, `/session create`, `/session restore`, `/session delete`
|
||||
- **Model**: `/model set`, `/model list`, `/model info`
|
||||
- **Permissions**: `/permissions set`, `/permissions show`
|
||||
- **Config**: `/config get`, `/config set`, `/config reload`
|
||||
- **Skills**: `/skills list`, `/skills install`, `/skills create`
|
||||
- **Plugins**: `/plugins list`, `/plugins install`
|
||||
- **Workflow**: `/plan`, `/review`, `/approve`, `/ultragoal`
|
||||
- **Debugging**: `/debug`, `/dump`, `/trace`
|
||||
- **Utilities**: `/help`, `/clear`, `/quit`, `/export`
|
||||
|
||||
**Command Format**: `/command [arg1] [arg2] ...` with arg parsing per command
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. ~40 commands implemented out of 120+.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/commands/src/lib.rs` (7,183 LOC)
|
||||
- Command specs in `SLASH_COMMAND_SPECS` static table
|
||||
|
||||
**Implemented Commands** (~40):
|
||||
- Session mgmt (list, create, etc.)
|
||||
- Help, status, version
|
||||
- Config (get, set, reload)
|
||||
- Skills (list, install)
|
||||
- Plugins (list, install)
|
||||
- Workspace/debug (clear, compact, etc.)
|
||||
|
||||
**Missing Commands** (~80):
|
||||
- Advanced workflow (`/plan`, `/review`, `/ultragoal`)
|
||||
- Model selection and info
|
||||
- Cost calculator (`/cost`)
|
||||
- Advanced debugging (`/dump`, `/trace`)
|
||||
- Theme management
|
||||
- Advanced permission controls
|
||||
- Task management (`/tasks list`, `/tasks cancel`)
|
||||
- IRC/coordination (`/irc`)
|
||||
- Many others
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Command Parser | 800 LOC | 800 LOC | 0% |
|
||||
| Spec Table (120+ entries) | 2,000 LOC | 2,000 LOC | 0% |
|
||||
| Handlers (80 missing) | 3,200 LOC | 1,800 LOC | 56% |
|
||||
| Help/suggestion | 600 LOC | 400 LOC | 30% |
|
||||
| **Total** | **7,200 LOC** | **4,000** | **3,200 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `commands` (expand existing)
|
||||
|
||||
**New Modules**:
|
||||
```
|
||||
rust/crates/commands/src/
|
||||
├── handlers/
|
||||
│ ├── workflow.rs (/plan, /review, /approve, /ultragoal)
|
||||
│ ├── model.rs (/model set, /model list, /model info)
|
||||
│ ├── cost.rs (/cost)
|
||||
│ ├── advanced_debug.rs (/dump, /trace, /debug advanced)
|
||||
│ ├── theme.rs (/theme set, /theme list)
|
||||
│ ├── task.rs (/tasks list, /tasks cancel)
|
||||
│ └── advanced_perms.rs (advanced permission commands)
|
||||
```
|
||||
|
||||
**Size Estimate**: 3,200 LOC (new command handlers)
|
||||
|
||||
**Dependencies**: `runtime`, `tools`, `plugins`
|
||||
|
||||
---
|
||||
|
||||
## 10. SUBAGENT DELEGATION & TASK EXECUTION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/task.ts`, `packages/coding-agent/src/task/`
|
||||
|
||||
GJC's **subagent system** enables parallel task execution:
|
||||
- **task Tool**: Spawn parallel subtasks with independent context
|
||||
- **Task States**: spawning, running, succeeded, failed
|
||||
- **Task Isolation**: Each task has isolated session, permissions, context
|
||||
- **Task Coordination**: `irc` tool for live inter-task communication
|
||||
- **Task Monitoring**: `task.inspect`, `task.list`, `task.cancel`
|
||||
- **Artifact Sharing**: Tasks share artifact URLs but not direct state
|
||||
|
||||
**Task Spawning**:
|
||||
```json
|
||||
{
|
||||
"agent": "executor|architect|planner",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "task-1",
|
||||
"description": "...",
|
||||
"assignment": "..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and working.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/tools/src/lib.rs` (task tool, ~300 LOC)
|
||||
- `rust/crates/runtime/src/task_*.rs` (task execution, state mgmt)
|
||||
|
||||
**Implementation**: Task tool works; spawning, monitoring, and coordination functional.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Task Spawning | ✓ | ✓ | 0% |
|
||||
| Task Isolation | ✓ | ✓ | 0% |
|
||||
| Task Monitoring | ✓ | ✓ | 0% |
|
||||
| IRC Coordination | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No significant gaps**. Task execution is compatible.
|
||||
|
||||
---
|
||||
|
||||
## 11. IMPLEMENTATION ROADMAP
|
||||
|
||||
### Phase 1: Foundation (SDK Wire Protocol)
|
||||
|
||||
**Slice 1.1: WebSocket Transport & Frame Correlation**
|
||||
- Create `sdk` crate structure
|
||||
- Implement `SdkClient` with WebSocket connection
|
||||
- Add frame ID correlation and response matching
|
||||
- Add reconnect logic with exponential backoff
|
||||
- Tests: transport connectivity, frame correlation, reconnect behavior
|
||||
|
||||
**Slice 1.2: Operation Registry & Schema**
|
||||
- Define Operation enum (65+ operation types)
|
||||
- JSON schema validation for requests
|
||||
- Error code definitions and handlers
|
||||
- Uncertain outcome recovery protocol
|
||||
- Tests: operation parsing, schema validation, error scenarios
|
||||
|
||||
**Slice 1.3: Session SDK Integration**
|
||||
- Bridge `runtime::Session` to SDK session model
|
||||
- Implement session router (durable lookup)
|
||||
- Add invocation reconciliation store
|
||||
- Terminal scope tracking per correlation
|
||||
- Tests: session creation, routing, reconciliation
|
||||
|
||||
### Phase 2: Core Capabilities (Tools & Skills)
|
||||
|
||||
**Slice 2.1: Missing Tool Implementation**
|
||||
- `image_gen` (DALL-E integration)
|
||||
- `ask` (interactive blocking prompts)
|
||||
- `workflow_gate_*` (plan approval gates)
|
||||
- `command_repl`, `shell_repl`, `powershell`
|
||||
- `cost_calculator`
|
||||
|
||||
**Slice 2.2: Skill Enhancement**
|
||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
||||
- Enhanced skill discovery (project, user, bundled hierarchy)
|
||||
- Skill chaining support (skill calling skill)
|
||||
- Workflow state handoff
|
||||
|
||||
### Phase 3: Polish (Settings, Commands, Integration)
|
||||
|
||||
**Slice 3.1: Settings & Configuration**
|
||||
- Session-level setting override
|
||||
- Setting schema validation
|
||||
- Setting propagation to tools
|
||||
- Config hotreload
|
||||
|
||||
**Slice 3.2: Slash Commands**
|
||||
- Workflow commands (/plan, /review, /ultragoal)
|
||||
- Model selection (/model set, /model list)
|
||||
- Cost calculator (/cost)
|
||||
- Advanced debugging (/dump, /trace)
|
||||
- Task management (/tasks list, /tasks cancel)
|
||||
- Theme management (/theme)
|
||||
|
||||
---
|
||||
|
||||
## 12. DEPENDENCY & CRATE RELATIONSHIPS
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ cli (rusty-claude-cli: main entry, REPL, TUI) │
|
||||
└────────────┬───────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼──────────────────────────────────────────┐
|
||||
│ commands (slash command specs & handlers) │
|
||||
└────────┬────────────────────────────────────────┬──────┘
|
||||
│ │
|
||||
│ ┌───▼────────────────────┐
|
||||
│ │ tools (55 tool impl) │
|
||||
│ └──────┬─────────────────┘
|
||||
│ │
|
||||
┌────────▼─────────────────────────────────────────▼──────────────────┐
|
||||
│ runtime (session, conversation, config, mcp, hooks, permissions) │
|
||||
└────────┬──────────────────────────────┬────────────────────────────┘
|
||||
│ │
|
||||
┌────▼──────────────┐ ┌──────▼─────────────────┐
|
||||
│ api (providers) │ │ plugins (plugin mgmt) │
|
||||
└───────────────────┘ └───────────────────────┘
|
||||
|
||||
NEW: sdk (WebSocket, session routing, reconciliation)
|
||||
│
|
||||
└─→ depends on: runtime, serde_json, tokio, tungstenite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. RISK & MITIGATION
|
||||
|
||||
| Risk | Probability | Severity | Mitigation |
|
||||
|------|-------------|----------|-----------|
|
||||
| SDK protocol complexity | High | High | Start with mock transport tests, iterate on real scenarios |
|
||||
| Session state inconsistency | Medium | High | Comprehensive reconciliation tests, durable state verification |
|
||||
| Tool compatibility gaps | Medium | Medium | Tool-by-tool comparison with GJC, shadow testing |
|
||||
| Breaking changes to runtime | Medium | High | Version gates, feature flags, phased rollout |
|
||||
| Performance regression | Medium | Medium | Benchmark key paths (session create, tool dispatch), profile |
|
||||
|
||||
---
|
||||
|
||||
## 14. VERIFICATION & SIGN-OFF
|
||||
|
||||
- [ ] SDK transport connects and communicates with mock server
|
||||
- [ ] Session lifecycle operations (create, prompt, steer, abort) work end-to-end
|
||||
- [ ] Tool execution with SDK matches GJC behavior
|
||||
- [ ] Skill discovery finds all three scopes (bundled, project, user)
|
||||
- [ ] Settings override works per-session
|
||||
- [ ] Slash commands parse and dispatch correctly
|
||||
- [ ] All AGENTS.md tests pass
|
||||
- [ ] Hooks fire at correct lifecycle points
|
||||
- [ ] Subagent tasks spawn and communicate via IRC
|
||||
- [ ] Public documentation has no internal paths, hosts, or private infra
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: 2026-10-13
|
||||
**Next Review**: After Slice 1.1 implementation complete
|
||||
Reference in New Issue
Block a user