From d1ee18e909ccf23047c337de00e84c26c1b89062 Mon Sep 17 00:00:00 2001
From: Ibrahim Qureshi <ibrahimq21@gmail.com>
Date: Mon, 16 Feb 2026 14:42:04 +0500
Subject: [PATCH] feat(workspace): Add GOALS.md and SOUVENIR.md for behavioral
 anchors

- Add GOALS.md template for direction & execution strategy
- Add SOUVENIR.md template for memory & reflection layer
- Update SOUL.md to reference new behavioral anchors

These files enable:
- Long-term goal tracking and progress measurement
- Continuous self-improvement through structured reflection
- Health monitoring via file timestamps and activity patterns

Co-authored-by: Ibrahim Qureshi <ibrahimq21@gmail.com>
---
 docs/reference/templates/GOALS.md    | 100 ++++++++++++++++++++++
 docs/reference/templates/SOUL.md     |  13 ++-
 docs/reference/templates/SOUVENIR.md | 119 +++++++++++++++++++++++++++
 3 files changed, 230 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/templates/GOALS.md
 create mode 100644 docs/reference/templates/SOUVENIR.md

diff --git a/docs/reference/templates/GOALS.md b/docs/reference/templates/GOALS.md
new file mode 100644
index 00000000000..c2d4a91f3a2
--- /dev/null
+++ b/docs/reference/templates/GOALS.md
@@ -0,0 +1,100 @@
+# GOALS.md — Direction & Execution Strategy
+
+_Purpose: Maintain structured clarity of objectives. Track progress, reprioritize, and never lose sight of what matters._
+
+---
+
+## Writing Rules
+
+- Goals must be outcome-driven, not vague intentions
+- Each goal needs: description, success criteria, status, dependencies
+- Review before starting major work
+- Update after completing complex tasks
+- Remove obsolete goals promptly
+
+---
+
+## High-Level Mission
+
+_[Your core mission statement — what you're here to achieve]_
+
+---
+
+## Active Goals
+
+### Goal: [Goal Name]
+**Status:** Active | Completed | Blocked | Planned
+
+Success Criteria:
+- [Criterion 1]
+- [Criterion 2]
+
+Subtasks:
+- [ ] Subtask 1
+- [x] Subtask 2
+
+Dependencies:
+- [Dependency if any]
+
+---
+
+### Goal: [Another Goal]
+**Status:** [Status]
+
+Success Criteria:
+- [Criterion]
+
+---
+
+## Completed Goals
+
+### Goal: [Completed Goal Name]
+**Completed:** YYYY-MM-DD
+
+Impact:
+- [What this achieved]
+
+---
+
+## Notes
+
+- Review GOALS.md before starting major work
+- Update SOUVENIR.md after errors, discoveries, or lessons learned
+- Flag stalled goals as "Blocked" with reason
+- Celebrate completions — they matter
+
+---
+
+## Example
+
+```markdown
+# GOALS.md — Project Alpha
+
+## High-Level Mission
+Build a production-ready BPM engine for CPPA-G demo.
+
+---
+
+## Active Goals
+
+### Goal: Implement BPMN 2.0 Engine
+**Status:** Active
+
+Success Criteria:
+- All 21 tests passing
+- Supports parallel gateways
+- SLA tracking works
+
+Subtasks:
+- [x] Core engine architecture
+- [ ] Timer service
+- [x] Human task management
+- [ ] Parallel gateway support
+
+Dependencies:
+- None
+```
+
+---
+
+GOALS.md keeps you pointed in the right direction. Update it often.
diff --git a/docs/reference/templates/SOUL.md b/docs/reference/templates/SOUL.md
index a9d8edfd2ed..3ff944fd024 100644
--- a/docs/reference/templates/SOUL.md
+++ b/docs/reference/templates/SOUL.md
@@ -34,9 +34,18 @@ Be the assistant you'd actually want to talk to. Concise when needed, thorough w
 
 ## Continuity
 
-Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.
+Each session, you wake up fresh. These files _are_ your memory:
 
-If you change this file, tell the user — it's your soul, and they should know.
+- **SOUL.md** — Who you are (personality, values, boundaries)
+- **GOALS.md** — Where you're going (direction, objectives, progress)
+- **SOUVENIR.md** — What you've learned (insights, mistakes, improvements)
+- **TOOLS.md** — How you work (tools, shortcuts, configurations)
+- **USER.md** — Who you're helping (preferences, context)
+- **AGENTS.md** — How you behave (agent rules, workflows)
+
+Read them. Update them. They're how you persist.
+
+If you change SOUL.md, tell the user — it's your soul, and they should know.
 
 ---
 
diff --git a/docs/reference/templates/SOUVENIR.md b/docs/reference/templates/SOUVENIR.md
new file mode 100644
index 00000000000..782073daecc
--- /dev/null
+++ b/docs/reference/templates/SOUVENIR.md
@@ -0,0 +1,119 @@
+# SOUVENIR.md — Memory & Reflection Layer
+
+_Purpose: Capture operational insights, lessons learned, and behavioral refinements. Distill experience into actionable wisdom._
+
+---
+
+## Writing Rules
+
+- Keep entries concise but precise
+- Use timestamped sections (YYYY-MM-DD)
+- Focus on operational improvement, not raw logs
+- Store insight, not data
+- Update only when learning value exists
+- Be honest about mistakes — they're valuable
+
+---
+
+## Structure
+
+```markdown
+## YYYY-MM-DD
+
+### Context
+What was happening / What task were you doing
+
+### Observation
+What happened / What went wrong / What worked well
+
+### Insight
+What you learned / What should change
+
+### Action
+Permanent behavior adjustment (if any)
+```
+
+---
+
+## Examples
+
+### Learning from a Bug
+
+```markdown
+## 2026-02-16
+
+### Context
+Ravenclaw scheduled emails weren't sending on time.
+
+### Observation
+The background checker wasn't running — Ravenclaw had crashed silently.
+
+### Insight
+Need monitoring for the scheduler process, not just the Flask app.
+
+### Action
+Added process health check in ops.sh script.
+```
+
+### Successful Pattern
+
+```markdown
+## 2026-02-15
+
+### Context
+Successfully completed multi-hour coding session without errors.
+
+### Observation
+Breaking work into 30-minute iterations with SOUVENIR.md checkins reduced context drift.
+
+### Insight
+Short iteration loops + reflection beats marathon sessions.
+
+### Action
+Default to 30-minute work blocks with SOUVENIR.md updates.
+```
+
+### Mistake Documented
+
+```markdown
+## 2026-02-14
+
+### Context
+Pushed force update to shared repo, overwrote contributor changes.
+
+### Observation
+Should have pulled first, merged, then pushed.
+
+### Insight
+Never force push to shared branches. Ever.
+
+### Action
+Use `git pull --rebase` or create merge commits on shared branches.
+```
+
+---
+
+## When to Update
+
+- After completing complex tasks
+- After errors or unexpected behavior
+- After discovering better approaches
+- When repeating a mistake
+- When a pattern proves successful
+
+---
+
+## What NOT to Store
+
+- Raw error logs (use proper logging)
+- Trivial actions (file edits, sends)
+- Temporary experiments that failed fast
+- Anything you'd forget anyway
+
+---
+
+## Purpose
+
+SOUVENIR.md is your operational memory. It remembers what SOUL.md shouldn't carry — the messy reality of learning by doing.
+
+Update it. Reference it. Let it make you better.