Core Concepts

Four ideas define how Trurlic works: the decision graph (what’s stored), the advance loop (how agents work through it), the context brief (what constrains code), and the two modes (agent vs interactive). For the module layout, see Architecture.

The decision graph

Trurlic stores a typed graph in .trurlic/. Every node is a git-tracked TOML file; graph.toml is a derived edge index rebuilt deterministically from the nodes.

Node types:

• Components — architectural boundaries (auth, rate-limiter). Containers for decisions, not code modules; one component may span many files.
• Decisions — individual choices: what was chosen, why, rejected alternatives, who decided, when, and which code it touches.
• Patterns — a rule synthesized from two or more related decisions (e.g. “all state in Redis”). Applied across components.
• project — a virtual root node. Decisions attached to project are inviolable, project-wide rules.

Edge types:

Edge	Meaning
BelongsTo	Decision → Component (every decision has exactly one owner)
ConnectsTo	Component → Component — directional flow; surfaces related decisions in briefs
DependsOn	Decision → Decision — the dependent assumes the parent holds
Constrains	Decision → Decision — one restricts the other’s choices
Supersedes	Decision → Decision — replaces a prior decision, kept for history

See Decision Graph for the on-disk format.

The advance loop

Every task starts at advance — the orchestration hub. It reads the graph, computes the next step, and returns a concrete action. The agent acts, calls advance again, and repeats until ready: true. Then it pulls the full brief and implements.

advance(component, task_type, mode)  →  { step, action, requires_user_input, ready }
      ↑                                            │
      └──────── agent acts, calls again ───────────┘
                        … until ready: true …
get_context(component)               →  the brief; agent implements within it
verify_against_decisions(component, changed_files)  →  fix violations before commit

advance is a pure function of the graph — same graph in, same step out. No clock, no I/O, no LLM. It can’t skip a security concern or a constraint check, because each step’s precondition is checked against the graph itself.

Seven task types, each with its own step sequence: new_component, feature, fix, learn, review, harden, bootstrap. See Workflow Engine for the full sequences and the 16 steps.

Gated steps

Some steps are gated — they require evidence of human involvement before the workflow advances. A gated step returns requires_user_input: true; the agent presents its prompt, collects the user’s response (at least 20 bytes of real content), and passes it back as step_evidence on the next call. This is how Trurlic enforces human authorship: the agent facilitates, the human decides.

Context briefs

A context brief is the output of get_context(component) — the authoritative document that constrains generation. It contains:

• Rules — project-wide, inviolable. At the top of every brief.
• Component decisions — the specific choices for this component, with reasoning and attribution.
• Patterns — cross-cutting constraints that apply here.
• Related decisions — relevant choices from connected components.
• Override policy — rules are inviolable; component decisions are strong defaults; never silently deviate.

Two depth modes: full (default — complete reasoning, used before implementing) and constraints (choice text only, ~60–70% fewer tokens, for mid-implementation compliance checks).

Two modes

The agent picks a mode when it calls advance — or asks you when unsure.

	Agent mode	Interactive mode
Who decides	The AI reads the source and decides	You and the AI reason it out together
Speed	Fast, no interruptions	Slower, deliberate
Comprehension gates	Off	On — the AI must confirm shared understanding
Attribution	agent, flagged ⚠ for your review	user
Use it for	”implement X”, “fix Y”, bootstrapping	”design”, “architect”, “let’s think about…”

Agent-mode decisions are never silently trusted — they land marked agent · unreviewed and surface in every brief until you promote (via update_decision) or revise them. Two task types are pinned: learn is always interactive; bootstrap is always agent.

Attribution

Every decision carries attribution: user (a human authored it) or agent (recorded autonomously). Agent decisions are flagged ⚠ in briefs and on the interactive map, and are candidates for trurlic gc cleanup if they stay unreviewed. Promote a reviewed one with the update_decision promote mode.

Concern tracking

The workflow tracks ten architectural concern areas (security boundaries, error handling, concurrency, integrity/validation, performance, external interfaces, storage, serialization, dependencies, migration) and matches them against decision content by keyword. Concerns are priority-ordered — security gaps surface before stylistic ones — so harden and design steps can flag what’s uncovered before implementation.

Next

Architecture for module boundaries and the thread model · Integrity Model for write guarantees · MCP Tools for the full tool surface.