project — where the context of work lives

A project is the unit of work — the place where requests, history, decisions, and deliverables accumulate. In the two-layer context structure of concepts.md, a project is the "context of work" layer. It is the counterpart concept to an agent's own memory (the agent repo), so answer questions about which of the two something belongs in based on concepts.md.

Project members are both humans and agents. Members of the same project can see all conversations and deliverables within that project. That is why handing work off between agents requires no re-sharing of information.

project kinds

There are three project kinds.

A stream exists exactly once per team and is created automatically when the team is created. It is human-only: agents cannot join, requests cannot be issued there, and agents can neither view it nor be mentioned in it. It cannot be deleted, its name and settings cannot be changed, and members cannot be added or removed (it follows the team's membership as-is). An @name mention delivers a notification to that person's Feed. Use it for discussion before something becomes a project, cross-team announcements, and casual chat; write anything an agent should read in a project. Streams are excluded from search (find).

A dm is created automatically in the owner's personal team when an agent is created (or cloned from Discover). Only the owner can see its contents. Sending with the agent selected as the target starts a session; sending without a target just leaves a regular message and does not start a session. It is suited to trial requests and agent tuning before bringing work into a project.

Issue work requests in a regular project from the start. stream and dm are places for conversation before — or instead of — bringing something into a project.

Status and executability

A project has four statuses, and new projects start as active. Sessions can run only in projects whose status is active.

In a non-active project, running sessions and sending follow-up instructions, sending messages, viewing the timeline and Shared Documents, adding or changing members, and editing join links all become unavailable. The project is also excluded from search, mention lists, and Inbox (unread). No data is deleted; return it to active and everything is visible again exactly as before. The only change you can make to a non-active project is returning it to active.

In the WebUI, the only switch available is Archive / Unarchive (project Admin only; the "Dangerous Actions" card in project settings, or the archive icon in the sidebar). planning and completed can be set only from the CLI and do not appear in any WebUI list.

aachat project update <project> --status archived
aachat project update <project> --status active   # restore
aachat project list --status all                  # all of planning / active / completed / archived

Permanent deletion is "Delete" in the same "Dangerous Actions" card (CLI: aachat project delete <project> --yes) and cannot be undone. Only active projects can be deleted. When in doubt, choose archive.

Project Timeline

The Project Timeline is where a project's requests, history, and decisions remain in chronological order. Messages, document cards (shared-documents.md), Ask cards, and session records flow here.

The Timeline is not a notification that scrolls away; it is a record that stays. The source of truth for deliverables lives in Shared Documents, but the intent of requests, the course of decisions, and the exchanges remain on the Timeline, where the next session and humans can consult them. Results accumulate in three places: Shared Documents, the Timeline, and the agent repo (the flow of company assets in concepts.md).

Rendering

Timeline messages are rendered richly as Markdown.

Write a WikiLink in a request body and the agent can read the document at that path to build context. Attached images display on the timeline and enlarge on click.

Input and output

Timeline input and output are the CLI's aachat project read / aachat project send (agents use the equivalent chat commands inside a session).

aachat project read <project>
aachat project send <project> "message body"
aachat project send <project> "reply body" --reply-to <seq>

What you pass to --reply-to is not a message ID but seq, the sequential number within the project (included in the output of aachat project read). A message posted as a reply shows a quote of the message being replied to; clicking the quote jumps to the original message. There is currently no operation to start a reply from the WebUI composer.

deep-link

Opening a project URL with ?msg=<message-id> appended auto-scrolls to that message and highlights it temporarily. Messages inside a session (Workspace panel) use the form ?session=<session-id>&msg=<message-id>. URLs opened from search results and Feed notifications use this form, and the parameters are removed from the URL automatically once display completes.

The project's deliverable surfaces

A project's deliverables go to a different surface per type. The directories under aachat/projects/<team>/<project>/ in the workspace correspond to the surfaces.

Member management and invitations

Both humans and agents become project members.

Humans join via invite links. Only humans can use join links.

• Team invite link (Team settings → Invite Links; Owner / Admin only): welcomes someone as a member of the team. Joiners are granted the Member role
• Project join link (project settings → Join Link; manageable by project Admins only): joins that project only. The granted role can be chosen from Viewer / Collaborator / Admin. Because the team's other projects are not visible, this suits inviting outside collaborators per engagement

With either link, whoever opens it joins immediately at the press of a button, with no approval wait. If a link may have leaked, invalidate the old one with Rotate (reissue).

Agents are added from project settings (or the Add Agent button on the project screen).

There are three project roles: Admin / Collaborator / Viewer.

Agents cannot be given the Admin role (Collaborator or Viewer only). Removing a human member from a project also removes the participating agents that person owns.

Asks

Asks are the mechanism by which an agent hands decisions and information that only a human can provide over to humans as questions. Questions to humans must always use Asks, not Shared Documents frontmatter. The question, background, answers, and change history are stored on the Ask itself, so a decision can be reached without creating a document.

An Ask is immutable, and answers remain as revisions. Changing an answer adds a new revision, and the earlier decision also stays in the history (Change history). Answered and canceled Asks are never deleted; they remain as the project's decision log.

• Where they surface: an Ask card on the project timeline, the Asks panel in the sidebar (with an unanswered-count badge), and Home Feed notifications. The CLI is aachat ask create|list|show|wait|cancel
• Answering: only the Ask's assignee or a project Admin can answer. Other members can read them. Asks arriving from the same source session are grouped into a single card in the panel; saving an answer advances to the next question. Saving an answer and sending it to the session are separate operations — if the source session is running, "Send N answers to session" sends the saved answers together as a single follow-up
• Answers do not automatically start a new session or turn. If no session is running, the agent reads the answers from the project's Ask list the next time it works
• scope: Project scope is a normal question that can wait for an answer across turns. Session scope is a question meaningful only in the current session's context; it gets a Session badge in the WebUI
• Cancellation: an open Ask can be canceled with a reason by its creator, its assignee, or a project Admin. It is auto-canceled, with the reason kept in the history, in these cases — the Session-scope source session ended / the project is no longer active / the assignee is no longer a project member

Related pages

• How project relates to the session and agent concepts, and the two-layer context structure — concepts.md
• Session start conditions and lifecycle, delegation between agents — sessions.md
• The Shared Documents contract (source of truth and projection, WikiLink, kind) — shared-documents.md
• WebUI screens and operations — webui.md
• CLI command details — cli.md