aios-core 2.2.1 → 2.3.1

package/.aios-core/core-config.yaml

@@ -69,7 +69,18 @@ slashPrefix: AIOS
 # SECTION 3: Resource Locations
 # ============================================
 toolsLocation: .aios-core/tools
-scriptsLocation: .aios-core/scripts
+
+# Scripts are organized into modules by domain (Story 6.16)
+# - core: Core framework modules (elicitation, session)
+# - development: Development scripts (greeting, workflow, exit hooks)
+# - infrastructure: Infrastructure scripts (git config, project status, validators)
+# - legacy: Migration utilities only (deprecated scripts have been removed)
+scriptsLocation:
+  core: .aios-core/core
+  development: .aios-core/development/scripts
+  infrastructure: .aios-core/infrastructure/scripts
+  legacy: .aios-core/scripts
+
 dataLocation: .aios-core/data
 elicitationLocation: .aios-core/elicitation
 # Squads replaced Squads in OSR-8 - see docs/guides/squads-guide.md

package/.aios-core/data/agent-config-requirements.yaml

@@ -64,10 +64,10 @@ agents:
       - path: .aios-core/data/technical-preferences.md
         lazy: false
         size: 15KB
-      - path: .aios-core/data/test-levels-framework.md
+      - path: .aios-core/product/data/test-levels-framework.md
         lazy: false
         size: 8KB
-      - path: .aios-core/data/test-priorities-matrix.md
+      - path: .aios-core/product/data/test-priorities-matrix.md
         lazy: false
         size: 6KB
     lazy_loading:
@@ -120,7 +120,7 @@ agents:
       - storyBacklog
       - templatesLocation
     files_loaded:
-      - path: .aios-core/data/elicitation-methods.md
+      - path: .aios-core/product/data/elicitation-methods.md
         lazy: false
         size: 5KB
     lazy_loading:
@@ -134,7 +134,7 @@ agents:
       - storyBacklog
       - dataLocation
     files_loaded:
-      - path: .aios-core/data/mode-selection-best-practices.md
+      - path: .aios-core/product/data/mode-selection-best-practices.md
         lazy: false
         size: 10KB
       - path: .aios-core/data/workflow-patterns.yaml
@@ -182,7 +182,7 @@ agents:
       - dataLocation
       - analyticsLocation
     files_loaded:
-      - path: .aios-core/data/brainstorming-techniques.md
+      - path: .aios-core/product/data/brainstorming-techniques.md
         lazy: false
         size: 2KB
     lazy_loading: {}

package/.aios-core/development/agents/devops.md

@@ -158,6 +158,13 @@ commands:
   - environment-bootstrap: Complete environment setup for new projects (CLIs, auth, Git/GitHub)
   - setup-github: Configure DevOps infrastructure for user projects (workflows, CodeRabbit, branch protection, secrets) [Story 5.10]
 
+  # MCP Management (via Docker Gateway) [Story 6.14]
+  - search-mcp: Search available MCPs in Docker MCP Toolkit catalog
+  - add-mcp: Add MCP server to Docker MCP Toolkit
+  - list-mcps: List currently enabled MCPs and their tools
+  - remove-mcp: Remove MCP server from Docker MCP Toolkit
+  - setup-mcp-docker: Initial Docker MCP Toolkit configuration [Story 5.11]
+
   # Utilities
   - session-info: Show current session details (agent history, commands)
   - guide: Show comprehensive usage guide for this agent
@@ -173,6 +180,10 @@ dependencies:
     - ci-cd-configuration.md
     - github-devops-repository-cleanup.md
     - release-management.md
+    # MCP Management Tasks [Story 6.14]
+    - search-mcp.md
+    - add-mcp.md
+    - setup-mcp-docker.md
   templates:
     - github-pr-template.md
     - github-actions-ci.yml
@@ -191,6 +202,7 @@ dependencies:
     - coderabbit        # Automated code review, pre-PR quality gate
     - github-cli        # PRIMARY TOOL - All GitHub operations
     - git               # ALL operations including push (EXCLUSIVE to this agent)
+    - docker-gateway    # Docker MCP Toolkit gateway for MCP management [Story 6.14]
 
   coderabbit_integration:
     enabled: true

package/.aios-core/development/scripts/squad/README.md

@@ -0,0 +1,112 @@
+# Squad Scripts Module
+
+Utilities for the squad-creator agent to manage squads in AIOS projects.
+
+## Overview
+
+This module provides utilities for:
+- **Loading** squad manifests from local directories
+- **Validating** squad structure and configuration (SQS-3)
+- **Generating** new squads from templates (SQS-4)
+
+## Components
+
+| File | Story | Description |
+|------|-------|-------------|
+| `squad-loader.js` | SQS-2 | Load and resolve squad manifests |
+| `squad-validator.js` | SQS-3 | Validate squad structure |
+| `squad-generator.js` | SQS-4 | Generate new squads |
+
+## Usage
+
+### Squad Loader
+
+```javascript
+const { SquadLoader } = require('./.aios-core/development/scripts/squad');
+
+// Create loader instance
+const loader = new SquadLoader({
+  squadsPath: './squads',  // Default: './squads'
+  verbose: false           // Enable debug logging
+});
+
+// Resolve squad by name
+const { path, manifestPath } = await loader.resolve('my-squad');
+
+// Load and parse manifest
+const manifest = await loader.loadManifest('./squads/my-squad');
+
+// List all local squads
+const squads = await loader.listLocal();
+// Returns: [{ name, path, manifestPath }, ...]
+```
+
+### Error Handling
+
+```javascript
+const { SquadLoader, SquadLoaderError } = require('./.aios-core/development/scripts/squad');
+
+try {
+  const loader = new SquadLoader();
+  await loader.resolve('non-existent-squad');
+} catch (error) {
+  if (error instanceof SquadLoaderError) {
+    console.error(`Error [${error.code}]: ${error.message}`);
+    console.log(`Suggestion: ${error.suggestion}`);
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description | Suggestion |
+|------|-------------|------------|
+| `SQUAD_NOT_FOUND` | Squad directory not found | Create squad with: @squad-creator *create-squad {name} |
+| `MANIFEST_NOT_FOUND` | No manifest file in squad | Create squad.yaml in squad directory |
+| `YAML_PARSE_ERROR` | Invalid YAML syntax | Check YAML syntax - use a YAML linter |
+| `PERMISSION_DENIED` | File permission error | Check file permissions: chmod 644 {path} |
+
+## Manifest Files
+
+The loader supports two manifest formats:
+
+1. **`squad.yaml`** (preferred) - New standard format
+2. **`config.yaml`** (deprecated) - Legacy format with console warning
+
+## Integration with squad-creator Agent
+
+This module is used by squad-creator agent tasks:
+
+- `*create-squad` - Uses loader to check for conflicts
+- `*validate-squad` - Uses loader to load and validate manifest
+- `*list-squads` - Uses loader to enumerate local squads
+
+## Related Stories
+
+- **SQS-2**: Squad Loader Utility (this module)
+- **SQS-3**: Squad Validator + Schema
+- **SQS-4**: Squad Creator Agent + Tasks
+
+## Dependencies
+
+- `js-yaml` - YAML parsing (project dependency)
+- `fs/promises` - File system operations (Node.js built-in)
+- `path` - Path manipulation (Node.js built-in)
+
+## Testing
+
+```bash
+# Run squad-loader tests
+npm test -- tests/unit/squad/squad-loader.test.js
+
+# Run with coverage
+npm test -- tests/unit/squad/squad-loader.test.js --coverage --collectCoverageFrom=".aios-core/development/scripts/squad/*.js"
+```
+
+**Coverage:** 94.5% statements (target: 80%+)
+
+## Version History
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0.0 | 2025-12-18 | Initial implementation (Story SQS-2) |

package/.aios-core/development/scripts/squad/index.js

@@ -0,0 +1,41 @@
+/**
+ * Squad Scripts Module
+ *
+ * Central exports for squad-related utilities used by the squad-creator agent.
+ *
+ * @module squad
+ * @see {@link ./squad-loader.js} - Load and resolve squad manifests
+ * @see {@link ./squad-validator.js} - Validate squad structure (SQS-3)
+ * @see {@link ./squad-generator.js} - Generate new squads (SQS-4)
+ */
+
+const {
+  SquadLoader,
+  SquadLoaderError,
+  MANIFEST_FILES,
+  DEFAULT_SQUADS_PATH,
+  ErrorCodes,
+} = require('./squad-loader');
+
+const {
+  SquadValidator,
+  ValidationErrorCodes,
+  TASK_REQUIRED_FIELDS,
+} = require('./squad-validator');
+
+module.exports = {
+  // Squad Loader (SQS-2)
+  SquadLoader,
+  SquadLoaderError,
+  MANIFEST_FILES,
+  DEFAULT_SQUADS_PATH,
+  ErrorCodes,
+
+  // Squad Validator (SQS-3)
+  SquadValidator,
+  ValidationErrorCodes,
+  TASK_REQUIRED_FIELDS,
+
+  // Squad Generator (SQS-4) - TODO: Implement in Story SQS-4
+  // SquadGenerator,
+};

package/.aios-core/development/scripts/squad/squad-loader.js

@@ -0,0 +1,359 @@
+/**
+ * Squad Loader Utility
+ *
+ * Utilities for loading and resolving squad manifests from local directories.
+ * Used by squad-creator agent tasks.
+ *
+ * @module squad-loader
+ * @version 1.0.0
+ * @see Story SQS-2: Squad Loader Utility
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Supported manifest file names in order of preference
+ * @constant {string[]}
+ */
+const MANIFEST_FILES = ['squad.yaml', 'config.yaml'];
+
+/**
+ * Default path for squads directory
+ * @constant {string}
+ */
+const DEFAULT_SQUADS_PATH = './squads';
+
+/**
+ * Error codes for SquadLoaderError
+ * @enum {string}
+ */
+const ErrorCodes = {
+  SQUAD_NOT_FOUND: 'SQUAD_NOT_FOUND',
+  MANIFEST_NOT_FOUND: 'MANIFEST_NOT_FOUND',
+  YAML_PARSE_ERROR: 'YAML_PARSE_ERROR',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+};
+
+/**
+ * Suggestions for each error code
+ * @constant {Object.<string, string|Function>}
+ */
+const ErrorSuggestions = {
+  [ErrorCodes.SQUAD_NOT_FOUND]: (squadName) =>
+    `Create squad with: @squad-creator *create-squad ${squadName}`,
+  [ErrorCodes.MANIFEST_NOT_FOUND]: () =>
+    'Create squad.yaml in squad directory',
+  [ErrorCodes.YAML_PARSE_ERROR]: () =>
+    'Check YAML syntax - use a YAML linter',
+  [ErrorCodes.PERMISSION_DENIED]: (filePath) =>
+    `Check file permissions: chmod 644 ${filePath}`,
+};
+
+/**
+ * Custom error class for Squad Loader operations
+ * @extends Error
+ */
+class SquadLoaderError extends Error {
+  /**
+   * Create a SquadLoaderError
+   * @param {string} code - Error code from ErrorCodes enum
+   * @param {string} message - Human-readable error message
+   * @param {string} [suggestion] - Suggested fix for the error
+   * @param {string} [filePath] - Path to the problematic file/directory
+   */
+  constructor(code, message, suggestion, filePath) {
+    super(message);
+    this.name = 'SquadLoaderError';
+    this.code = code;
+    this.suggestion = suggestion || '';
+    this.filePath = filePath || '';
+
+    // Maintains proper stack trace for where error was thrown (V8 engines)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, SquadLoaderError);
+    }
+  }
+
+  /**
+   * Create error for squad not found
+   * @param {string} squadName - Name of the squad
+   * @param {string} squadsPath - Path searched
+   * @returns {SquadLoaderError}
+   */
+  static squadNotFound(squadName, squadsPath) {
+    const filePath = path.join(squadsPath, squadName);
+    return new SquadLoaderError(
+      ErrorCodes.SQUAD_NOT_FOUND,
+      `Squad "${squadName}" not found in ${squadsPath}/`,
+      ErrorSuggestions[ErrorCodes.SQUAD_NOT_FOUND](squadName),
+      filePath,
+    );
+  }
+
+  /**
+   * Create error for manifest not found
+   * @param {string} squadPath - Path to squad directory
+   * @returns {SquadLoaderError}
+   */
+  static manifestNotFound(squadPath) {
+    return new SquadLoaderError(
+      ErrorCodes.MANIFEST_NOT_FOUND,
+      `No manifest found in ${squadPath}/ (expected squad.yaml or config.yaml)`,
+      ErrorSuggestions[ErrorCodes.MANIFEST_NOT_FOUND](),
+      squadPath,
+    );
+  }
+
+  /**
+   * Create error for YAML parse failure
+   * @param {string} filePath - Path to the YAML file
+   * @param {Error} parseError - Original YAML parse error
+   * @returns {SquadLoaderError}
+   */
+  static yamlParseError(filePath, parseError) {
+    return new SquadLoaderError(
+      ErrorCodes.YAML_PARSE_ERROR,
+      `Failed to parse YAML in ${filePath}: ${parseError.message}`,
+      ErrorSuggestions[ErrorCodes.YAML_PARSE_ERROR](),
+      filePath,
+    );
+  }
+
+  /**
+   * Create error for permission denied
+   * @param {string} filePath - Path to the file/directory
+   * @param {Error} originalError - Original file system error
+   * @returns {SquadLoaderError}
+   */
+  static permissionDenied(filePath, originalError) {
+    return new SquadLoaderError(
+      ErrorCodes.PERMISSION_DENIED,
+      `Permission denied accessing ${filePath}: ${originalError.message}`,
+      ErrorSuggestions[ErrorCodes.PERMISSION_DENIED](filePath),
+      filePath,
+    );
+  }
+
+  /**
+   * Returns formatted error string
+   * @returns {string}
+   */
+  toString() {
+    let str = `[${this.code}] ${this.message}`;
+    if (this.suggestion) {
+      str += `\n  Suggestion: ${this.suggestion}`;
+    }
+    return str;
+  }
+}
+
+/**
+ * Squad Loader class for loading and resolving squad manifests
+ */
+class SquadLoader {
+  /**
+   * Create a SquadLoader instance
+   * @param {Object} [options={}] - Configuration options
+   * @param {string} [options.squadsPath='./squads'] - Path to squads directory
+   * @param {boolean} [options.verbose=false] - Enable verbose logging
+   */
+  constructor(options = {}) {
+    this.squadsPath = options.squadsPath || DEFAULT_SQUADS_PATH;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Log message if verbose mode is enabled
+   * @private
+   * @param {string} message - Message to log
+   */
+  _log(message) {
+    if (this.verbose) {
+      console.log(`[SquadLoader] ${message}`);
+    }
+  }
+
+  /**
+   * Resolve squad path by name
+   *
+   * Finds a squad directory and its manifest file.
+   *
+   * @param {string} squadName - Name of the squad (kebab-case)
+   * @returns {Promise<{path: string, manifestPath: string}>} Resolved paths
+   * @throws {SquadLoaderError} SQUAD_NOT_FOUND if squad directory doesn't exist
+   * @throws {SquadLoaderError} MANIFEST_NOT_FOUND if no manifest file found
+   *
+   * @example
+   * const loader = new SquadLoader();
+   * const { path, manifestPath } = await loader.resolve('etl-squad');
+   * // { path: './squads/etl-squad', manifestPath: './squads/etl-squad/squad.yaml' }
+   */
+  async resolve(squadName) {
+    this._log(`Resolving squad: ${squadName}`);
+    const squadPath = path.join(this.squadsPath, squadName);
+
+    // Check if squad directory exists
+    const exists = await this._pathExists(squadPath);
+    if (!exists) {
+      throw SquadLoaderError.squadNotFound(squadName, this.squadsPath);
+    }
+
+    // Find manifest file
+    const manifestPath = await this._findManifest(squadPath);
+    if (!manifestPath) {
+      throw SquadLoaderError.manifestNotFound(squadPath);
+    }
+
+    this._log(`Resolved: ${squadPath} -> ${manifestPath}`);
+    return { path: squadPath, manifestPath };
+  }
+
+  /**
+   * Load and parse squad manifest
+   *
+   * Loads the manifest file from a squad directory and parses it.
+   * Shows deprecation warning for config.yaml files.
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<Object>} Parsed manifest data
+   * @throws {SquadLoaderError} MANIFEST_NOT_FOUND if no manifest file found
+   * @throws {SquadLoaderError} YAML_PARSE_ERROR if YAML parsing fails
+   * @throws {SquadLoaderError} PERMISSION_DENIED if file cannot be read
+   *
+   * @example
+   * const loader = new SquadLoader();
+   * const manifest = await loader.loadManifest('./squads/etl-squad');
+   * console.log(manifest.name); // 'etl-squad'
+   */
+  async loadManifest(squadPath) {
+    this._log(`Loading manifest from: ${squadPath}`);
+
+    const manifestPath = await this._findManifest(squadPath);
+    if (!manifestPath) {
+      throw SquadLoaderError.manifestNotFound(squadPath);
+    }
+
+    // Deprecation warning for config.yaml
+    const manifestFilename = path.basename(manifestPath);
+    if (manifestFilename === 'config.yaml') {
+      console.warn(
+        `\u26a0\ufe0f  DEPRECATED: ${manifestPath} uses legacy format. Rename to squad.yaml`,
+      );
+    }
+
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8');
+      const parsed = yaml.load(content);
+      this._log(`Manifest loaded successfully: ${manifestPath}`);
+      return parsed;
+    } catch (error) {
+      if (error.code === 'EACCES' || error.code === 'EPERM') {
+        throw SquadLoaderError.permissionDenied(manifestPath, error);
+      }
+      if (error.name === 'YAMLException') {
+        throw SquadLoaderError.yamlParseError(manifestPath, error);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * List all local squads in project
+   *
+   * Scans the squads directory for valid squad directories
+   * (directories containing a manifest file).
+   *
+   * @returns {Promise<Array<{name: string, path: string, manifestPath: string}>>}
+   *          Array of squad info objects
+   *
+   * @example
+   * const loader = new SquadLoader();
+   * const squads = await loader.listLocal();
+   * // [
+   * //   { name: 'etl-squad', path: './squads/etl-squad', manifestPath: '...' },
+   * //   { name: 'creator-squad', path: './squads/creator-squad', manifestPath: '...' }
+   * // ]
+   */
+  async listLocal() {
+    this._log(`Listing squads in: ${this.squadsPath}`);
+
+    const exists = await this._pathExists(this.squadsPath);
+    if (!exists) {
+      this._log('Squads directory does not exist, returning empty array');
+      return [];
+    }
+
+    let entries;
+    try {
+      entries = await fs.readdir(this.squadsPath, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'EACCES' || error.code === 'EPERM') {
+        throw SquadLoaderError.permissionDenied(this.squadsPath, error);
+      }
+      throw error;
+    }
+
+    const squads = [];
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const squadPath = path.join(this.squadsPath, entry.name);
+        const manifestPath = await this._findManifest(squadPath);
+        if (manifestPath) {
+          squads.push({
+            name: entry.name,
+            path: squadPath,
+            manifestPath,
+          });
+          this._log(`Found squad: ${entry.name}`);
+        } else {
+          this._log(`Skipped directory (no manifest): ${entry.name}`);
+        }
+      }
+    }
+
+    this._log(`Found ${squads.length} squad(s)`);
+    return squads;
+  }
+
+  /**
+   * Find manifest file in squad directory
+   * @private
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<string|null>} Path to manifest or null if not found
+   */
+  async _findManifest(squadPath) {
+    for (const filename of MANIFEST_FILES) {
+      const manifestPath = path.join(squadPath, filename);
+      if (await this._pathExists(manifestPath)) {
+        return manifestPath;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Check if path exists
+   * @private
+   * @param {string} filePath - Path to check
+   * @returns {Promise<boolean>} True if path exists
+   */
+  async _pathExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = {
+  SquadLoader,
+  SquadLoaderError,
+  MANIFEST_FILES,
+  DEFAULT_SQUADS_PATH,
+  ErrorCodes,
+};