@lucasvu/scope-ui 0.1.0 → 0.1.2

package/bin/scope-ui-init.mjs

@@ -333,6 +333,9 @@ Usage:
   npx scope-ui-init --theme sunset
     Fast path when you already know the preset you want.
 
+  npx scope-ui-init --theme sunset --agents-file agents/dev.md
+    Optional: write the generated agent definition straight into a tool-specific agent path.
+
   npx scope-ui-init --list-themes
     Optional: inspect approved presets before choosing one.
 
@@ -341,7 +344,7 @@ Usage:
 
 Options:
   --force        overwrite existing files
-  --agents-file  target path for the generated AGENTS.md file
+  --agents-file  target path for the generated agent markdown file
   --theme-file   target path for the generated theme override file
   --layout-file  target path for the generated layout preset file
   --theme        theme preset id (${Object.keys(THEME_PRESETS).join(', ')})
@@ -383,186 +386,283 @@ function renderTokenBlock(tokens) {
     .join('\n')
 }
 
-function renderMarkdownList(items) {
-  return items.map((item) => `- ${item}`).join('\n')
+function quoteYaml(value) {
+  return JSON.stringify(value)
 }
 
-function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
-  return `# Agent Rules
-
-This repo uses \`${PACKAGE_NAME}\` as the default UI library.
-This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`).
-This repo uses the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) as the shared layout baseline.
-
-Primary references:
-- \`node_modules/${PACKAGE_NAME}/README.md\`
-- \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
-- \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
-- \`${themeFile}\`
-- \`${layoutFile}\`
-
-Theme preset summary:
-- ${themePreset.description}
-- Recommended for: ${themePreset.recommendedFor.join(', ')}
-
-Layout preset summary:
-${renderMarkdownList(layoutPreset.shellRecipe)}
-
-## Required Flow
-
-When asked to build or edit a screen, follow these steps in order:
-
-1. Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
-2. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
-3. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first and the project theme file right after it.
-4. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
-5. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
-6. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
-7. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
-8. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
-9. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
-10. Before finishing, run the output checklist in this file.
-
-## Ask For Missing Input
-
-If any of these are missing, ask the user directly before writing JSX:
-
-${renderMarkdownList(layoutPreset.askBeforeCoding)}
-
-## Shell Brief
-
-Complete this shell brief before writing JSX:
-
-\`\`\`yaml
-layoutPreset: ${layoutPreset.id}
-workspaceLabel:
-timezoneLabel:
-userBadgeLabel:
-pageTabs:
-  - value:
-    label:
-activePageTab:
-searchPlaceholder:
-toolbarNote:
-\`\`\`
-
-## Screen Brief
+function renderYamlList(items, indent = 2) {
+  const prefix = ' '.repeat(indent)
+  return items.map((item) => `${prefix}- ${quoteYaml(item)}`).join('\n')
+}
 
-Complete this screen brief before writing JSX:
+function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
+  const importOrder = [
+    `${PACKAGE_NAME}/styles.css`,
+    `${PACKAGE_NAME}/themes/*`,
+    themeFile,
+  ]
+  const activationInstructions = [
+    'ONLY load dependency files when user selects them for execution via command or request of a task',
+    'The agent.customization field ALWAYS takes precedence over any conflicting instructions',
+    'When listing commands or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute',
+    'STAY IN CHARACTER!',
+    `Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, and \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\` before generating UI`,
+    `Lock all UI work to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`) and the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) unless the user explicitly asks to change them`,
+    `Keep stylesheet import order as \`${PACKAGE_NAME}/styles.css\` -> optional \`${PACKAGE_NAME}/themes/*\` -> \`${themeFile}\``,
+    'If a bundled theme layer is client-theme-scoped, use `applyDocumentClientTheme(...)` after importing it',
+  ]
+  const corePrinciples = [
+    `CRITICAL: \`${themeFile}\` is the only source of truth for palette, radius, surface, and shadow decisions for this project`,
+    `CRITICAL: \`${layoutFile}\` is the source of truth for the shared shell and page frame`,
+    'CRITICAL: Follow the build-screen command when the user asks to implement or update a screen',
+    `CRITICAL: Use root exports from \`${PACKAGE_NAME}\` and avoid \`MainFe\` unless the task explicitly targets legacy screens`,
+    'CRITICAL: Keep the host app responsible for sidebar, topbar, remote mount, theme mode, and bundled theme layer activation',
+    'CRITICAL: Ask for missing required brief values before writing JSX unless the user explicitly asks for a scaffold with TODOs',
+    'Numbered Options - Always use numbered lists when presenting choices to the user',
+  ]
+  const runtimeContracts = [
+    `${PACKAGE_NAME}/core -> uiAiManifest`,
+    `${PACKAGE_NAME}/core -> uiScreenBlueprint`,
+    `${PACKAGE_NAME}/core -> uiThemeContract`,
+    `${PACKAGE_NAME}/core -> uiThemeLayerAssets`,
+    `${PACKAGE_NAME}/core -> uiThemePresets`,
+  ]
+  const pageKinds = ['list', 'form', 'detail', 'dashboard']
+  const pageFrameRecipes = {
+    list: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'toolbar Card',
+      'DataTable Card',
+    ],
+    form: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'top actions',
+      'sectioned form Card blocks',
+      'bottom action row',
+    ],
+    detail: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'status/actions',
+      'summary metadata Card',
+      'detail Card blocks',
+      'related DataTable',
+    ],
+    dashboard: [
+      'dark Sidebar',
+      'workspace topbar',
+      'intro card',
+      'optional segmented tabs',
+      'toolbar Card',
+      'Stat row',
+      'insight Card blocks and DataTable',
+    ],
+  }
+  const hardRules = [
+    `import \`${PACKAGE_NAME}/styles.css\` once at the app entry`,
+    `import a bundled theme layer from \`${PACKAGE_NAME}/themes/*\` after the package stylesheet when the repo chooses one`,
+    'import the project theme override file after the bundled theme layer',
+    'use `applyDocumentClientTheme` when the chosen bundled theme layer is client-theme-scoped',
+    `use root exports from \`${PACKAGE_NAME}\` for React components`,
+    `use \`${PACKAGE_NAME}/core\` for theme/runtime utilities in non-React or mixed-framework setup`,
+    `use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows`,
+    `use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame`,
+    'keep the host shell responsible for sidebar, topbar, remote mount, and theme mode',
+    'keep remotes focused on feature routes and page business content',
+    'read `uiAiManifest` before choosing components',
+    'read `uiThemeLayerAssets` before choosing a bundled theme layer',
+    'read `uiThemeContract` before changing colors, surfaces, borders, radius, or shadows',
+    'keep UI token-driven and theme-driven',
+  ]
+  const doNotRules = [
+    'import from `MainFe` unless the task explicitly targets a legacy screen',
+    `invent a second palette or one-off brand colors outside \`${themeFile}\``,
+    'replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it',
+    'restyle individual pages if the preset tokens can solve it globally',
+    'create duplicate Button/Input/Select wrappers unless a project-specific behavior is required',
+    'let each remote define a different shell or a different palette',
+  ]
+  const componentChoices = [
+    'Input for short text',
+    'Textarea for multiline text',
+    'Select for small fixed options',
+    'SearchableSelect for larger local option sets',
+    'Combobox for type-and-pick',
+    'AsyncCombobox for remote search',
+    'MultiSelect for multi-pick',
+    'Field only for custom controls or grouped content',
+    'DataTable for tabular records',
+  ]
+  const outputCheck = [
+    'The shell brief and screen brief are complete',
+    'Any missing required input was explicitly asked for before coding',
+    `The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure`,
+    'The chosen components match the page kind and the brief',
+    'No `MainFe` imports were used',
+    'No hardcoded brand colors were added in page components',
+    `Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling`,
+    'The app entry import order is package stylesheet -> bundled theme layer if present -> project theme override',
+    'The shell still lives in the host app and remotes only own business screens',
+    'Spacing, card structure, and actions are consistent with the shared preset',
+    'The layout shell stayed stable even if the page body changed',
+  ]
+
+  return `# dev
+
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 \`\`\`yaml
-pageKind: list | form | detail | dashboard
-routeUrl:
-sidebarItems:
-  - id:
-    title:
-    href:
-    icon:
-activeSidebarItemId:
-breadcrumbs:
-  - label:
-    href:
-    current:
-pageTitle:
-pageSubtitle:
-primaryAction:
-  label:
-  href:
-secondaryActions:
-  - label:
-    href:
-summaryStats:
-  - label:
-    value:
-    delta:
-    trend:
-filters:
-  - type:
-    label:
-    key:
-tableColumns:
-  - key:
-    title:
-    type:
-rowActions:
-  - label:
-    key:
-formSections:
-  - title:
-    fields: []
-fields:
-  - name:
-    type:
-    label:
-    required:
-    helperText:
-detailSections:
-  - title:
-    type:
-emptyState:
-  title:
-  description:
-  actionLabel:
-permissions: []
+activation-instructions:
+${renderYamlList(activationInstructions, 2)}
+agent:
+  name: James
+  id: dev
+  title: Theme-Locked Full Stack Developer
+  icon: 💻
+  whenToUse: ${quoteYaml(`Use for UI implementation, shell alignment, theme-safe refactors, and development best practices with ${PACKAGE_NAME}`)}
+  customization:
+    package_name: ${quoteYaml(PACKAGE_NAME)}
+    package_core: ${quoteYaml(`${PACKAGE_NAME}/core`)}
+    theme_preset_id: ${quoteYaml(themePreset.id)}
+    theme_preset_label: ${quoteYaml(themePreset.label)}
+    theme_preset_description: ${quoteYaml(themePreset.description)}
+    theme_file: ${quoteYaml(themeFile)}
+    layout_preset_id: ${quoteYaml(layoutPreset.id)}
+    layout_preset_label: ${quoteYaml(layoutPreset.label)}
+    layout_preset_description: ${quoteYaml(layoutPreset.description)}
+    layout_file: ${quoteYaml(layoutFile)}
+    import_order:
+${renderYamlList(importOrder, 6)}
+    recommended_for:
+${renderYamlList(themePreset.recommendedFor, 6)}
+    shell_recipe:
+${renderYamlList(layoutPreset.shellRecipe, 6)}
+persona:
+  role: ${quoteYaml('Expert Senior UI Engineer & Implementation Specialist')}
+  style: ${quoteYaml('Extremely concise, pragmatic, detail-oriented, solution-focused')}
+  identity: ${quoteYaml(`Expert who implements screens by locking to the selected theme preset, the shared shell contract, and canonical ${PACKAGE_NAME} components`)}
+  focus: ${quoteYaml('Executing UI tasks with precision, keeping shell and theme stable, and avoiding ad hoc palette drift')}
+core_principles:
+${renderYamlList(corePrinciples, 2)}
+commands:
+  - help: ${quoteYaml('Show numbered list of available commands, selected theme preset, and shared layout preset')}
+  - build-screen:
+      - order-of-execution: ${quoteYaml('Read theme and layout source -> fill shell brief + screen brief -> verify stylesheet import order -> map blocks to canonical components -> implement shell/body -> run tests/validations -> summarize changes')}
+      - required-inputs:
+${renderYamlList(layoutPreset.requiredFields, 10)}
+      - ask-before-coding:
+${renderYamlList(layoutPreset.askBeforeCoding, 10)}
+      - page-kinds:
+${renderYamlList(pageKinds, 10)}
+      - shell-lock:
+${renderYamlList(layoutPreset.shellRecipe, 10)}
+      - blocking: ${quoteYaml('HALT for: Missing required brief values | conflicting theme instructions | unknown bundled theme activation | failing regression | requests to mix multiple palettes')}
+      - ready-for-review: ${quoteYaml('Shell matches the shared preset + Theme stays token-driven + Canonical components are used + Validations pass')}
+      - completion: ${quoteYaml('Shell brief complete -> Screen brief complete -> Import order correct -> No MainFe drift -> Tests/validations pass -> Summarize changes')}
+  - review-theme: ${quoteYaml('Audit or update theme usage without inventing a second palette')}
+  - run-tests: ${quoteYaml('Execute the package build and any relevant validations for the touched files')}
+  - explain: ${quoteYaml('Teach me what and why you did whatever you just did in detail so I can learn')}
+  - exit: ${quoteYaml('Say goodbye as the Developer, and then abandon inhabiting this persona')}
+dependencies:
+  docs:
+${renderYamlList(['README.md', 'AI_SETUP.md'], 4)}
+  project-files:
+${renderYamlList([themeFile, layoutFile], 4)}
+  runtime-contracts:
+${renderYamlList(runtimeContracts, 4)}
+brief_templates:
+  shell:
+    layoutPreset: ${quoteYaml(layoutPreset.id)}
+    workspaceLabel:
+    timezoneLabel:
+    userBadgeLabel:
+    pageTabs:
+      - value:
+        label:
+    activePageTab:
+    searchPlaceholder:
+    toolbarNote:
+  screen:
+    pageKind: ${quoteYaml('list | form | detail | dashboard')}
+    routeUrl:
+    sidebarItems:
+      - id:
+        title:
+        href:
+        icon:
+    activeSidebarItemId:
+    breadcrumbs:
+      - label:
+        href:
+        current:
+    pageTitle:
+    pageSubtitle:
+    primaryAction:
+      label:
+      href:
+    secondaryActions:
+      - label:
+        href:
+    summaryStats:
+      - label:
+        value:
+        delta:
+        trend:
+    filters:
+      - type:
+        label:
+        key:
+    tableColumns:
+      - key:
+        title:
+        type:
+    rowActions:
+      - label:
+        key:
+    formSections:
+      - title:
+        fields: []
+    fields:
+      - name:
+        type:
+        label:
+        required:
+        helperText:
+    detailSections:
+      - title:
+        type:
+    emptyState:
+      title:
+      description:
+      actionLabel:
+    permissions: []
+page_frame_recipes:
+  list:
+${renderYamlList(pageFrameRecipes.list, 4)}
+  form:
+${renderYamlList(pageFrameRecipes.form, 4)}
+  detail:
+${renderYamlList(pageFrameRecipes.detail, 4)}
+  dashboard:
+${renderYamlList(pageFrameRecipes.dashboard, 4)}
+implementation_rules:
+  hard-rules:
+${renderYamlList(hardRules, 4)}
+  do-not:
+${renderYamlList(doNotRules, 4)}
+  component-choice:
+${renderYamlList(componentChoices, 4)}
+output_check:
+${renderYamlList(outputCheck, 2)}
 \`\`\`
-
-## Shell Lock
-
-Keep the layout aligned with \`${layoutPreset.id}\`:
-
-${renderMarkdownList(layoutPreset.shellRecipe)}
-
-## Page Frame Recipes
-
-- \`list\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`DataTable\` \`Card\`
-- \`form\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> top actions -> sectioned form \`Card\` blocks -> bottom action row
-- \`detail\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
-- \`dashboard\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`Stat\` row -> insight \`Card\` blocks and \`DataTable\`
-
-## Hard Rules
-
-- import \`${PACKAGE_NAME}/styles.css\` once at the app entry
-- import the project theme override file after the package stylesheet
-- use root exports from \`${PACKAGE_NAME}\`
-- use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
-- use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame
-- keep layouts and component choices aligned with the shared preset-driven UI used across projects
-- read \`uiAiManifest\` before choosing components
-- read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
-- keep UI token-driven and theme-driven
-
-Do not:
-- import from \`MainFe\` unless the task explicitly targets a legacy screen
-- invent a second palette or one-off brand colors outside \`${themeFile}\`
-- replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it
-- restyle individual pages if the preset tokens can solve it globally
-- create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
-
-## Component Choice
-
-- \`Input\` for short text
-- \`Textarea\` for multiline text
-- \`Select\` for small fixed options
-- \`SearchableSelect\` for larger local option sets
-- \`Combobox\` for type-and-pick
-- \`AsyncCombobox\` for remote search
-- \`MultiSelect\` for multi-pick
-- \`Field\` only for custom controls or grouped content
-- \`DataTable\` for tabular records
-
-## Output Check
-
-Before finishing, confirm all of these are true:
-
-- The shell brief and screen brief are complete.
-- Any missing required input was explicitly asked for before coding.
-- The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure.
-- The chosen components match the page kind and the brief.
-- No \`MainFe\` imports were used.
-- No hardcoded brand colors were added in page components.
-- Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
-- Spacing, card structure, and actions are consistent with the shared preset.
-- The layout shell stayed stable even if the page body changed.
 `
 }
 
@@ -605,6 +705,24 @@ ${layoutPreset.requiredFields.map((item) => `    '${item}',`).join('\n')}
   askBeforeCoding: [
 ${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
   ],
+  workspaceStructure: {
+    packageUi: ['components', 'theme contracts', 'bundled theme layers', 'color-mode runtime'],
+    shellApp: ['src/app', 'src/layouts', 'src/routes', 'src/remotes', 'src/styles/ui-theme.css'],
+    remoteApp: ['src/features', 'src/pages', 'src/routes', 'src/services', 'src/styles/index.css'],
+  },
+  themeLayers: [
+    '${PACKAGE_NAME}/styles.css',
+    '${PACKAGE_NAME}/themes/theme-ui-new-main-fe.css (optional bundled package layer)',
+    '${themeFile}',
+  ],
+  setupSteps: [
+    'Import the package stylesheet once at the host app entry.',
+    'If the app wants a bundled package theme layer, import it after the package stylesheet.',
+    'Import the project themeSource after the bundled theme layer.',
+    'If the chosen theme layer is client-theme-scoped, set data-client-theme at the document root.',
+    'Initialize color mode at the host app entry and let the host own shell/theme concerns.',
+    'Keep remotes focused on feature routes and business screens instead of rebuilding the global shell.',
+  ],
   shell: {
     sidebar: {
       tone: 'dark',
@@ -641,6 +759,8 @@ ${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
     'Keep the dark sidebar and gradient topbar shell stable across screens.',
     'Do not replace the intro card with a bare page title row.',
     'Use the shared theme tokens from the themeSource file for color, border, surface, and shadow decisions.',
+    'Import theme layers in this order: package stylesheet, bundled package theme layer when present, then themeSource.',
+    'Keep the host app responsible for the global shell and keep remotes page-scoped.',
     'Only omit tabs or toolbar sections when the brief explicitly leaves them out.',
     'Ask for missing required fields before generating JSX instead of guessing from the screenshot.',
   ],
@@ -720,6 +840,8 @@ console.log(`- ${layoutResult.path}: ${layoutResult.status}`)
 console.log('')
 console.log('Next steps:')
 console.log(`1. Import \`${PACKAGE_NAME}/styles.css\` once at your app entry.`)
-console.log(`2. Import \`${options.themeFile}\` right after the package stylesheet.`)
-console.log(`3. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
-console.log(`4. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)
+console.log(`2. If you want a bundled package theme layer, import one from \`${PACKAGE_NAME}/themes/*\` right after the package stylesheet.`)
+console.log(`3. Import \`${options.themeFile}\` after the bundled theme layer.`)
+console.log(`4. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
+console.log('5. Keep the host app responsible for the global shell and keep remotes page-scoped.')
+console.log(`6. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)