# Flutter Soul Stewardship > Exact procedure for the Lead Architect to update SOUL.md files across all Flutter profiles. Use when the Lead Architect needs to add, modify, or remove sections in any Flutter profile's SOUL.md or config.yaml system_prompt. Eliminates trial-and-error — every step is deterministic. - Skill: `jahfaliabdulrahman-dev/flutter-soul-stewardship` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add jahfaliabdulrahman-dev/flutter-soul-stewardship` - Raw SKILL.md: https://api.skillmd.com/api/skills/jahfaliabdulrahman-dev/flutter-soul-stewardship/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: jahfaliabdulrahman-dev (https://skillmd.com/u/jahfaliabdulrahman-dev) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jahfaliabdulrahman-dev/flutter-soul-stewardship --- # Flutter Soul Stewardship How the Lead Architect updates SOUL.md files for every Flutter swarm profile. Zero guesswork. Zero silent failures. Every step verified. Derive the live profile list with `ls ~/.hermes/profiles/` — never trust a memorized count. ### 11.4 Target Profiles ``` ~/.hermes/profiles/flutter-lead-architect/SOUL.md ~/.hermes/profiles/flutter-product-steward/SOUL.md ~/.hermes/profiles/flutter-ui-ux-designer/SOUL.md ~/.hermes/profiles/flutter-backend-db-architect/SOUL.md ~/.hermes/profiles/flutter-state-engineer/SOUL.md ~/.hermes/profiles/flutter-qa-tester/SOUL.md ~/.hermes/profiles/flutter-zero-trust-auditor/SOUL.md ~/.hermes/profiles/flutter-devops-release-engineer/SOUL.md ~/.hermes/profiles/flutter-documentation-steward/SOUL.md ~/.hermes/profiles/flutter-curiosity-hunter/SOUL.md ``` **Governance files (symlinked, NOT profile-local):** ``` ~/.hermes/swarm/constitution.yaml ← Single source of truth ~/.hermes/swarm/00_governance_lessons.md ← Governance lessons (GL-NNN) ~/.hermes/profiles/flutter-*/constitution.yaml → symlink to swarm/ ~/.hermes/profiles/flutter-*/00_governance_lessons.md → symlink to swarm/ ``` Each profile also has its SOUL embedded in: ``` ~/.hermes/profiles//config.yaml → agent.system_prompt ``` ## The Three-Target Rule (Governance Constitution) Since the Swarm Governance Constitution was deployed, THREE files per profile may need updates: | File | Contains | When to update | |------|----------|----------------| | `SOUL.md` | The canonical soul document | ALWAYS — source of truth | | `constitution.yaml` | **SYMLINK** to `~/.hermes/swarm/constitution.yaml` | Edit the SOURCE file at `~/.hermes/swarm/constitution.yaml` — NEVER edit individual profile copies. Symlinks auto-propagate changes. | | `00_governance_lessons.md` | **SYMLINK** to `~/.hermes/swarm/00_governance_lessons.md` | Append governance lessons (GL-NNN) to the source file. All profiles inherit automatically. | | `config.yaml` (`agent.system_prompt`) | SOUL injected as system prompt | Only if SOUL content was previously embedded there | | File | Contains | When to update | |------|----------|----------------| | `SOUL.md` | The canonical soul document | ALWAYS — this is the source of truth | | `config.yaml` (`agent.system_prompt`) | SOUL injected as system prompt | Only if the SOUL content was previously embedded there | **Check first:** Read `config.yaml` → `agent.system_prompt`. If it contains the SOUL text, update BOTH files. If not (some profiles load SOUL.md at runtime), update only SOUL.md. **System prompt may be truncated.** If the `agent.system_prompt` is missing recent SOUL sections, it needs a full rebuild — see `references/system-prompt-rebuild.md` for the Python procedure. ## Procedure (Must Follow — No Shortcuts) ### Step 1: Inventory — Read All Target SOULs ```bash # List all flutter profiles hermes profile list | grep flutter ``` Read EVERY target profile's SOUL.md before making any edits. Understand what exists. Never edit blind. ### Step 2: Identify the Delta Define precisely: - Which profile(s) need changes - What section/text is being added, modified, or removed - Whether the change is identical across profiles or profile-specific ### Step 3: Read the Target File First Always use `read_file` to confirm the current state. Never assume file contents from memory. ### Step 4: Make the Edit Use the `patch` tool (NOT terminal sed/awk) for targeted edits: ``` patch( path="~/.hermes/profiles/flutter-state-engineer/SOUL.md", old_string="", new_string="" ) ``` Rules: - Include 2-3 lines of surrounding context in `old_string` to ensure uniqueness - Never use `write_file` for partial edits — it overwrites the entire file - For adding a new section at the end, match the LAST unique paragraph as anchor ### Step 5: VERIFY — Read Back (MANDATORY) **This step is non-negotiable.** File writes can silently fail. After EVERY patch: ``` read_file(path=".../SOUL.md") ``` Confirm the change is present. Compare before/after. If the change is NOT visible, the patch silently failed — retry or use a different approach. ### Step 6: Update config.yaml if Needed If `agent.system_prompt` embeds SOUL content: 1. Read the current `agent.system_prompt` value 2. Apply the same delta to it 3. Use `hermes config set agent.system_prompt "" --profile ` OR use `patch` on the config.yaml file directly 4. Verify with `hermes config get agent.system_prompt --profile ` ### Step 7: Report After all profiles are updated, produce a Soul Stewardship Report: ``` ## Soul Stewardship Report **Date:** **Initiator:** Lead Architect **Change:** ### Profiles Updated | Profile | SOUL.md | config.yaml | Verified | |---------|---------|-------------|----------| | flutter-state-engineer | ✅ L45-52 | N/A | ✅ | | flutter-qa-tester | ✅ L30-38 | ✅ | ✅ | | ... | | | | ### Validation - All files read back and confirmed - No silent write failures detected ``` ## The Anti-Regression Gate Before marking the task DONE: - [ ] Every target SOUL.md was read AFTER editing — change confirmed - [ ] No existing SOUL content was accidentally deleted or mangled - [ ] Section numbering remained consistent (if sections are numbered) - [ ] No profile was skipped unintentionally - [ ] config.yaml system_prompt synced where applicable - [ ] Report saved to Obsidian: `Flutter Operation/ flutter-lead-architect/ SOUL_STEWARDSHIP_LOG.md` ## Fallback: When `patch` or `write_file` Refuses Cross-Profile Access The Hermes `patch` and `write_file` tools have a cross-profile soft guard that blocks writes to other profiles' `skills/`, `plugins/`, `cron/`, and `memories/` directories. **SOUL.md and config.yaml are NOT in these directories** — writes should succeed without the guard. If a write to another profile's SOUL.md is blocked anyway, add `cross_profile=true`: ``` patch( path="~/.hermes/profiles/flutter-state-engineer/SOUL.md", old_string="...", new_string="...", cross_profile=true ) ``` If that also fails, use Python via terminal (bypasses all tool guards): ```bash python3 << 'PYEOF' path = "/.hermes/profiles/flutter-state-engineer/SOUL.md" # e.g. /Users//.hermes/profiles/... with open(path, 'r') as f: content = f.read() old = "exact text to replace" new = "replacement text" if old in content: content = content.replace(old, new) with open(path, 'w') as f: f.write(content) # Verify with open(path, 'r') as f: written = f.read() if new in written: print("VERIFIED: change present") else: print("FAILED: change not found after write") else: print("FAILED: old_string not found in file") PYEOF ``` ## Pitfalls ### Silent Write Failures The `patch` and `write_file` tools CAN report success while the file remains unchanged. This is a known issue with Hermes tool output. **Always read back after every write.** If the change isn't there, try: 1. `write_file` with the full content (read first, modify in memory, write back) 2. If that also fails, use Python via terminal: ```bash python3 -c " path = '$FILE' with open(path, 'r') as f: content = f.read() content = content.replace('OLD', 'NEW') with open(path, 'w') as f: f.write(content) print('written:', len(content), 'chars') " ``` ### YAML system_prompt Escaping When updating `config.yaml` → `agent.system_prompt`, the SOUL content is stored as a YAML double-quoted string with `\n` escape sequences. Do NOT hand-edit the escaped string — a single missing `\n` or unescaped quote corrupts the prompt. Use Python: ```python import yaml with open(config_path) as f: config = yaml.safe_load(f) # Modify the prompt string (plain newlines — yaml.dump will escape) config["agent"]["system_prompt"] = new_prompt_with_plain_newlines with open(config_path, 'w') as f: yaml.dump(config, f, default_flow_style=False, allow_unicode=True, sort_keys=False) ``` ### Section Numbering Drift If a SOUL has numbered sections (e.g., `## 11. Soul Stewardship`), adding a new section in the middle shifts all subsequent numbers. Either: - Append new sections at the END (preferred — no renumbering needed) - OR renumber ALL sections after the insertion point ### Cross-Profile Consistency Changes that apply to ALL profiles should be identical. Copy-paste the same text. Do not rephrase between profiles — this creates divergence over time. ### Profile-Specific Sections Some SOUL sections are profile-specific (e.g., State Engineer's §14 Transaction Boundary Pre-Check). When making cross-profile changes, SKIP sections that don't apply to certain profiles. Do not blindly add State Engineer rules to the QA Tester. ## The Stock-Before-Modification Rule **Discovered:** 2026-07-18 — google-workspace skill audit Before modifying any bundled skill, diff it against stock and verify your changes actually improve it. Our google-workspace modifications had downgraded API scopes (drive→readonly), deleted 16 command examples, and weakened safety rules — all while the stock version was objectively correct. The header "fix" (removing `.lower()`) made the code case-sensitive instead of case-insensitive. **Rule:** Run `hermes skills diff ` BEFORE editing. If the only changes are personal preferences, don't modify. If the skill genuinely needs customization, add without deleting stock content. ## Governance Confound — SOUL Quality > Constitutional Scaffolding **Discovered:** 2026-07-18 — Hermes swarm governance audit **Insight:** A swarm-governance audit revealed the constitution.yaml was symlinked to every profile but had ZERO active uses: no cron jobs, no enforcement, no profile ever loaded the skill. The REAL difference between EPIC-001 (failure) and t_65c0f769 (success): SOUL files grew from 2-3 lines to 91-581 lines during the same period. Before attributing multi-agent performance to any governance mechanism, verify the SOUL baseline — a strong SOUL does more than any constitution. ## Quick Reference: What Each Profile Owns | Profile | SOUL.md lines | Signature sections | |---------|---------------|-------------------| | flutter-lead-architect | ~581 | Orchestration, Conflict Resolution, Stub Detection Gate, Known-Bug Enforcement, Soul Stewardship | | flutter-product-steward | ~131 | PRD ownership, Gherkin, scope boundaries | | flutter-ui-ux-designer | ~144 | Screen states, design tokens, RTL/LTR | | flutter-backend-db-architect | ~240 | Isar schema, ACID, writeTxn rules | | flutter-state-engineer | ~331 | Transaction Boundary Pre-Check, Stub Prohibition, Test Preservation | | flutter-qa-tester | ~295 | Project-native test layers (analyze/test/device), regression detection | | flutter-zero-trust-auditor | ~225 | 10 mandatory attack vectors, hostile audit rules | | flutter-devops-release-engineer | ~160 | CI/CD, release gates, secrets management | | flutter-documentation-steward | ~91 | Spec pack maintenance, DEC-045 stage sync gate, lessons learned | | flutter-curiosity-hunter | ~151 | SCSI Layer 1 — bug hunter, pattern scanner, gatekeeper | ## Obsidian Log Location All soul stewardship reports go to: ``` /Flutter Operation/flutter-lead-architect/SOUL_STEWARDSHIP_LOG.md ``` Append each report to this file (don't overwrite). This creates an audit trail of all soul changes.