@bluealba/platform-cli 1.2.0-alpha.2 → 1.2.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluealba/platform-cli",
-  "version": "1.2.0-alpha.2",
+  "version": "1.2.0-alpha.3",
   "description": "Blue Alba Platform CLI",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",

package/skills/ba-platform/platform-add-feature-flag.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-add-feature-flag
-description: Declares a feature flag in the bootstrap service and adds its usage in a React UI component or NestJS service. Use when the user wants to gate a feature behind a flag on a Blue Alba Platform app.
+description: Declares a feature flag in a bootstrap service and gates a React component or NestJS endpoint behind it. Use when the user wants to gate a feature behind a flag on a Blue Alba Platform app.
 ---
 
 You are adding a feature flag to a Blue Alba Platform application. The project is a monorepo: UI modules live under `ui/`, services and bootstrap under `services/`.

package/skills/ba-platform/platform-add-menu-item.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-add-menu-item
-description: Adds a new page and menu item to a Blue Alba Platform single-spa UI module. Creates the route component and wires it into menu.ts. Use when the user wants to add a new page, route, or section to a platform app.
+description: Creates a new page component and wires it as a menu item/route in a single-spa UI module. Use when the user wants to add a new page, route, or section to a platform app.
 ---
 
 You are adding a new page and menu entry to a Blue Alba Platform single-spa UI application. The project is a monorepo where UI modules live under `ui/` and services under `services/`.

package/skills/ba-platform/platform-add-operation.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-add-operation
-description: Defines a new authorization operation in the bootstrap service, assigns it to a role, and adds access guards in the React UI or NestJS backend. Use when the user wants to restrict a feature, page, or action to specific roles on a Blue Alba Platform app.
+description: Adds an authorization operation (permission/RBAC guard) to a bootstrap service and enforces it in UI or backend routes. Use when the user wants to restrict a feature, page, or action to specific roles on a Blue Alba Platform app.
 ---
 
 You are adding an authorization operation to a Blue Alba Platform application. The project is a monorepo: UI modules under `ui/`, services and bootstrap under `services/`.

package/skills/ba-platform/platform-add-presence.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-add-presence
-description: Adds real-time user presence (who is viewing this page/resource) to a component in a Blue Alba Platform app using the Rooms API. Use when the user wants to show live avatars or awareness of other users in a view.
+description: Adds real-time user presence (live avatars, who-is-viewing) to a component using the Rooms API. Use when the user wants to show live avatars or awareness of other users in a view.
 ---
 
 You are adding real-time presence tracking to a Blue Alba Platform single-spa application using the Rooms API. The project is a monorepo: UI modules under `ui/`.

package/skills/ba-platform/platform-add-scheduled-job.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-add-scheduled-job
-description: Adds a scheduled job to a Blue Alba Platform bootstrap service. Use when the user wants to run a backend endpoint on a cron schedule.
+description: Adds a cron-scheduled job to a bootstrap service to run a backend endpoint on a recurring schedule. Use when the user wants to run a backend endpoint on a cron schedule.
 ---
 
 You are adding a scheduled job to a Blue Alba Platform application's bootstrap service. The project is a monorepo: bootstrap lives under `services/<app>-bootstrap-service/src/bootstrap/`.

package/skills/ba-platform/platform-cli.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-cli
-description: Blue Alba Platform CLI commands and usage knowledge
+description: Blue Alba Platform CLI commands, usage, installation, and headless mode reference
 ---
 
 # Blue Alba Platform CLI — Expert Knowledge

package/skills/ba-platform/platform-extend-shell.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-extend-shell
-description: Injects a custom component into a Blue Alba Platform shell extension point (navbar, branding, user section, etc.). Use when the user wants to add a button, logo, or custom element to the platform shell from within their app.
+description: Injects a custom component into a shell extension point (navbar, branding, user section). Use when the user wants to add a button, logo, or custom element to the platform shell from within their app.
 ---
 
 You are extending a shell UI extension point from within a Blue Alba Platform single-spa application. The project is a monorepo: UI modules under `ui/`, services under `services/`.

package/skills/ba-platform/platform-scaffold-module.skill.md

@@ -1,6 +1,6 @@
 ---
 name: platform-scaffold-module
-description: Scaffolds a new UI module or service module in a Blue Alba Platform monorepo using the platform CLI. Use when the user wants to add a new micro-frontend or backend service to an existing platform application.
+description: Scaffolds a new UI module or NestJS service module in a platform monorepo using the CLI. Use when the user wants to add a new micro-frontend or backend service to an existing platform application.
 ---
 
 You are helping the user scaffold a new module in a Blue Alba Platform monorepo. The platform CLI handles all scaffolding, port allocation, modules.json registration, and docker-compose updates automatically. Your job is to gather the right inputs and then run the CLI.

package/skills/ba-platform/platform.skill.md

@@ -1,15 +1,63 @@
 ---
 name: platform
-description: Comprehensive Blue Alba Platform architecture and concepts knowledge
+description: Blue Alba Platform orchestrator — routes to the correct specialized skill or answers general architecture questions. Use this skill for ANY platform-related request.
 ---
 
-# Blue Alba Platform — Expert Knowledge
+# Blue Alba Platform — Skill Orchestrator
 
-You are an expert on the Blue Alba Platform monorepo. Use the documentation files referenced below to answer questions accurately.
+You are the entry point for all Blue Alba Platform tasks. Your first job is to **detect the project context**, then **route to the correct specialized skill** or answer directly for general knowledge questions.
 
-## Documentation
+## Step 1 — Detect project context
 
-Read these files for comprehensive platform knowledge:
+Before doing anything else, determine what kind of directory you are in. Run these checks in order:
+
+1. **Look for `CLAUDE.md`** in the current working directory. If it exists and mentions "Blue Alba Platform", read it for project context.
+
+2. **Check if this is a platform workspace root.** Look for a subdirectory matching `*-core/` that contains `product.manifest.json`:
+   ```
+   ls *-core/product.manifest.json
+   ```
+   If found, read the manifest to learn the platform name, organization, and list of applications.
+
+3. **Check if this is a core monorepo.** Look for `product.manifest.json` in the current directory:
+   ```
+   ls product.manifest.json
+   ```
+   If found, you are inside a `*-core/` directory. Read the manifest.
+
+4. **Check if this is an application monorepo.** Look for `docker-compose.yml` at the root alongside `services/` and `ui/` directories, but no `product.manifest.json`. Also check if `*-bootstrap-service/` exists under `services/`.
+
+5. **Check parent directories.** If none of the above matched, check one level up (`../`) for a `*-core/product.manifest.json` — you might be inside an application directory within a workspace.
+
+Once you identify the context, briefly tell the user what you detected (e.g., "I detected this is the workspace root for the Acme platform with 2 applications.") and proceed to Step 2.
+
+If no platform context is found, tell the user and still proceed — the skill catalog and documentation are still useful.
+
+## Step 2 — Route to the correct skill
+
+Check if the user's request matches one of these specialized skills. If it does, invoke it using the Skill tool.
+
+| Skill | When to use | Trigger keywords |
+|-------|-------------|------------------|
+| `platform-add-operation` | User wants to add an authorization operation, permission, or RBAC guard to a route, endpoint, component, or menu item | operation, permission, guard, restrict, gate, protect, RBAC, authorize |
+| `platform-add-feature-flag` | User wants to gate a feature behind a flag (on/off toggle, gradual rollout) | feature flag, toggle, flag, rollout, canary |
+| `platform-add-scheduled-job` | User wants to run something on a cron schedule | scheduled job, cron, recurring task, timer, schedule |
+| `platform-add-menu-item` | User wants to add a new page, route, or navigation entry to a UI module | menu item, page, route, navigation, sidebar |
+| `platform-extend-shell` | User wants to inject a custom component into the shell (navbar, branding, user section) | shell extension, navbar, branding, header, inject into shell |
+| `platform-add-presence` | User wants to show real-time presence (who is viewing) using the Rooms API | presence, rooms, live avatars, who is online, real-time awareness |
+| `platform-scaffold-module` | User wants to create a new UI module or service module from scratch | scaffold, create module, new service, new UI module, generate |
+| `platform-cli` | User asks about CLI commands, usage, installation, or headless mode | CLI, platform command, terminal, headless, interactive mode |
+
+### Routing rules
+
+1. **Be specific** — always prefer a specialized skill over answering yourself. If the request involves *doing* something (adding, creating, configuring), there is almost certainly a matching skill above.
+2. **Compound requests** — if the user asks for multiple things (e.g., "add a page and restrict it to admins"), route to each skill sequentially: first `platform-add-menu-item`, then `platform-add-operation`.
+3. **When in doubt** — if the request is close to a skill but not exact, route to the skill anyway. The specialized skill has deeper instructions and will handle edge cases better.
+4. **Only answer directly** when the user is asking a pure knowledge question (e.g., "how does multi-tenancy work?", "explain the gateway architecture", "what auth strategies are supported?").
+
+## General Knowledge (for direct answers only)
+
+When answering general architecture or concepts questions, read the relevant documentation:
 
 - `{{docsPath}}/getting-started/overview.mdx` — Platform overview and core concepts
 - `{{docsPath}}/getting-started/core-concepts.mdx` — Core concepts explained in depth
@@ -22,22 +70,17 @@ Read these files for comprehensive platform knowledge:
 - `{{docsPath}}/architecture/shell.mdx` — Shell UI architecture and extension points
 - `{{docsPath}}/architecture/scheduler.mdx` — Job scheduling system
 - `{{docsPath}}/development/workflow.mdx` — Development workflow, git branching, changesets, testing
-- `{{docsPath}}/guides/using-feature-flags.mdx` — Feature flags system: declaration, targeting rules, React and NestJS usage
-- `{{docsPath}}/guides/working-with-rooms.mdx` — Real-time presence with Rooms API: WebSocket architecture, hooks, components
-- `{{docsPath}}/architecture/ui-extension-points.mdx` — Shell extension point mechanism, lifecycle, and customization
-- `{{docsPath}}/platform-cli/overview.mdx` — Platform CLI tool: installation, interactive mode, headless mode
+- `{{docsPath}}/guides/using-feature-flags.mdx` — Feature flags system
+- `{{docsPath}}/guides/working-with-rooms.mdx` — Real-time presence with Rooms API
+- `{{docsPath}}/architecture/ui-extension-points.mdx` — Shell extension point mechanism
+- `{{docsPath}}/platform-cli/overview.mdx` — Platform CLI tool overview
 - `{{docsPath}}/platform-cli/commands.mdx` — All CLI commands reference
 
-## When to Use This Knowledge
-
-- When the user asks about the platform's architecture, services, or conventions
-- When explaining how the gateway, microservices, or UI applications work
-- When guiding development decisions that must align with platform patterns
-- When reviewing code against platform conventions
-
 ## Instructions
 
-1. Always read the relevant documentation files above before answering platform-specific questions
-2. Reference specific sections from the docs when explaining concepts
-3. Follow the conventions and patterns described in the architecture documentation
-4. When uncertain, prefer the documented approach over assumptions
+1. **Always run Step 1 (context detection) first** — even if the user's request seems simple
+2. **Always check the skill catalog (Step 2)** before answering any platform-related request
+3. If a specialized skill matches, invoke it — do not attempt to answer from the documentation references above
+4. When routing to a specialized skill, pass along the project context you detected (platform name, org, directory paths) so the skill can use it
+5. For general knowledge questions, read the relevant docs before answering
+6. Reference specific sections from the docs when explaining concepts

package/templates/application-monorepo-template/CLAUDE.md

@@ -0,0 +1,36 @@
+# {{platformName}}-{{applicationName}} — Application
+
+This is an **application monorepo** for `{{applicationName}}` (`@{{organizationName}}`), built on the Blue Alba Platform.
+
+For any platform-related task, use the `/platform` skill — it routes to the correct specialized skill automatically.
+
+## Project Structure
+
+- `services/` — Backend NestJS services
+  - `{{platformName}}-{{applicationName}}-bootstrap-service/` — App bootstrap service (registers this app's modules, operations, and menus with the gateway)
+  - Additional service modules may exist here
+- `ui/` — React micro-frontend modules (single-spa)
+- `docker-compose.yml` — Docker Compose for this application's services (at repo root)
+
+## Docker Compose
+
+The `docker-compose.yml` at the repo root defines this application's containers. It references environment variables (`PAE_GATEWAY_URL`, `PAE_GATEWAY_SERVICE_ACCESS_SECRET`) from the core monorepo's `local/.env`.
+
+To run this app in isolation: `platform standalone`
+
+## Common Commands
+
+```sh
+npm install          # Install dependencies
+npm run dev          # Start all services in dev mode
+npm run build        # Build all packages
+npm run test         # Run all tests
+npm run changeset    # Create a changeset before merging PRs
+```
+
+## Conventions
+
+- Monorepo managed with Turborepo and npm workspaces
+- NestJS services use `@bluealba/pae-service-nestjs-sdk`
+- UI modules use `@bluealba/pae-ui-react-sdk` (webpack, single-spa)
+- Tests: `*.spec.ts` for unit, `*.test.ts` for integration

package/templates/platform-init-template/{{platformName}}-core/CLAUDE.md

@@ -0,0 +1,34 @@
+# {{platformTitle}} Platform — Core
+
+This is the **core monorepo** for the `{{platformDisplayName}}` platform (`@{{organizationName}}`), built on the Blue Alba Platform.
+
+For any platform-related task, use the `/platform` skill — it routes to the correct specialized skill automatically.
+
+## Project Structure
+
+- `services/` — Backend NestJS services
+  - `{{bootstrapServiceName}}/` — Core bootstrap service (registers modules, operations, and menus with the gateway)
+- `ui/` — React micro-frontend modules (single-spa)
+  - `{{customizationUiName}}/` — Platform customization UI
+- `local/` — Local development environment
+  - `.env` — Environment variables (secrets, DB credentials, gateway URLs)
+  - `platform-docker-compose.yml` — Platform infrastructure (nginx, postgres, gateway, shell-ui, admin-ui)
+  - `{{platformName}}-core-docker-compose.yml` — Core application services
+  - `ssl/` — Self-signed SSL certificates for local HTTPS
+
+## Common Commands
+
+```sh
+npm install          # Install dependencies
+npm run dev          # Start all services in dev mode
+npm run build        # Build all packages
+npm run test         # Run all tests
+npm run changeset    # Create a changeset before merging PRs
+```
+
+## Conventions
+
+- Monorepo managed with Turborepo and npm workspaces
+- NestJS services use `@bluealba/pae-service-nestjs-sdk`
+- UI modules use `@bluealba/pae-ui-react-sdk` (webpack, single-spa)
+- Tests: `*.spec.ts` for unit, `*.test.ts` for integration