Part 2 — The AI-Native Architecture

The Container
That Teaches Itself

when your codebase is the prompt

AI Writes Code.
But Whose Architecture?

The problem isn't AI's code. It's that AI has no map.
02

Everything Describes Itself

// Any helper can explain itself at runtime
const fs = container.feature('fs')

fs.introspect()        // full API: methods, state shape, events
fs.introspectAsText()  // human-readable docs
fs.introspectAsType()  // TypeScript interface

// Discover everything available
container.features.available  // what exists
container.features.describe() // what each one does
Know the philosophy. The container teaches you the rest.
03

An Agent Walks Into a Container

AGENT container.features.available
LUCA ['fs', 'git', 'proc', 'ui', 'networking', 'grep', ...]
AGENT container.feature('git').introspect()
LUCA { methods: [branch, sha, lsFiles, ...], state: { branch, sha, isRepo }, events: [...] }
AGENT container.git.branch → writes code against it
No docs needed. No training data. The runtime IS the documentation.
04

Every Helper Is a Tool Surface

// Any feature can expose itself to an AI assistant
const git = container.feature('git')
const { schemas, handlers } = git.toTools()

// schemas  → OpenAI-compatible function definitions
// handlers → the actual implementations

// Give an assistant access to any feature
assistant.use(container.feature('fs'))
assistant.use(container.feature('git'))
assistant.use(container.feature('proc'))
Build the feature once. Expose it to AI with one line.
05

Assistants Are Just Folders

Structure
assistants/researcher/
├── CORE.md      system prompt
├── tools.ts     Zod-schema tools
├── hooks.ts     lifecycle hooks
└── docs/        auto-injected context
Usage
const asst = container
  .feature('assistant')

// Give it any feature as tools
asst.use(container.feature('fs'))
asst.use(container.feature('git'))

const reply = await asst.ask(
  'What changed this week?'
)
assistant.use(anyFeature) — that's the whole integration story.
06

One Map. Two Navigators.

Human Defines
🏗 The architecture
📋 Helper interfaces
📁 Where things live
🏷 What categories exist
←
container
shared mental model
→
AI Implements
⚙ Helper internals
🧪 Tests and validation
🔄 Composition logic
🔨 The boring stuff
You design the map. AI respects it. The codebase stays yours.
07

More AI Code = More Trust

Normally, the more AI writes, the less confident you feel. With Luca, AI composes with helpers you've already reviewed. New code gets captured into new helpers. The codebase grows more trustworthy.

Week 1
reviewed
Month 1
reviewed
Month 6
reviewed
The surface area of unreviewed code shrinks because AI reaches for existing helpers.
08

Agents Can Watch Everything

// An agent monitors the system in real-time
container.on('featureEnabled', (id) => {
  agent.log(`Feature ${id} came online`)
})

server.state.observe((type, key, val) => {
  if (key === 'requestCount' && val > 1000)
    agent.alert('Traffic spike detected')
})

// Same primitives that power the UI, power the agent
Observable state + events = AI can monitor, react, and intervene.
09

REPL-Friendly = Agent-Friendly

Discoverability

What's available? What can it do? Ask and the container answers.

Introspection

Every method, every event, every state shape — queryable at runtime.

Observable State

Watch anything change. React without polling. Same as React, but headless.

Immediate Feedback

Run code, see results, iterate. The agent loop IS the REPL loop.

What makes something nice for a REPL is exactly what makes it nice for an agent.
10

Your Codebase
Is the Prompt.

bun add luca

github.com/soederpop/luca