# Split Monolith

> Safe procedure for decomposing a god file (400+ LOC) into a sub-package without breaking any imports. Load when a file exceeds 400 lines or mixes multiple concerns. Implements vibecodex Principles A1 and A8 — folder-instead-of-file with backward-compatible re-exports.

- **Type:** Skill
- **Install:** `agentstack add skill-yerdaulet-damir-vibe-coding-rules-split-monolith`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yerdaulet-damir](https://agentstack.voostack.com/s/yerdaulet-damir)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yerdaulet-damir](https://github.com/yerdaulet-damir)
- **Source:** https://github.com/yerdaulet-damir/vibe-coding-rules/tree/main/.claude/skills/split-monolith
- **Website:** https://vibecodex-omega.vercel.app

## Install

```sh
agentstack add skill-yerdaulet-damir-vibe-coding-rules-split-monolith
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# split-monolith

A file split done wrong breaks every caller. Follow this procedure exactly — it is reversible at every step.

---

## Step 0 — Confirm the file needs splitting

```bash
wc -l app/services/.py
```

| Lines | Action |
|-------|--------|
|  600 | Split immediately (Principle A7 hard cap) |

Also ask: does this file mix multiple concerns? A file that is long but cohesive is better than a premature split.

---

## Step 1 — Identify the domain splits

Do NOT split by size. Split by **type of responsibility**.

Good splits (by domain):
```
wallet_service.py (1200 LOC) →
  wallet/user.py      ← user-facing operations (charge, refund)
  wallet/admin.py     ← admin operations (top-up, override)
  wallet/history.py   ← read-only queries
```

Good splits (by layer):
```
generation_service.py (1000 LOC) →
  generation/orchestrator.py   ← coordinates the flow
  generation/cost.py           ← cost calculation logic
  generation/storage.py        ← result persistence
```

Bad splits (by size only — don't do this):
```
big_service.py →
  big_service_part1.py   ← meaningless
  big_service_part2.py   ← meaningless
```

Write the target structure before touching any file.

---

## Step 2 — Create the package directory

```bash
mkdir app/services//
```

Do NOT move any code yet.

---

## Step 3 — Create sub-files one at a time

For each sub-file, copy (not move) the relevant functions:

```bash
# Create the new file with the relevant subset
touch app/services//user.py
# Copy relevant classes/functions from the original
```

Each sub-file must:
- Have its own imports (do not rely on `*` imports)
- Be under 200 LOC (you're splitting — keep it lean)
- Contain one cohesive responsibility

---

## Step 4 — Create `__init__.py` with ALL old names re-exported

This is the most important step. Every name that existed in the original file must still be importable from the same path.

```python
# app/services//__init__.py

# Principle A8: re-export everything so callers don't change.
from app.services..user import CreditsUserService
from app.services..admin import CreditsAdminService
from app.services..user import get_credits_user_service

# Backward-compat alias if the old class had a different name
CreditsService = CreditsUserService  # old name → new class

__all__ = [
    "CreditsUserService",
    "CreditsAdminService",
    "CreditsService",           # backward compat
    "get_credits_user_service",
]
```

---

## Step 5 — Verify no import breaks

```bash
# Check every file that imported from the old module still works
python3 -c "from app.services. import "
python3 -c "from app.services. import "

# Run the full test suite
pytest tests/ -x -q
```

All tests must be GREEN before deleting the original file.

---

## Step 6 — Delete the original file

Only after Step 5 passes:

```bash
rm app/services/.py
```

Run tests again:

```bash
pytest tests/ -x -q
bash scripts/lint-architecture.sh
```

Both must pass.

---

## Common mistakes

| Mistake | Consequence | Prevention |
|---------|------------|------------|
| Split before writing `__init__.py` | Import errors everywhere | Always create `__init__.py` first |
| Split by size, not responsibility | Sub-files still coupled | Ask: "what is the single job of this file?" |
| Forget to re-export old names | Callers break silently | List every public name before splitting |
| Move code instead of copy+verify | Can't roll back | Copy first, delete only after tests pass |
| Split and refactor at same time | Impossible to debug | One PR = one split. No logic changes. |

---

## Verification

The split was done correctly when:
- [ ] All sub-files are under 200 LOC
- [ ] `__init__.py` re-exports every name that existed before
- [ ] `python3 -c "from app.services. import "` works
- [ ] `pytest tests/ -x -q` is green
- [ ] `bash scripts/lint-architecture.sh` exits 0
- [ ] Original file is deleted

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yerdaulet-damir](https://github.com/yerdaulet-damir)
- **Source:** [yerdaulet-damir/vibe-coding-rules](https://github.com/yerdaulet-damir/vibe-coding-rules)
- **License:** MIT
- **Homepage:** https://vibecodex-omega.vercel.app

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yerdaulet-damir-vibe-coding-rules-split-monolith
- Seller: https://agentstack.voostack.com/s/yerdaulet-damir
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.