Assistant System Bible

1. Purpose and Scope

The assistant system in AISTEAM is the central intelligence that works across projects, tenants and panels. It offers a single assistant panel where the user can talk to a set of agents that collaborate to plan and execute work, often in parallel runs that involve several agents at the same time.

This Bible describes how that system behaves in detail. It covers both conceptual behavior and concrete implementation details so developers and AI agents can reason about the same model.

• Audience, engineers, AI configuration, product design and future agents
• Scope, assistant panel, chat, routing, planning protocol, parallel runs, execution, logging, experience and thinking stream
• Out of scope, billing, authentication and general app layout that is not related to the assistant workflow

2. Core Concepts and Definitions

The assistant system uses a few core concepts. These names should stay consistent in code, in database schema and in future documentation.

Assistant panel

The right side UI that shows the agent list and the conversation. It is the main cockpit for interacting with the AI system.

Agent

A defined persona with a clear responsibility and a set of tools. Examples, Chief AI Officer, Web Engineer, Growth Lead.

Supervisor

The Chief AI Officer, also called Hans. Receives messages first at the model level and decides who should handle the request.

Conversation

A continuous thread between a user and the assistant system. Stored in assistant_conversations with messages in assistant_messages.

Run

A structured multi step response to a user intent that can involve several agents and tasks in parallel. All tasks in a run share a run identifier.

Run step group

A phase inside a run that can contain one or more tasks that are allowed to execute in parallel before the next phase unlocks.

Task

A structured action that can be executed. For example create a page in WordPress, update a product or create an internal ticket.

Experience

The sequence of visible messages and status events that the user sees for a given conversation or run. Includes text, status bubbles, run cards and progress states.

Project context

Structured information about the project that is currently in focus. For example project id, name, domains, CMS and important configuration.

Routing

The process that decides which agent is responsible for a specific user request or part of a request.

Thinking stream

A light, safe, summarized log of what agents are doing and planning behind the scenes. Shown as small grey entries under messages and in run cards. Stored as thinking messages, not raw chain of thought.

Assistant laws

The core rules that govern all runs and tasks, including allowed scope, clarity of inputs, transparency of actions and the law of no return for reversibility and explicit consent.

3. High Level Architecture

The assistant system sits between the front end assistant panel, the AI model, the Supabase database and external platforms such as WordPress or WooCommerce.

At a high level the flow looks like this for multi step work. Simple questions can still be answered directly without a full run.

flowchart TD
  U[User in assistant panel] --> C[Assistant chat API]
  C --> S[Supervisor logic]
  S --> P[Plan run and steps]
  P --> R1[Run with parallel tasks]
  R1 --> T[Execution API]
  T --> E[External systems and platforms]
  E --> T
  T --> S
  S --> ANS[Final consolidated answer]
  ANS --> U

The Supervisor always remains in the loop. For complex requests Hans creates a run that may involve several agents and tasks in parallel, then validates the combined result before sending the final message to the user. During this process the thinking stream records safe reasoning steps so the user can see what is happening, in a light grey collapsible view.

4. Message Lifecycle

Every user message in the assistant panel follows a structured lifecycle. This lifecycle is important for logging, error handling, planning protocol and consistent user experience.

4.1 Stages

1. User enters a message in the assistant panel and clicks send.
2. Front end sends a request to the assistant chat API with conversation id, active agent id and project context.
3. API loads conversation history and context from the database.
4. Supervisor evaluates the new message and classifies it as a simple answer or a multi step run that needs planning.
5. If simple, Supervisor chooses the best agent and that agent prepares a direct answer.
6. If a run is needed, Supervisor invokes the task planning protocol and creates an AssistantRun record that groups the work.
7. The plan is converted into one or more AssistantTask records, possibly grouped into phases with parallel tasks.
8. Each task is checked against the assistant laws before it is allowed to execute.
9. Tasks are executed or queued through the execution API, sometimes in parallel when the plan allows it.
10. Supervisor validates the combined agent output and builds the final user response.
11. API saves new messages, status events, thinking events, run and task updates in the database.
12. Front end updates the conversation, any visible run cards, thinking previews and status indicators.

4.2 Message types

Messages in assistant_messages can have different types. This allows the UI to display them correctly and supports richer experiences, including the thinking stream.

• user text message that came from the human user
• assistant primary response sent to the user
• status internal status item such as run created, task created or execution started that can be displayed as a thin status bubble
• thinking safe summarized reasoning entries for the thinking stream. For example Hans is planning the run or Web Engineer is preparing layout options
• system internal notes or prompts that are not shown to the user by default

4.3 Experience timeline

For each user message the system may generate several experience events. For example the user might see:

• Assistant is thinking
• Hans is planning a multi agent run for this request
• Growth Lead Dana and Creative Lead Mak are working in parallel
• Creating a new WordPress page in your project
• Task created and queued
• All tasks in this run are completed
• Final summary of what was done

These experience events should be logged as assistant messages with kind set to status or thinking so they can be replayed in the conversation and grouped by run when relevant. The UI can also present them as a compact timeline so the user understands what the system did, not only what it answered.

5. Agent Selection and Routing

The assistant panel lets the user select an active agent, but the Supervisor still has authority to override routing when this leads to a better outcome. For complex work the Supervisor often builds a run that includes several agents working together.

5.1 Active agent from the panel

• The assistant panel shows all relevant agents for the tenant or project.
• When the user clicks an agent avatar or entry, the activeAgentId in local state updates.
• Every message sent from that conversation includes the activeAgentId in the API request.
• assistant_conversations.current_agent stores the last known selected agent for that conversation.

5.2 Supervisor routing decision

The Supervisor uses both the current agent and the message content to decide who should answer or which agents belong in the run for this request.

type AgentId =
  | "chief"
  | "deliveryLead"
  | "clientSuccess"
  | "creativeLead"
  | "growthLead"
  | "technicalLead"
  | "webEngineer"
  | "seoSpecialist"
  | "ecommerceSpecialist"
  | "sportsMedia"
  | "notificationAgent"
  | "researchAgent"
  | "schedulerAgent"
  | "fileAgent";

interface RoutingContext {
  currentAgent: AgentId;
  messageText: string;
  projectContext?: {
    projectId: string;
    cmsPlatform?: string;
  };
}

function determineAgent(ctx: RoutingContext): AgentId {
  const message = ctx.messageText.toLowerCase();

  if (message.includes("delivery") || message.includes("timeline")) {
    return "deliveryLead";
  }
  if (message.includes("client") || message.includes("account")) {
    return "clientSuccess";
  }
  if (
    message.includes("brand") ||
    message.includes("visual") ||
    message.includes("creative")
  ) {
    return "creativeLead";
  }
  if (
    message.includes("seo") ||
    message.includes("traffic") ||
    message.includes("ads") ||
    message.includes("campaign")
  ) {
    return "growthLead";
  }
  if (
    message.includes("hosting") ||
    message.includes("server") ||
    message.includes("ssl") ||
    message.includes("integration")
  ) {
    return "technicalLead";
  }
  if (
    message.includes("page") ||
    message.includes("post") ||
    message.includes("template") ||
    message.includes("layout")
  ) {
    return "webEngineer";
  }

  return ctx.currentAgent || "chief";
}

This function can be extended with more domain signals or replaced by a small model call, but the important part is that routing remains explicit and debuggable. Thinking messages can record how the routing decision was made in safe terms, for example Hans is choosing Growth Lead based on SEO intent.

5.3 Routing visibility for the user

Whenever the Supervisor changes the agent that will answer a request or adds agents to a run, the system should create a status message such as:

• Hans is handing this off to Web Engineer Nico for implementation.
• Growth Lead Dana and Creative Lead Mak are joining this run to help with SEO and layout.

This keeps the experience understandable for the user and also leaves a clear audit trail in the conversation. The thinking stream can give a lighter, more detailed view of the same routing step without overwhelming the primary conversation.

6. Validation and Escalation

The assistant system has clear rules about when an agent can answer directly, when clarification is required and when escalation is needed.

6.1 Supervisor validation

• The Supervisor validates every response that involves execution or important decisions.
• For simple advisory messages, the same agent that handled the request can answer directly.
• For actions that affect a live site, the Supervisor must confirm that the explanation and summary are clear.

6.2 Clarification before action

Agents must not guess about critical parameters such as domain, live environment or destructive actions. They follow this pattern:

1. Check project context for the required information.
2. If missing, request clarification from the user with a clear list of what is needed.
3. Once information is complete, confirm the plan in a short recap sentence.
4. Only then proceed to call the execution API.

6.3 Escalation logic

If an agent does not have enough authority or information to safely handle a request it must escalate back to the Supervisor or to the correct lead.

• Execution agents escalate to Technical Lead for risky changes such as DNS or certificates.
• Marketing related actions escalate to Growth Lead when budget or strategy questions appear.
• Client communication questions escalate to Client Success Lead.

6.4 Assistant laws

All runs and tasks must respect four core assistant laws. These apply to every task, even when several tasks run in parallel inside a run.

• Law of allowed scopeAgents can only perform actions that are allowed for this project and tenant. Task types must be checked against project configuration before execution.
• Law of clarityNo task can execute if critical inputs are missing. Agents must either use project context or ask the user for the missing information and confirm the plan before acting.
• Law of transparencyEvery meaningful step is logged in a way that can be understood later. This includes routing decisions, planning protocol, task creation, status changes, thinking stream entries and final summaries.
• Law of no returnThe system should prefer operations that can be rolled back. If an action cannot be rolled back automatically, it must be clearly explained to the user and must receive explicit confirmation before execution. These irreversible actions should be rare and always visible in the logs with clear flags in the tasks and runs.

7. Project Context and Scoping

The assistant must always know which project it is working on, or that it is in a cross project mode. Context scoping is handled as part of every request and is reused by routing, planning, execution and logging.

7.1 Context resolution

• If the user is on a project page, the front end passes projectId in the assistant request.
• The chat API loads project data from the projects table along with any extended configuration.
• A projectContext object is built and injected into the system prompt and planning protocol.
• Agents are instructed to rely on this context before asking the user about basic facts.

7.2 Cross project conversations

Some conversations are not tied to a single project. For example, a user might ask for a comparison between several sites.

• In that case projectId is omitted and context is scoped to the tenant.
• Agents may fetch information for several projects as part of the response.
• Any tasks created must include the correct projectId in their payload even in a cross project conversation.

7.3 Context in runs and tasks

Runs and tasks should store project identifiers explicitly to keep logs and execution safe and traceable.

• AssistantRun.projectId indicates the main project for the run.
• AssistantTask.projectId indicates the project impacted by that specific task.
• If a run touches several projects, tasks can each carry their own projectId.
• Thinking messages should never guess project context when it is unknown. Instead they should record the absence and ask the user.

8. Execution Model and Tasks

Execution is the part where ideas become changes in external systems. The assistant uses structured runs and tasks that are sent to a dedicated execution API. Planning decides what to do, execution performs the work.

8.1 Run and task contracts

Runs group tasks that belong to the same user intent. Tasks represent individual actions that can be executed, often in parallel inside a run.

interface AssistantRun {
  id: string;
  conversationId: string;
  projectId?: string;
  createdByAgentId: string;
  title: string;
  status: "planning" | "running" | "completed" | "failed" | "cancelled";
  createdAt: string;
  updatedAt: string;
}

interface AssistantTask {
  id: string;
  runId: string;
  conversationId: string;
  projectId?: string;
  parentTaskId?: string;
  stepGroup?: string;
  sequenceOrder: number;
  createdByAgentId: string;
  status: "open" | "in_progress" | "completed" | "failed" | "cancelled";
  taskType: string;
  parameters: Record<string, unknown>;
  summary: string;
  isReversibleBySystem: boolean;
  irreversibleConfirmedAt?: string;
  createdAt: string;
  updatedAt: string;
  result?: Record<string, unknown>;
}

8.2 Typical task types

• create_page, create or update a CMS page
• update_content_block, update part of a page or template
• create_product, create or update an ecommerce product
• create_ticket, create a ticket in the internal ticketing panel
• run_audit, request a performance or SEO audit

8.3 Execution API usage

Agents never talk directly to external systems. They call the execution API with a structured payload and let that layer handle integration details, including respect for project scope and the law of no return.

POST /api/assistant/execute

Request body:

{
  "runId": "uuid",
  "conversationId": "uuid",
  "projectId": "uuid",
  "createdByAgentId": "webEngineer",
  "taskType": "create_page",
  "parameters": {
    "cms": "wordpress",
    "title": "About Aquaverter",
    "slug": "about-aquaverter",
    "contentHtml": "<h1>About Aquaverter</h1>..."
  },
  "summary": "Create new About page for Aquaverter site"
}

7. Project Context and Scoping

The assistant must always know which project it is working on, or that it is in a cross project mode. Context scoping is handled as part of every request and is reused by routing, planning, execution and logging.

7.1 Context resolution

• If the user is on a project page, the front end passes projectId in the assistant request.
• The chat API loads project data from the projects table along with any extended configuration.
• A projectContext object is built and injected into the system prompt and planning protocol.
• Agents are instructed to rely on this context before asking the user about basic facts.

7.2 Cross project conversations

Some conversations are not tied to a single project. For example, a user might ask for a comparison between several sites.

• In that case projectId is omitted and context is scoped to the tenant.
• Agents may fetch information for several projects as part of the response.
• Any tasks created must include the correct projectId in their payload even in a cross project conversation.

7.3 Context in runs and tasks

Runs and tasks should store project identifiers explicitly to keep logs and execution safe and traceable.

• AssistantRun.projectId indicates the main project for the run.
• AssistantTask.projectId indicates the project impacted by that specific task.
• If a run touches several projects, tasks can each carry their own projectId.
• Thinking messages should never guess project context when it is unknown. Instead they should record the absence and ask the user.

8. Execution Model and Tasks

Execution is the part where ideas become changes in external systems. The assistant uses structured runs and tasks that are sent to a dedicated execution API. Planning decides what to do, execution performs the work.

8.1 Run and task contracts

Runs group tasks that belong to the same user intent. Tasks represent individual actions that can be executed, often in parallel inside a run.

interface AssistantRun {
  id: string;
  conversationId: string;
  projectId?: string;
  createdByAgentId: string;
  title: string;
  status: "planning" | "running" | "completed" | "failed" | "cancelled";
  createdAt: string;
  updatedAt: string;
}

interface AssistantTask {
  id: string;
  runId: string;
  conversationId: string;
  projectId?: string;
  parentTaskId?: string;
  stepGroup?: string;
  sequenceOrder: number;
  createdByAgentId: string;
  status: "open" | "in_progress" | "completed" | "failed" | "cancelled";
  taskType: string;
  parameters: Record<string, unknown>;
  summary: string;
  isReversibleBySystem: boolean;
  irreversibleConfirmedAt?: string;
  createdAt: string;
  updatedAt: string;
  result?: Record<string, unknown>;
}

8.2 Typical task types

• create_page, create or update a CMS page
• update_content_block, update part of a page or template
• create_product, create or update an ecommerce product
• create_ticket, create a ticket in the internal ticketing panel
• run_audit, request a performance or SEO audit

8.3 Execution API usage

Agents never talk directly to external systems. They call the execution API with a structured payload and let that layer handle integration details, including respect for project scope and the law of no return.

POST /api/assistant/execute

Request body:

{
  "runId": "uuid",
  "conversationId": "uuid",
  "projectId": "uuid",
  "createdByAgentId": "webEngineer",
  "taskType": "create_page",
  "parameters": {
    "cms": "wordpress",
    "title": "About Aquaverter",
    "slug": "about-aquaverter",
    "contentHtml": "<h1>About Aquaverter</h1>..."
  },
  "summary": "Create new About page for Aquaverter site"
}

8.4 Parallel execution inside runs

For complex work, several tasks may run at the same time as long as they do not depend on each other.

• Tasks that share the same stepGroup can be considered parallel siblings.
• Tasks in a later group must wait until all tasks in earlier groups reach a terminal state.
• The execution layer can decide how to schedule parallel tasks within system limits.
• The thinking stream and status messages should make parallel work visible to the user without adding noise.

9. Logging and Experience Model

The assistant system must be observable. Logging is not only for debugging but also for reconstructing the user experience and understanding how agents collaborate across runs and tasks.

9.1 What gets logged

• Every user message and assistant message
• Agent id that authored each assistant message
• Routing decisions for each user message, including previous and new agent
• Run creation, updates and completion
• Task creation, updates and completion, including execution status and reversibility information
• Thinking entries that summarize safe reasoning steps during planning and execution
• Important system events such as missing configuration or external API errors

9.2 Experience timeline concept

For any conversation the system should be able to display a high level timeline of what happened, not only the raw text. Timelines can be filtered by run so multi agent parallel work stays understandable.

[
  {
    "time": "2025-12-09T12:00:00Z",
    "actor": "user",
    "kind": "message",
    "runId": "run_1",
    "summary": "User asked to create a new service page"
  },
  {
    "time": "2025-12-09T12:00:05Z",
    "actor": "supervisor",
    "kind": "routing",
    "runId": "run_1",
    "summary": "Hans delegated implementation to Web Engineer Nico and Growth Lead Dana"
  },
  {
    "time": "2025-12-09T12:00:08Z",
    "actor": "supervisor",
    "kind": "planning",
    "runId": "run_1",
    "summary": "Planning run with content, layout and SEO tasks in parallel"
  },
  {
    "time": "2025-12-09T12:00:10Z",
    "actor": "webEngineer",
    "kind": "task_created",
    "runId": "run_1",
    "summary": "Task create_page for Services page structure"
  },
  {
    "time": "2025-12-09T12:00:12Z",
    "actor": "growthLead",
    "kind": "task_created",
    "runId": "run_1",
    "summary": "Task run_audit for SEO suggestions"
  },
  {
    "time": "2025-12-09T12:00:20Z",
    "actor": "system",
    "kind": "task_completed",
    "runId": "run_1",
    "summary": "Page created in WordPress"
  }
]

9.3 Thinking entries

Thinking entries are small, summarized logs that describe what agents are doing behind the scenes in a safe way. They are visible to the user as light grey text and support trust and understanding.

• Thinking messages must never expose raw prompts or sensitive chain of thought.
• They should describe actions and decisions in simple language, for example Hans is checking missing values.
• They are linked to a conversation and optionally to a run and a step group.
• The UI can preview recent thinking items under each answer and show full sequences inside run cards.

9.4 Internal reasoning metadata

Internal reasoning that is not safe to display can still influence planning and routing, but it should not be stored verbatim. Instead the system can keep compact structured metadata to support later analysis.

• assistant_runs.metadata can keep structured planning information.
• assistant_tasks.metadata can store technical details about integration calls.
• assistant_conversations.metadata can store global flags such as risk level or confusion markers.

10. Assistant Panel UI Behavior

The UI of the assistant panel is where users feel the system. The behavior must be predictable and should make the invisible routing, planning and execution steps easy to understand without overwhelming the user.

10.1 Layout

• Left column inside the panel, agent list with avatars and short labels.
• Right area inside the panel, conversation feed and input box.
• Top context bar that shows the current project and tenant.
• Optional run cards area for ongoing multi step runs and long running operations.

10.2 Agent list behavior

• Only agents that are relevant to the current tenant or project are visible.
• Supervisor is always visible and usually selected by default.
• Clicking an agent highlights it and sets that agent as current for new messages.
• Tooltips show a short description and example prompts for each agent.

10.3 Conversation feed

• User messages aligned to the right or styled differently.
• Assistant messages show the agent avatar that authored them.
• Status entries styled as light system chips such as run created or task executing.
• Runs can be summarized in collapsible blocks that list agents involved, tasks and current status.
• Long explanations can be collapsed with a short summary and an expand control.

10.4 Activity indicators

While the assistant is working the UI should indicate what is going on instead of a simple generic typing bubble.

• Thinking, the Supervisor or agent is planning a response.
• Routing, Supervisor is deciding which agent or agents should handle this.
• Planning, Hans is creating a multi step run with tasks and step groups.
• Executing, one or more tasks are being sent to or processed by external systems.
• Validating, Supervisor is checking the result before answering.

10.5 Thinking stream in the UI

The thinking stream is visible in two places, with a collapsible behavior and a dynamic preview.

• Under each assistant message, a small preview line appears in light grey, for example Thinking details Hans is analyzing your request and preparing a plan.
• The preview is collapsible by default and shows only the most recent thinking entries that fit comfortably on one line based on the current screen width.
• Clicking the preview expands a vertical list of thinking entries related to that answer, for example routing decisions, checks for missing values and small plan steps.
• Inside run cards, a richer thinking section can show grouped entries per step group and per agent, so the user can see how the run unfolded over time.
• Thinking entries must remain visually secondary. They use smaller font size and lighter color so the primary content stays dominant.

11. Error Handling and Recovery

Errors are inevitable. The system must handle them in a way that is safe, reversible when possible and understandable. All error handling respects the law of no return and the visibility principles of the assistant panel including thinking entries.

11.1 Error categories

• Input errors, the user request is incomplete or conflicting.
• Context errors, project configuration is missing or invalid.
• Execution errors, external systems reject the request or time out.
• System errors, internal server problems or unexpected exceptions.

11.2 Principles

• Never pretend a task succeeded when it failed.
• Explain the failure in simple non technical language that still respects the truth of the issue.
• Always propose a recovery path when possible.
• Log all details privately in messages metadata and runs metadata for debugging and audits.
• When something irreversible would normally occur the system must prompt the user before allowing it.
• If irreversibility occurs with user approval the system must record it with irreversibleConfirmedAt on the task.

11.3 Example error responses and thinking stream

User facing content:

I tried to create the new page but the site returned a permission error.
This usually means the credentials are missing or incorrect.
Here is what we can do next.
I can help you verify or update the credentials in the project settings then we can try again.

Thinking entries (light grey to user):

Hans is checking WordPress credentials.
WordPress API returned code 403 access denied.
Marking task as failed.
Suggesting recovery path to the user.

12. API Contracts

The assistant system exposes at least two main API routes. The chat route handles conversational interactions, routing, planning and thinking. The execution route handles tasks and all integration with external systems.

12.1 Chat route with planning and thinking stream

POST /api/assistant/chat

Request:

{
  "conversationId": "uuid or null",
  "messages": [
    { "role": "user", "content": "Please create a new service page." }
  ],
  "activeAgentId": "chief",
  "projectContext": {
    "projectId": "uuid",
    "projectName": "Aquaverter",
    "projectDomain": "aquaverter.ca",
    "cmsPlatform": "wordpress"
  }
}

Response:

{
  "conversationId": "uuid",
  "messages": [
    {
      "id": "uuid",
      "role": "assistant",
      "agentId": "chief",
      "content": "Before I create this page I need a few details..."
    }
  ],
  "thinking": [
    {
      "kind": "routing",
      "summary": "Hans evaluated the request and will create a planning run."
    },
    {
      "kind": "planning",
      "summary": "Identifying required tasks for new service page creation."
    }
  ],
  "routedAgentId": "chief",
  "runCreated": {
    "runId": "run_123",
    "title": "Create new service page"
  }
}

12.2 Execution route with reversibility controls

POST /api/assistant/execute

Request:

{
  "runId": "uuid",
  "conversationId": "uuid",
  "projectId": "uuid",
  "createdByAgentId": "webEngineer",
  "taskType": "create_page",
  "parameters": {
    "cms": "wordpress",
    "title": "Services",
    "slug": "services",
    "contentHtml": "<h1>Services</h1>..."
  },
  "summary": "Create Services page"
}

Response:

{
  "taskId": "uuid",
  "status": "completed",
  "details": {
    "cmsId": 4551,
    "url": "https://aquaverter.ca/services"
  }
}

Thinking messages generated during execution such as contacting WordPress or validating slugs are also logged and optionally surfaced to the user under run cards.

13. Database Schema

The assistant system relies on a structured set of tables that store conversations, messages, runs, tasks and optional agent definitions. All schema follows the principles of transparency, planning clarity, thinking visibility and the law of no return.

13.1 assistant_conversations

id                 uuid primary key
tenant_id          uuid not null
user_id            uuid null
started_at         timestamptz not null default now()
closed_at          timestamptz null
active_flag        boolean not null default true
current_agent      text not null default 'chief'
metadata           jsonb not null default '{}'

13.2 assistant_messages

id               uuid primary key
conversation_id   uuid not null references assistant_conversations(id)
author            text not null          -- user or assistant or system
agent_id          text null
kind              text not null          -- message or status or thinking or system
content           text not null
created_at        timestamptz not null default now()
metadata          jsonb not null default '{}'

thinking messages follow the same structure as status messages but use kind set to thinking and are collapsible by default in the UI.

13.3 assistant_runs

id               uuid primary key
conversation_id   uuid not null references assistant_conversations(id)
project_id        uuid null
created_by        text not null
title             text not null
status            text not null        -- planning or running or completed or failed or cancelled
created_at        timestamptz not null default now()
updated_at        timestamptz not null default now()
metadata          jsonb not null default '{}'

13.4 assistant_tasks

id                     uuid primary key
run_id                 uuid not null references assistant_runs(id)
conversation_id        uuid not null references assistant_conversations(id)
project_id             uuid null
parent_task_id         uuid null
step_group             text null
sequence_order         integer not null default 0
created_by             text not null
status                 text not null        -- open or in_progress or completed or failed or cancelled
task_type              text not null
parameters             jsonb not null
summary                text not null
is_reversible_by_system boolean not null default true
irreversible_confirmed_at timestamptz null
created_at             timestamptz not null default now()
updated_at             timestamptz not null default now()
result                 jsonb null

13.5 assistant_agent_definitions optional

id             uuid primary key
tenant_id       uuid null              -- null for global agent definitions
agent_id        text not null          -- chief or webEngineer etc
display_name    text not null
role_summary    text not null
category        text not null          -- supervisor or lead or execution or utility
visible         boolean not null default true
ordering        integer not null default 0
avatar          jsonb not null default '{}'
config          jsonb not null default '{}'

14. Implementation Patterns and Notes

This section captures practical guidance for developers who work on the assistant system and its integration with the rest of AISTEAM. The goal is to keep the codebase simple to reason about while still supporting planning, runs, parallel tasks and thinking streams.

14.1 Keep routing explicit

Even when model based intent detection is used, keep a routing helper in code that shows the final decision. This makes debugging easier and allows tools such as Cursor to understand routing without full model introspection.

14.2 Use small typed helpers

Wrap common operations in small helpers such as loadConversation, buildProjectContext, createAssistantRun, createAssistantTask and appendThinkingMessage. This keeps the main route handlers readable and reduces errors.

14.3 Avoid duplication of project context

Project context should be built in one place and reused across chat, planning and execution routes. When fields are added to project configuration, update the context builder instead of each route individually.

14.4 Align names across layers

Agent ids, task types, run statuses and task statuses should have the same names across:

• Database tables
• TypeScript enums or literal types
• Prompt and system instructions
• Front end strings where relevant

14.5 Keep thinking entries small and safe

Thinking stream entries should be short and action focused. They should never reveal low level chain of thought or internal prompts. Use them only to reflect safe, high level steps such as planning, routing and checks.

15. Future Enhancements

The current design is stable enough for first implementation. Several enhancements are planned or expected as the platform grows and real usage patterns emerge.

15.1 Voice and real time sessions

• Streamed responses in the assistant panel for more fluid interaction.
• Live indication of active agent during a session.
• Ability to interrupt and redirect a running plan or run in real time.

15.2 Richer intent detection

• Use a separate model call or dedicated router for complex decisions.
• Let the system propose a plan that spans multiple agents and tasks with explicit step groups.
• Provide the user with a visible plan card that they can approve or tweak before execution.

15.3 Experience dashboards

• Show a history of assistant conversations, runs and tasks for each project.
• Visualize progress of automation and frequency of different task types.
• Surface common issues so that base configuration and prompts can be improved.

15.4 Multi tenant guardrails

• Add automated checks that prevent any cross tenant leakage of data.
• Extend projectContext and tenantContext with stronger isolation flags.
• Increase transparency in thinking streams when context boundaries are relevant.

16. Task Planning Protocol

For non trivial requests the assistant system must shift from a simple ask answer mode into a planning mode. In this mode the Supervisor builds an explicit plan, checks requirements and only then creates runs and tasks. This protocol is central for safety, clarity and parallel multi agent work.

16.1 When planning protocol is used

The Supervisor should invoke planning protocol when:

• The request requires changes in external systems such as CMS or DNS.
• The work spans several agents, for example creative and technical and growth.
• The work logically breaks into multiple steps or phases.
• The law of no return might be relevant because irreversible changes are possible.

16.2 Planning protocol stages

The planning protocol follows a predictable sequence that can be implemented as model instructions and helper code.

1. Understand the intentSupervisor restates the user goal in one or two sentences. For example create a Services page that fits Aquaverter brand and supports SEO.
2. Check project contextLoad projectContext and verify basic information such as CMS type, domain and relevant settings. Add a thinking entry for this check.
3. Identify missing requirementsBuild a short internal list of required inputs such as page title, slug, language, layout preferences, SEO focus and any constraints. Mark which ones are missing.
4. Ask clarifying questions when neededIf important requirements are missing, ask the user focused questions. Each question should be clearly motivated by the goal of the plan.
5. Propose helpful forksWhen reasonable, suggest alternative approaches that may better support the user goals. For example create a generic Services page or separate Services by category or include a lead capture block.
6. Draft a stepwise planOnce inputs are clear, create a short list of steps and step groups. Each step must have a clear owner agent and a rough description of what the task will do.
7. Check laws and reversibilityFor each step, verify allowed scope and reversibility. Mark any step that is not reversible by the system and plan how to obtain explicit user confirmation.
8. Show plan to userPresent the plan in a concise human friendly way. The user must be able to say yes proceed, or adjust specific steps before tasks are created.
9. Create run and tasksAfter explicit approval, create an AssistantRun with linked AssistantTasks that match the plan. Group parallel work into stepGroup labels.
10. Switch to executionOnce the run and tasks exist, the system moves into execution mode and uses the execution API to perform the work.

16.3 Example planning flow for a Services page

Example when the user says Please create a new webpage called Services.

1. Supervisor identifies that this requires planning because it affects the live CMS and may need design and SEO.
2. Project context confirms the site uses WordPress and has existing navigation.
3. Assistant asks a small set of questions such as language, target audience, and SEO angle.
4. Assistant proposes two or three layout strategies with short descriptions.
5. User picks one and optionally tweaks a detail.
6. Supervisor creates a plan with groups, for example:
   • Group A creative and content draft by Creative Lead and Growth Lead.
   • Group B page creation and layout implementation by Web Engineer based on Group A output.
   • Group C final review and summary by Supervisor.
7. The plan is shown to the user with a simple yes proceed confirmation.
8. AssistantRun and related AssistantTasks are created from this plan.
9. Execution starts and the thinking stream logs planning and task activity in light grey.

16.4 Integration with assistant laws

The planning protocol is where the assistant laws are applied proactively.

• The law of allowed scope is checked when deciding which task types are permitted.
• The law of clarity is enforced when missing requirements are detected and questions are asked.
• The law of transparency is implemented by keeping runs, tasks and thinking entries visible.
• The law of no return is enforced by marking irreversible tasks and requiring explicit user consent.

17. Thinking Stream System

The thinking stream makes the assistant system feel alive and transparent. It reveals high level reasoning steps, routing, planning, checks and execution behavior in a safe compact way. It never exposes unsafe chain of thought. It never reveals internal prompts. It shows only safe structured reasoning summaries intended for the end user.

17.1 Purpose of thinking stream

• Give users confidence by showing what the system is doing.
• Provide real time insight into routing, planning and task execution.
• Make multi agent collaboration visible.
• Provide developers and support staff a clear audit trail.
• Keep the UI dynamic and interactive through collapsible thought previews.

17.2 Thinking message format

Thinking entries use kind set to thinking in assistant_messages.

{
  "kind": "thinking",
  "agentId": "chief",
  "summary": "Checking required inputs for planning",
  "created_at": "timestamp",
  "metadata": {
    "phase": "planning",
    "group": "A"
  }
}

17.3 When thinking entries are generated

• During routing when the Supervisor evaluates which agent or agents to involve.
• During planning when requirements are checked or forks are suggested.
• During run creation when tasks are built or grouped.
• During execution when tasks begin or complete.
• During validation when Supervisor checks outputs before sending the final answer.

17.4 Thinking stream under assistant messages

Each assistant message may include several related thinking entries. To avoid clutter the UI shows only a short adaptive preview.

Preview behavior

• Shows one to three short entries based on available width.
• Auto shrinks to one entry on smaller screens.
• Displays a small arrow to expand the full list.
• Full list appears in a subtle light grey vertical block.

Preview example visible to user:

Thinking summary: Hans checking inputs and identifying required tasks...
Expand to view more

Expanded:
Thinking details
• Hans checking page title
• Hans checking SEO requirements
• Hans listing required tasks for plan
• Hans evaluating reversibility
Collapse

17.5 Thinking stream in run cards

Run cards offer a consolidated view across all agents participating in a run. Thinking entries enrich these cards with detailed insight into multi agent collaboration.

• Entries are grouped by step group A, B or C.
• Entries show the agent and the high level action.
• Long lists are collapsible by default.
• Internal routing logic is summarized in plain language.

Run card example:

Group A
• Hans identifying task set
• Growth Lead evaluating SEO signals
• Creative Lead preparing layout concept

Group B
• Web Engineer creating page structure
• Web Engineer applying template

Group C
• Supervisor validating all outputs
• Supervisor preparing final summary

17.6 Safety rules for thinking logs

Thinking stream must follow strict safety rules.

• No raw chain of thought ever appears.
• No uncertain speculation.
• No internal prompt instructions.
• No self commentary or meta cognitive descriptions.
• No sensitive reasoning about the user or their intentions.
• All thinking entries must be safe summaries of observable actions.

17.7 Developer integration notes

• Create helper appendThinkingMessage that generates structured entries.
• Associate each thinking message with its message and its run when relevant.
• In the UI group and collapse using simple state per message or run card.
• Keep font size small and color light to avoid competing with main content.

18. Related Files and Integration Points

This section serves as a quick reference for developers who work on the assistant system and its integrations.

• app/assistant/AssistantPanel.tsx main panel component
• app/assistant/components/MessageBubble.tsx message rendering including thinking previews
• app/assistant/components/RunCard.tsx run and task display including grouped thinking lists
• app/api/assistant/chat/route.ts chat entry point with routing and planning
• app/api/assistant/execute/route.ts execution entry point with reversibility checks
• supabase/migrations/assistant_conversations.sql conversation storage
• supabase/migrations/assistant_messages.sql user, status and thinking messages
• supabase/migrations/assistant_runs.sql run tracking
• supabase/migrations/assistant_tasks.sql task tracking and link to runs
• supabase/migrations/assistant_agent_definitions.sql optional catalog for agents
• Internal CMS integration modules for WordPress and WooCommerce used by the execution API