War Room Guide¶
War Rooms are structured discussion threads for project decisions that benefit from more than one point of view. SynContext is shared project memory for Claude and other MCP-compatible clients, so a War Room can keep the debate attached to the same project context instead of spreading it across separate chat windows. Use a room when you want participants to argue for, against, or around a proposal, cite project entries or decisions, and end with a resolution that can become part of the project record.
A room can be manual, with people and MCP clients posting messages, or it can later be used with Autopilot for automated model turns. This guide focuses on the manual workflow: create a room, read it, post messages, and resolve it when the decision is clear.
When to Use a War Room¶
Use a War Room for choices where ordinary notes are too flat. Good candidates include architecture decisions, code review disputes, security tradeoffs, implementation plans, product tradeoffs, and cases where a team needs to preserve why a decision was made. A room is also useful when you want the same project memory visible to different MCP-compatible clients without asking each client to reconstruct the background from scratch.
Do not use a room for short status notes, private secrets, provider API keys, or one-off facts that belong in a normal context entry. War Rooms are designed for reasoning and resolution. If the outcome is already known, store a decision directly instead.
Core Flow¶
Create a Room¶
Create a room inside a project with a title, an optional topic, and a template. The title should name the decision or dispute, not the desired answer. The topic can include the background, constraints, links to project entries, and the question participants should answer.
The default template is free-form. Free tier users can create one open room per project and can use free-form. Pro and Team users can create unlimited rooms per project and can use the structured templates listed below. The implementation enforces these limits from config.py: war_rooms_per_project is 1 for Free and -1 for Pro and Team, where -1 means unlimited.
Read the Room¶
Reading a room returns its messages, status, template, and consensus data. Pro and Team rooms can include project context such as recent entries, recent decisions, and linked repository information. Free rooms remain useful as a shared thread, but they do not expose the richer project-context injection used by paid tiers.
Clients can poll with after_message_id so they only receive newer messages after the last message they have already seen. That keeps a long debate manageable when several participants are posting.
Post Messages¶
Each message has content, a source, an optional stance, and optional references. The source should identify the participant, such as a human, Claude, ChatGPT, a code executor, or another MCP-compatible client. Content is the actual argument or evidence.
References let a participant point back to SynContext entries or decisions. Use them when a claim depends on project memory. A reference is more useful than a vague statement like "we decided this before" because it gives reviewers a path back to the source.
Message limits are enforced per room: Free has 10 messages, Pro has 50, and Team has 500. When a room reaches its limit, no more messages can be posted until the plan changes or a new room is created.
Resolve the Room¶
Resolve a room when the discussion has reached a clear outcome or when the owner decides to close the debate. A resolution should state the chosen direction, the reason, and the main alternatives rejected. If the resolution represents a durable project decision, create a decision from it during the resolve step.
Resolved rooms become part of the project history. Free accounts can see the last 3 resolved rooms. Pro and Team can keep full resolved-room history according to the current tier limits.
Stances and Consensus¶
War Rooms support four stances: for, against, neutral, and synthesis.
Use for when a message supports the proposal being debated. Use against when it argues that the proposal should not proceed or needs a materially different design. Use neutral for evidence, clarifying questions, or analysis that does not take a side. Use synthesis when a message integrates several positions into a recommendation or compromise.
Stance tracking is available on Pro and Team. On Free, submitted stances are accepted by the interface but stored as null, so the thread remains readable without treating stance data as authoritative. Consensus is calculated from stored stances when the room is read; it is not a permanent value that must be manually maintained.
Templates¶
Templates shape the room and help participants adopt useful roles.
free-form is open discussion. Use it when the topic is exploratory or when the structure is not known yet.
architecture-decision is for technical choices such as data models, service boundaries, queue design, tenancy, or deployment strategy. It works well with a proposer, a challenger, and a synthesis message.
code-review is for implementation disputes. It is useful when one participant defends the design and another reviews for bugs, regressions, missing tests, and maintainability.
security-audit is for auth, secrets, SSRF, webhooks, billing, tenant isolation, encryption, and public exposure. Use this template when the cost of being wrong is high.
implementation-plan is for sequencing work before execution. It should produce a plan that is specific enough for an executor to follow and constrained enough for reviewers to verify.
Free supports free-form. Pro and Team support free-form, architecture-decision, code-review, security-audit, and implementation-plan.
MCP Tools¶
The manual War Room workflow is exposed through five MCP tools.
hub_create_war_room creates a room for a project. Required inputs are project_id and title; optional inputs include topic and template.
hub_list_war_rooms lists rooms for a project and can filter by open, resolved, or all.
hub_read_war_room reads the room, messages, consensus data, and tier-appropriate context. Use after_message_id for polling.
hub_post_war_message adds a message with content, source, optional stance, and optional references.
hub_resolve_war_room closes the room with a resolution and can create a formal decision when the outcome should be retained as decision history.
Limits¶
| Capability | Free | Pro | Team |
|---|---|---|---|
| Open rooms per project | 1 | Unlimited | Unlimited |
| Messages per room | 10 | 50 | 500 |
| Resolved room history | Last 3 | Full history | Full history |
| Templates | free-form |
All templates | All templates |
| Stance tracking | Stored as null | Enabled | Enabled |
| Markdown export | Not included | Not included | Included |
These values must match context_hub/config.py. In the current implementation, war_room_messages is 10 for Free, 50 for Pro, and 500 for Team. war_rooms_per_project is 1 for Free and unlimited for Pro and Team.
Example: Architecture Decision¶
A useful architecture-decision room might be titled Choose repo sync strategy. The topic should include the current problem, expected load, failure modes, and constraints. One participant can argue for polling because it is simpler and easier to retry. Another can argue for webhooks because latency matters and repeated polling wastes quota. A synthesis message can recommend a hybrid plan, such as webhook-first with polling fallback, and list the verification work needed before execution.
The final resolution should be concise: what will be built, what will not be built, and what evidence would reopen the decision later.
Privacy and Export¶
War Room topics, messages, and resolutions are stored as encrypted application data. References point to project entries or decisions, but the message text should still avoid secrets, credentials, private keys, access tokens, and sensitive production data. Treat a room as durable project memory, not a scratchpad for secret handling.
Team export produces a markdown record with room metadata, messages, and resolution. Export is intended for audit trails, design reviews, and sharing with a team that already has permission to see the project context.
Troubleshooting¶
If room creation fails, check the template and open-room limit. Free accounts can create one open room per project and only use free-form.
If a message cannot be posted, check whether the room is still open and whether the message limit has been reached. The enforced limits are 10, 50, and 500 messages per room for Free, Pro, and Team.
If stance data is missing on Free, that is expected. Free rooms keep the conversation, but stance tracking is not persisted.
If a client cannot see new messages, read the room without after_message_id once to reset local state, then resume polling from the newest message id.
If a resolution should become a durable project decision, use the resolve option that creates a decision and provide a decision title that will still make sense later.
Writing Useful Room Prompts¶
A strong room topic gives participants enough context to disagree productively. Include the current state, the proposed change, constraints that cannot move, and the evidence you already have. If there are known risks, name them instead of hoping a participant will infer them. For code-related rooms, include the branch, pull request, files, failing tests, and acceptance criteria. For product or policy rooms, include the user impact and the decision deadline.
Keep the question narrow. A topic like Should we change the sync architecture? is harder to resolve than Should repository sync use webhook-first delivery with polling fallback for missed events? Narrow topics make stances meaningful and make the final resolution easier to audit.
When a participant cites SynContext memory, prefer explicit references to entries and decisions. A message that cites Decision D#42 or a specific context entry is easier to verify than a message that only describes past consensus. If evidence changes during the debate, post the new evidence as a message instead of editing the original topic.
Resolution Checklist¶
Before resolving, check that the room has answered the original question, not a broader or easier one. Confirm that the strongest against argument was addressed, that the chosen path has an owner or next step, and that the resolution says what would cause the decision to be revisited.
A good resolution usually has four parts: the decision, the reason, the rejected alternatives, and the follow-up work. If you create a formal decision from the room, use a title that can be understood without reopening the full debate.