238 lines
7.3 KiB
Markdown
238 lines
7.3 KiB
Markdown
# 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
|