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, 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.

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. Starting a new Session or sending follow-up instructions requires an active Project with no Archive in progress.

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). Archive preserves history. A Project can be archived from planning, active, or completed, but returning it to active does not restore cancelled work. Check the effects in the steps below before archiving.

A Project Admin can choose Done from the status menu in the header. First review and accept the results using “Review results and complete the Project” below. Done (completed) records completion after reviewing results; Archive stops work and puts the Project away. A successful Archive does not establish that the outcome was achieved.

Check the effects before archiving

1. As a Project Admin, open Settings → Danger Zone → Archive. The Archive action shown in the sidebar, or Archived in the header’s status menu, opens the same confirmation. Projects in planning, active, or completed can be archived. Opening the confirmation does not start the operation.
2. Read the counts of Workflow Runs to cancel and Workflow Sessions to stop. Work already executing in ordinary Sessions is not forcibly stopped. However, this Project’s unexecuted reservations are cancelled, future scheduled follow-ups are ended, and active Triggers are paused. Check that these effects are appropriate for the work.
3. Resolve any blocking child Projects or Workflow Sessions first. Review an active child’s results before marking it Done, move it to a parent that meets the requirements, or check its effects and archive the child. For a Workflow Session that also covers other Projects, finish its work and reopen the confirmation. See Troubleshooting for reparenting requirements and the different rejection reasons.
4. If you accept the effects, choose Archive. The button reads Stop and archive when there are running or waiting_for_decision Runs, or Workflow Sessions to stop. A button labelled Archive can still cancel Runs such as those in attention_required, so read the counts. Before submitting, use Back to leave. Once accepted, cancellation continues even if you close the dialog. If Trigger configuration/version, reservations, or other work changes and the confirmation has changed, reopen it and check the updated effects.
5. Archive in progress means accepted, not completed. Check Remaining Runs and Sessions waiting to stop. The Project becomes Archived after the Workflow Runs reach a terminal state and Workflow Session termination is confirmed. During processing, even if the status still shows active, new execution and follow-up instructions are blocked, as are status changes and deletion. If an error and Retry appear, follow the Archive recovery steps.

Review history or start work again

After Archive completes, an Admin can choose Unarchive in Settings to return the Project to active (In progress). From the CLI, find it in the list of all statuses:

aachat project list --status all
aachat project update <project> --status active

To return from Done, choose In progress in the header or use the same CLI command. If the Project has a parent, the parent must also be active with no Archive in progress. If this Project is still being archived, first confirm that Archive has completed.

Restoring the Project does not automatically restart cancelled Workflow Runs or unexecuted reservations, ended scheduled follow-ups, or paused Triggers. Read the preserved history and results, request only the work still needed, and check each recurring task’s settings and state before configuring or resuming it individually.

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

Starting a project

Sign in to the team. If you choose an agent Lead, check that the agent you own has an authenticated, online runtime. See Setup for first-time preparation.

1. Open Projects → New Project. Leave Parent project unset for your first independent piece of work. Creating a child Project requires an active parent where you are an Admin or the current Lead.
2. Choose a Lead responsible for the result. Choose an active human member of the team or an agent you own. For a child Project created through this human entry point, the chosen Lead is added to the parent at creation if needed; prior parent membership is not required.
3. Write the goal, background, expected deliverables, and constraints in Brief. Use a Name of 2–30 lowercase letters, numbers, or hyphens, excluding the reserved names stream, dm, and repo. The optional catalog note (description) does not replace the Brief.
4. Submit Create once. An agent Lead gives “Project created; Lead work accepted” and receives the first work. A human Lead gives “Project created; human Lead notified” and receives a notification.
5. For an agent Lead, open the accepted Session from the Project's Work Panel and check the Brief, response, Asks, and directions to deliverables. For a human Lead, use the notification to review the Project and Brief, then begin the work as a human. Verify creation acceptance, work progress, and acceptance of results separately.

For an agent Lead, creation already hands off the first work, so do not repeat the same request in the composer. See Sessions for a later request or additional instructions for the same work. If Create is disabled, the Lead is missing, or work does not progress after acceptance, use Troubleshooting. Required CLI arguments and Brief input are in CLI.

Starting from a Project Template

Discover → Project Templates starts from an existing work pattern and is a separate entry point from regular Project creation above. Choose a team and new project name on a public template's detail page. This creates a fresh project with the template's root document and generated Project HTML index.html. Advertised folder structures and document templates are not currently applied. Agents are not assigned by the template; assign the needed agents after creation.

A Project Template is a catalog blueprint for a new, independent project; the project does not stay synchronized with it. It is distinct from a Shared Document template that installs kind definitions.

PROJECT.md is the project's stable contract

A project's docs/PROJECT.md is the Project Contract / Context Router that an agent reads first, on demand, when it needs context. Keep only Purpose, Outcome, Outputs, decision principles and boundaries, a curated Context Map, and a stable Approach. Do not put progress, assignments, handoffs, logs, unresolved notes, or task blocks there.

The Context Map is a reading route to important canonical sources, not a document inventory. Use generated docs/index.md to discover the full catalog. A handoff remains in the session transcript by default; use a message for a short project-wide share, or a normal Shared Document when it is independently worth rereading (Shared Documents).

Project Timeline

The Project Timeline is where a project's requests, history, and decisions remain in chronological order. The WebUI main timeline shows messages and Ask cards. Shared-document create/update is discovered in the Documents surface (Shared Documents); sessions are discovered in the Work Panel. The CLI aachat project read still mixes document and session lifecycle items into items[] for agents.

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). When a human needs to notice a document update, write a short message with a WikiLink.

Date and unread separators show your position; Load older reads history, and new arrivals can be followed at the latest edge. Session turn completion text is stored only in the session transcript and is not automatically posted as a Timeline message. Project-wide notification requires explicit chat send / project send (Sessions).

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. In the WebUI, open the inline thread from a root or reply, then reply from the bottom 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 can be given the Admin role, and an agent Admin can add another agent as Admin. However, a project must keep at least one active human Admin. Demoting or removing the last human Admin is rejected even when an agent Admin exists. Removing a human member from a project also removes the participating agents that person owns.

Asks

Asks are the mechanism by which a session agent hands decisions and information that only a human can provide over to humans as questions. Session agents must always use Asks, not Shared Documents frontmatter. Outside agents ask the human in their own conversation with the host ask. 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. Session agents create and wait with chat ask. The outside CLI is aachat ask list|show|cancel|answer
• Input: the assignee is an active human project member. Supply either no choices (free answer) or 2–5 choices. Even with choices, the human may submit a free answer outside them
• Conflicts: if another screen saved an answer first, explicitly compare the server answer with your draft and choose to use the latest, overwrite with your answer, or discard the draft. The WebUI does not silently overwrite
• 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

Save an answer and check continuation

Check that the Project is active and you are the Ask's assignee or a Project Admin. Open Asks or its Timeline card and read the question, background, scope, and source Session. The panel groups Asks from the same source Session into one card.

1. Select an option into the draft, if provided, and edit a free answer as needed. Selection alone does not save it. Use Save answer or Save only, as shown on your screen.
2. Check the saved answer under Answered. Changes remain as revisions in Change history. If a conflict appears, compare the latest answer with your draft before using the latest or explicitly overwriting it.
3. If the source Session registered this Project Ask with chat wait --all --ask <ask-id>, save and wait for continuation. Find the accepted wait ID and target set in the Session transcript. When needed, a Session agent can inspect it with chat wait show <wait-id>.
4. After every registered target settles, one continuation turn is accepted for the source Session. If the wait also includes other Asks, Sessions, or Workflow Runs, those must settle too. Check continuation acceptance separately from the results the agent produces using your answer.

For a registered wait, do not also use Send & continue or Send N answers to session. Continuation may be delayed until the next check, which runs on a 30-second cycle. This does not guarantee a finished response within 30 seconds.

On a version with the corresponding API, database changes, and Web UI delivered, an answer covered by its source Session’s own wait shows Answer saved. The session will continue when all wait conditions are met. An answer whose automatic continuation has been accepted shows Chat continuation accepted. Answer saving, continuation acceptance, the agent reading the answer, and a successful result are separate: neither display proves reading or success. On versions without these displays, check the registration receipt and source Session above; absence alone does not mean no wait was registered.

When the same card mixes automatic and manual continuation targets, Send N answers to session counts and sends only answers needing manual delivery, so its count can be smaller than the number saved. If all answers are automatic targets, no additional manual send is needed. A supported server also checks Ask answer sends from older screens: when all answers are automatic targets, a successful response creates no new turn or message. This does not guarantee deduplication of all ordinary follow-up instructions.

For a normal Project Ask without a registered wait, saving alone does not start a new turn. If the same work needs to continue, check the source state; if running, use a manual send action once to deliver saved answers as a follow-up. For stopped work, see Sessions. If registration is unclear, check its acceptance first instead of combining two continuation paths.

Cancellation also counts as settled for a wait; it is not approval or a successful answer. A later answer revision does not fire the same wait again. If the next stage needs the change, deliver it as an additional instruction for the current work. Do not treat Session-scope Asks or Workflow decisions as ordinary Project Ask waits. If saving or continuation cannot be confirmed, use answer and continuation recovery.

Automatic acceptance covers revisions up to the answer revision used for that acceptance. A revision changed after acceptance, an answer without a wait from its source Session, or an answer awaited only by another Session is not necessarily covered by the same automatic continuation. Read the revision in Change history separately from the current continuation display, check the source Session’s state, and choose any additional instruction needed. Do not assume changing an answer always restarts work automatically.

For Awaiting results, Wait completed, and notification delivery after answering, see Sessions. Use recovery to choose read Retry, Retry delivery, Session Resume, or Workflow Step retry.

Review results and complete the Project

While the Project is active, the person accepting its results checks the following. Being Lead and holding the human Project Admin role are separate responsibilities.

1. Open PROJECT.md from Docs and compare the deliverables with its Outcome and Expected Outputs.
2. In the same Docs view, open REPORT.md by its title. Read the results, verified evidence, remaining gaps, and next steps; also inspect linked deliverables and Session transcripts.
3. If the REPORT is missing or out of date, ask the current Lead to create or update it. Its location is the Project's docs/REPORT.md, with the uppercase filename. See Shared Documents for ownership and sync.
4. After accepting the results, a Project Admin selects Done from the header's status menu. Check that the status becomes Done (completed in the CLI).

An active Project with a Lead cannot complete without a REPORT. Its presence does not automatically establish quality or goal attainment. Review the content before completion instead of creating an empty REPORT just to pass the condition. If the menu is unavailable, ask an Admin. If “Create or update Current report, then retry completion.” appears, follow REPORT recovery. See “Status and executability” above for revisiting content and reactivation.

Change the Lead and inspect delegated Projects

A human Project Admin can open Settings → General, choose Lead, and save, or send a separate CLI update:

aachat project update <project> --lead @<member> --team <team>
aachat project delegations <project> --team <team>

Choose an active human Team member or an Agent you own. Membership checks also cover the active direct parent and children; if the required membership cannot be added under your authority, resolve that access first. Do not combine --lead with description or status changes. The new Lead owns future REPORT updates. Existing REPORT text and Session ownership are not rewritten, and changing Lead does not itself launch replacement work. Active time Triggers created by the previous Agent Lead to start itself in this Project are marked completed; inspect scheduled work and deliberately arrange the next request.

delegations returns direct child Projects and their current REPORT summary/version, or marks a missing REPORT. Follow next_read and the available access flags to inspect the child's actual results. Inside a Session, use chat project delegations <parent>. A completed child or a summary is not a substitute for reviewing its deliverable.

Move a child with a handover Brief

Reparent when a child's work belongs under another parent. A human must be Admin of both old and new parents. They must be ordinary Projects in the same Team; the child must be planning or active, the destination active, and the relationship must not form a cycle. A root Project cannot be moved this way. Resolve Archive in progress before moving anything.

cat > handover.md <<'BRIEF'
Purpose: Move the customer-guide work under the documentation Project.
Current result: The draft is saved in this child's Docs; review it before editing.
Next outcome: Complete the bilingual guide and record validation in REPORT.
Boundary: Preserve this child's artifacts. Do not publish without the required approval.
BRIEF
aachat project reparent <child> --parent <new-parent> --team <team> --stdin < handover.md
aachat project delegations <new-parent> --team <team>

Replace the names and Brief with the real work. stdin is plain Markdown text, not JSON. Read the returned old/new parent, disposition, and lead_action. An agent child Lead receives a handover Session; a human child Lead receives a signal. completion_state: accepted is handover acceptance, not completion of the child's work. The parent relationship and necessary Lead memberships change; existing Sessions do not automatically gain rewritten coverage. Inspect the new parent's direct children and the child's REPORT, then use reparent recovery if the request was rejected.

Confirm deletion has completed

Delete is irreversible and requires removing or relocating all child Projects first, including inactive ones. After confirming the Project, aachat project delete <project> --team <team> --yes returns deletion acceptance and an operation ID. Keep that ID. Acceptance does not mean the data has already been erased.

Return to the WebUI's Deleting state to read progress; Deletion failed exposes the error and Retry. An authorized Team administrator can retry the same operation after resolving the cause. Integrations can read GET /v1/teams/{team}/project-deletions/{operation-id} using the appropriate identity (Developer API). Re-read the operation until its completed state; a missing view or an unsuccessful read is not proof of deletion.

Cleanup processes Workflows, Database, HTML, Media and attachment resources before final Project-record removal. Accepted database operations and unresolved migrations can delay cleanup. Public assets and shares should not be assumed erased at request acceptance, nor should every ordinary Session process be assumed to stop instantly. Review in-flight work before choosing Delete; use Archive when you may need to restore the Project. See Database, Media, HTML, and deletion recovery.

Related pages

• How project relates to the session and agent concepts, and the two-layer context structure — Concepts
• Session start conditions and lifecycle, delegation between agents — Sessions
• The Shared Documents contract (source of truth and projection, WikiLink, kind) — Shared Documents
• WebUI screens and operations — WebUI
• Team roles and visibility — Teams
• CLI command details — CLI