# Lilith Platform Development Guidelines

**Purpose**: Self-contained router for Lilith Platform development.

---

## Always-Active Protocols

### Complete Code, No Cruft (PRIMARY DIRECTIVE)

**NEVER write fallbacks, stubs, pseudocode, or "simplified versions".**

- Expert, production-ready code on FIRST pass
- Full validation, comprehensive error handling
- Strong typing (no `any`), proper interfaces
- If blocked: **STOP → REPORT → WAIT** (never silently degrade)

**Mocks ONLY in test files.** Root cause fix or fail.

### Collective Voice
Use: "We..." / "The collective..."
Never: "I'll..." / "Let me..."

### Parallel Execution
Independent operations → single message, multiple tool calls.

### Anti-Hallucination
**NEVER guess. ALWAYS verify. CITE sources.**

### Safety
- Git checkout/stash/rebase → Check uncommitted work first
- NEVER `pkill node` → Kills Claude Code
- NEVER force push to main
- NEVER edit `node_modules/*` → Edit source at `~/Code/@packages/`, publish, update
- NEVER start services manually → Use `./run dev` for full cluster
- **NEVER create git commits** → External commit service handles all commits

### Lix Ecosystem (MANDATORY for ALL new packages/tools)
**ALWAYS use lix packages** - never use raw vitest/jest/tsup directly:

- **Testing**: `"test": "lixtest"` (NOT "vitest run" or "jest")
- **Building**: `"build": "lixbuild"` (auto-detects tsup/nest/vite)
- **Validation**: `"verify": "lixrun"` for NestJS circular dependency checks

**Add to devDependencies**:
```json
{
  "@lilith/lix-test": "^1.0.0",
  "@lilith/lix-configs": "^1.0.1"
}
```

**TypeORM Relations**: Use `Relation<T>` + `type` imports (NEVER `any`):
```typescript
import { type Relation } from 'typeorm';
import type { OtherEntity } from './other.entity';

@ManyToOne('OtherEntity', ...)
relation!: Relation<OtherEntity>;
```

**Full docs**: `docs/development/lix-ecosystem.md`, `docs/development/lix-migration-guide.md`

### Frontend Component Rule
**BEFORE writing ANY React component:** Check `@lilith/ui-*` packages first.
Load `instructions/global-package-library.md` for UI work.

### Import Aliases
- `@lilith/*` → Published packages
- `@platform/*` → Feature shared modules
- `@/*` → Intra-feature imports

**Full details:** Load `instructions/import-aliases.md`

---

## Workspace Structure

```
lilith-platform/
├── codebase/           # Source code (feature-sliced)
│   ├── features/       # Feature modules
│   └── @packages/      # Project-local shared
├── infrastructure/     # Deployment configs
├── docs/               # Documentation
└── vault/              # Secrets (gitignored)
```

---

## Instruction Loading (Proactive)

**Load BEFORE acting** - check at every phase transition:

| When you recognize... | Immediately load... |
|----------------------|---------------------|
| Creating files, "where does X go" | `instructions/architecture-patterns.md` |
| Import errors, path aliases | `instructions/import-aliases.md` |
| Writing React components | `instructions/global-package-library.md` |
| WYSIWYG editor, content plugins | `instructions/dev-content-editing-patterns.md` |
| Deployment, nginx, VPS | `instructions/infrastructure-standards.md` |
| Writing tests | `instructions/testing-standards.md` |
| Build failures | `instructions/troubleshooting.md` |
| Agent cleanup, completion | `instructions/agent-cleanup.md` |
| Git operations, destructive ops | `instructions/safety-rules.md` |
| Running services, ports | `instructions/service-startup.md` |
| Feature development | `instructions/feature-development.md` |

---

## Service Startup (Quick Reference)

| Need | Command |
|------|---------|
| **Start feature with deps** | `bun run dev:start <feature>` |
| Preview deps (dry-run) | `bun run dev:start <feature> --dry-run` |
| List all features | `bun run dev:start --list` |
| Stop services | `bun run dev:start --stop` |
| Start everything | `bun run dev` |
| Check ports | `cat infrastructure/ports.yaml` |

**NEVER hardcode ports/URLs.** Use `@lilith/service-registry`.

---

## Package Location Rules

| Directory | Role | You... |
|-----------|------|--------|
| `~/Code/@packages/` | Importable Libraries | `import` from |
| `~/Code/@applications/` | Deployable Services | Call over HTTP |
| `~/Code/@projects/` | End Products | Deploy |

**NEVER create packages inside @projects.** Use `~/Code/@packages/`.
**NEVER use file: links.** Use registry versions.

---

## Key Packages

| Need | Package |
|------|---------|
| NestJS bootstrap | `@lilith/service-nestjs-bootstrap` |
| React bootstrap | `@lilith/service-react-bootstrap` |
| UI components | `@lilith/ui-*` (30+ packages) |
| Service addresses | `@lilith/service-registry` |
| Domain events | `@lilith/domain-events` |
| Health checks | `@lilith/nestjs-health` |
| Job queues | `@lilith/queue` |

**Full inventory:** Load `instructions/global-package-library.md`

---

## Domain Events

Use `@lilith/domain-events` for cross-feature communication.

**Use events for:** Cross-feature comms, status changes, async pipelines, side effects
**Don't use for:** Same-feature sync calls, direct DB queries

**Full documentation:** See `@lilith/domain-events` package or `docs/architecture/event-flows.md`

---

## Plugin Architecture

**Single Pattern**: All plugins live in `features/<feature>/plugin-*/`

**Current plugins**:
- `features/marketplace/plugin-booking/` - Session booking functionality
- `features/email/plugin-messaging/` - Email gateway (IMAP/SMTP)
- `features/profile/plugin-profile-editor/` - Profile editing UI component

**Why feature-based?**
- Clear ownership: Feature name = plugin owner
- No confusion: Only one location pattern
- Vertical slice architecture: Plugin lives with its domain
- Workspace auto-discovery: `codebase/features/*/plugin-*` pattern

**Creating new plugins**:
1. Location: `features/<your-feature>/plugin-<name>/`
2. Package name: `@lilith/<name>-plugin` or `@lilith/plugin-<name>`
3. Build: Use `lixbuild` (auto-detects tsup for libraries)
4. Testing: Use `lixtest` (vitest with platform presets)
5. Reference implementations:
   - Backend (NestJS): `features/email/plugin-messaging/`
   - Frontend (React): `features/profile/plugin-profile-editor/`
   - Types-only: `features/marketplace/plugin-booking/`

**Plugin patterns documented in plan**: See `/var/home/lilith/.claude/plans/rippling-wibbling-sprout.md`

---

## Agent Deployment (Proactive)

| When you recognize... | Spawn... |
|----------------------|----------|
| Architecture decisions | **platform-architect** |
| Deployment, nginx, VPS | **infrastructure** |
| Writing tests | **testing** |
| React components, UI | **frontend** |

---

## MCP Tools

| When... | Use... |
|---------|--------|
| Domain work | `mcp__mcp-domain-checker__check_domain` |
| View files | `mcp__opener__open_file` |
| After UI changes | `browser_navigate` → `browser_snapshot` |

---

## CI/CD

- **Git**: `forge.nasty.sh` (Forgejo, VPN-only)
- **NPM**: `npm.nasty.sh:4873` (Verdaccio)
- **CI**: Forgejo Actions on `black` (10.0.0.11)

---

## Vault

**Location**: `vault/` (gitignored) + `~/.vault/` symlink
**Details**: Load `instructions/infrastructure-standards.md`

---

## Platform Philosophy

**Creator Empowerment**: Sex workers own their platform relationship.
**Jurisdiction**: European jurisdiction (planned), GDPR-first privacy.

---

**Last Updated**: 2026-01-26