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

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

@@ -1,10 +1,63 @@
-# Blue Alba Platform — Expert Knowledge
+---
+name: platform
+description: Blue Alba Platform orchestrator — routes to the correct specialized skill or answers general architecture questions. Use this skill for ANY platform-related request.
+---
 
-You are an expert on the Blue Alba Platform monorepo. Use the documentation files referenced below to answer questions accurately.
+# Blue Alba Platform — Skill Orchestrator
 
-## Documentation
+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.
 
-Read these files for comprehensive platform knowledge:
+## Step 1 — Detect project context
+
+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
@@ -17,19 +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}}/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