Summary
Provide a curated SoarAgents.md file documenting the agentic Soar development cycle (how an LLM/agent should use the extension's MCP tools, datamap/layout conventions, and runtime debugging workflow). The extension distributes this file into user projects so coding agents pick it up automatically, with explicit controls so the extension never silently overwrites user edits.
Goals
Give agents working in a Soar project a reliable, version-controlled description of the intended development workflow.
Distribute it through the extension (single source of truth), not by hand-copying.
Keep the user in control: opt-in placement, and consent before any overwrite.
Behavior
-
Bundled template
The canonical SoarAgents.md content ships with the extension as the source of truth (embedded constant, mirroring DEFAULT_SOARIGNORE_CONTENT in src/layout/soarIgnore.ts). It carries a version marker (e.g. an HTML comment with the extension version) so later updates can be detected.
-
Explicit command
A new command — soar.addAgentsFile ("Soar: Add SoarAgents.md to Project") — writes SoarAgents.md to the workspace root on demand. If the file already exists, it asks before overwriting.
-
Setting: write on project creation
A new setting soar.createAgentsFile (boolean). When enabled, project creation (src/layout/projectCreator.ts) writes SoarAgents.md automatically alongside the existing default .soarignore, only if absent.
-
Update notification
When the extension activates after an update (detected by comparing the stored extension version in globalState against the running package.json version) and the workspace already contains a SoarAgents.md whose embedded version is older than the bundled one, the extension shows a notification:
"SoarAgents.md has an updated version available. Overwrite the project copy?" — [Overwrite] [Show Diff] [Dismiss]
The file is only replaced if the user explicitly confirms. Dismiss leaves the existing file untouched and does not nag again for that version.
Controls / safety invariants
Never overwrite SoarAgents.md without explicit user confirmation (command, creation-time absence check, or update-notification consent).
Respect the soar.createAgentsFile setting; recommended default on (only writes when the file is absent).
The version marker is the basis for both the "is an update available" check and the "skip if already current" behavior.
Files likely touched
New: src/layout/agentsTemplate.ts — SOAR_AGENTS_MD_CONTENT + version constant + write/version-compare helpers.
src/layout/projectCreator.ts — creation-time write gated by setting.
src/extension.ts — register soar.addAgentsFile; run the post-update check via context.globalState.
package.json — contribute command + soar.createAgentsFile setting.
CLAUDE.md — update Project creation, commands/settings, and Data persistence sections.
Open questions
Summary
Provide a curated SoarAgents.md file documenting the agentic Soar development cycle (how an LLM/agent should use the extension's MCP tools, datamap/layout conventions, and runtime debugging workflow). The extension distributes this file into user projects so coding agents pick it up automatically, with explicit controls so the extension never silently overwrites user edits.
Goals
Give agents working in a Soar project a reliable, version-controlled description of the intended development workflow.
Distribute it through the extension (single source of truth), not by hand-copying.
Keep the user in control: opt-in placement, and consent before any overwrite.
Behavior
Bundled template
The canonical SoarAgents.md content ships with the extension as the source of truth (embedded constant, mirroring DEFAULT_SOARIGNORE_CONTENT in src/layout/soarIgnore.ts). It carries a version marker (e.g. an HTML comment with the extension version) so later updates can be detected.
Explicit command
A new command — soar.addAgentsFile ("Soar: Add SoarAgents.md to Project") — writes SoarAgents.md to the workspace root on demand. If the file already exists, it asks before overwriting.
Setting: write on project creation
A new setting soar.createAgentsFile (boolean). When enabled, project creation (src/layout/projectCreator.ts) writes SoarAgents.md automatically alongside the existing default .soarignore, only if absent.
Update notification
When the extension activates after an update (detected by comparing the stored extension version in globalState against the running package.json version) and the workspace already contains a SoarAgents.md whose embedded version is older than the bundled one, the extension shows a notification:
"SoarAgents.md has an updated version available. Overwrite the project copy?" — [Overwrite] [Show Diff] [Dismiss]
The file is only replaced if the user explicitly confirms. Dismiss leaves the existing file untouched and does not nag again for that version.
Controls / safety invariants
Never overwrite SoarAgents.md without explicit user confirmation (command, creation-time absence check, or update-notification consent).
Respect the soar.createAgentsFile setting; recommended default on (only writes when the file is absent).
The version marker is the basis for both the "is an update available" check and the "skip if already current" behavior.
Files likely touched
New: src/layout/agentsTemplate.ts — SOAR_AGENTS_MD_CONTENT + version constant + write/version-compare helpers.
src/layout/projectCreator.ts — creation-time write gated by setting.
src/extension.ts — register soar.addAgentsFile; run the post-update check via context.globalState.
package.json — contribute command + soar.createAgentsFile setting.
CLAUDE.md — update Project creation, commands/settings, and Data persistence sections.
Open questions