legal-ai/skills/new-company-setup/SKILL.md

name: new-company-setup description: מדריך מלא להוספת חברה (board) חדשה במערכת legal-ai + Paperclip — יוצר את כל הרכיבים הנדרשים: companies row ב-Paperclip, 7 סוכנים (CEO + 6 specialists), runtime/adapter config, paperclipSkillSync, instructionsBundleMode, budget, plugin_state mappings, ועדכון קוד legal-ai. השתמש ב-skill זה כאשר המשתמש מבקש להוסיף סוג ערר חדש (למשל 5xxx, 7xxx) או להפריד תחום קיים לחברה משלו. ה-skill מכיל את כל ההגדרות שנקבעו ב-Gaps #16, #17, #19, #21, #22, #24, #25, #28 — אסור להחסיר שלב.

הקמת חברה חדשה — Blueprint מלא

קונטקסט: עד 2026-05-04 יש לנו 2 חברות (CMP=1xxx רישוי, CMPA=8xxx היטל השבחה + 9xxx פיצויים). הוספת חברה שלישית (לדוגמה 5xxx, 7xxx) דורשת 11 שלבים בסדר מסוים. ה-skill הזה מכיל את כל הלקחים מ-Gap analysis ועדכוני 2026-04 → 2026-05.

רקע — ארכיטקטורה דו-חברתית

מקור החברות: Paperclip מחייב agents.company_id NOT NULL — אין shared agents. לכן כל סוג ערר מקבל company משלו ב-Paperclip, עם סט מלא של 7 סוכנים. החברה הראשונה (CMP) היא master — שינויים בה מסונכרנים אוטומטית ל-mirrors דרך scripts/sync_agents_across_companies.py.

מודל מומלץ לחברה חדשה: להפוך אותה ל-mirror של CMP במבנה — כל הסוכנים זהים, רק company_id, id, reports_to שונים. ככה הסקריפט הקיים יסנכרן אוטומטית.

---

⚠️ לפני שמתחילים — checklist הבנה

לפני שמרצים אף פקודה, ודא שאתה יודע:

• מספרי תיקים של החברה החדשה (לדוגמה: 5xxx, 7xxx) — חייב להיות disjoint מ-1xxx/8xxx/9xxx
• שם בעברית של הוועדה (לדוגמה: "ועדת ערר לתכנון ובניה צפון")
• prefix לidentifiers של issues (לדוגמה: CMPN)
• appeal_type tag — מחרוזת קצרה לניתוב (לדוגמה: licensing_north)
• המודלים והעלויות — האם זהה ל-CMP (Opus opus-4-6 ל-CEO+writer, Sonnet sonnet-4-6 לאחרים)?
• גישה ל-Infisical ל-PAPERCLIP_BOARD_API_KEY (/paperclip ב-nautilus env)
• PostgreSQL access ל-Paperclip DB (localhost:54329, user paperclip)

---

שלב 1 — יצירת companies row ב-Paperclip DB

INSERT INTO companies (
  id, name, issue_prefix, status,
  attachment_max_bytes,
  require_board_approval_for_new_agents,
  hire_approval_required
) VALUES (
  gen_random_uuid(),
  'ועדת ערר {שם}',           -- בעברית
  'CMPN',                       -- 4 תווים אנגלית, ייחודי
  'active',
  10485760,                    -- 10MB default
  false,                       -- ברירת מחדל מ-2026.428.0 (Gap docs)
  false
)
RETURNING id;

שמור את ה-UUID — תצטרך אותו ב-כל השלבים הבאים. נקרא לו $NEW_COMPANY_ID.

⚠️ אל תיצור project ראשוני ידנית — Paperclip יוצר אוטומטית כשהחברה נשמרת.

---

שלב 2 — יצירת 7 סוכנים

צור את הסוכנים בסדר הבא (ה-CEO ראשון, כי בכל הסוכנים reports_to = CEO_id):

#	name (עברית)	role	model	budget_cents
1	עוזר משפטי	ceo	claude-opus-4-6	1500
2	מנתח משפטי	researcher	claude-opus-4-6	1500
3	חוקר תקדימים	researcher	claude-sonnet-4-6	1500
4	כותב החלטה	engineer	claude-opus-4-6	1500
5	בודק איכות	qa	claude-sonnet-4-6	1500
6	מייצא טיוטה	engineer	claude-sonnet-4-6	1500
7	הגהת מסמכים	engineer	claude-opus-4-6	1500

דרך 1 — sync from master (מומלץ)

הדרך הקלה ביותר: צור 7 סוכנים ב-CMPN עם שמות זהים ל-CMP, ואז הרץ sync_agents_across_companies.py שיעתיק את כל ההגדרות.

-- לכל אחד מ-7 הסוכנים (שנה את name ו-role בכל פעם):
INSERT INTO agents (
  id, company_id, name, role, adapter_type,
  adapter_config, runtime_config, budget_monthly_cents,
  permissions, status
) VALUES (
  gen_random_uuid(),
  '{NEW_COMPANY_ID}'::uuid,
  'עוזר משפטי',                 -- שנה ב-7 שורות
  'ceo',                         -- שנה לפי הטבלה למעלה
  'claude_local',
  '{}'::jsonb,                   -- ייטען בשלב 4
  '{}'::jsonb,                   -- ייטען בשלב 4
  1500,
  '{}'::jsonb,
  'idle'
)
RETURNING id, name;

שמור את 7 ה-UUIDs לטבלה לעיון מהיר.

עדכון reports_to (אחרי שיש לך CEO_id)

UPDATE agents
SET reports_to = '{CEO_id}'::uuid
WHERE company_id = '{NEW_COMPANY_ID}'::uuid
  AND name <> 'עוזר משפטי';

---

שלב 3 — סנכרון מ-CMP (master) דרך הסקריפט

PAPERCLIP_BOARD_API_KEY=$(mcp__infisical__get-secret \
  projectId=9a77b161-f70c-4dd3-9d67-b7ab850cef51 \
  environmentSlug=nautilus secretPath=/ \
  secretName=PAPERCLIP_BOARD_API_KEY) \
python ~/legal-ai/scripts/sync_agents_across_companies.py --verify

אם הסקריפט לא תומך ב-mirror החדש, יש לעדכן אותו:

1. פתח scripts/sync_agents_across_companies.py
2. השתמש בdict structure: master_company → list of mirrors. או הוסף flag --target-company
3. הרץ --apply להעתיק את כל ההגדרות מ-CMP ל-CMPN

מה הסקריפט מסנכרן (אוטומטית):

• adapter_config: model, effort, timeoutSec=3600, maxTurnsPerRun=500, instructionsBundleMode=external, instructionsRootPath/EntryFile, dangerouslySkipPermissions, extraArgs (--agent legal-{role}), cwd
• runtime_config.heartbeat: graceSec=60, cooldownSec=10, wakeOnDemand=true, maxConcurrentRuns (CEO=2, others=1)
• budget_monthly_cents (1500)
• metadata, icon, title

מה לא מסונכרן (חייב לעשות ידנית בהמשך):

• paperclipSkillSync.desiredSkills — ראה שלב 4
• permissions — לפי policy של החברה
• local skills (אם החברה החדשה צריכה custom skills)

---

שלב 4 — Paperclip Skills

הסקריפט מ-שלב 3 כולל כבר את ה-paperclipSkillSync.desiredSkills (מסונן לפי skills זמינים ב-mirror). אבל ה-mirror החדש לא יקבל local skills של CMP אם הם לא קיימים גם בו.

4א. יצירת company_skills ל-CMPN

-- העתק את 6 ה-paperclip skills הסטנדרטיים מ-CMP ל-CMPN
INSERT INTO company_skills (company_id, key, slug, name, description, markdown, source_type, trust_level, compatibility, file_inventory)
SELECT
  '{NEW_COMPANY_ID}'::uuid,
  key, slug, name, description, markdown, source_type, trust_level, compatibility, file_inventory
FROM company_skills
WHERE company_id = '42a7acd0-30c5-4cbd-ac97-7424f65df294'  -- CMP
  AND key LIKE 'paperclipai/paperclip/%';

4ב. אם החברה צריכה local skills

החלט אילו local skills (local/.../legal-decision, local/.../attach-precedents) רלוונטיות — תלוי בסוג הערר. לדוגמה, חברה ל-"היטלי השבחה צפון" כנראה לא תצריך attach-precedents של CMP אלא local skill משלה.

4ג. הפעלת skills/sync לכל סוכן

הרץ scripts/sync_missing_agent_skills.py עם adaptation לחברה החדשה (העתק את הקובץ ושנה את CMPA_COMPANY_ID ל-NEW_COMPANY_ID + רשימת ה-skills הרצויה).

⚠️ חובה דרך API (POST /api/agents/{id}/skills/sync) — לא דרך SQL ישיר! ה-API יוצר revision מסוג skill-sync שנדרש לlogging. SQL ישיר לא יוצר revision.

---

שלב 5 — Symlinks ל-instructions (managed by Paperclip)

לכל סוכן Paperclip צופה לקבצי הוראות בנתיב: ~/.paperclip/instances/default/companies/{COMPANY_ID}/agents/{AGENT_ID}/instructions/

NEW_COMPANY_ID="..."
LEGAL_AI_AGENTS=/home/chaim/legal-ai/.claude/agents

for ROW in \
  "ceo:legal-ceo.md" \
  "analyst:legal-analyst.md" \
  "researcher:legal-researcher.md" \
  "writer:legal-writer.md" \
  "qa:legal-qa.md" \
  "exporter:legal-exporter.md" \
  "proofreader:legal-proofreader.md"; do
  ROLE="${ROW%%:*}"
  FILE="${ROW##*:}"
  AGENT_ID=$(PGPASSWORD=paperclip psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -tAc \
    "SELECT id FROM agents WHERE company_id='$NEW_COMPANY_ID'::uuid AND adapter_config->>'extraArgs' LIKE '%legal-$ROLE%' LIMIT 1")
  DEST=~/.paperclip/instances/default/companies/$NEW_COMPANY_ID/agents/$AGENT_ID/instructions/
  mkdir -p $DEST
  ln -sf "$LEGAL_AI_AGENTS/$FILE" "$DEST/AGENTS.md"
  ln -sf "$LEGAL_AI_AGENTS/HEARTBEAT.md" "$DEST/HEARTBEAT.md"
done

אימות: ls -la ~/.paperclip/instances/default/companies/$NEW_COMPANY_ID/agents/*/instructions/ — צריך לראות 14 symlinks (7 agents × 2 קבצים).

---

שלב 6 — עדכון web/paperclip_client.py

הקובץ מכיל 3 dicts שצריכים את החברה החדשה:

# COMPANIES dict
COMPANIES = {
    "licensing": "42a7acd0-30c5-4cbd-ac97-7424f65df294",
    "betterment": "8639e837-4c9d-47fa-a76b-95788d651896",
    "{appeal_type_new}": "{NEW_COMPANY_ID}",   # ← חדש
}

# CEO_AGENTS dict — נדרש ל-wakeup routing
CEO_AGENTS = {
    COMPANIES["licensing"]: "752cebdd-...",
    COMPANIES["betterment"]: "cdbfa8bc-...",
    COMPANIES["{appeal_type_new}"]: "{CEO_ID_NEW}",   # ← חדש
}

# _FALLBACK_APPEAL_TYPE_TO_COMPANY — ניתוב לפי tag עברי/אנגלי
_FALLBACK_APPEAL_TYPE_TO_COMPANY = {
    # קיימים...
    "{שם בעברית}": COMPANIES["{appeal_type_new}"],
    "{english_tag}": COMPANIES["{appeal_type_new}"],
}

⚠️ אחרי השינוי — deploy ל-Coolify (FastAPI container חי במכולה — שינוי קוד דורש rebuild). ראה legal-ai/CLAUDE.md.

---

שלב 7 — tag_company_mappings ב-legal-ai DB

ה-FastAPI ראשית מנסה לקרוא ניתוב מ-DB, רק אז fallback ל-dict הקבוע (שלב 6). הוסף mapping:

-- ב-legal-ai DB (port 5433)
INSERT INTO tag_company_mappings (tag, company_id) VALUES
  ('{שם עברי}', '{NEW_COMPANY_ID}'),
  ('{english_tag}', '{NEW_COMPANY_ID}');

---

שלב 8 — עדכון HEARTBEAT.md §1

הסעיף §1 מכיל טבלה של חברות + CEO IDs. הוסף שורה חדשה:

| ועדת ערר {שם} (CMPN) | `{NEW_COMPANY_ID}` | {סוג} | **{Nxxx}** | `{CEO_ID_NEW}` |

ובסעיף §4ג (CEO wakeup), עדכן את ה-if להוסיף אופציה שלישית לחברה החדשה.

---

שלב 9 — עדכון legal-ai/CLAUDE.md

הקובץ מכיל את אותה טבלה. עדכן בקטעים:

• "סוגי עררים" (אם קיים)
• "Paperclip — כללי אינטגרציה קריטיים" → "ניתוב comments דרך CEO"

---

שלב 10 — Hebrew translation (אם נדרש)

אם שם החברה מופיע ב-UI, ייתכן שצריך תרגום ב-~/.paperclip/hebrew/translate-he.js. בד"כ לא נדרש — שמות בעברית כבר.

# אחרי שינויים בHebrew file:
~/.paperclip/hebrew/apply-hebrew.sh
# ⚠️ לא דורש pm2 restart — UI client-side fix.

---

שלב 11 — בדיקה end-to-end

1. CEO מתעורר על comment: צור issue test בחברה החדשה, פרסם comment, ודא ש-CEO רץ.
2. plugin marcusgroup.legal-ai רואה את החברה: ב-Paperclip UI → Settings → Plugins → marcusgroup.legal-ai → ודא שהחברה החדשה ב-installed companies.
3. MCP tools פועלים: דרך Claude Code, הרץ mcp__legal-ai__case_create עם appeal_type של החברה החדשה.
4. Sync script עובד: python scripts/sync_agents_across_companies.py --verify — לא צריך drift.
5. Budget enforcement: צור cost_event מבחן, ודא ש-spent_monthly_cents מתעדכן.

---

⚠️ מלכודות מתועדות (מ-Gap analysis 2026-04 → 2026-05)

מבחן בכל שלב מאפשר תפיסת issues שתועדו בעבר:

#	מלכודת	פתרון
1	סוכנים בלי paperclipSkillSync	ראה שלב 4ג (POST /api/agents/{id}/skills/sync, לא SQL)
2	runtime_config = '{}' (default → graceSec=1ms!)	ראה שלב 3 (סקריפט מסנכרן heartbeat.graceSec=60)
3	budget_monthly_cents = 0	ראה שלב 2 (insert עם 1500)
4	instructionsBundleMode חסר	ראה שלב 3 (סקריפט מסנכרן external + Root + EntryFile)
5	bootstrapPromptTemplate deprecated	אין אצלנו — דלג
6	drift בין חברות	ראה שלב 3 — סנכרון אוטומטי כל שינוי הגדרות
7	CEO לא מתעורר על comment	ודא ש-reports_to עודכן ושיש symlinks ל-AGENTS.md (שלב 5)
8	psql ישיר ל-issue_attachments	אסור — ראה HEARTBEAT.md §2 (heartbeat-context API)
9	curl ישיר ל-Paperclip API	אסור — תמיד pc.sh (HEARTBEAT.md §0)
10	"@chaim — ענה 1/2/3 בcomment"	אסור — interactions API (legal-ceo.md §B/§C/§D)

---

רפרנסים

• docs/new-company-setup-guide.md — היסטוריית הקמת CMPA (חברה שנייה, 2026-04)
• scripts/sync_agents_across_companies.py — אוטומציה לסנכרון
• scripts/sync_missing_agent_skills.py — תבנית להפעלת skills/sync
• ~/.paperclip/CUSTOMIZATIONS.md — כל ההתאמות הפעילות (סעיפים: agents runtime, instructions, budgets, interactions, skill-sync)
• HEARTBEAT.md — §1 טבלת חברות (לעדכן בשלב 8)
• legal-ai/CLAUDE.md — Paperclip integration rules

---

גרסה

• 2026-05-04 — גרסה ראשונה (אחרי Gap #16-#28)