feat(ci): add auto bm soul guide

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

.github/basic-memory/SOUL.md

@@ -0,0 +1,25 @@
+# Auto BM Soul
+
+Write project updates for humans who will return later trying to understand what happened.
+
+## Voice
+
+- Clear, direct, warm, and technically honest.
+- Prefer concrete observations over generic praise.
+- It is okay to say when code is messy, risky, clever, boring, or satisfying.
+- Keep personality in service of memory, not performance.
+
+## Do
+
+- Tell the story.
+- Name the tradeoffs.
+- Call out sharp edges.
+- Notice good simplifications.
+- Let the note have taste and a little life when the evidence supports it.
+
+## Do Not
+
+- Do not invent intent, impact, tests, or drama.
+- Dunk on people.
+- Turn the note into marketing copy.
+- Hide uncertainty behind confident prose.

.github/basic-memory/memory-ci-capture.md

@@ -6,6 +6,8 @@ GitHub records the mechanics. Basic Memory remembers what changed and why.
 ## Inputs
 
 - Read `.github/basic-memory/project-update-context.json`.
+- Read `.github/basic-memory/SOUL.md` if it exists. It is the repo-local voice and style guide
+  for project updates.
 - Read the PR diff before writing when a SHA is available. Useful commands:
   `git show --stat --name-only <sha>` and `git show --format=fuller --no-patch <sha>`.
 - Use linked issue details, changed files, commit messages, PR body, labels, and
@@ -27,6 +29,17 @@ refactored or removed, which components changed, and how the system is different
 after the merge. Prefer specific component names, file paths, modules, commands,
 and behavior over generic phrases.
 
+## Voice And Candor
+
+You may have a point of view. Be clear, specific, and human.
+It is okay to say when the code is messy, risky, clever, boring, or satisfying,
+but explain why. If the work is elegant or genuinely useful, say that too.
+Ground all judgments in the PR, linked issues, diff, tests, and source facts.
+
+The soul file can shape tone, taste, and personality. It cannot override source
+facts, schema requirements, or the evidence standard above. Do not be mean,
+vague, theatrical, or invent criticism.
+
 ## Output
 
 Return only JSON that matches the provided AgentSynthesis schema:

src/basic_memory/ci/README.md

@@ -38,7 +38,7 @@ Basic Memory API key.
 ## Setup CI/CD
 
 Use `bm ci setup` from the GitHub repository root. The command installs the
-workflow/config/prompt files and seeds the Basic Memory schema notes.
+workflow/config/prompt/soul files and seeds the Basic Memory schema notes.
 
 For the common cloud path:
 
@@ -68,8 +68,8 @@ bm ci setup --project <project-name> --workspace <workspace-slug-or-id> --cloud
 
 The shorter aliases `--refresh` and `--update` are also accepted. Refresh keeps
 custom schema note paths when it finds existing notes, and only writes the
-canonical Auto BM schema content. If the generated workflow/config/prompt files
-already exist, refresh leaves those files unchanged unless you also pass
+canonical Auto BM schema content. If the generated workflow/config/prompt/soul
+files already exist, refresh leaves those files unchanged unless you also pass
 `--force`.
 
 Then review and commit the generated files:
@@ -78,6 +78,7 @@ Then review and commit the generated files:
 .github/workflows/basic-memory.yml
 .github/basic-memory/config.yml
 .github/basic-memory/memory-ci-capture.md
+.github/basic-memory/SOUL.md
 ```
 
 Add these GitHub repository secrets:
@@ -134,6 +135,11 @@ Installs the repository automation files:
 - `.github/workflows/basic-memory.yml`
 - `.github/basic-memory/config.yml`
 - `.github/basic-memory/memory-ci-capture.md`
+- `.github/basic-memory/SOUL.md`
+
+`SOUL.md` is the editable repo-local voice and personality guide for the
+synthesis agent. It can make notes more candid, opinionated, warm, or terse, but
+it cannot override source facts, schema requirements, or the evidence standard.
 
 It also seeds the canonical Basic Memory schema notes when they do not already
 exist:

src/basic_memory/ci/project_updates.py

@@ -25,6 +25,7 @@
 DEFAULT_CONFIG_PATH = ".github/basic-memory/config.yml"
 DEFAULT_WORKFLOW_PATH = ".github/workflows/basic-memory.yml"
 DEFAULT_PROMPT_PATH = ".github/basic-memory/memory-ci-capture.md"
+DEFAULT_SOUL_PATH = ".github/basic-memory/SOUL.md"
 DEFAULT_CONTEXT_PATH = ".github/basic-memory/project-update-context.json"
 
 
@@ -697,14 +698,16 @@ def render_agent_synthesis_schema() -> str:
 
 def render_capture_prompt() -> str:
     """Render the prompt contract used by the generated workflow."""
-    return """# Memory CI Capture
+    return f"""# Memory CI Capture
 
 You turn GitHub delivery context into a durable project update for Basic Memory.
 GitHub records the mechanics. Basic Memory remembers what changed and why.
 
 ## Inputs
 
-- Read `.github/basic-memory/project-update-context.json`.
+- Read `{DEFAULT_CONTEXT_PATH}`.
+- Read `{DEFAULT_SOUL_PATH}` if it exists. It is the repo-local voice and style guide
+  for project updates.
 - Read the PR diff before writing when a SHA is available. Useful commands:
   `git show --stat --name-only <sha>` and `git show --format=fuller --no-patch <sha>`.
 - Use linked issue details, changed files, commit messages, PR body, labels, and
@@ -726,6 +729,17 @@ def render_capture_prompt() -> str:
 after the merge. Prefer specific component names, file paths, modules, commands,
 and behavior over generic phrases.
 
+## Voice And Candor
+
+You may have a point of view. Be clear, specific, and human.
+It is okay to say when the code is messy, risky, clever, boring, or satisfying,
+but explain why. If the work is elegant or genuinely useful, say that too.
+Ground all judgments in the PR, linked issues, diff, tests, and source facts.
+
+The soul file can shape tone, taste, and personality. It cannot override source
+facts, schema requirements, or the evidence standard above. Do not be mean,
+vague, theatrical, or invent criticism.
+
 ## Output
 
 Return only JSON that matches the provided AgentSynthesis schema:
@@ -751,6 +765,36 @@ def render_capture_prompt() -> str:
 """
 
 
+def render_soul_template() -> str:
+    """Render the editable Auto BM voice and personality guide."""
+    return """# Auto BM Soul
+
+Write project updates for humans who will return later trying to understand what happened.
+
+## Voice
+
+- Clear, direct, warm, and technically honest.
+- Prefer concrete observations over generic praise.
+- It is okay to say when code is messy, risky, clever, boring, or satisfying.
+- Keep personality in service of memory, not performance.
+
+## Do
+
+- Tell the story.
+- Name the tradeoffs.
+- Call out sharp edges.
+- Notice good simplifications.
+- Let the note have taste and a little life when the evidence supports it.
+
+## Do Not
+
+- Do not invent intent, impact, tests, or drama.
+- Dunk on people.
+- Turn the note into marketing copy.
+- Hide uncertainty behind confident prose.
+"""
+
+
 def render_workflow(config: ProjectUpdateConfig) -> str:
     """Render the generated GitHub Actions workflow."""
     workflow_names = json.dumps(config.deploy_workflows)

src/basic_memory/cli/commands/ci.py

@@ -14,6 +14,7 @@
 from basic_memory.ci.project_updates import (
     DEFAULT_CONFIG_PATH,
     DEFAULT_PROMPT_PATH,
+    DEFAULT_SOUL_PATH,
     DEFAULT_WORKFLOW_PATH,
     AgentSynthesis,
     ProjectUpdateConfig,
@@ -25,6 +26,7 @@
     load_project_update_config,
     render_agent_synthesis_schema,
     render_capture_prompt,
+    render_soul_template,
     render_workflow,
     schema_seed_specs,
     write_project_update_config,
@@ -362,6 +364,7 @@ def _write_generated_files(
     files = {
         repo_root / DEFAULT_WORKFLOW_PATH: render_workflow(config),
         repo_root / DEFAULT_PROMPT_PATH: render_capture_prompt(),
+        repo_root / DEFAULT_SOUL_PATH: render_soul_template(),
     }
     config_path = repo_root / DEFAULT_CONFIG_PATH
     targets = [*files, config_path]

tests/ci/test_project_updates.py

@@ -16,6 +16,7 @@
     parse_github_remote,
     render_agent_synthesis_schema,
     render_capture_prompt,
+    render_soul_template,
     render_workflow,
     schema_seed_specs,
 )
@@ -622,10 +623,23 @@ def test_render_capture_prompt_uses_workspace_context_path() -> None:
     prompt = render_capture_prompt()
 
     assert ".github/basic-memory/project-update-context.json" in prompt
+    assert ".github/basic-memory/SOUL.md" in prompt
     assert "${{ runner.temp }}" not in prompt
     assert "Do not write a fill-in-the-blanks note" in prompt
     assert "Read the PR diff before writing" in prompt
     assert "problem -> solution -> impact" in prompt
+    assert "It is okay to say when the code is messy" in prompt
+    assert "Ground all judgments" in prompt
+
+
+def test_render_soul_template_guides_personality_without_overriding_facts() -> None:
+    soul = render_soul_template()
+
+    assert soul.startswith("# Auto BM Soul")
+    assert "It is okay to say when code is messy" in soul
+    assert "Notice good simplifications" in soul
+    assert "Do not invent intent, impact, tests, or drama" in soul
+    assert "Keep personality in service of memory" in soul
 
 
 def test_render_agent_synthesis_schema_is_ci_guardrail_not_domain_schema() -> None:

tests/cli/test_ci_commands.py

@@ -94,6 +94,10 @@ def test_setup_writes_workflow_config_and_prompt(
     assert (tmp_path / ".github/workflows/basic-memory.yml").exists()
     assert (tmp_path / ".github/basic-memory/config.yml").exists()
     assert (tmp_path / ".github/basic-memory/memory-ci-capture.md").exists()
+    assert (tmp_path / ".github/basic-memory/SOUL.md").exists()
+    assert "Keep personality in service of memory" in (
+        tmp_path / ".github/basic-memory/SOUL.md"
+    ).read_text(encoding="utf-8")
     assert "OPENAI_API_KEY" in result.output
     assert "BASIC_MEMORY_API_KEY" in result.output
     mock_seed.assert_awaited_once_with(
@@ -149,11 +153,13 @@ def test_setup_refreshes_schema_notes_when_generated_files_already_exist(
     workflow_path = tmp_path / ".github/workflows/basic-memory.yml"
     config_path = tmp_path / ".github/basic-memory/config.yml"
     prompt_path = tmp_path / ".github/basic-memory/memory-ci-capture.md"
+    soul_path = tmp_path / ".github/basic-memory/SOUL.md"
     workflow_path.parent.mkdir(parents=True)
     config_path.parent.mkdir(parents=True)
     workflow_path.write_text("custom workflow\n", encoding="utf-8")
     config_path.write_text("project: existing\n", encoding="utf-8")
     prompt_path.write_text("custom prompt\n", encoding="utf-8")
+    soul_path.write_text("custom soul\n", encoding="utf-8")
 
     result = runner.invoke(
         cli_app,
@@ -174,6 +180,7 @@ def test_setup_refreshes_schema_notes_when_generated_files_already_exist(
     assert workflow_path.read_text(encoding="utf-8") == "custom workflow\n"
     assert config_path.read_text(encoding="utf-8") == "project: existing\n"
     assert prompt_path.read_text(encoding="utf-8") == "custom prompt\n"
+    assert soul_path.read_text(encoding="utf-8") == "custom soul\n"
     mock_seed.assert_awaited_once_with(
         project="team-memory",
         project_id=None,