Core System Overview¶

Samuel (Artificial Intelligence Coding Framework) is built on a simple but powerful architecture designed for progressive adoption and cross-tool compatibility.

Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                      Your Project                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌──────────────────────────────────┐   │
│  │  CLAUDE.md  │    │           .claude/                │   │
│  │             │    │                                    │   │
│  │  • Commands │    │  ├── skills/ (language, framework, │   │
│  │  • Guards   │    │  │          workflow skills)       │   │
│  │  • Methods  │    │  └── auto/ (autonomous loop state) │   │
│  │             │    │                                    │   │
│  └─────────────┘    └──────────────────────────────────┘   │
│        ↑                           ↑                        │
│        └───────────────────────────┘                        │
│                    References                               │
└─────────────────────────────────────────────────────────────┘

Core Components¶

CLAUDE.md - The Brain¶

The main instruction file loaded by AI assistants. Contains:

Size: ~500 lines (optimized for token efficiency)

Learn about CLAUDE.md

.claude/ Directory - The Memory¶

Project-specific context that grows over time:

.claude/
├── skills/                # Agent Skills (language, framework, workflow)
│   ├── go-guide/          # 21 language guide skills
│   ├── react/             # 33 framework skills
│   ├── create-prd/        # 23 workflow skills
│   ├── auto/              # Autonomous loop skill
│   └── ...
├── auto/                  # Autonomous loop state (generated by samuel auto init)
│   ├── prd.json           # Machine-readable task state
│   ├── progress.md       # Learnings journal
│   ├── prompt.md          # Iteration prompt
│   └── discovery-prompt.md # Discovery prompt (pilot mode)
└── settings.local.json    # Claude Code local settings (gitignored)

Loading Protocol:

1. Session Start: AI loads CLAUDE.md → checks per-folder CLAUDE.md
2. During Work: Language guide loads based on file extensions
3. Complex Features: Workflows and framework skills loaded on-demand
4. Autonomous Mode: Reads prd.json, progress.md for task selection

Learn about .claude directory

The 3 Modes¶

AI auto-detects which mode based on task complexity:

ATOMIC Mode¶

For: Bug fixes, small features (<5 files)

graph LR
    A[Task] --> B[Deconstruct]
    B --> C[Diagnose]
    C --> D[Develop]
    D --> E[Deliver]
    E --> F[Done ✓]

• Direct implementation
• Quick validation
• One commit

FEATURE Mode¶

For: New components, API endpoints (5-10 files)

graph TD
    A[Task] --> B[Break into 3-5 subtasks]
    B --> C1[Subtask 1]
    B --> C2[Subtask 2]
    B --> C3[Subtask 3]
    C1 --> D[Integration Test]
    C2 --> D
    C3 --> D
    D --> E[Documentation]
    E --> F[Done ✓]

• Break into subtasks
• Sequential implementation
• Multiple commits

COMPLEX Mode¶

For: New subsystems, architecture (>10 files)

graph TD
    A[Task] --> B[Create PRD]
    B --> C[Generate Tasks]
    C --> D[Task 1]
    D --> E[Task 2]
    E --> F[Task N]
    F --> G[Integration]
    G --> H[Documentation]
    H --> I[Done ✓]

• PRD workflow (optional but recommended)
• Full task breakdown
• Staged delivery

Learn the Methodology

The 4D Methodology¶

Every task follows four phases:

Deep dive into 4D

Guardrails System¶

35+ testable rules across categories:

All Guardrails

Language Guides¶

Auto-loaded based on file extensions:

No manual selection needed - AI detects and loads automatically.

Workflows¶

On-demand workflows for complex tasks:

Progressive Growth¶

The system grows with your project:

Day 1:     CLAUDE.md + .claude/ templates only
           ↓
Week 1:    .claude/project.md created (tech stack)
           ↓
Month 1:   .claude/patterns.md populated (conventions)
           ↓
Ongoing:   .claude/memory/ captures decisions

Cross-Tool Compatibility¶

Works with any AI coding assistant:

Setup: ln -s CLAUDE.md AGENTS.md

Cross-Tool Setup

Next Steps¶