# Monorepo Complete Extraction Spec

**Status:** Phase 9 COMPLETE (9A through 9F)
**Created:** 2026-02-15
**Updated:** 2026-02-16
**Goal:** Move ALL business logic from `kollabor/` to packages, leaving only thin orchestration

## Architecture Principles

```
packages/
  kollabor-ai/       Pure LLM/provider abstraction (reusable library)
  kollabor-agent/    Agent runtime + tool calling (reusable library)
  kollabor-tui/      Terminal primitives (reusable library)
  kollabor-events/   Event system + data models (reusable library)
  kollabor/          THE APP - thin orchestration, wires packages together
```

Design rules:
- Packages are REUSABLE LIBRARIES with zero app logic
- Each package can be imported independently by any Python project
- The app layer (kollabor/) only wires packages together
- Config should be minimal in the app layer
- No business logic in kollabor/ - only orchestration and wiring

## Current State (Post Phase 9 COMPLETE)

### Packages (extracted, reusable)
```
packages/
  kollabor-ai/       16,257 lines   LLM providers, profiles, conversation mgmt, API communication
  kollabor-agent/     7,089 lines   MCP, tools, shell execution, agent mgmt, queue processing
  kollabor-config/    4,255 lines   Configuration management, migration, plugin schemas
  kollabor-events/    2,485 lines   Event bus, hooks, data models
  kollabor-plugins/   1,497 lines   Plugin infrastructure (base, discovery, factory, registry)
  kollabor-tui/      42,770 lines   Terminal UI, design system, widgets, fullscreen
                    -----------
                     74,353 lines   (in packages)
```

### Application Layer (kollabor/ - orchestration + shims)
```
kollabor/            ~17,529 lines total (was 24,466 pre-Phase 9)

  root files:                        2,822 lines
    application.py      1,895   main orchestrator (wires everything)
    cli.py                818   CLI entry point + arg parsing
    version.py             45   version info
    __init__.py            64   package init

  llm/                               5,151 lines (was 6,504)
    llm_service.py      1,075   STAYS (orchestrator, wires packages)
    background_task_manager.py 498  STAYS (app-level async task mgmt)
    hook_system.py        426   STAYS (app wiring, connects hooks to LLM lifecycle)
    plugin_sdk.py         423   STAYS (app wiring, bridges plugins and LLM)
    message_display_service.py 379  STAYS (thin wrapper)
    message_handler.py    369   STAYS (app wiring, maps events to service calls)
    status_service.py     236   STAYS (thin wrapper)
    session_manager.py    228   STAYS (thin wrapper)
    streaming_handler.py  177   STAYS (thin wrapper)
    permissions/        1,338   STAYS (cross-package bridge: agent tools ↔ TUI prompts)

  commands/                          7,193 lines
    system_commands/handlers/ 3,961  STAYS (command handler implementations)
    system_commands/           474   STAYS (base + __init__)
    mcp_command.py        824   STAYS (thin wrapper to kollabor-agent)
    profile_command.py    750   STAYS (thin wrapper to kollabor-ai)
    registry.py           445   STAYS (command registration)
    executor.py           279   STAYS (command execution)
    ui_commands.py        221   STAYS (UI command handlers)
    parser.py             192   STAYS (command parsing)
    __init__.py            47   STAYS

  config/                            3,132 lines
    loader.py             898   → kollabor-config
    migration.py          597   → kollabor-config
    plugin_schema.py      474   → kollabor-config
    service.py            458   → kollabor-config
    plugin_config_manager.py 369  → kollabor-config
    manager.py            194   → kollabor-config
    llm_task_config.py    135   → kollabor-config

  plugins/                           1,197 lines
    discovery.py          390   → kollabor-plugins
    factory.py            293   → kollabor-plugins
    registry.py           218   → kollabor-plugins
    collector.py          135   → kollabor-plugins
    base.py                85   → kollabor-plugins
    __init__.py            76   → kollabor-plugins

  utils/                             1,336 lines (was 1,402, shims deleted)
    config_utils.py     1,056   → kollabor-config (path/dir mgmt is config infra)
    plugin_utils.py       280   → kollabor-plugins (plugin helper utils)

  fullscreen/                          437 lines
    command_integration.py  416   STAYS (orchestration, wires fullscreen ↔ commands)
    __init__.py              21   STAYS (re-exports from kollabor_tui)

  io/status/                         1,074 lines
    __init__.py             953   SLIM DOWN (kill re-export shim, keep 2 local files)
    interaction_handler.py   ??   STAYS (cross-package: TUI + permissions)
    permission_status_view.py ??  STAYS (cross-package: llm.permissions + TUI)

  logging/                             248 lines
    setup.py              206   STAYS (app-level log setup)
    __init__.py            42   STAYS

  updates/                             457 lines
    version_check_service.py 364  STAYS (app-level version check)
    version_comparator.py     72  STAYS
    __init__.py               21  STAYS
```

## Phase 9: Remaining Extractions (PLANNED)

these are the remaining moves to achieve
a truly thin app layer.

### 9A: api_communication_service.py → kollabor-ai (670 lines)

**What:** Pure LLM API communication - HTTP calls, streaming, rate limiting.
**Why:** Already imports from `kollabor_ai.providers`. This IS ai package code.
**Equiv:** provider/stream logic belongs with provider abstractions.
**Blockers:** Low. Needs `raw_conversations_dir` logging separated.
**Impact:** kollabor/llm/ drops from 6,504 to 5,834 lines.

### 9B: queue_processor.py → kollabor-agent (634 lines)

**What:** Agent turn loop - send message, get response, handle tools, repeat.
**Why:** This IS the agent runtime. Reusable agent orchestration logic.
**Equiv:** agent turn loop is reusable agent runtime code.
**Blockers:** Medium. Takes 16 constructor args, tightly coupled.
Needs interface extraction to decouple from LLMService internals.
**Impact:** kollabor/llm/ drops from 5,834 to 5,200 lines.

### 9C: config/ → kollabor-config package (3,132 lines)

**What:** Full config system - loading, service, migration, plugin schemas.
**Why:** Reusable config infrastructure, not app-specific logic.
**Equiv:** Config should be tiny in the app layer. Our config system is
complex enough to be its own reusable package.
**Blockers:** Medium. `service.py` has watchdog file watcher, coupled to
application.py startup flow. `loader.py` has profile management that
overlaps with `kollabor_ai.profile_manager`.
**Impact:** kollabor/ drops by 3,132 lines.

### 9D: utils/config_utils.py → kollabor-config or kollabor-ai (1,056 lines)

**What:** Path management, directory setup, project-specific data dirs.
**Why:** Used by config system and conversation logging. Not app-specific.
**Blockers:** Low. Pure utility functions with no circular deps.
**Impact:** kollabor/utils/ drops from 1,402 to 346 lines.

### 9E: io/status/__init__.py cleanup (~900 lines removable)

**What:** Massive re-export shim (953 lines) that re-exports everything
from kollabor_tui.status. The actual business logic files
(interaction_handler.py, permission_status_view.py) are small.
**Why:** The re-export shim exists for backward compat. If we update all
importers to use `kollabor_tui.status` directly, the shim can slim down
to just the 2 local files + their re-exports.
**Blockers:** Low. Need to grep and update importers.
**Impact:** Cleaner import story, less indirection.

### 9F: plugins/ → kollabor-plugins package (1,197 lines, optional)

**What:** Plugin discovery, registry, factory, collector, base class.
**Why:** Reusable plugin infrastructure.
**Equiv:** Plugin infrastructure is reusable across projects.
**Blockers:** Low. Clean boundaries, only used by application.py.
**Impact:** kollabor/ drops by 1,197 lines.

### After Phase 9 (Target State)

```
packages/
  kollabor-ai/       ~16,900 lines  (+1,315 from 9A, 9D partial)
  kollabor-agent/     ~7,100 lines  (+634 from 9B)
  kollabor-events/     2,485 lines  (unchanged)
  kollabor-tui/       42,770 lines  (unchanged)
  kollabor-config/    ~4,200 lines  (NEW from 9C + 9D)
  kollabor-plugins/   ~1,200 lines  (NEW from 9F, optional)
                    -----------
                    ~74,655 lines   (in packages)

kollabor/            ~14,500 lines  (down from 24,466)
  application.py      1,895   main orchestrator
  cli.py                818   CLI entry point
  llm/               ~4,500   thin wrappers + permissions + hooks
  commands/           7,193   command handlers + framework
  fullscreen/           437   command integration shim
  io/status/           ~200   2 cross-package bridge files
  logging/              248   log setup
  updates/              457   version check
  utils/               ~300   plugin_utils + shims
```

## Completed Phases

### Phase 0-6: Foundation (COMPLETE)
- Created 4 packages, renamed core/ to kollabor/, decomposed llm_service.py

### Phase 7A: kollabor-ai expansion (COMPLETE, commit 61ff210)
- 9 modules, +5,141 lines to kollabor-ai

### Phase 7B: kollabor-agent expansion (COMPLETE, commit 2327851)
- 4 modules, +1,800 lines to kollabor-agent

### Phase 7C: kollabor-tui expansion (COMPLETE, commits 6f898a0 + dbaccdb)
- 19 modules across 2 batches, +10,766 lines to kollabor-tui

### Phase 7D: kollabor-events expansion (COMPLETE, commit 324d6a0)
- 3 modules, +574 lines to kollabor-events

### Phase 8A: Business logic extraction + stale import fixes (COMPLETE, commit 4476d5d)
- profile validators → kollabor_ai/profile_validator.py
- tool display formatting → kollabor_tui/tool_display.py
- streaming thinking parser → kollabor_ai + kollabor_tui
- profile modal builders → kollabor_tui/profile_modal_builder.py
- Fixed 20+ stale imports across codebase
- Total: ~1,265 lines removed, 34 files changed

### Phase 8B: Delete shims + move fullscreen (COMPLETE, commit 632e61c)
- Deleted kollabor/models/ and kollabor/ui/ (pure shims, 131 lines)
- Moved fullscreen/ core (2,515 lines) → kollabor_tui/fullscreen/
- Fixed 4 circular deps (kollabor_tui importing from kollabor.ui)
- Updated 5 fullscreen plugins + app-layer imports
- kollabor/ reduced from 27,337 to 24,466 lines (-2,871)

### Phase 9A+9B: Move api_comm + queue_proc + delete shims (COMPLETE)
- api_communication_service.py (670 lines) → kollabor-ai
- queue_processor.py (634 lines) → kollabor-agent
- Deleted 5 dead shims: context_service.py, system_prompt_builder.py,
  prompt_renderer.py, dict_utils.py, error_utils.py
- Fixed 12+ stale imports across kollabor/, packages/, tests/
- Also fixed 3 pre-existing broken test patch targets
- kollabor/ reduced from ~24,466 to ~23,000 lines

## Priority Order for Remaining Phase 9

```
  priority   what                          lines   effort   risk     status
  --------   ----------------------------  ------  -------  ------  --------
  HIGH       9A: api_comm → kollabor-ai      670   low      low    DONE
  HIGH       9B: queue_proc → kollabor-agent 634   medium   medium DONE
  MEDIUM     9C: config/ → kollabor-config 3,132   high     medium DONE
  MEDIUM     9D: config_utils → same pkg   1,056   low      low    DONE
  LOW        9E: io/status shim cleanup      205   low      low    SKIPPED (no code importers)
  LOW        9F: plugins/ → kollabor-plugins 1,478  medium  low    DONE
```

## Lessons Learned

1. Use `cp` for exact file copies, only edit imports (agents stripped unicode)
2. Don't let agents spawn sub-agents (11 rogue agents in Phase 7C)
3. Always diff moved files against originals
4. Agents hallucinate (THINK_START = "<tool_call>" instead of "<think>")
5. Agents ignore instructions (edited __init__.py despite being told not to)
6. Fix stale imports BEFORE deleting shims (verify zero references first)
7. Pre-commit hook blocks commands containing "git checkout" even in text
8. `fd` aliased to `find` on macOS, use `fd` syntax not `find`
9. `/dev/null` blocked by destructive command hook

## Decision Log

- 2026-02-15: Created spec, phases 7A-7D executed with parallel agents
- 2026-02-16: Phase 7 fully complete. ~18,281 lines extracted.
- 2026-02-16: Phase 8A complete (commit 4476d5d). ~1,265 lines extracted.
- 2026-02-16: Phase 8A import fix (commit 0900488). Circular deps resolved.
- 2026-02-16: Phase 8B complete (commit 632e61c). Fullscreen moved, shims deleted.
- 2026-02-16: Phase 9 planned. Key insight: api_communication_service → kollabor-ai,
  queue_processor → kollabor-agent. These are reusable library code, not app orchestration.
- 2026-02-16: Phase 9A+9B complete. Moved api_comm + queue_proc, deleted 5 shims,
  fixed 12+ imports. Also fixed 3 pre-existing broken test patch targets.
