npm - @delorenj/pjangler - Versions diffs - 1.2.25 → 1.3.0 - Mend

@delorenj/pjangler 1.2.25 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (849) hide show

package/templates/commonproject/_bmad/bmb/workflows/module/data/module-installer-standards.md DELETED Viewed

@@ -1,348 +0,0 @@
-# Module Installer Standards
-**Purpose:** How the `_module-installer` folder works, including installer.js patterns and platform-specific configuration.
----
-## Overview
-The `_module-installer` folder contains optional installation logic for your module. It runs AFTER the IDE installations and can:
-- Create directories specified in module.yaml
-- Copy assets or templates
-- Configure IDE-specific settings
-- Set up platform-specific integrations
----
-## When Do You Need an Installer?
-### Use an Installer When:
-- Creating directories based on user configuration
-- Copying template files to the user's project
-- IDE-specific setup (Claude Code, Windsurf, Cursor, etc.)
-- Platform-specific integrations
-### Skip the Installer When:
-- Module only provides agents and workflows
-- No file operations needed
-- No IDE-specific configuration
----
-## Folder Structure
-```
-_module-installer/
-├── installer.js                 # Main installer (REQUIRED if folder exists)
-└── platform-specifics/          # IDE-specific handlers (optional)
-    ├── claude-code.js
-    ├── windsurf.js
-    ├── cursor.js
-    └── ...
-```
----
-## installer.js Pattern
-### Function Signature
-```javascript
-/**
- * Module Installer
- *
- * @param {Object} options - Installation options
- * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from module.yaml (resolved variables)
- * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
- * @param {Object} options.logger - Logger instance for output
- * @returns {Promise<boolean>} - Success status (true = success, false = failure)
- */
-async function install(options) {
-  const { projectRoot, config, installedIDEs, logger } = options;
-  try {
-    // Installation logic here
-    logger.log(chalk.blue('Installing {Module Name}...'));
-    // ... your logic ...
-    logger.log(chalk.green('✓ {Module Name} installation complete'));
-    return true;
-  } catch (error) {
-    logger.error(chalk.red(`Error installing module: ${error.message}`));
-    return false;
-  }
-}
-module.exports = { install };
-```
----
-### What You Receive
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `projectRoot` | string | Absolute path to the user's project root |
-| `config` | object | Resolved module.yaml variables |
-| `installedIDEs` | array | List of IDE codes installed (e.g., `['claude-code', 'windsurf']`) |
-| `logger` | object | Logger with `.log()`, `.warn()`, `.error()` methods |
-The `config` object contains your module.yaml variables **after** user input:
-```javascript
-// If module.yaml defined:
-// project_name:
-//   prompt: "What is your project name?"
-//   result: "{value}"
-config.project_name  // = user's input
-config.planning_artifacts  // = resolved path
-```
----
-## Common Installation Tasks
-### 1. Create Directories
-```javascript
-const fs = require('fs-extra');
-const path = require('node:path');
-// Create directory from config
-if (config['planning_artifacts']) {
-  const dirConfig = config['planning_artifacts'].replace('{project-root}/', '');
-  const dirPath = path.join(projectRoot, dirConfig);
-  if (!(await fs.pathExists(dirPath))) {
-    logger.log(chalk.yellow(`Creating directory: ${dirConfig}`));
-    await fs.ensureDir(dirPath);
-  }
-}
-```
-### 2. Copy Assets
-```javascript
-const assetsSource = path.join(__dirname, 'assets');
-const assetsDest = path.join(projectRoot, 'docs');
-if (await fs.pathExists(assetsSource)) {
-  await fs.copy(assetsSource, assetsDest);
-  logger.log(chalk.green('✓ Copied assets to docs/'));
-}
-```
-### 3. IDE-Specific Configuration
-```javascript
-// Handle IDE-specific configurations
-if (installedIDEs && installedIDEs.length > 0) {
-  logger.log(chalk.cyan(`Configuring for IDEs: ${installedIDEs.join(', ')}`));
-  for (const ide of installedIDEs) {
-    await configureForIDE(ide, projectRoot, config, logger);
-  }
-}
-```
----
-## Platform-Specific Handlers
-### Pattern
-Create files in `platform-specifics/{ide-code}.js`:
-```javascript
-// platform-specifics/claude-code.js
-/**
- * Configure module for Claude Code
- */
-async function install(options) {
-  const { projectRoot, config, logger, platformInfo } = options;
-  try {
-    // Claude Code specific configuration
-    logger.log(chalk.dim('  Configuring Claude Code integration...'));
-    // Your logic here
-    return true;
-  } catch (error) {
-    logger.warn(chalk.yellow(`  Warning: ${error.message}`));
-    return false;
-  }
-}
-module.exports = { install };
-```
-### Load from Main Installer
-```javascript
-// installer.js
-const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes'));
-async function configureForIDE(ide, projectRoot, config, logger) {
-  // Validate platform code
-  if (!platformCodes.isValidPlatform(ide)) {
-    logger.warn(chalk.yellow(`  Unknown platform: '${ide}'. Skipping.`));
-    return;
-  }
-  const platformName = platformCodes.getDisplayName(ide);
-  const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`);
-  try {
-    if (await fs.pathExists(platformSpecificPath)) {
-      const platformHandler = require(platformSpecificPath);
-      if (typeof platformHandler.install === 'function') {
-        await platformHandler.install({ projectRoot, config, logger });
-        logger.log(chalk.green(`  ✓ Configured for ${platformName}`));
-      }
-    }
-  } catch (error) {
-    logger.warn(chalk.yellow(`  Warning: Could not configure ${platformName}: ${error.message}`));
-  }
-}
-```
----
-## Complete Example: BMM Installer
-```javascript
-const fs = require('fs-extra');
-const path = require('node:path');
-const chalk = require('chalk');
-const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/platform-codes'));
-/**
- * BMM Module Installer
- */
-async function install(options) {
-  const { projectRoot, config, installedIDEs, logger } = options;
-  try {
-    logger.log(chalk.blue('🚀 Installing BMM Module...'));
-    // Create output directory
-    if (config['output_folder']) {
-      const outputConfig = config['output_folder'].replace('{project-root}/', '');
-      const outputPath = path.join(projectRoot, outputConfig);
-      if (!(await fs.pathExists(outputPath))) {
-        logger.log(chalk.yellow(`Creating output directory: ${outputConfig}`));
-        await fs.ensureDir(outputPath);
-      }
-    }
-    // Create implementation artifacts directory
-    if (config['implementation_artifacts']) {
-      const storyConfig = config['implementation_artifacts'].replace('{project-root}/', '');
-      const storyPath = path.join(projectRoot, storyConfig);
-      if (!(await fs.pathExists(storyPath))) {
-        logger.log(chalk.yellow(`Creating story directory: ${storyConfig}`));
-        await fs.ensureDir(storyPath);
-      }
-    }
-    // IDE-specific configuration
-    if (installedIDEs && installedIDEs.length > 0) {
-      logger.log(chalk.cyan(`Configuring BMM for IDEs: ${installedIDEs.join(', ')}`));
-      for (const ide of installedIDEs) {
-        await configureForIDE(ide, projectRoot, config, logger);
-      }
-    }
-    logger.log(chalk.green('✓ BMM Module installation complete'));
-    return true;
-  } catch (error) {
-    logger.error(chalk.red(`Error installing BMM: ${error.message}`));
-    return false;
-  }
-}
-async function configureForIDE(ide, projectRoot, config, logger) {
-  if (!platformCodes.isValidPlatform(ide)) {
-    logger.warn(chalk.yellow(`  Warning: Unknown platform '${ide}'. Skipping.`));
-    return;
-  }
-  const platformSpecificPath = path.join(__dirname, 'platform-specifics', `${ide}.js`);
-  try {
-    if (await fs.pathExists(platformSpecificPath)) {
-      const platformHandler = require(platformSpecificPath);
-      if (typeof platformHandler.install === 'function') {
-        await platformHandler.install({ projectRoot, config, logger });
-      }
-    }
-  } catch (error) {
-    logger.warn(chalk.yellow(`  Warning: Could not load handler for ${ide}: ${error.message}`));
-  }
-}
-module.exports = { install };
-```
----
-## Best Practices
-### DO:
-- Return `true` for success, `false` for failure
-- Use chalk for colored output
-- Log what you're doing (create, copy, configure)
-- Handle errors gracefully with try/catch
-- Validate paths before creating directories
-### DON'T:
-- Assume paths exist — check with `fs.pathExists()`
-- Overwrite user files without asking
-- Fail silently — log errors
-- Use absolute paths — build from `projectRoot`
----
-## Available Platform Codes
-Common IDE codes:
-- `claude-code` — Anthropic's Claude Code
-- `windsurf` — Windsurf IDE
-- `cursor` — Cursor AI IDE
-- `vscode` — Visual Studio Code
-Use `platformCodes.isValidPlatform(ide)` to validate.
----
-## Testing Your Installer
-1. Create a test project
-2. Run `bmad install {your-module}`
-3. Verify directories are created
-4. Check that config variables are resolved correctly
-5. Test platform-specific handlers
----
-## Quick Reference
-| Task | Code Pattern |
-|------|--------------|
-| Create directory | `await fs.ensureDir(path)` |
-| Check if exists | `await fs.pathExists(path)` |
-| Copy files | `await fs.copy(src, dest)` |
-| Log info | `logger.log(chalk.blue('message'))` |
-| Log success | `logger.log(chalk.green('✓ message'))` |
-| Log warning | `logger.warn(chalk.yellow('warning'))` |
-| Log error | `logger.error(chalk.red('error'))` |

package/templates/commonproject/_bmad/bmb/workflows/module/data/module-standards.md DELETED Viewed

@@ -1,280 +0,0 @@
-# Module Standards
-**Purpose:** Defines what a BMAD module is, its structure, and the three types of modules.
----
-## What is a BMAD Module?
-A **BMAD module** is a self-contained package of functionality that extends the BMAD framework. Modules provide:
-- **Agents** — AI personas with specialized expertise and menu-driven commands
-- **Workflows** — Structured processes for accomplishing complex tasks
-- **Configuration** — module.yaml for user customization
-- **Installation** — Optional installer.js for setup logic
----
-## Module Types
-### 1. Standalone Module
-A new, independent module focused on a specific domain.
-**Characteristics:**
-- Own module code (e.g., `healthcare-ai`, `legal-assist`)
-- Independent of other modules
-- Can be installed alongside any other modules
-- Has its own agents, workflows, configuration
-**Location:** `src/modules/{module-code}/`
-**Example:** CIS (Creative Innovation Suite) — a standalone module for innovation workflows
----
-### 2. Extension Module
-Extends an existing BMAD module with additional functionality.
-**Characteristics:**
-- Builds upon an existing module's agents and workflows
-- May add new agents or workflows that complement the base module
-- Shares configuration context with the extended module
-- Typically installed alongside the module it extends
-**Location:** `src/modules/{base-module}/extensions/{extension-code}/`
-**Example:** An extension to BMM that adds specialized security review workflows
----
-### Extension Module: Override & Merge Pattern
-When an extension module is installed, its files merge with the base module following these rules:
-#### Code Matching
-The extension's `module.yaml` `code:` field matches the base module's code:
-```yaml
-# Base module: src/modules/bmm/module.yaml
-code: bmm
-# Extension: src/modules/bmm/extensions/security/module.yaml
-code: bmm  # SAME CODE — extends BMM
-```
-The **folder name** is unique (e.g., `bmm-security`) but the `code:` matches the base module.
-#### File Merge Rules
-| File Type | Same Name | Different Name |
-|-----------|-----------|----------------|
-| Agent file | **OVERRIDE** — replaces the base agent | **ADD** — new agent added |
-| Workflow folder | **OVERRIDE** — replaces the base workflow | **ADD** — new workflow added |
-| Other files | **OVERRIDE** — replaces base file | **ADD** — new file added |
-#### Examples
-**Override scenario:**
-```
-Base module (BMM):
-├── agents/
-│   └── pm.agent.yaml          # Original PM agent
-Extension (bmm-security):
-├── agents/
-│   └── pm.agent.yaml          # Security-focused PM — REPLACES original
-Result after installation:
-├── agents/
-│   └── pm.agent.yaml          # Now the security version
-```
-**Add scenario:**
-```
-Base module (BMM):
-├── agents/
-│   ├── pm.agent.yaml
-│   └── architect.agent.yaml
-Extension (bmm-security):
-├── agents/
-│   └── security-auditor.agent.yaml  # NEW agent
-Result after installation:
-├── agents/
-│   ├── pm.agent.yaml
-│   ├── architect.agent.yaml
-│   └── security-auditor.agent.yaml  # ADDED
-```
-**Mixed scenario:**
-```
-Extension contains both overrides and new files — applies rules per file
-```
----
-### 3. Global Module
-Affects the entire BMAD framework and all modules.
-**Characteristics:**
-- Core functionality that impacts all modules
-- Often provides foundational services or utilities
-- Installed at the framework level
-- Use sparingly — only for truly global concerns
-**Location:** `src/modules/{module-code}/` with `global: true` in module.yaml
-**Example:** A module that provides universal logging or telemetry across BMAD
----
-## Required Module Structure
-```
-{module-code}/
-├── module.yaml                 # Module configuration (REQUIRED)
-├── README.md                   # Module documentation (REQUIRED)
-├── agents/                     # Agent definitions (if any)
-│   └── {agent-name}.agent.yaml
-├── workflows/                  # Workflow definitions (if any)
-│   └── {workflow-name}/
-│       └── workflow.md
-├── _module-installer/          # Installation logic (optional)
-│   ├── installer.js
-│   └── platform-specifics/
-│       ├── claude-code.js
-│       ├── windsurf.js
-│       └── ...
-└── {other folders}             # Tasks, templates, data as needed
-```
----
-## Required Files
-### module.yaml (REQUIRED)
-Every module MUST have a `module.yaml` file with at minimum:
-```yaml
-code: {module-code}
-name: "Module Display Name"
-header: "Brief module description"
-subheader: "Additional context"
-default_selected: false
-```
-See: `module-yaml-conventions.md` for full specification.
----
-### README.md (REQUIRED)
-Every module MUST have a README.md with:
-- Module name and purpose
-- Installation instructions
-- Components section (agents, workflows)
-- Quick start guide
-- Module structure diagram
-- Configuration section
-- Usage examples
-- Author information
----
-## Optional Components
-### Agents
-Agents are AI personas with:
-- Metadata (id, name, title, icon, module)
-- Persona (role, identity, communication_style, principles)
-- Menu (trigger → workflow/exec mappings)
-See: `agent-architecture.md` for design guidance.
----
-### Workflows
-Workflows are structured processes with:
-- workflow.md (entry point)
-- steps/ folder with step files
-- data/ folder with shared reference
-- templates/ folder if needed
----
-### _module-installer/
-Optional installation logic for:
-- Creating directories
-- Copying assets
-- IDE-specific configuration
-- Platform-specific setup
-See: `module-installer-standards.md` for patterns.
----
-## Module Type Decision Tree
-```
-START: Creating a module
-│
-├─ Is this a brand new independent domain?
-│  └─ YES → Standalone Module
-│
-├─ Does this extend an existing module?
-│  └─ YES → Extension Module
-│
-└─ Does this affect all modules globally?
-   └─ YES → Global Module (use sparingly)
-```
----
-## Naming Conventions
-### Module Code
-- **kebab-case** (e.g., `bmm`, `cis`, `bmgd`, `healthcare-ai`)
-- Short, memorable, descriptive
-- 2-20 characters
-- Lowercase letters, numbers, hyphens only
-### Agent Files
-- Format: `{role-name}.agent.yaml`
-- Example: `pm.agent.yaml`, `architect.agent.yaml`
-### Workflow Folders
-- Format: `{workflow-name}/`
-- Example: `prd/`, `create-architecture/`
----
-## Module Dependencies
-Modules can depend on:
-- **Core BMAD** — Always available
-- **Other modules** — Specify in module.yaml as `dependencies:`
-- **External tools** — Document in README, handle in installer
----
-## Quick Reference
-| Question | Answer |
-|----------|--------|
-| What's a module? | Self-contained package of agents, workflows, config |
-| What are the types? | Standalone, Extension, Global |
-| What's required? | module.yaml, README.md |
-| Where do modules live? | `src/modules/{code}/` |
-| How do agents work? | Menu triggers → workflow/exec |
-| How does installation work? | module.yaml prompts + optional installer.js |