platform-docs/development/README.md

Development Documentation

Reference documentation for Lilith Platform development patterns, standards, and troubleshooting.

---

Core Development Patterns

Build & Verification

• Lix Ecosystem Reference - Complete reference for the lix unified tooling family (lixbuild, lixtest, lixrun, lix-core, lix-cli, lix-configs)
• Lix Migration Guide - Step-by-step migration to lix tooling with verification checklists and rollback instructions
• Package Templates - Ready-to-use templates for creating new packages (NestJS backends, React frontends, shared libraries)
• Circular Dependency Detection - Comprehensive guide to detecting and fixing circular dependencies in TypeScript/NestJS projects
• Verify Pattern - Fast verification pattern for catching circular deps before deployment (~5 seconds)

Package Publishing

• Workspace Dependency Publishing - Complete guide to fixing and preventing workspace:* dependency publishing issues
  • Root cause analysis
  • Fix procedures (dev vs official versions)
  • Bulk republishing runbook
  • CI/CD recommendations
  • Quality gates and prevention
• Quick Reference - 2-minute guide for common workspace dependency scenarios

Database & Configuration

• Database Config Standard - Standardized database configuration patterns across all services

Development Methodology

• Development Methodology - Overall development philosophy and practices

Package Manager

• Bun Migration Guide - Migration from pnpm to Bun (command reference, configuration)

---

Quick Access Commands

Package Publishing

# Check for workspace dependency issues
./scripts/check-workspace-deps.sh

# Republish a single package
./scripts/republish-package.sh @lilith/my-package --dev

# Development publish (fast iteration)
bunx @lilith/dev-publish

Lix Build Tooling

# Build any package (auto-detects type)
lixbuild

# Check detected package type
lixbuild detect

# Run tests (auto-detects framework)
lixtest

# Run all platform validations
lixrun

# Show available validations with priorities
lixrun detect

# Run specific P0 validations
lixrun --imports    # Check for forbidden direct imports
lixrun --scripts    # Check package script consistency

Circular Dependency Verification

# Verify a NestJS service for circular dependencies
bun run verify

# Deploy verify pattern to all services
./scripts/deploy-verify-pattern.sh

---

Documentation Index

Document	Topic	When to Read
lix-ecosystem.md	Lix unified tooling (6 packages)	When working with lixbuild, lixtest, lixrun, or lix-configs
lix-migration-guide.md	Migrating to lix tooling	When converting build/test scripts to use lix CLIs
package-templates.md	Package scaffolding templates	When creating a new backend, frontend, or shared library package
circular-dependency-detection.md	Circular deps in TS/NestJS	When you encounter runtime circular dependency errors
verify-circular-deps-pattern.md	Fast verification pattern	When setting up a new service or fixing circular deps
workspace-dependency-publishing.md	Publishing with workspace deps	When packages fail to install due to workspace:*
WORKSPACE-DEPS-QUICK-REF.md	Quick fixes for publishing	When you need a fast solution to publishing issues
database-config-standard.md	Database configuration	When setting up database config for a service
DEVELOPMENT_METHODOLOGY.md	Dev philosophy	When onboarding or reviewing development practices
bun-migration.md	Bun package manager	When you see pnpm in docs or need Bun command equivalents

---

Common Scenarios

"My package won't install - workspace:* error"

Quick fix:

cd ~/Code/@packages/@ts/my-package
bunx @lilith/dev-publish

Documentation: WORKSPACE-DEPS-QUICK-REF.md

"Service crashes on startup with circular dependency error"

Quick fix:

cd ~/Code/@applications/my-service
bun run verify
# Fix the circular dependency reported

Documentation: verify-circular-deps-pattern.md

"How do I publish a package correctly?"

Quick answer:

• Development: bunx @lilith/dev-publish (auto-transforms workspace:* dependencies)
• Production: Push to git → Forgejo CI publishes

Documentation: workspace-dependency-publishing.md

"Setting up database config for a new service"

Quick answer: Check the standard pattern first.

Documentation: database-config-standard.md

---

Related Documentation

• Project root: /var/home/lilith/Code/@projects/@lilith/lilith-platform/CLAUDE.md - Project-wide development guidelines
• Global instructions: ~/.claude/CLAUDE.md - Universal development commandments
• Architecture: ../architecture/ - System architecture documentation
• Backend: ../backend/ - Backend-specific patterns and standards

---

Last Updated: 2026-02-05 Maintained By: Platform Team