add-feature

name	add-feature
description	Add features to an existing Mozaiks project. Helps users upgrade tiers or enable individual capabilities.
argument-hint	[optional: feature name or preset]

Before starting: git fetch origin && gh pr list --state open && git log origin/main --oneline -3 — if another agent has an open PR touching the same files you need, wait for it to merge or branch off it instead of main.

Help the user add features to an existing Mozaiks project.

Available Features

Mozaiks features are additive. You can enable them individually or upgrade to a higher tier preset.

Individual Features

Feature	What It Enables	Requires
chat_ui	Frontend chat interface	-
modules	Deterministic CRUD/action modules and module routes	-
event_bus	Domain event bus for module↔workflow communication	-
auth	Provider-neutral OIDC/JWT validation and browser PKCE auth	OIDC provider or local mock
admin	Admin portal with observability, token tracking	auth

Tier Presets

Preset	Features Included
engine	ai_runtime
chat	ai_runtime, chat_ui
integrated	ai_runtime, chat_ui, modules, event_bus, auth
full	All features

Commands

Enable Individual Feature

mozaiks add <feature>

Examples:

mozaiks add modules       # Add deterministic module handling
mozaiks add event_bus     # Add event-driven automation
mozaiks add auth          # Add provider-neutral OIDC/JWT authentication
mozaiks add admin         # Add admin portal

Upgrade to Higher Tier

mozaiks add --preset <tier>

Examples:

mozaiks add --preset chat        # Upgrade to chat tier
mozaiks add --preset integrated  # Upgrade to integrated tier
mozaiks add --preset full        # Upgrade to full tier

What Happens

When you add a feature:

1. Updates app/app.json:

   • Adds feature override OR upgrades preset
   • Example: {"features": {"modules": true}}

2. Shows next steps:

   • What directories to create
   • What config to update
   • What services to start

3. Requires restart:

   • Backend reads app.json at startup
   • Restart to apply changes

Feature-Specific Next Steps

Adding modules

Next steps:
1. Create app/modules/<name>/
2. Add module.yaml with identity, actions, permissions
3. Add backend/handler.py (thin dispatch), backend/service.py (logic),
   backend/repo.py (MongoDB), backend/policy.py (scoping), backend/schemas.py (typed shapes)
4. Restart backend: mozaiks serve .

Adding event_bus

Next steps:
1. Use event_bus.publish() to emit app events
2. Add workflow triggers in orchestrator.yaml
3. Restart backend

Adding auth

Next steps:
1. Update app/app.json: authRequired: true
2. Add or review app/config/auth.yaml using schema_version: mozaiks.auth.v1
3. Configure .env with AUTH_PROVIDER=jwt plus MOZAIKS_OIDC_* / AUTH_* / VITE_OIDC_* env handles
4. Use VITE_MOCK_MODE=true for local mock auth, or run the optional local OIDC broker from compose
5. Restart backend

Adding admin

Next steps:
1. Configure admins in app/app.json
2. Access admin portal at /admin
3. Requires auth to be enabled

Adding chat_ui

Next steps:
1. Install frontend deps once: npm --prefix web_shell install
2. Start frontend: .\scripts\run-frontend.ps1 (or npm --prefix web_shell run dev -- --host 0.0.0.0 --port 3000 --strictPort)
3. Configure branding in the active app bundle brand directory
4. Access chat/UI at http://localhost:3000
5. By default, web_shell resolves factory_app/app unless PLATFORM_PATH or -AppWorkspacePath is set

When to Use This Skill

• User wants to add a feature to existing project
• User says "enable modules" or "add auth"
• User wants to upgrade from one tier to another
• User asks "how do I add [feature]"

Check Current Config

Before adding features, check what's currently enabled:

mozaiks info

Example Interaction

User: "I want to add modules to my chatbot"

You: "You can enable modules with:

mozaiks add modules

This will:

1. Update app/app.json to enable the modules feature
2. Allow you to create modules in app/modules/

After running this command:

1. Create a module directory: app/modules/my_module/
2. Add module.yaml with id, actions, permissions
3. Add backend/handler.py (dispatch), backend/service.py (logic), backend/repo.py (data)
4. Restart your backend: mozaiks serve .

Modules are great for deterministic business logic that doesn't need AI. For AI tasks, use workflows instead."