legal-ai/docs/superpowers/plans/2026-05-16-per-agent-claude-md.md

Per-Agent CLAUDE.md Versioning & Validation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: הוסף validation ו-version tracking לקבצי הוראות הסוכנים. כעת, לפני שה-sync script מחיל שינויים, הוא מאמת שכל instructionsFilePath קיים. בנוסף, metadata של הסוכן ב-DB יכיל claude_md_mtime — השינוי האחרון בקובץ — כדי לזהות drift.

Architecture: sync_agents_across_companies.py מקבל --check-instructions flag שסורק את כל הסוכנים ומדווח על קבצים חסרים/ישנים. ב---apply, מתווספת בדיקת pre-flight שמבטלת את הsync אם קובץ חסר. agents.metadata מקבל claude_md_mtime עם ה-mtime בפועל של הקובץ.

Tech Stack: Python 3.10+, asyncpg, httpx, os.path.getmtime(), Paperclip REST API (PATCH /api/agents/{id}).

---

File Map

Action	File
Modify	legal-ai/scripts/sync_agents_across_companies.py — --check-instructions flag, pre-flight, metadata update

זה הקובץ היחיד שצריך לגעת בו. כל שאר הלוגיקה קיימת כבר.

---

Task 1: הוסף --check-instructions flag

Files:

• Modify: legal-ai/scripts/sync_agents_across_companies.py

• Step 1: קרא את החלק של argparse בסקריפט

grep -n "argparse\|add_argument\|--verify\|--dry-run\|--apply" \
  /home/chaim/legal-ai/scripts/sync_agents_across_companies.py | head -20

• Step 2: הוסף את הargument

מצא את הסקציה שמגדירה args והוסף:

parser.add_argument(
    "--check-instructions",
    action="store_true",
    help="Scan all agents' instructionsFilePath and report missing/outdated files",
)

• Step 3: הוסף את הפונקציה check_instructions()

הוסף לפני async def main():

async def check_instructions(agents: list[dict]) -> bool:
    """Print a report of all agents' instruction files. Returns True if all OK."""
    all_ok = True
    print(f"\n{'Agent':<30} {'File':<60} {'Status':<15} {'Size':>8} {'Modified'}")
    print("-" * 120)

    for agent in agents:
        adapter_cfg = agent.get("adapter_config") or {}
        if isinstance(adapter_cfg, str):
            import json as _json
            adapter_cfg = _json.loads(adapter_cfg)

        file_path = adapter_cfg.get("instructionsFilePath", "")
        name = agent.get("name", agent.get("id", "?"))[:29]

        if not file_path:
            print(f"{name:<30} {'(none)':<60} {'⚠️  NOT SET':<15}")
            continue

        if not os.path.exists(file_path):
            print(f"{name:<30} {file_path[-59:]:<60} {'❌ MISSING':<15}")
            all_ok = False
            continue

        stat = os.stat(file_path)
        size_kb = stat.st_size // 1024
        mtime = datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M")

        # Compare with DB metadata
        metadata = agent.get("metadata") or {}
        if isinstance(metadata, str):
            import json as _json
            metadata = _json.loads(metadata)

        db_mtime = metadata.get("claude_md_mtime", "")
        actual_mtime = str(int(stat.st_mtime))
        drift = " ⚠️ DRIFT" if db_mtime and db_mtime != actual_mtime else ""

        print(f"{name:<30} {file_path[-59:]:<60} {'✅ OK':<15} {size_kb:>6}KB  {mtime}{drift}")

    print()
    return all_ok

from datetime import datetime ו-import os — בדוק שמיובאים בראש הסקריפט. אם לא, הוסף.

• Step 4: הוסף קריאה ל-check_instructions() ב-main()

בתוך async def main(), אחרי שloading הagents מה-DB:

if args.check_instructions:
    all_ok = await check_instructions(master_agents + mirror_agents)
    sys.exit(0 if all_ok else 1)

• Step 5: בדיקה

cd /home/chaim/legal-ai
python scripts/sync_agents_across_companies.py --check-instructions

Expected: טבלה עם כל הסוכנים, paths, סטטוס ✅/❌.

• Step 6: Commit

cd /home/chaim/legal-ai
git add scripts/sync_agents_across_companies.py
git commit -m "feat: add --check-instructions flag to sync script"

---

Task 2: הוסף pre-flight validation לפני --apply

Files:

• Modify: legal-ai/scripts/sync_agents_across_companies.py

• Step 1: מצא את נקודת הכניסה של --apply

grep -n "args.apply\|if.*apply\|apply.*mode" \
  /home/chaim/legal-ai/scripts/sync_agents_across_companies.py | head -10

• Step 2: הוסף pre-flight לפני apply

בתחילת בלוק --apply, לפני כל שינוי:

if args.apply:
    # Pre-flight: abort if any agent is missing its instructions file
    print("🔍 Pre-flight: checking instruction files...")
    all_ok = await check_instructions(master_agents + mirror_agents)
    if not all_ok:
        print("❌ Abort: one or more instruction files are missing. Fix paths before --apply.")
        sys.exit(1)
    print("✅ Pre-flight passed.\n")
    # ... rest of apply logic ...

• Step 3: בדיקה — הפעל עם קובץ חסר (סימולציה)

# שנה זמנית path לקובץ שלא קיים
cd /home/chaim/legal-ai
python scripts/sync_agents_across_companies.py --dry-run 2>&1 | head -5

Expected: dry-run עובר. אם תנסה --apply עם agent שhis file חסר — הsync יבוטל.

• Step 4: Commit

cd /home/chaim/legal-ai
git add scripts/sync_agents_across_companies.py
git commit -m "feat: add pre-flight instruction file validation before --apply"

---

Task 3: עדכן agents.metadata עם claude_md_mtime

Files:

• Modify: legal-ai/scripts/sync_agents_across_companies.py

• Step 1: מצא את compute_diff() או apply_diff()

grep -n "def compute_diff\|def apply_diff\|def build_patch\|metadata" \
  /home/chaim/legal-ai/scripts/sync_agents_across_companies.py | head -20

• Step 2: הוסף פונקציה get_claude_md_mtime()

def get_claude_md_mtime(adapter_config: dict) -> str | None:
    """Return the Unix mtime of the agent's instructionsFilePath, or None if missing."""
    path = adapter_config.get("instructionsFilePath", "")
    if not path or not os.path.exists(path):
        return None
    return str(int(os.path.getmtime(path)))

• Step 3: שלב mtime בbuild של metadata patch

מצא את המקום שמכין את ה-metadata לsync. הוסף:

# Build metadata patch with claude_md_mtime
current_metadata = master_agent.get("metadata") or {}
if isinstance(current_metadata, str):
    import json as _json
    current_metadata = _json.loads(current_metadata)

adapter_cfg = master_agent.get("adapter_config") or {}
if isinstance(adapter_cfg, str):
    import json as _json
    adapter_cfg = _json.loads(adapter_cfg)

mtime = get_claude_md_mtime(adapter_cfg)
if mtime:
    current_metadata["claude_md_mtime"] = mtime
    current_metadata["claude_md_last_synced"] = datetime.utcnow().isoformat() + "Z"

כלול את ה-current_metadata המעודכן ב-PATCH לAPI.

• Step 4: בדוק שה-metadata מתעדכן

הפעל --dry-run וחפש claude_md_mtime בoutput:

python scripts/sync_agents_across_companies.py --dry-run 2>&1 | grep -i "mtime\|metadata" | head -10

לאחר --apply, בדוק ב-DB:

psql -h localhost -p 54329 -U paperclip -c \
  "SELECT name, metadata->>'claude_md_mtime' AS mtime FROM agents WHERE metadata->>'claude_md_mtime' IS NOT NULL LIMIT 5" \
  paperclip

• Step 5: Commit

cd /home/chaim/legal-ai
git add scripts/sync_agents_across_companies.py
git commit -m "feat: track claude_md_mtime in agents.metadata during sync"

---

Task 4: הוסף make check-agents shortcut

Files:

• Modify: legal-ai/Makefile (אם קיים) אחרת הוסף alias

• Step 1: בדוק אם Makefile קיים

ls /home/chaim/legal-ai/Makefile 2>/dev/null && echo "EXISTS" || echo "MISSING"

• Step 2א: אם Makefile קיים — הוסף target

check-agents:
	python scripts/sync_agents_across_companies.py --check-instructions

sync-agents-dry:
	python scripts/sync_agents_across_companies.py --dry-run

sync-agents:
	python scripts/sync_agents_across_companies.py --apply

• Step 2ב: אם Makefile לא קיים — הוסף alias ל-~/.bashrc

echo "alias check-agents='cd /home/chaim/legal-ai && python scripts/sync_agents_across_companies.py --check-instructions'" >> ~/.bashrc
source ~/.bashrc

• Step 3: בדוק

# אם Makefile:
make -C /home/chaim/legal-ai check-agents
# אם alias:
check-agents

Expected: טבלת סוכנים מוצגת.

• Step 4: Commit (אם Makefile)

cd /home/chaim/legal-ai
git add Makefile
git commit -m "feat: add check-agents and sync-agents make targets"

---

אימות סופי

בדיקה	פקודה	תוצאה מצופה
--check-instructions	python sync_agents... --check-instructions	טבלה עם ✅ לכל agent
Pre-flight בולם apply	מחק קובץ זמנית + --apply	Abort עם הודעה ברורה
mtime ב-DB	SELECT metadata->>'claude_md_mtime' FROM agents	timestamp לכל agent
DRIFT זוהה	שנה קובץ + --check-instructions	⚠️ DRIFT מוצג
shortcut	check-agents או make check-agents	עובד