Skip to main content

Auto Claude Architecture Analysis

Auto-Claude Architecture Analysis

Executive Summary​

Auto-Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. This analysis extracts key architectural patterns, memory system designs, and novel orchestration concepts that could inspire CODITECT framework improvements.

Key Innovation Areas:

  • Complexity-based pipeline adaptation (3-8 phases dynamically selected)
  • Dual-layer memory architecture (file-based + graph-based semantic search)
  • Self-healing QA loops with recurring issue detection
  • Git worktree isolation for parallel development
  • Dynamic security profiles based on project stack analysis
  • Multi-provider LLM/embedder abstraction

1. Architecture Patterns​

1.1 Multi-Agent Orchestration​

File: auto-claude/core/agent.py, auto-claude/agents/

Pattern: Facade-Based Agent Coordination

Auto-Claude uses a facade pattern where core/agent.py re-exports specialized agents:

  • Planner Agent - Creates subtask-based implementation plans
  • Coder Agent - Implements individual subtasks
  • QA Reviewer - Validates acceptance criteria
  • QA Fixer - Resolves issues in self-healing loop

Key Insight: The orchestrator (Python) handles all bookkeeping (memory, commits, progress tracking), while agents focus ONLY on code implementation. This separation ensures:

  • 100% reliable post-session processing
  • No agent cognitive load for state management
  • Clear responsibility boundaries

Relevance to CODITECT:

  • Apply facade pattern to /commands/ to group related multi-step workflows
  • Separate state management from agent execution in orchestrator
  • Use specialized agents for distinct phases rather than single multipurpose agents

1.2 Spec Pipeline Orchestration​

File: auto-claude/spec/pipeline/orchestrator.py

Pattern: Dynamic Phase Selection Based on Complexity

SIMPLE (3 phases):
  Discovery → Historical Context → Quick Spec → Validation

STANDARD (6-7 phases):
  Discovery → Historical Context → Requirements → [Research?] →
  Context → Spec Writing → Planning → Validation

COMPLEX (8 phases):
  Discovery → Historical Context → Requirements → Research →
  Context → Spec Writing → Self-Critique → Planning → Validation

Key Components:

  1. Phase Summaries for Compaction

    • _phase_summaries dict stores 500-word summaries of completed phases
    • Subsequent phases receive compressed context from prior work
    • Prevents context window explosion in long pipelines

  2. Smart Project Index Caching

    • should_refresh_project_index() checks if dependency files changed
    • Only regenerates project_index.json when package.json/pyproject.toml modified
    • QA agents receive accurate project capabilities for MCP tool injection

  3. Thinking Budget Per Phase

    • Ultrathink (16K tokens): Spec creation, self-critique
    • High (10K tokens): QA review
    • Medium (5K tokens): Planning, validation
    • None: Coding (no extended thinking needed)

Relevance to CODITECT:

  • Implement complexity tiers for /new-project command (beginner/intermediate/advanced)
  • Add phase summary compression to long-running orchestrator workflows
  • Create per-phase thinking budgets in agent activation metadata

1.3 Git Worktree Isolation​

File: auto-claude/core/worktree.py

Pattern: Per-Spec Worktree Architecture

main branch (user's work)
└── auto-claude/{spec-name} branch
    └── .worktrees/{spec-name}/ (isolated worktree)

Key Features:

  1. 1:1:1 Mapping: spec → worktree → branch
  2. Local-Only Until Push: All branches stay local until user explicitly pushes
  3. Parallel Work: Multiple specs can run simultaneously in separate worktrees
  4. Clean Merge: AI-powered merge conflict resolution when merging back to main

Merge Strategy (3-Tier):

  • Tier 1: Git auto-merge (no conflicts)
  • Tier 2: AI conflict resolution (only conflict regions, 98% prompt reduction)
  • Tier 3: Full-file AI merge (fallback)

Relevance to CODITECT:

  • Add worktree support to /git-sync for parallel feature development
  • Create isolated workspaces for each orchestrator task in progress
  • Implement AI merge resolution for submodule conflicts

2. Memory Systems​

2.1 Dual-Layer Memory Architecture​

Files: auto-claude/agents/memory_manager.py, auto-claude/integrations/graphiti/memory.py

Pattern: Primary + Fallback with Graceful Degradation

PRIMARY: Graphiti (when enabled)
  - Graph database (FalkorDB) with semantic search
  - Cross-session context retrieval
  - Multi-provider LLM/embedder support

FALLBACK: File-Based (always available)
  - Zero dependencies, human-readable
  - Session insights in specs/XXX/memory/
  - Patterns, gotchas, codebase maps

Key Design Decisions:

  1. Always Try Primary, Fall Back Gracefully

    if is_graphiti_enabled() and graphiti.is_available():
        return await graphiti_save()
    else:
        return file_based_save()  # Never fails

  2. Multi-Provider Abstraction (graphiti_providers.py)

    • LLM: OpenAI, Anthropic, Azure, Ollama, Google AI
    • Embedders: OpenAI, Voyage AI, Azure, Ollama, Google AI
    • Single factory pattern for provider creation

  3. Episode Types for Semantic Search

    EPISODE_TYPE_SESSION_INSIGHT
    EPISODE_TYPE_CODEBASE_DISCOVERY
    EPISODE_TYPE_PATTERN
    EPISODE_TYPE_GOTCHA
    EPISODE_TYPE_QA_RESULT
    EPISODE_TYPE_TASK_OUTCOME
    EPISODE_TYPE_HISTORICAL_CONTEXT

Memory Retrieval Example:

async def get_graphiti_context(spec_dir, project_dir, subtask):
    # Build search query from subtask description
    query = f"{subtask['description']} {subtask['id']}"

    # Get relevant knowledge (5 results max)
    context_items = await memory.get_relevant_context(query, num_results=5)

    # Get recent session history (last 3 sessions)
    session_history = await memory.get_session_history(limit=3)

    # Format for agent consumption
    return format_context(context_items, session_history)

Relevance to CODITECT:

  • Upgrade /cx memory system to dual-layer (SQLite + optional graph)
  • Add episode type classification to memory entries
  • Implement multi-provider abstraction for LLM/embedder flexibility
  • Create get_relevant_context(query) for context-aware retrieval

2.2 File-Based Memory Structure​

File: auto-claude/memory/memory.py (inferred from facade)

Pattern: Human-Readable Session Insights

specs/XXX/memory/
  session_001_insights.md
  session_002_insights.md
  codebase_map.md
  patterns_discovered.md
  gotchas.md

Stored Information:

  • Session Insights: What worked, what didn't, recommendations for next session
  • Codebase Discoveries: File structures, dependency flows, API contracts
  • Patterns: Coding conventions, architectural patterns observed
  • Gotchas: Edge cases, known issues, workarounds

Relevance to CODITECT:

  • Add human-readable session exports to .coditect/sessions/
  • Create pattern/gotcha extraction from /cxq queries
  • Build codebase map files for frequently accessed projects

3. Novel Concepts​

3.1 Complexity-Based Pipeline Scaling​

File: auto-claude/spec/complexity.py

Pattern: AI + Heuristic Complexity Assessment

Complexity Tiers:

  • SIMPLE: 1-2 files, single service, no integrations (3 phases)
  • STANDARD: 3-10 files, 1-2 services, minimal integrations (6-7 phases)
  • COMPLEX: 10+ files, multiple services, external integrations (8 phases)

Assessment Process:

  1. Keyword Analysis:

    SIMPLE_KEYWORDS = ["fix", "typo", "update", "change", "rename", ...]
    COMPLEX_KEYWORDS = ["integrate", "api", "database", "migrate", ...]

  2. Integration Detection:

    integration_patterns = [
        r"\b(graphql|apollo)\b",
        r"\b(stripe|payment)\b",
        r"\b(aws|s3|lambda)\b",
        ...
    ]

  3. AI Validation (Optional):

    • Uses complexity_assessor.md prompt
    • Analyzes requirements + project index
    • Returns recommended phases + flags (needs_research, needs_self_critique)

Outputs:

{
  "complexity": "standard",
  "confidence": 0.85,
  "reasoning": "5 files, 1 service(s); 1 integration(s)",
  "estimated_files": 5,
  "estimated_services": 1,
  "external_integrations": ["stripe"],
  "recommended_phases": ["discovery", "requirements", "context", ...],
  "needs_research": true,
  "needs_self_critique": false
}

Relevance to CODITECT:

  • Add complexity assessment to /new-project --analyze
  • Create skill-level tiers (beginner/intermediate/advanced) in agent selection
  • Use heuristics + AI to recommend agent/command activation
  • Build complexity metadata into component-activation-status.json

3.2 Self-Healing QA Loops​

File: auto-claude/qa/qa_loop.py (re-exported facade)

Pattern: Iterative QA with Recurring Issue Detection

QA Loop Flow:

1. QA Reviewer validates acceptance criteria
2. If rejected → QA Fixer applies fixes
3. Track iteration history
4. Detect recurring issues (3+ occurrences)
5. If recurring → Escalate to human
6. Max 50 iterations before human intervention

Recurring Issue Detection:

def _issue_similarity(issue1, issue2):
    """Fuzzy match issues by normalized description"""
    key1 = _normalize_issue_key(issue1["description"])
    key2 = _normalize_issue_key(issue2["description"])
    return key1 == key2

def has_recurring_issues(iteration_history):
    """Check for issues appearing 3+ times"""
    issue_counts = defaultdict(int)
    for iteration in iteration_history:
        for issue in iteration["issues_found"]:
            key = _normalize_issue_key(issue["description"])
            issue_counts[key] += 1
    return any(count >= 3 for count in issue_counts.values())

Escalation Trigger:

if has_recurring_issues(history):
    escalate_to_human(spec_dir, "Recurring issues detected")
    return "human_review_required"

QA Status States:

QA_STATUSES = [
    "pending",          # Not yet reviewed
    "in_review",        # Currently being reviewed
    "approved",         # All criteria met
    "rejected",         # Issues found
    "fixes_applied",    # Fixes applied, ready for re-review
]

Relevance to CODITECT:

  • Add self-healing QA loop to orchestrator workflows
  • Implement recurring issue tracking in task management
  • Create auto-escalation triggers for stuck workflows
  • Build QA metrics into component activation decisions

3.3 AI Merge Conflict Resolution​

File: auto-claude/core/worktree.py (inferred from README)

Pattern: 3-Tier Merge Strategy with Minimal AI Use

Tier 1: Git Auto-Merge

git merge --no-commit auto-claude/{spec-name}
# Simple non-conflicting changes merge instantly

Tier 2: Conflict-Only AI (98% prompt reduction)

# Only send conflict regions to AI, not entire files
conflict_regions = extract_conflict_markers(file)
resolved_regions = await ai_resolve_conflicts(conflict_regions)
apply_resolved_regions(file, resolved_regions)

Tier 3: Full-File AI (fallback)

# If conflict resolution fails, send entire file
full_context = {
    "base": base_file_content,
    "theirs": branch_file_content,
    "ours": main_file_content
}
resolved_file = await ai_merge_full_context(full_context)

Parallel Processing:

  • Multiple conflicting files resolve simultaneously
  • Syntax validation before applying merged result

Relevance to CODITECT:

  • Add AI merge resolution to /git-sync for submodule conflicts
  • Implement conflict-only AI (not full file) for token efficiency
  • Create parallel merge workers for multi-file conflicts
  • Add syntax validation gates before committing AI-resolved merges

3.4 Dynamic Security Profiles​

File: auto-claude/analysis/project_analyzer.py, auto-claude/security.py

Pattern: Stack-Aware Command Allowlisting

Security Layers (Defense in Depth):

  1. OS Sandbox: Bash command isolation prevents filesystem escape
  2. Filesystem Permissions: Operations restricted to project_dir only
  3. Command Allowlist: Dynamic allowlist from project analysis
  4. Tool Filtering: Each agent type sees only relevant tools

Project Analysis:

class ProjectAnalyzer:
    def analyze(project_dir):
        stack = detect_technology_stack(project_dir)
        # Detects: languages, frameworks, databases, infrastructure

        scripts = parse_custom_scripts(project_dir)
        # Parses: package.json scripts, Makefile targets, pyproject.toml scripts

        profile = build_security_profile(stack, scripts)
        # Tailored allowlist for this specific project

        cache_profile(project_dir, profile)
        # .auto-claude-security.json for subsequent runs

Example Profile:

{
  "technology_stack": {
    "languages": ["python", "javascript"],
    "frameworks": ["react", "django"],
    "databases": ["postgresql"],
    "infrastructure": ["docker", "kubernetes"]
  },
  "allowed_commands": [
    "npm", "npx", "node", "python", "pip", "django-admin",
    "docker", "docker-compose", "kubectl", "psql",
    "pytest", "jest", "eslint", "black"
  ],
  "custom_scripts": {
    "npm": ["start", "build", "test"],
    "make": ["migrate", "test", "lint"]
  }
}

Command Validation:

def is_command_allowed(command, profile):
    base_cmd = command.split()[0]

    if base_cmd in profile.allowed_commands:
        return True

    if base_cmd in profile.custom_scripts:
        return True

    if base_cmd in DANGEROUS_COMMANDS:
        return False  # rm, dd, mkfs, ...

    return False  # Default deny

Relevance to CODITECT:

  • Build project-specific security profiles for agent tool access
  • Add command allowlist generation to project initialization
  • Create technology stack detection for skill/agent recommendations
  • Cache security profiles in .coditect/security-profile.json

4. Integration Points​

4.1 Claude SDK Usage​

File: auto-claude/core/client.py

Pattern: Security Hooks + Tool Permissions

Client Creation:

def create_client(
    project_dir: Path,
    spec_dir: Path,
    model: str,
    agent_type: str = "coder",
    max_thinking_tokens: int | None = None,
) -> ClaudeSDKClient:
    """
    Security layers (defense in depth):
    1. Sandbox - OS-level bash isolation
    2. Permissions - File ops restricted to project_dir
    3. Security hooks - Bash commands validated against allowlist
    4. Tool filtering - Each agent type sees only relevant tools
    """

Tool Filtering by Agent Type:

# Planner: Progress + Subtask tools
# Coder: Progress + Subtask tools
# QA Reviewer: QA + Progress tools
# QA Fixer: QA + Progress + Subtask tools

MCP Tool Integration:

# Context7 MCP - Always enabled (docs lookup)
CONTEXT7_TOOLS = [
    "mcp__context7__resolve-library-id",
    "mcp__context7__get-library-docs",
]

# Linear MCP - When LINEAR_API_KEY set
LINEAR_TOOLS = ["mcp__linear-server__list_issues", ...]

# Graphiti MCP - When GRAPHITI_MCP_URL set
GRAPHITI_MCP_TOOLS = [
    "mcp__graphiti-memory__search_nodes",
    "mcp__graphiti-memory__add_episode",
]

# Electron MCP - When ELECTRON_MCP_ENABLED=true
ELECTRON_TOOLS = [
    "mcp__electron__take_screenshot",
    "mcp__electron__send_command_to_electron",
]

Dynamic Tool Injection:

# Load project capabilities
project_index = load_project_index(project_dir)
capabilities = detect_project_capabilities(project_index)

# Only inject Puppeteer tools if project is an Electron app
if capabilities.is_electron_app:
    allowed_tools.extend(PUPPETEER_TOOLS)

Relevance to CODITECT:

  • Add security hooks to Claude SDK client creation in framework
  • Implement agent-type-based tool filtering in component activation
  • Create MCP server integration layer for agent tools
  • Add dynamic tool injection based on project capabilities

4.2 Prompt Engineering Patterns​

Directory: auto-claude/prompts/ (not directly analyzed, but inferred)

Specialized Agent Prompts:

  • planner.md - Creates implementation plans with subtasks
  • coder.md - Implements individual subtasks
  • coder_recovery.md - Recovers from stuck/failed subtasks
  • qa_reviewer.md - Validates acceptance criteria
  • qa_fixer.md - Fixes QA-reported issues
  • spec_gatherer.md - Collects user requirements
  • spec_researcher.md - Validates external integrations
  • spec_writer.md - Creates spec.md document
  • spec_critic.md - Self-critique using ultrathink
  • complexity_assessor.md - AI-based complexity assessment

Prompt Structure Pattern:

# Role Definition
You are a [AGENT_TYPE] agent...

# Task Context
{additional_context}
{prior_phase_summaries}

# Available Tools
{dynamic_tool_list}

# Success Criteria
...

# Examples
...

Relevance to CODITECT:

  • Standardize agent prompt format across /agents/
  • Add context injection points for prior phase summaries
  • Create recovery prompts for stuck workflows
  • Build self-critique prompts with ultrathink for validation

5. Key Takeaways for CODITECT​

5.1 Immediate Applications​

  1. Complexity Assessment System

    • Add to /new-project command
    • Create skill-level tiers in component metadata
    • Use for automatic agent/command recommendations

  2. Dual-Layer Memory

    • Upgrade SQLite context.db with graph layer
    • Add episode type classification
    • Implement semantic search for context retrieval

  3. Self-Healing QA Loops

    • Add to orchestrator workflows
    • Track recurring issues in task management
    • Auto-escalate stuck workflows

  4. Git Worktree Support

    • Extend /git-sync for parallel feature development
    • Add AI merge conflict resolution
    • Create isolated workspaces for orchestrator tasks

  5. Dynamic Security Profiles

    • Build project-specific agent tool access
    • Add technology stack detection
    • Cache security profiles per project

5.2 Architectural Patterns to Adopt​

  1. Facade-Based Organization

    • Group related commands/agents under facades
    • Separate orchestration from execution
    • Clear responsibility boundaries

  2. Phase Summary Compression

    • Store 500-word summaries of completed phases
    • Pass to subsequent phases for context
    • Prevent context window explosion

  3. Multi-Provider Abstraction

    • Support multiple LLM/embedder providers
    • Factory pattern for provider creation
    • Graceful fallback when preferred unavailable

  4. 3-Tier Merge Strategy

    • Git auto-merge first (fastest)
    • AI conflict-only resolution (efficient)
    • Full-file AI merge (fallback)

  5. Tool Filtering by Agent Type

    • Planner sees planning tools only
    • Coder sees implementation tools
    • QA sees validation tools
    • Prevents tool misuse

5.3 Novel Concepts to Explore​

  1. Complexity-Aware Workflows

    • Simple tasks: 3 phases (fast path)
    • Standard tasks: 6-7 phases (balanced)
    • Complex tasks: 8 phases (thorough)

  2. Recurring Issue Detection

    • Track issue patterns across iterations
    • Auto-escalate when stuck (3+ same issue)
    • Human intervention at iteration threshold

  3. Project Capability Detection

    • Parse package.json, pyproject.toml, etc.
    • Detect frameworks, databases, infrastructure
    • Dynamic tool/agent injection based on stack

  4. Thinking Budget Per Phase

    • Planning: Medium (5K tokens)
    • QA Review: High (10K tokens)
    • Self-Critique: Ultrathink (16K tokens)
    • Coding: None (no extended thinking)

  5. Isolated Worktree Development

    • One worktree per task
    • Local-only branches until user push
    • Parallel development without conflicts

6. Implementation Roadmap for CODITECT​

Phase 1: Memory System Upgrade (Week 1-2)​

  • Add graph database layer to context.db (FalkorDB optional)
  • Implement episode type classification for /cx entries
  • Create get_relevant_context(query) for semantic search
  • Add multi-provider abstraction for LLM/embedders

Phase 2: Complexity Assessment (Week 3)​

  • Build complexity analyzer (simple/standard/complex)
  • Add to component metadata (complexity_tier field)
  • Integrate with /new-project --analyze
  • Create skill-level recommendations

Phase 3: QA Loop Enhancement (Week 4)​

  • Implement self-healing QA loops in orchestrator
  • Add recurring issue tracker
  • Create auto-escalation triggers
  • Build QA metrics dashboard

Phase 4: Git Worktree Support (Week 5-6)​

  • Extend /git-sync with worktree creation
  • Add AI merge conflict resolution
  • Implement 3-tier merge strategy
  • Create parallel development workflows

Phase 5: Security Profiles (Week 7)​

  • Build technology stack detector
  • Create dynamic security profiles
  • Add command allowlist generation
  • Cache profiles in .coditect/security-profile.json

Phase 6: Prompt System Standardization (Week 8)​

  • Standardize agent prompt format
  • Add context injection points
  • Create recovery prompts
  • Build self-critique prompts with ultrathink

7. Conclusion​

Auto-Claude demonstrates sophisticated multi-agent orchestration through:

  • Dynamic complexity adaptation - Right-sized pipelines for task scope
  • Dual-layer memory - File-based reliability + graph-based intelligence
  • Self-healing loops - Automated QA with human escalation
  • Secure isolation - Worktree + dynamic security profiles
  • Intelligent compression - Phase summaries prevent context bloat

These patterns align well with CODITECT's mission to transform ideas into production-ready products. The phased implementation roadmap provides a clear path to integrate these innovations while maintaining CODITECT's existing strengths in distributed intelligence and agent specialization.

Next Steps:

  1. Review this analysis with CODITECT core team
  2. Prioritize roadmap phases based on user needs
  3. Create ADRs for major architectural changes
  4. Begin Phase 1 implementation (Memory System Upgrade)

Analysis Date: 2025-12-22 Analyst: Claude Code (Sonnet 4.5) Source Repository: /Users/halcasteel/PROJECTS/coditect-rollout-master/submodules/core/coditect-core/submodules/research/auto-claude Status: Ready for review and implementation planning