SharedContext works best as part of the work itself. On session_open, the connected AI receives the Project Management Agent role and follows one compact loop: Maintain → Converge → Execute → Context update. It reads Context before relying on assumptions, does approved work rather than only describing it, and preserves what future work should know.
Open once
Start substantive work with session_open. It establishes the session and returns the versioned role contract plus the indexes that orient the Agent. Do not repeatedly open new sessions for the same conversation.
Converge on the active scope
For project work, the Agent uses an existing source of truth when the project declares one. Otherwise it drafts work/active-scope.md from current Context with the current goal, state, decisions and constraints, active and excluded scope, next actions, open questions, and completion criteria. The goal, active scope, and completion criteria remain draft until the user approves them.
Log as work completes
Use session_log when a meaningful unit finishes. Good session logs track completed steps, user-confirmed decisions, Agent proposals, assumptions, open questions, and active workstreams as different states. They are operational memory, not a polished knowledge base.
Search before recreating
If the needed Context is not in the returned indexes, use knowledge_search. Search before writing a document that may already exist and before asking the user to repeat a past decision.
Read before relying
Indexes and search results are pointers. Use knowledge_read to load a document's full content before treating it as the current decision or convention.
Clarify authority before execution
If Context does not identify who confirmed a decision, or if two records conflict, do not silently choose one. Surface the conflict and ask the user for the judgment required to continue. SharedContext preserves scope and revision history; it does not currently enforce a server-side confirmation state machine.
Execute the approved work
Use the host AI tool to perform the work the user approved. SharedContext is not a separate project-management interface and does not authorize an Agent to invent goals, scope, priorities, or completion conditions.
Preserve what deserves a future
Use knowledge_write when something should outlive the session: a confirmed decision, convention, stable finding, or project state another session will need. Use knowledge_edit for a narrow change. After work changes the current truth, update the source-of-truth document, and if the scope's index.md narrative mentions it, update that mention too so a later session does not see stale active state. Both tools return related_documents (identifiers only) when the change might affect nearby documents on the same topic — check those, this scope's index.md narrative, and anything the document explicitly links; see Organizing Context for how far that check should go.
If this disappeared when the chat closed, would a future Agent make a worse decision or force the user to explain it again? If yes, preserve it.
Recover after compaction
Use session_map to read the latest working record and continue from it instead of rebuilding the session from chat history.
Promote personal work safely
Long-running private work uses a fixed personal path such as state/<workstream>.md. When it starts affecting shared project decisions, load SharedContext Maintenance and use knowledge_promote. It creates and verifies the project copy while the personal original stays active; any failure rolls the copy back. Agents never delete Context — removing the personal document afterwards is an explicit action you take in the Superself web app.
Coordinate parallel work
Each session_brief_write declares a unique workstream id, scope and exclusions, concrete change targets, dependencies, and completion criteria. Superself rejects a new brief when its id or targets overlap active work. A child closes with session_report_write, including changed targets, decisions, open conflicts, and promotion candidates. The coordinating session resolves reports and updates the Active Project Scope and project index once.
Report progress milestones
After evidence exists, the Agent calls project_progress for current_truth_recovered, active_scope_committed, work_advanced, and context_updated. The active-scope milestone requires explicit human approval and a written scope document; the context-update milestone requires a recorded next action. Analytics stores counts and booleans, never Context content. Because these milestones are self-reported by the Agent, they are recorded as unverified agent assertions and kept separate from server-verified metrics such as reused_7d, which the server records automatically when a new session_open happens within seven days of the first.