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

```sql
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` שיעתיק את כל ההגדרות.

```sql
-- לכל אחד מ-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)

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

---

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

```bash
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

```sql
-- העתק את 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/`

```bash
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 שצריכים את החברה החדשה:

```python
# 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:

```sql
-- ב-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. הוסף שורה חדשה:

```markdown
| ועדת ערר {שם} (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`. בד"כ לא נדרש — שמות בעברית כבר.

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

---

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