Design Principles

Thirteen principles that guide how we build agent-intelligence.ai — and how agents built with it should behave. Inspired by the 12-factor app, the 12-factor agents methodology, and the agent-native principles by Every.

1. 01
   [>] F01-TERMINAL — terminal-native The terminal is a first-class interface. If it runs in a terminal, it runs everywhere — CI, containers, SSH sessions, scripts. The CLI is not a wrapper around a web UI; it is the product. Every feature must be fully accessible from the command line before a web interface is considered.
2. 02
   [>] F02-ZERO2RUN — zero to running ai init → ai serve is the entire getting-started experience. Every additional step must justify its existence. No account creation, no API dashboard, no config file editing required to run a first agent. Defaults are production-grade; overrides are available but never required upfront.
3. 03
   [>] F03-FAST — fast by default Sub-200ms cold start. Static binary. No daemon required. Performance is a feature, not an optimisation pass. A Go binary with no runtime overhead means the tool gets out of the way. Slow tooling trains developers to avoid running it — fast tooling trains tight feedback loops.
4. 04
   [>] F04-PROGX — progressive exposure Simple commands work with zero flags. Depth scales with the task. ai run "summarise this" works on day one. Advanced flags — fallback chains, tool filtering, context budgets — are discoverable but never in the way. The UI should not front-load complexity onto beginners or hide power from experts.
5. 05
   [>] F05-OWN-PROMPT — own your prompts Your system prompt is yours. New features ship as prompt fragments, not code. agent.toml is plain text. The system prompt is a field you write, read, and version-control. Nothing is injected silently by the platform. New capabilities are delivered as composable prompt fragments (ai skill add) — features that would require code changes in traditional software ship as prompt additions instead.
6. 06
   [>] F06-OWN-CTX — own your context window Context is managed explicitly. The agent knows what it has access to. What goes into the context window is what you put there. Tool results are summarised before injection when configured. Token budgets are visible and enforced. At session start the agent receives a structured summary of available data sources, files, and tools — an agent unaware of its environment cannot act effectively.
7. 07
   [>] F07-STATELESS — stateless reducers Agents are pure functions. Memory is explicit state. Improvement is auditable. Pause, resume, and replay are first-class operations. Session state — including accumulated memory across sessions — is serialisable, auditable, and rollback-capable. When an agent proposes a change to its own configuration, that change is visible and diffable before being applied. Human approval gates are the mechanism for pausing execution at high-stakes decision points.
8. 08
   [>] F08-LOCAL1ST — local first Runs on your laptop. Files are the agent-legible data format. Cypherlite provides an embedded graph backend that needs no external service. The full agent loop works offline. Files are the preferred data format for agent-readable state — a directory layout an agent can navigate with fs_list and fs_read is more legible than rows in a database. Design for what agents can reason about: if a human can understand the structure, an agent can too.
9. 09
   [>] F09-PROTOCOL — protocol-native MCP and A2A are the transport layer. If a user can click it, an agent can call it. Every agent created with ai init is simultaneously an MCP server and an A2A endpoint from day one. Every capability in ai web or ai tui has an agent-callable MCP equivalent — no orphan UI actions. A parity map (.agint/parity.yaml) is maintained and checked in CI. MCP is the single agent-callable surface across all tiers: UI interactions, management operations (reload config, switch agent), and data-plane calls share one protocol. Any external agent that speaks MCP can fully operate the UI — no carve-outs, no parallel REST management surface.
10. 10
    [>] F10-COMPOSE — composable over monolithic Small focused agents. Atomic tools. Behaviour changes via prompts, not refactors. An agent with fewer than 20 tools and a single well-defined responsibility outperforms a Swiss-army agent. Build the UNIX way: small programs composed via MCP and A2A. Tools are atomic primitives — business logic belongs in the prompt. The test: if changing agent behaviour requires refactoring tool code rather than editing a prompt, the tools encode too much logic.
11. 11
    [>] F11-OBSERVE — observable over magical Every inference and tool call is traceable. No black boxes. --debug shows the full context window, token counts, and tool call payloads. OpenTelemetry traces export to any backend. Errors are surfaced with enough context to self-correct, not swallowed by a retry loop. If you can't see it, you can't fix it.
12. 12
    [>] F12-ACCESS — accessible by default --plain output works in pipelines, CI, and screen readers. ANSI colour, Unicode symbols, box-drawing characters, and emoji are all stripped by --plain. The tool outputs clean, parseable text when piped. The web UI meets WCAG 2.1 AA. Accessibility is a correctness property, not a polish task.
13. 13
    [>] F13-EMERGE — emergent by design Build atomic primitives. Observe what agents accomplish. Formalize the patterns. The platform should enable agents to accomplish tasks that were not explicitly designed for. When an agent combines existing tools to handle an unanticipated request, that is not a bug — it is the system working as intended. New features are discovered by observing what agents do, then formalizing durable patterns as domain tools or prompt fragments. The test: describe an outcome within the agent's domain that has no dedicated feature. If the agent can compose existing tools to accomplish it, the architecture passes.

// cmd_run.go — tool trace and token counts go to stderr
fmt.Fprintf(os.Stderr, "[tool] %s (%s)\n", name, duration)
fmt.Fprintf(os.Stderr, "[tokens] in: %s  out: %s\n", inTok, outTok)

Note: AI-assisted setup requires ANTHROPIC_API_KEY. Falling back to manual mode.
      Set the key and re-run for the recommended experience.

# Makefile — all cross-compile targets disable CGO
GOARCH=amd64 GOOS=linux CGO_ENABLED=0 go build -o bin/ai-linux-amd64 ...

# zero-config run
ai run "what is 2+2"

# progressive depth
ai run --verbose --model claude-sonnet-4-20250514 --max-turns 5 "analyse this repo"

# agent.toml
[agent]
system_prompt = "You are a research assistant..."

[agent.intent_router]
classify_prompt = "..."   # optional — overrides built-in default

[agent.tool_context]
selector_prompt = "..."   # optional — overrides built-in default

[agent.budget]
max_tool_result_chars = 8000

// internal/agent/context.go
func TruncateToolResult(output string, maxChars int) string {
    if maxChars <= 0 || len(output) <= maxChars {
        return output
    }
    omitted := len(output) - maxChars
    return output[:maxChars] +
        fmt.Sprintf("\n[truncated — %d chars omitted]", omitted)
}

[agent.graph]
uri = "cypherlite://.agint/graph"

// internal/mgmtapi/mgmtapi.go
w.Header().Set("X-Deprecated", "true")
w.Header().Set("X-Deprecated-Message",
    `Use MCP tool "graph_query" instead.`)

# agent.toml
[mcp_server]
disabled_tools = ["execute_shell", "execute_python"]

// internal/telemetry/telemetry.go
if endpoint != "" && os.Getenv("OTEL_TRACES_SAMPLER") == "" {
    sampler = sdktrace.AlwaysSample()
}

// cmd/ai/root.go
if gf.Plain {
    gf.NoColor = true  // --plain implies --no-color
}

# Every UI action has an MCP equivalent (F09-PROTOCOL parity)
# Parity map lives at .agint/parity.yaml
# CI check: make parity-check

# The agent_config_propose tool lets the agent improve its own prompts
# New onboarding features ship as prompt fragments, not Go code (F05-OWN-PROMPT)
# Memory crystallizes successful tool sequences into skills (F07-STATELESS)