Startr.Team Agent Framework — Specification

Status: Draft v0.1.0 · License: Apache-2.0 · Reference implementation: startr-team (Python)

This spec describes a small agent framework with an unusual set of priorities: every run is auditable (markdown vault), plans are human-editable (wikilinked markdown graphs), tool selection is natural language first (NLT), and outbound action is gated (a human holds the send switch). It was extracted from two working agents — Downes (education) and Lia Fáil (a governance herald) — that had independently converged on the same engine.

Architecture

agent.yaml ──► AgentProfile ──► persona block in every system prompt
                                        │
 instruction ──► Agent.run() ───────────┤
                 1. plan   (steps, or a graph plan)
                 2. act    (per step: NLT selects a tool, or draft directly)
                 3. answer (compose the final result)
                                        │
                 Vault ◄── every artifact, transcript, and trace
                                        │
      [messaging] Roll ──► resolve recipients ──► clean ──► deliver()
                                            (dry-run first; human gates --send)

Two install surfaces:

core — the loop, profile, LLM interface, tools + NLT, vault, graph plans.
[messaging] extra — channels, the roll, gated dispatch, cleanup pipeline.

The contracts

Page	Contract
Agent loop	`Agent.run()` — plan → act → answer, safety guards, the `work_step` seam
Readable code	House style: `this`, narrating helpers, why
Profile	`agent.yaml` → `AgentProfile` → every prompt
LLM interface	`call_llm` — provider-agnostic, per-role overrides
Tools + NLT	The registry, `@tool` convention, NLT-first selection
Vault	Run directories, artifacts, LLM transcripts
Graph plans	Plans as wikilinked markdown vaults; loops, budgets, resume
Messaging	`Channel` ABC, the roll, gated dispatch
Configuration	The full environment surface
Extending	Recipes: new tool, new channel, new agent
Examples	The runnable examples, rendered from source

Design positions

Audit is a feature, not a log level. Everything the agent reads, decides, and produces lands in the vault as markdown a human can read.
NLT-first. JSON function calling is a pluggable alternative, not the default. Small, local decisions in plain language beat schema serialization, especially on small models.
Plans belong to people. A plan you cannot open, read, and edit in your notes app is a plan you do not really control. Code-defined graphs (LangGraph et al.) are powerful; ours are legible.
The LLM composes; it never sends. Delivery is deterministic code with a dry-run default.
One engine, many agents. Domain lives in agent.yaml, the tool registry, and (optionally) overridden prompts — never in the engine.