Platform Constitution

✓ Examples

• · A date picker is built once and shared via the component library
• · User authentication is a single service consumed by all modules
• · File upload is handled by the Core integration, never reimplemented

✗ Anti-Patterns

• · Copy-pasting a component and modifying it
• · Building a new auth flow for a special case
• · Creating a parallel data model that duplicates an existing entity

✓ Examples

• · A form builder used by BusinessOS™ is also used by HealthcareiOS™
• · A workflow engine serves government approvals and publishing pipelines alike
• · Analytics dashboards are composable widgets, not hardcoded pages

✗ Anti-Patterns

• · Hardcoding a workflow to a specific industry
• · Building a dashboard that only works for one entity type
• · Creating a form that cannot be templated

✓ Examples

• · Entity CRUD is available via SDK before the admin page exists
• · Workflow triggers are API endpoints, not just buttons
• · Analytics data is queryable, not just displayed

✓ Examples

• · A project belongs to an organization
• · A workflow runs within a workspace
• · An analytics dashboard filters by department

✗ Anti-Patterns

• · Creating an entity without organization_id
• · Querying without organization scope
• · Assuming single-tenancy in business logic

✓ Examples

• · A list endpoint filters by what the user can see
• · A create operation checks the user role
• · An admin action is logged with who, what, and when

✓ Examples

• · Executive Search finds projects, risks, decisions, and people
• · Knowledge Center searches documentation and glossary
• · Marketplace is fully searchable by category and tag

✓ Examples

• · Every entity has a schema page in the Knowledge Center
• · Every API endpoint has examples and response schemas
• · Every admin page has a user guide

✗ Anti-Patterns

• · Shipping a feature and documenting it later
• · Relying on tribal knowledge
• · Outdated docs that do not match the code

✓ Examples

• · Platform versions track releases
• · API versions allow backward compatibility
• · Entity schemas evolve without data loss

✓ Examples

• · An operating system enables only the modules it needs
• · A marketplace package can extend any OS
• · Modules are installed per organization, not hardcoded

✓ Examples

• · Admin layouts collapse to drawer navigation
• · Data tables become cards on mobile
• · Forms are touch-friendly by default

✓ Examples

• · Every interactive element has a focus state
• · Every image has alt text
• · Every form field has a label

✗ Anti-Patterns

• · Color-only indicators without text
• · Click handlers on non-interactive elements
• · Missing ARIA attributes on dynamic content

✓ Examples

• · Entity CRUD has integration tests
• · UI components have snapshot tests
• · Workflows have execution tests

✓ Examples

• · Entity operations are logged in audit trail
• · API errors are captured with full context
• · Performance metrics are tracked per endpoint

✓ Examples

• · All API calls require authentication
• · All secrets are stored in the secrets manager
• · All data is encrypted at rest and in transit

✓ Examples

• · Webhooks fire on entity events
• · Workflows can be customized per organization
• · The marketplace allows third-party modules

✓ Examples

• · A project list page shows projects, not project creation forms
• · A settings page groups by concern, not by feature team
• · A dashboard shows metrics, not configuration

✗ Anti-Patterns

• · Modal within modal within modal
• · A single page handling create, list, and detail
• · Tabs that fundamentally change the page purpose

✓ Examples

• · All padding uses the spacing scale (p-4, p-6, p-8)
• · All text uses font-heading, font-body, font-display tokens
• · All colors use semantic tokens (bg-card, text-muted-foreground)

✗ Anti-Patterns

• · Inline styles with hardcoded hex colors
• · Arbitrary pixel values for spacing
• · Different font families per page

✓ Examples

• · "No projects yet. Create your first project to get started."
• · An icon and a call-to-action button
• · A link to documentation

✗ Anti-Patterns

• · A blank page
• · A generic "No data" message
• · An empty table with headers but no rows and no explanation

✓ Examples

• · A spinner while data loads
• · A skeleton placeholder for content structure
• · An error message with a "Try again" button

✗ Anti-Patterns

• · A frozen page with no feedback
• · A raw error message like "500 Internal Server Error"
• · A blank screen during loading

✓ Examples

• · All colors use CSS variables with light and dark values
• · All components render correctly in both modes
• · Images and icons have proper contrast in both modes

✓ Examples

• · Tab order follows visual order
• · Enter activates buttons and links
• · Escape closes modals and menus

✓ Examples

• · "Generating briefing from live data..."
• · "AI analyzed 200 records and found 5 risks"
• · Tool calls are visible in the conversation with status and results

✗ Anti-Patterns

• · AI that modifies data without notification
• · Results presented without indicating AI was involved
• · Hidden AI processing with no user feedback

✓ Examples

• · AI-generated briefings can be edited before publishing
• · AI recommendations appear as suggestions, not commands
• · AI tool calls show parameters and results for inspection

✗ Anti-Patterns

• · AI that publishes content directly
• · AI that deletes records without confirmation
• · AI that sends emails without review

✓ Examples

• · AI generates a new version of a document, keeping the original
• · AI suggests edits as tracked changes, not replacements
• · AI creates new records rather than modifying existing ones

✗ Anti-Patterns

• · AI that replaces document content in place
• · AI that updates entity fields without showing the diff
• · AI that regenerates over previous AI output without history

✓ Examples

• · AI returns {title, summary, risks: []} not a paragraph
• · AI classifications use enums, not free-form labels
• · AI-generated content is stored as structured fields

✓ Examples

• · AI search only returns results the user has permission to view
• · AI summaries only include data from entities the user can access
• · AI does not use service-role access for user-facing features

✗ Anti-Patterns

• · AI using admin credentials to answer user questions
• · AI exposing data from other organizations
• · AI that bypasses RLS policies

✓ Examples

• · You can create a briefing manually or generate one with AI
• · You can write content or use AI to draft it
• · You can search manually or ask the AI

✗ Anti-Patterns

• · A feature that only works with AI
• · A workflow that requires AI approval
• · A page with no manual fallback

✓ Examples

• · A new entity has a schema page, API reference, and user guide
• · A new admin page has a screenshot and step-by-step instructions
• · A new API endpoint has request/response examples

✗ Anti-Patterns

• · Shipping first, documenting later
• · Documentation that does not match the shipped feature
• · Missing API examples

✓ Examples

• · Platform Engine™ is always "Platform Engine™" everywhere
• · Organization is never "Org", "Tenant", or "Account"
• · Operating System™ is always "Operating System™" not "OS"

✗ Anti-Patterns

• · Using "tenant" in the API and "organization" in the UI
• · Abbreviating names differently in different contexts
• · Renaming a concept without migrating all references

✓ Examples

• · UniversaliOS™ (first mention), UniversaliOS (subsequent)
• · Barnett Intelligence™
• · Platform Studio™

✗ Anti-Patterns

• · Inconsistent ™ usage
• · Using ® instead of ™
• · Forgetting trademarks in API docs

✓ Examples

• · /platform-engines/publishing-engine
• · /executive/risks
• · /knowledge/getting-started

✗ Anti-Patterns

• · /page?id=123
• · /PlatformEngines/PublishingEngine
• · /exec_risks

✓ Examples

• · CI runs all tests on every PR
• · Accessibility scanner runs on every UI change
• · Security review required for new API endpoints

✗ Anti-Patterns

• · Merging with failing tests "just this once"
• · Skipping accessibility review for a "quick fix"
• · Shipping without docs and adding them later

✓ Examples

• · Before building a new chart component, check the analytics widget library
• · Before building a new form, check the form builder
• · Before building a new search, check the executive search infrastructure

✗ Anti-Patterns

• · "I did not know it existed so I built a new one"
• · Building a parallel system because the existing one is "too complex"
• · Forking a module instead of extending it

✓ Examples

• · Generous whitespace over dense layouts
• · Monochrome palettes with purposeful accent colors
• · System fonts over decorative fonts

✗ Anti-Patterns

• · Gratuitous animations
• · Decorative gradients that serve no purpose
• · Following the latest design trend

✓ Examples

• · Smooth transitions and micro-interactions
• · Consistent iconography across the platform
• · Premium typography with proper hierarchy

✗ Anti-Patterns

• · Cluttered interfaces
• · Inconsistent spacing
• · Jarring transitions or no transitions

✓ Examples

• · A workflow engine that supports any process — timeless
• · An OS factory that generates any industry — timeless
• · A hardcoded integration with a specific vendor — not timeless

✗ Anti-Patterns

• · Building for a specific customer's one-off request
• · Hardcoding business logic that will change
• · Optimizing for a current trend

✓ Examples

• · A document editor — platform feature (all OS products need it)
• · A legal case management module — OS-specific (AttorneyiOS™ only)
• · A patient records system — OS-specific (MedicaliOS™ only)

✗ Anti-Patterns

• · Putting industry-specific logic in a platform engine
• · Building an OS feature into the core platform
• · Coupling platform features to a specific OS

✓ Examples

• · The form builder became the Universal Form Builder™ — infrastructure
• · The workflow engine became a Platform Engine™ — infrastructure
• · The analytics system became the Universal Analytics Engine™ — infrastructure

✗ Anti-Patterns

• · Building a feature that only serves one use case
• · Not extracting shared patterns into engines
• · Duplicating infrastructure across modules

✓ Examples

• · PublishingiOS™ and MedicaliOS™ share the same platform core
• · A government organization and a healthcare org use the same BusinessOS™
• · The same codebase publishes to web, iOS, and Android

✗ Anti-Patterns

• · Forking the codebase for a specific customer
• · Maintaining separate branches per industry
• · Building a different platform for each OS product

✓ Examples

• · PublishingiOS™ is an Intelligent Operating System™, not a separate platform
• · The Workflow Engine is a Platform Engine™, not a product
• · Barnett Intelligence™ is the company, not a product name

✗ Anti-Patterns

• · Calling an OS product a "platform"
• · Creating a new layer outside the hierarchy
• · Mixing company identity with product identity