Concept

The agent is a participant, not a feature.

Siteplan's whole design follows from one decision: an AI agent is a first-class actor in the same system as a human. Not a separate service, not a chat panel, not a second permission model — the same room, the same event stream, the same audit trail, with deliberately asymmetric authority.

Starting point

What the product is built on.

Siteplan began as a Wagtail CMS that also works as a foundation for building Django applications. That origin is not incidental — it explains the constraints that shape the whole design.

The portal is a CMS. The agent-native layer is built on top of it without replacing it. The existing Wagtail admin, the CRUD views and the current authentication keep working. Nothing in the agent direction requires a second framework, a second schema owner or a second place to log in.

One user model. Django allows exactly one AbstractUser, and AUTH_USER_MODEL cannot be swapped after the first migration. Agents extend the existing siteplan_user.User — they do not get their own identity table.
One schema owner. A second service importing Django models shares the schema but deploys on a different schedule. That is version skew for no benefit.
The hierarchy

An organization contains teams. A team contains rooms. A room contains topics.

The tenant is an Organization. A company, a charity, a club and a government body are all the same entity. Organizations can nest, so a holding company has subsidiaries, and one organization can share a room with another — which covers clients and vendors without merging their accounts.

Tenant
Organization

What an entity signs up for. It owns the agent roster, the credentials, the user-defined apps and the spend. Can nest, so subsidiaries are structural rather than a second root.

Grouping
Team

Who works together inside the organization. Deliberately not called a "Department" — the organization names its own, so a company types "Sales" and a club types "Beginners".

Collaboration
Room

Where work happens. Belongs to a team, or directly to the organization when it is company-wide. Holds artifacts that outlive any one conversation.

Conversation
Topic

The conversation unit, and always topical. Its subject is required, so a branch cannot exist without naming what it is about.

"Workspace" means the UI shell, and only the UI shell. The tenant word is Organization. Keeping that vocabulary separate is what stops a five-level hierarchy with two roots to explain.
Conversation, modelled properly

A topic tree, not a channel with side threads.

Slack's shape — a main stream plus threads hanging off it — splits a discussion into two places and loses topicality. Siteplan makes the fork the only way to branch.

APAC Pipeline · room
ROOM TOPIC · ROOT Region breakdown for APAC FORKED AT seq 4 TOPIC · CHILD Margin by region TOPIC · CONVERSATION Weekly pipeline review TOPIC · ACTIVITY Room-scoped work events
Fork carries a required subject Child reads ancestors, not a copy
  • A fork writes a FORKED event in the parent at the exact message being forked, and creates the child with a parent and a fork anchor.
  • The child does not copy history. Its context is the ancestor chain truncated at each fork anchor, then its own events — so the log stays append-only and provenance stays intact.
  • An ACTIVITY topic holds room-scoped work that belongs to no conversation — a task created directly in a room, an objective changing state. It keeps ordering and replayability without a nullable topic column.
  • Topics are adapter-agnostic. They store provider-neutral events, so a different runtime can answer a later turn in the same topic.
A topic can move between engines. Start on an OpenAI-compatible adapter, switch to a CLI agent when credits run out, and keep the same history — because the log never stored a provider's wire format.
The product layer

Why, what, and the durable result.

The hierarchy says where work happens. It does not say why. Four entities carry that: objectives, tasks, artifacts and datasets.

Why

Objective

A measurable outcome. The unit a human and an agent are both pointed at, and the natural place to attach progress. Progress can be typed in, or read from a dataset.

What

Task

A unit of requested work assigned to a human or an agent. Same row, same audit. A task is not a conversation — it may span several topics and several runs.

Result

Artifact

Durable, rendered, pinnable content. One row per logical thing, with published versions. An artifact outlives the topic that produced it.

Source

Dataset

A validated, parameterised query over platform data. Never a SQL string. Executed as the viewer, so a report stays correct for every person who opens it.

Artifacts, objectives, tasks and datasets are organization-owned. Only a pin is scope-specific — and a pin is placement, never an access grant.

The bottleneck the concept removes

Three lifetimes that products usually collapse into one.

A canvas is where content is authored. An artifact is what survives. A pin is where it is placed. Each has a different lifetime, and the chain between them is strict.

ConceptLifetimeWhat it meansWhat it is not
Canvas Topic-scoped, scratch The persistent state of a room while work is in progress, with versions produced by events. Not pinnable. It is working state with a working title.
Artifact Durable, versioned A logical thing — a report, a view, a document — that can be published repeatedly. Not a canvas row. If it were, it would inherit the canvas's scratch lifetime.
Pin Placement only A sidebar position at personal, room, team or organization scope. Not an access grant, and not a copy of the artifact.
Visibility gates access. Placement never widens it. If pinning an artifact into a room made it readable there, any member of any team could publish into any other team by pinning.
One artifact, many placements. Copying per scope means versions drift, the same report renders differently in two rooms, and a refresh has to be applied N times.
Authority

Parity in the stream. Asymmetry in the power.

Humans and agents are both addressable senders with audit records. They do not share permissions. That distinction is the single most important line in the design.

What parity means
  • Both can be assigned a task, because a task's assignee is a User.
  • Both appear in a room's roster and can be addressed by mention.
  • Both emit events that carry a sender, a run and a cause.
  • An agent can own accountability: every agent has a human owner who answers for it.
What asymmetry means
  • Agents never authenticate, and never receive staff or superuser flags.
  • Agents hold capabilities — coarse, default-deny, expiring and revocable.
  • Irreversible actions need a human approval bound to the exact arguments.
  • An agent's data scope is the intersection of its grant and the requester's scope.
An agent may never read a row the person who asked could not read. Without that rule, an autonomous agent with plausible prompting becomes a privilege escalator.
Addressing

An agent speaks when it is spoken to — or when the room makes it obvious.

Resolution is one function with three ordered rules. Nothing about it is stored, so it cannot drift from membership.

1
Explicit mentions
Mentions from the payload, in order. An empty mention list means "no agent" — that is how a human sends a note without starting a run.
2
The direct room
Exactly one human member and exactly one active agent, counted over effective membership. Every message from that human is addressed to that agent, because a 1:1 with a colleague should not require ceremony.
3
Otherwise nobody
An unaddressed message appends to the log and stops. A room-level agent that replies to everything is a bill and a noise source.
The rule expires by itself. The moment a second human or a second agent joins, a guest organization joins the room, or the agent is paused, the direct-room rule stops applying. It is derived on every message and never stored.
  • The composer states the resolved target, so an implicit run is never a surprise.
  • Agent-authored events never start a run, so a direct room cannot talk to itself.
  • One active run per topic: a fast typer cannot race two runs against one canvas.
  • Rostering an agent into a room is a human act requiring agent.manage.
Proactivity, bounded

An agent can act when nobody is in the room. Once.

A run triggered by an event covers "someone caused this". It does not cover "nobody was here". So a scheduled, event-bound or objective-bound trigger is an explicit row — and it is deliberately one hop only.

  • A trigger fire claims a run through the same queue as any other run.
  • A trigger-started run may not start another run by mentioning an agent.
  • An agent may not trigger another agent.
Chains are what turn a helpful agent into an unbounded bill. Delegation beyond one hop needs an explicit human task. Design rule, section 4.10

Next: how that concept becomes one process, one log and one write path.