myclaude/docs/architecture.md

System Architecture

Overview

Multi-agent AI development system with Claude Code as orchestrator and pluggable execution backends.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User                                 │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   │ /dev, /gh-implement, etc.
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                   Claude Code (Orchestrator)                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ - Planning & context gathering                          ││
│  │ - Requirements clarification                            ││
│  │ - Task breakdown                                        ││
│  │ - Verification & reporting                              ││
│  └─────────────────────────────────────────────────────────┘│
└──────────────────┬──────────────────────────────────────────┘
                   │
                   │ via codeagent-wrapper
                   ▼
┌─────────────────────────────────────────────────────────────┐
│              Codeagent-Wrapper (Execution Layer)             │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Backend Interface                                        │
│  ├──────────────┬──────────────┬──────────────┐            │
│  │ Codex        │ Claude       │ Gemini       │            │
│  │ Backend      │ Backend      │ Backend      │            │
│  └──────────────┴──────────────┴──────────────┘            │
│                                                              │
│  ┌──────────────────────────────────────────────────────────┤
│  │ Features:                                                │
│  │ - Multi-backend execution                                │
│  │ - JSON stream parsing                                    │
│  │ - Session management                                     │
│  │ - Parallel task execution                                │
│  │ - Timeout handling                                       │
│  └──────────────────────────────────────────────────────────┘
└──────────────────┬──────────────────────────────────────────┘
                   │
                   │ CLI invocations
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                    AI CLI Backends                           │
│  ┌──────────────┬──────────────┬──────────────┐            │
│  │ Codex CLI    │ Claude CLI   │ Gemini CLI   │            │
│  │              │              │              │            │
│  │ Code editing │ Reasoning    │ Fast proto   │            │
│  └──────────────┴──────────────┴──────────────┘            │
└─────────────────────────────────────────────────────────────┘

Component Architecture

1. Orchestrator Layer (Claude Code)

Responsibilities:

• User interaction and requirements gathering
• Context analysis and exploration
• Task planning and breakdown
• Workflow coordination
• Verification and reporting

Key Workflows:

/dev
├── Requirements clarification (AskUserQuestion)
├── Codex analysis (Task tool → Explore agent)
├── Dev plan generation (Task tool → dev-plan-generator)
├── Parallel execution (codeagent-wrapper --parallel)
├── Coverage validation (≥90%)
└── Completion summary

/gh-implement <issue>
├── Issue analysis (gh issue view)
├── Clarification (if needed)
├── Development (codeagent-wrapper or /dev)
├── Progress updates (gh issue comment)
└── PR creation (gh pr create)

2. Execution Layer (Codeagent-Wrapper)

Architecture:

┌─────────────────────────────────────────────────────────┐
│                    Main Entry Point                      │
│  - Parse CLI arguments                                   │
│  - Detect mode (new/resume/parallel)                     │
│  - Select backend                                        │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   Backend Selection                       │
│  func SelectBackend(name string) Backend                 │
│  ┌──────────────┬──────────────┬──────────────┐         │
│  │ CodexBackend │ ClaudeBackend│ GeminiBackend│         │
│  └──────────────┴──────────────┴──────────────┘         │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   Executor                                │
│  func RunCodexTask(cfg *Config) (string, error)          │
│  ┌──────────────────────────────────────────────────────┤
│  │ 1. Build command args via Backend.BuildArgs()        │
│  │ 2. Start process with timeout                        │
│  │ 3. Stream stdout/stderr                              │
│  │ 4. Parse JSON stream via ParseJSONStream()           │
│  │ 5. Extract session ID                                │
│  │ 6. Handle signals (SIGINT, SIGTERM)                  │
│  └──────────────────────────────────────────────────────┘
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   Parser                                  │
│  func ParseJSONStream(r io.Reader) (string, string)      │
│  ┌──────────────────────────────────────────────────────┤
│  │ Detects format:                                      │
│  │ - Codex: {"type":"thread.started","thread_id":...}  │
│  │ - Claude: {"type":"...","subtype":"result"}         │
│  │ - Gemini: {"type":"...","role":"assistant"}         │
│  │                                                      │
│  │ Extracts:                                            │
│  │ - Agent messages                                     │
│  │ - Session IDs                                        │
│  └──────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────┘

Backend Interface:

type Backend interface {
    Name() string
    Command() string
    BuildArgs(cfg *Config, targetArg string) []string
}

// Codex: codex e --skip-git-repo-check -C <workdir> --json <task>
// Claude: claude -p --dangerously-skip-permissions --output-format stream-json --verbose <task>
// Gemini: gemini -o stream-json -y -p <task>

Key Files:

• main.go - Entry point and orchestration
• config.go - CLI argument parsing
• backend.go - Backend interface and implementations
• executor.go - Process execution and stream handling
• parser.go - JSON stream parsing (multi-format)
• logger.go - Async logging with ring buffer
• utils.go - Helper functions

3. Hooks System

Architecture:

┌─────────────────────────────────────────────────────────┐
│                  Claude Code Events                       │
│  UserPromptSubmit │ PostToolUse │ Stop                   │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ reads
                   ▼
┌─────────────────────────────────────────────────────────┐
│              .claude/settings.json                        │
│  {                                                        │
│    "hooks": {                                             │
│      "UserPromptSubmit": [                                │
│        {                                                  │
│          "hooks": [                                       │
│            {                                              │
│              "type": "command",                           │
│              "command": "$CLAUDE_PROJECT_DIR/hooks/..."   │
│            }                                              │
│          ]                                                │
│        }                                                  │
│      ]                                                    │
│    }                                                      │
│  }                                                        │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ executes
                   ▼
┌─────────────────────────────────────────────────────────┐
│                   Hook Scripts                            │
│  ┌────────────────────────────────────────────────────┐  │
│  │ skill-activation-prompt.sh                         │  │
│  │ - Reads skills/skill-rules.json                    │  │
│  │ - Matches user prompt against triggers             │  │
│  │ - Injects skill suggestions                        │  │
│  └────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────┐  │
│  │ pre-commit.sh                                      │  │
│  │ - Validates staged files                           │  │
│  │ - Runs tests                                       │  │
│  │ - Formats code                                     │  │
│  └────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

4. Skills System

Structure:

skills/
├── codex/
│   └── SKILL.md         # Codex CLI integration
├── codeagent/
│   └── SKILL.md         # Multi-backend wrapper
├── gemini/
│   └── SKILL.md         # Gemini CLI integration
└── skill-rules.json     # Auto-activation rules

skill-rules.json Format:

{
  "rules": [
    {
      "trigger": {
        "pattern": "implement|build|create feature",
        "type": "regex"
      },
      "skill": "codeagent",
      "priority": 1,
      "suggestion": "Use codeagent skill for code implementation"
    }
  ]
}

Data Flow

Example: /dev Workflow

1. User: /dev "add user authentication"
   │
   ▼
2. Claude Code:
   │ ├─ Clarifies requirements (AskUserQuestion)
   │ ├─ Analyzes codebase (Explore agent)
   │ └─ Generates dev-plan.md
   │
   ▼
3. Claude Code invokes: codeagent-wrapper --parallel <<EOF
   ---TASK---
   id: auth_backend_1701234567
   workdir: /project/backend
   ---CONTENT---
   implement JWT authentication in @src/auth

   ---TASK---
   id: auth_frontend_1701234568
   workdir: /project/frontend
   dependencies: auth_backend_1701234567
   ---CONTENT---
   implement login form consuming /api/auth

   ---TASK---
   id: auth_tests_1701234569
   workdir: /project
   dependencies: auth_backend_1701234567, auth_frontend_1701234568
   ---CONTENT---
   add integration tests for auth flow
   EOF
   │
   ▼
4. Codeagent-Wrapper:
   │ ├─ Parses parallel config
   │ ├─ Topological sort (resolves dependencies)
   │ ├─ Executes tasks concurrently:
   │ │  ├─ Task 1: codex e --json "implement JWT..."
   │ │  ├─ Task 2: waits for Task 1, then codex e --json "implement login..."
   │ │  └─ Task 3: waits for Tasks 1&2, then codex e --json "add tests..."
   │ └─ Aggregates results
   │
   ▼
5. Claude Code:
   │ ├─ Validates coverage (≥90%)
   │ ├─ Runs final tests
   │ └─ Reports summary
   │
   ▼
6. User receives:
   ✅ Authentication implemented
   📊 Coverage: 92%
   📁 Files modified: 8
   🧪 Tests: 24 passed

Module System

Installation system uses modular architecture:

config.json
├── dev module (enabled)
│   ├── merge_dir: dev-workflow → ~/.claude
│   ├── copy_file: memorys/CLAUDE.md
│   ├── copy_file: skills/codex/SKILL.md
│   └── run_command: install codeagent-wrapper binary
│
├── gh module (enabled)
│   ├── merge_dir: github-workflow → ~/.claude
│   ├── copy_file: skills/codeagent/SKILL.md
│   ├── copy_dir: hooks → ~/.claude/hooks
│   └── merge_json: hooks-config.json → settings.json
│
└── essentials module (enabled)
    └── merge_dir: development-essentials → ~/.claude

Installation Flow:

python3 install.py --module dev,gh

1. Load config.json
2. Validate against config.schema.json
3. Select modules: dev, gh
4. Execute operations:
   ├─ dev:
   │  ├─ Merge dev-workflow/commands → ~/.claude/commands
   │  ├─ Copy CLAUDE.md → ~/.claude/CLAUDE.md
   │  ├─ Copy codex skill → ~/.claude/skills/codex/
   │  └─ Run install.sh (compile codeagent-wrapper)
   │
   └─ gh:
      ├─ Merge github-workflow/commands → ~/.claude/commands
      ├─ Copy codeagent skill → ~/.claude/skills/codeagent/
      ├─ Copy hooks → ~/.claude/hooks
      └─ Merge hooks-config.json → ~/.claude/settings.json
5. Write installed_modules.json
6. Log to install.log

Parallel Execution Engine

Algorithm:

1. Parse task config (---TASK--- delimited format)
2. Build dependency graph
3. Topological sort (detect cycles)
4. Execute in layers:
   Layer 0: Tasks with no dependencies
   Layer 1: Tasks depending only on Layer 0
   Layer 2: Tasks depending on Layers 0-1
   ...
5. Within each layer: unlimited concurrency
6. On failure: skip dependent tasks, continue others
7. Aggregate results

Example:

Tasks:
  A (no deps)
  B (no deps)
  C (depends on A)
  D (depends on A, B)
  E (depends on D)

Execution:
  Layer 0: A, B (parallel)
  Layer 1: C (waits for A), D (waits for A, B)
  Layer 2: E (waits for D)

Timeline:
  t=0:   Start A, B
  t=1:   A completes
  t=2:   B completes, start C, D
  t=3:   C completes
  t=4:   D completes, start E
  t=5:   E completes

Security Considerations

1. No credential storage - Uses existing CLI auth
2. Sandbox execution - Tasks run in specified workdir
3. Timeout enforcement - Prevents runaway processes
4. Signal handling - Graceful shutdown on Ctrl+C
5. Input validation - Sanitizes task configs

Performance Characteristics

Operation	Complexity	Notes
Backend selection	O(1)	Map lookup
Task parsing	O(n)	Linear scan
Topological sort	O(V+E)	Kahn's algorithm
Parallel execution	O(depth)	Depth of dependency graph
JSON parsing	O(n)	Streaming parser

Extensibility

Adding New Backend

1. Implement Backend interface:

type NewBackend struct{}

func (NewBackend) Name() string { return "new" }
func (NewBackend) Command() string { return "new-cli" }
func (NewBackend) BuildArgs(cfg *Config, targetArg string) []string {
    return []string{"--json", targetArg}
}

2. Register in config.go:

backendRegistry = map[string]Backend{
    "codex":  CodexBackend{},
    "claude": ClaudeBackend{},
    "gemini": GeminiBackend{},
    "new":    NewBackend{},
}

3. Add JSON format detection in parser.go:

if hasKey(obj, "new_specific_field") {
    // Parse new backend format
}

Adding New Hook

1. Create script in hooks/:

#!/bin/bash
# hooks/my-custom-hook.sh
echo "Hook executed"

2. Register in .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/hooks/my-custom-hook.sh"
          }
        ]
      }
    ]
  }
}

Adding New Skill

1. Create skills/my-skill/SKILL.md:

---
name: my-skill
description: My custom skill
---

# My Custom Skill

Usage instructions...

2. Add activation rule in skills/skill-rules.json:

{
  "rules": [
    {
      "trigger": {"pattern": "my keyword", "type": "regex"},
      "skill": "my-skill",
      "priority": 1
    }
  ]
}

Further Reading

• Codeagent-Wrapper Guide
• GitHub Workflow Guide
• Hooks Documentation
• README