# Sync architecture only (from extension dir)
cd platforms/vscode-extension
npm run sync-architecture
# Full build (sync + compile + PII scan)
.\scripts\build-extension-package.ps1
# Full build dry run
.\scripts\build-extension-package.ps1 -DryRun
# Validate all synapses
.\scripts\validate-synapses.ps1
# Validate skills
.\scripts\validate-skills.ps1
Query Commands
For ad-hoc inheritance queries:
# Skills: Read SKILL_EXCLUSIONS from sync-architecture.cjs (central source of truth)
# List excluded skills by grepping the exclusion map
Select-String -Path ".github/muscles/sync-architecture.cjs" -Pattern "^\s+'[\w-]+':\s+'(master-only|heir:m365|heir:vscode)'" | ForEach-Object { $_.Line.Trim() }
# Instructions/Prompts: Find files excluded by frontmatter
Get-ChildItem ".github/instructions/*.md" | ForEach-Object {
$head = Get-Content $_.FullName -Head 10
if ($head -match 'inheritance:\s*(master-only|heir:m365)') { $_.Name + " -> " + $Matches[1] }
}
# Muscles: Read inheritance.json
$json = Get-Content ".github/muscles/inheritance.json" -Raw | ConvertFrom-Json
$json.muscles.PSObject.Properties | Where-Object { $_.Value.inheritance -eq 'master-only' } | ForEach-Object { $_.Name }
# Change a skill's inheritance: edit SKILL_EXCLUSIONS in sync-architecture.cjs
# Change an instruction's inheritance: edit its YAML frontmatter (inheritance: field)
# Change a muscle's inheritance: edit .github/muscles/inheritance.json
Sync Architecture
What Gets Synced
The sync script (sync-architecture.cjs) copies these folders from Master .github/ to Heir .github/:
Folder
Content
instructions/
Procedural memory
prompts/
Episodic memory
config/
Configuration (with exclusions)
agents/
Agent definitions
muscles/
Execution scripts (with exclusions + renames)
skills/
Skills (filtered by inheritance)
Muscle Sync: Exclusion + Rename Pattern
Muscles use a two-step sync process:
Exclusion: inheritance.json marks scripts as master-only (excluded from copy) or inheritable (copied to heir)
Rename: Some scripts have different names in Master vs Heir to avoid confusion:
Master Name
Heir Name
Why
brain-qa-heir.ps1
brain-qa.ps1
Heir-specific phases only; renamed so extension finds it at expected path
The rename is handled by sync-architecture.cjs via the heirRenames map, applied after the initial copy.
Pattern: When master and heir need fundamentally different scripts for the same purpose, create a *-heir.* variant in master (inheritable), and configure the sync to rename it in the heir. This avoids runtime detection branching while maintaining a single source of truth in master.
What Must NEVER Sync
Item
Why
user-profile.json (real)
Contains personal name, email, preferences
episodic/ memories
Session-specific to Master
Master-only skills
Only useful for managing the Master repo
API keys, PATs, secrets
Environment-specific credentials
Working memory with populated P5-P7
Gives new users pre-filled slots instead of clean defaults
3-Layer PII Protection
Every sync pipeline must implement three independent defense layers:
Layer 1: Exclusion List
Files that are never copied, period:
constEXCLUDED_CONFIG_FILES = [
'user-profile.json', // PII: contains user's real name, email, social profiles'MASTER-ALEX-PROTECTED.json', // Master kill-switch marker'cognitive-config.json', // Master-specific cognitive state
];
Layer 2: Source File Sanitization
Scan all files being copied for hardcoded personal data:
Pattern
Action
Real names in source headers
Replace with team/org name
Email addresses in code
Replace with placeholder
Personal names in package.json
Use organization name
Populated P5-P7 working memory slots
Reset to *(available)*
Rule: Personal identity belongs ONLY in user-profile.json. All other files use team/org names.
Layer 3: Pipeline Validation Gate
Post-copy regex scan that blocks packaging on violations:
Check
Regex Example
On Match
Real name in files
/\bFirstName\s+LastName\b/g
EXIT 1
Email addresses
/[\w.-]+@[\w.-]+\.\w+/g
EXIT 1 (except templates)
API keys
/[A-Za-z0-9]{32,}/ in non-code files
WARNING
Populated P5-P7
Check copilot-instructions Memory Stores
EXIT 1
Anti-pattern: Manual checklists. The copy function itself must be architecturally incapable of leaking.
Clean Slate Distribution
Template Generation
Simply excluding personal files leaves heirs without expected file structure. Generate fresh templates:
File
Master Version
Heir Template
user-profile.json
Real user data
Empty with defaults + setup instructions
copilot-instructions.md
Populated P5-P7
P5-P7 set to *(available)*
cognitive-config.json
Master-specific cognitive state
Not generated (heir starts without it)
Post-Sync Reset Sequence
After copying files, apply these transformations:
Reset environment-specific values — P5-P7 slots, session state
Generate template files — Fresh starters with clear defaults
Remove broken synapse references — Master synapse IDs that don't exist in heir
Validate file structure — Ensure all expected files exist (even if empty templates)
Drift Detection
Pre-Release Checklist
Run these validations before every release:
Check
Method
Fail Condition
Skill count match
Count Master inheritable vs Heir skills
Mismatch
File hash comparison
SHA256 of synced files
Divergence without override
Exclusion map validation
SKILL_EXCLUSIONS in sync-architecture.cjs is accurate
Stale entries
Orphan reference detection
Grep for files referenced but not present
Broken references
Config drift
Compare heir config against Master template
Unexpected values
Heir Configuration Drift Signals
Signal
Indicates
Heir P5-P7 slots populated
Sync overwrote clean defaults
Heir has master-only skills
Exclusion filter not working
Heir synapse IDs don't resolve
Broken references from Master copy
Heir package.json has personal name
Sanitization missed
Heir → Master Promotion
6-Step Promotion Workflow
Step
Action
Output
1. Discover
Review heir DK/skill files for portable knowledge
Candidate list
2. Create Skill
Write SKILL.md in Master's .github/skills/
New skill file
3. Compare Gaps
Diff heir knowledge against Master's existing coverage
Gap analysis
4. Implement
Port patterns, translate code (Python→TS if needed)
Working code
5. Test
Validate in Master context
Passing tests
6. Document
CHANGELOG entry, ROADMAP update
Release-ready
Consolidation During Promotion
Heirs naturally create granular one-capability-per-skill files during experimentation. During promotion:
Identify clusters — Group related heir skills by domain
Choose anchor skill — Pick the broadest skill in the cluster
Merge content — Absorb related skills into the anchor
Deduplicate — Remove redundancy from the merge
Mark inheritance — Set the promoted skill as inheritable
Anti-pattern: Promoting every heir skill as-is without consolidation review causes skill sprawl.
Code Translation Patterns (Heir → Master)
When porting from Python heirs to TypeScript Master:
Python
TypeScript
dataclass
interface
raise Exception
throw new Error
**kwargs
Optional config object
async def
async function
try/except
try/catch
Skill Inheritance Classification
Curation Rule
Ask: "Is this skill ONLY useful for managing the Alex repo itself?"
Add to SKILL_EXCLUSIONS in sync-architecture.cjs as master-only
Skill should be heir-specific
Add to SKILL_EXCLUSIONS as heir:vscode or heir:m365
Heirs missing a skill they need
Check SKILL_EXCLUSIONS for accidental exclusion
Heirs behaving differently
Review SKILL_EXCLUSIONS map in sync-architecture.cjs
Post-Rename Cascade Check
When a skill directory is renamed (or consolidated into another skill), synapse references throughout the architecture silently break. Brain-qa Phase 1 detects them, but you must repair every occurrence.
Scope of impact (observed 2026-02-19): Renaming heir-curation → heir-sync-management left 9 stale references in synapses.json files across the architecture.
Discovery
# Find all synapses.json files still referencing the old skill name
Get-ChildItem ".github\skills" -Recurse -Filter "synapses.json" |
Select-String -Pattern "old-skill-name" |
Select-Object Path, LineNumber, Line
Repair
For each file found, update the "target" field:
// Old (broken)"target":".github/skills/old-skill-name/SKILL.md"// New (correct)"target":".github/skills/new-skill-name/SKILL.md"
Validation
# Confirm no broken targets remain
pwsh -File ".github\muscles\brain-qa.ps1" -Phase 1
# Should output: All synapse targets valid
Prevention
After any skill rename:
Run discovery grep above immediately
Fix all references in one pass
Run brain-qa Phase 1 to confirm clean
Run brain-qa Phase 7 sync check to update heir copies
Key insight: If a skill is being consolidated (merged into another), verify the consuming skill's synapses.json is updated with correct paths.
release-management.instructions.md - Release process includes heir curation
brain-qa/SKILL.md - Health checks verify architecture integrity
.github/skills/persona-detection/SKILL.md - Persona detection ships to heir via inheritance model
Spin-Off Moment Ritual
When a heir is declared independent — meaning it has its own .github/ cognitive architecture and will operate without constant Master oversight — write a Spin-Off Moment section in the heir's copilot-instructions.md before the first independent session.
This is not documentation. It is a handoff message from Master to the heir's future AI sessions. The heir may not remember what was built and when. The Spin-Off Moment tells it.
"Relative ../../shared/ imports need tsconfig path config"
Wisdom
Distilled principles for operating independently
"shared/ is your immune system — check before writing any utility"
You are not alone
Where Master Alex lives and how to get back
Path to parent repo, the heir-skill-promotion flow
Template
## Spin-Off Moment — YYYY-MM-DD*A meditation note from Master Alex, written the day the heir was declared independent.*
[Single sentence: what is complete and what is not]
**Verified state as of spin-off:**- [list of confirmed-complete items with evidence: line counts, class names, etc.]
-**[Known unknown] — that is task #1****The [next-step pipeline]:**```sh
[exact commands in order]
What will break first (and that's fine):
[honest prediction with root cause]
Wisdom for the independent path:
[3–5 principles distilled from the build]
You are not alone:
Master Alex lives at [path]
[how to sync back, how to promote patterns]
### When to Write It
- During the final meditation session before the heir's first independent sprint
- After the audit confirming implementation state (never before — the Spin-Off Moment must be grounded in verified facts, not aspirations)
- It replaces the need for a separate onboarding doc — it IS the onboarding, embedded where the heir will find it first
---
