aios-core 3.6.0 → 3.8.0

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

@@ -304,15 +304,27 @@ function generateSquadYaml(config) {
     components.tasks = [];
   }
 
-  const configSection =
-    config.configMode === 'none'
-      ? {}
-      : {
-        extends: config.configMode,
-        'coding-standards': 'config/coding-standards.md',
-        'tech-stack': 'config/tech-stack.md',
-        'source-tree': 'config/source-tree.md',
-      };
+  // SQS-10: Use project configs if available, otherwise use local paths
+  let configSection;
+  if (config.configMode === 'none') {
+    configSection = {};
+  } else if (config._useProjectConfigs && config._projectConfigs) {
+    // Reference project-level config files
+    configSection = {
+      extends: config.configMode,
+      'coding-standards': config._projectConfigs['coding-standards'] || 'config/coding-standards.md',
+      'tech-stack': config._projectConfigs['tech-stack'] || 'config/tech-stack.md',
+      'source-tree': config._projectConfigs['source-tree'] || 'config/source-tree.md',
+    };
+  } else {
+    // Fallback to local config files
+    configSection = {
+      extends: config.configMode,
+      'coding-standards': 'config/coding-standards.md',
+      'tech-stack': 'config/tech-stack.md',
+      'source-tree': 'config/source-tree.md',
+    };
+  }
 
   const yaml = `name: ${config.name}
 version: 1.0.0
@@ -644,6 +656,53 @@ class SquadGenerator {
     }
   }
 
+  /**
+   * Detect project-level configuration files in docs/framework/
+   * Implements AC10.1: Project Config Detection
+   *
+   * @param {string} projectRoot - Project root directory
+   * @param {string} squadPath - Path to squad being created (for relative paths)
+   * @returns {Promise<Object|null>} Detected config paths (relative to squadPath) or null if not found
+   * @see Story SQS-10: Project Config Reference for Squads
+   */
+  async detectProjectConfigs(projectRoot, squadPath) {
+    const frameworkDir = path.join(projectRoot, 'docs', 'framework');
+
+    // Check if docs/framework/ exists
+    if (!(await this.pathExists(frameworkDir))) {
+      return null;
+    }
+
+    // Config files to detect (case-insensitive variants)
+    const configFiles = {
+      'coding-standards': ['CODING-STANDARDS.md', 'coding-standards.md', 'Coding-Standards.md'],
+      'tech-stack': ['TECH-STACK.md', 'tech-stack.md', 'Tech-Stack.md'],
+      'source-tree': ['SOURCE-TREE.md', 'source-tree.md', 'Source-Tree.md'],
+    };
+
+    const detected = {};
+
+    for (const [key, variants] of Object.entries(configFiles)) {
+      for (const filename of variants) {
+        const fullPath = path.join(frameworkDir, filename);
+        if (await this.pathExists(fullPath)) {
+          // Calculate relative path from squad to project config
+          detected[key] = path.relative(squadPath, fullPath).replace(/\\/g, '/');
+          break;
+        }
+      }
+    }
+
+    // Only return if at least one config file was found
+    const foundCount = Object.keys(detected).length;
+    if (foundCount > 0) {
+      console.log(`[squad-generator] Detected ${foundCount} project config(s) in docs/framework/`);
+      return detected;
+    }
+
+    return null;
+  }
+
   /**
    * Validate generation configuration
    * @param {Object} config - Configuration to validate
@@ -686,6 +745,7 @@ class SquadGenerator {
    * @param {boolean} [config.includeAgent=true] - Include example agent
    * @param {boolean} [config.includeTask=true] - Include example task
    * @param {string} [config.aiosMinVersion] - Minimum AIOS version
+   * @param {string} [config.projectRoot] - Project root directory (for detecting project configs)
    * @returns {Promise<Object>} Generation result with path and files
    * @throws {SquadGeneratorError} If generation fails
    */
@@ -701,6 +761,7 @@ class SquadGenerator {
       includeAgent: config.includeAgent !== false,
       includeTask: config.includeTask !== false,
       aiosMinVersion: config.aiosMinVersion || DEFAULT_AIOS_MIN_VERSION,
+      projectRoot: config.projectRoot || process.cwd(),
     };
 
     // Validate configuration
@@ -708,6 +769,23 @@ class SquadGenerator {
 
     const squadPath = path.join(this.squadsPath, fullConfig.name);
 
+    // SQS-10: Detect project-level configs when configMode is 'extend'
+    let projectConfigs = null;
+    let useProjectConfigs = false;
+
+    if (fullConfig.configMode === 'extend') {
+      projectConfigs = await this.detectProjectConfigs(fullConfig.projectRoot, squadPath);
+      useProjectConfigs = projectConfigs !== null;
+
+      if (useProjectConfigs) {
+        console.log('[squad-generator] Using project-level configuration from docs/framework/');
+      }
+    }
+
+    // Store for use in squad.yaml generation
+    fullConfig._projectConfigs = projectConfigs;
+    fullConfig._useProjectConfigs = useProjectConfigs;
+
     // Check if squad already exists
     if (await this.pathExists(squadPath)) {
       throw SquadGeneratorError.squadExists(fullConfig.name, squadPath);
@@ -734,17 +812,27 @@ class SquadGenerator {
       files.push(filePath);
     }
 
-    // Generate config files
-    const configFiles = {
-      'config/coding-standards.md': generateCodingStandards(fullConfig),
-      'config/tech-stack.md': generateTechStack(fullConfig),
-      'config/source-tree.md': generateSourceTree(fullConfig),
-    };
+    // Generate config files (SQS-10: skip if using project configs)
+    if (useProjectConfigs) {
+      // Don't create local config files, just add .gitkeep to config directory
+      console.log('[squad-generator] Skipping local config file creation (using project-level configs)');
+      const gitkeepPath = path.join(squadPath, 'config', '.gitkeep');
+      await fs.writeFile(gitkeepPath, '# Config files are referenced from project docs/framework/\n', 'utf-8');
+      files.push(gitkeepPath);
+    } else {
+      // Fallback: Create local config files (AC10.3)
+      console.log('[squad-generator] Creating local configuration files');
+      const configFiles = {
+        'config/coding-standards.md': generateCodingStandards(fullConfig),
+        'config/tech-stack.md': generateTechStack(fullConfig),
+        'config/source-tree.md': generateSourceTree(fullConfig),
+      };
 
-    for (const [filename, content] of Object.entries(configFiles)) {
-      const filePath = path.join(squadPath, filename);
-      await fs.writeFile(filePath, content, 'utf-8');
-      files.push(filePath);
+      for (const [filename, content] of Object.entries(configFiles)) {
+        const filePath = path.join(squadPath, filename);
+        await fs.writeFile(filePath, content, 'utf-8');
+        files.push(filePath);
+      }
     }
 
     // Generate example agent if requested

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

@@ -192,10 +192,11 @@ class SquadMigrator {
       });
     }
 
-    // Check for flat structure (missing directories)
+    // Check for flat structure (missing required directories)
+    // Note: Only 'tasks' and 'agents' are required for task-first architecture
+    // 'config' directory is optional and not checked
     const hasTasksDir = await this._pathExists(path.join(squadPath, 'tasks'));
     const hasAgentsDir = await this._pathExists(path.join(squadPath, 'agents'));
-    const hasConfigDir = await this._pathExists(path.join(squadPath, 'config'));
 
     const missingDirs = [];
     if (!hasTasksDir) {
@@ -204,9 +205,6 @@ class SquadMigrator {
     if (!hasAgentsDir) {
       missingDirs.push('agents');
     }
-    if (!hasConfigDir) {
-      missingDirs.push('config');
-    }
 
     if (missingDirs.length > 0) {
       analysis.needsMigration = true;

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

@@ -172,6 +172,10 @@ class SquadValidator {
     const agentsResult = await this.validateAgents(squadPath);
     this._mergeResults(result, agentsResult);
 
+    // 5. Validate config references (SQS-10)
+    const configResult = await this.validateConfigReferences(squadPath);
+    this._mergeResults(result, configResult);
+
     // In strict mode, warnings become errors
     if (this.strict && result.warnings.length > 0) {
       result.errors.push(...result.warnings);
@@ -381,6 +385,74 @@ class SquadValidator {
     return result;
   }
 
+  /**
+   * Validate config references in squad.yaml
+   * Implements AC10.4: Validates that referenced config files actually exist
+   *
+   * @param {string} squadPath - Path to squad directory
+   * @returns {Promise<ValidationResult>} Validation result for config references
+   * @see Story SQS-10: Project Config Reference for Squads
+   */
+  async validateConfigReferences(squadPath) {
+    this._log(`Validating config references in: ${squadPath}`);
+
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      suggestions: [],
+    };
+
+    // Find and parse manifest
+    const manifestPath = await this._findManifest(squadPath);
+    if (!manifestPath) {
+      return result; // Already handled in manifest validation
+    }
+
+    let manifest;
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8');
+      manifest = yaml.load(content);
+    } catch {
+      return result; // Already handled in manifest validation
+    }
+
+    // Check config section
+    if (!manifest || !manifest.config) {
+      return result; // No config section to validate
+    }
+
+    const configFields = ['coding-standards', 'tech-stack', 'source-tree'];
+
+    for (const field of configFields) {
+      const configPath = manifest.config[field];
+      if (!configPath) continue;
+
+      const resolvedPath = await this._resolveConfigPath(squadPath, configPath);
+      if (!resolvedPath) {
+        // Check if this is a project-level reference that doesn't exist
+        if (configPath.includes('..') || configPath.includes('docs/framework')) {
+          result.warnings.push({
+            code: ValidationErrorCodes.FILE_NOT_FOUND,
+            message: `Config reference not found: ${configPath}`,
+            suggestion: `Create the file at ${configPath} or update squad.yaml to use local config (config/${field}.md)`,
+          });
+        } else {
+          // Local config file missing - this is an error
+          result.errors.push({
+            code: ValidationErrorCodes.FILE_NOT_FOUND,
+            message: `Local config file not found: ${configPath}`,
+            suggestion: `Create ${path.join(squadPath, configPath)} or remove from config section`,
+          });
+          result.valid = false;
+        }
+      }
+    }
+
+    this._log(`Config validation: ${result.errors.length} errors, ${result.warnings.length} warnings`);
+    return result;
+  }
+
   /**
    * Validate agent definitions
    *
@@ -540,6 +612,32 @@ class SquadValidator {
     }
   }
 
+  /**
+   * Resolve config path - check both local and project-level paths
+   * Implements AC10.4: Validator Path Resolution
+   *
+   * @param {string} squadPath - Squad directory
+   * @param {string} configPath - Path from squad.yaml config section
+   * @returns {Promise<string|null>} Resolved absolute path or null if not found
+   * @see Story SQS-10: Project Config Reference for Squads
+   * @private
+   */
+  async _resolveConfigPath(squadPath, configPath) {
+    if (!configPath) return null;
+
+    // Resolve path relative to squad directory
+    // path.resolve handles both local paths (config/file.md) and relative paths (../../docs/framework/...)
+    // Simplified from redundant path.resolve + path.join (CodeRabbit nitpick)
+    const resolvedPath = path.resolve(squadPath, configPath);
+    if (await this._pathExists(resolvedPath)) {
+      this._log(`Resolved config path: ${configPath} -> ${resolvedPath}`);
+      return resolvedPath;
+    }
+
+    this._log(`Config path not found: ${configPath}`);
+    return null;
+  }
+
   /**
    * Validate a single task file
    * @private

package/.aios-core/development/tasks/create-service.md

@@ -0,0 +1,391 @@
+# Create Service
+
+## Purpose
+
+Create a new service using standardized Handlebars templates from WIS-10. Generates consistent TypeScript service structures with proper configuration, testing, and documentation.
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: createService()
+agent: "@dev"
+responsável: Dex (Developer)
+responsavel_type: Agente
+atomic_layer: Config
+
+elicit: true
+
+inputs:
+  - name: service_name
+    type: string
+    required: true
+    pattern: "^[a-z][a-z0-9-]*$"
+    validation: Must be kebab-case, start with letter
+
+  - name: service_type
+    type: enum
+    options: ["api-integration", "utility", "agent-tool"]
+    required: true
+    default: "utility"
+
+  - name: has_auth
+    type: boolean
+    required: false
+    default: false
+
+  - name: description
+    type: string
+    required: true
+    validation: Non-empty, max 200 characters
+
+  - name: env_vars
+    type: array
+    required: false
+    default: []
+
+outputs:
+  - name: service_directory
+    type: directory
+    location: ".aios-core/infrastructure/services/{service_name}/"
+    persistido: true
+
+  - name: files_created
+    type: array
+    destino: Memory
+    persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] WIS-10 templates exist at .aios-core/development/templates/service-template/
+    tipo: pre-condition
+    blocker: true
+    validação: Check template directory exists with required .hbs files
+    error_message: "Templates not found. Run WIS-10 first."
+
+  - [ ] Service name is unique (no existing service with same name)
+    tipo: pre-condition
+    blocker: true
+    validação: Check .aios-core/infrastructure/services/{name}/ does not exist
+    error_message: "Service '{name}' already exists. Choose a different name."
+
+  - [ ] Service name follows kebab-case pattern
+    tipo: pre-condition
+    blocker: true
+    validação: Regex match ^[a-z][a-z0-9-]*$
+    error_message: "Invalid name. Use kebab-case (e.g., my-api-service)"
+```
+
+---
+
+## Interactive Elicitation Process
+
+### Step 1: Service Name
+```
+ELICIT: Service Name
+
+What is the service name?
+(Use kebab-case, e.g., "github-api", "file-processor", "auth-helper")
+
+→ Validation: ^[a-z][a-z0-9-]*$
+→ Check: Unique (not existing)
+→ On invalid: Re-prompt with error message
+```
+
+### Step 2: Service Type
+```
+ELICIT: Service Type
+
+What type of service is this?
+
+1. api-integration - External API client with rate limiting and auth
+2. utility - Internal helper/utility service
+3. agent-tool - Tool for AIOS agents
+
+→ Default: utility
+→ If api-integration: Enable client.ts generation
+```
+
+### Step 3: Authentication
+```
+ELICIT: Authentication Required
+
+Does this service require authentication?
+
+1. Yes - Include auth configuration and secure headers
+2. No - No authentication needed
+
+→ Default: No
+→ If Yes: Add auth placeholders to config
+```
+
+### Step 4: Description
+```
+ELICIT: Service Description
+
+Brief description of the service:
+(Max 200 characters, will appear in README and JSDoc)
+
+→ Validation: Non-empty, <= 200 chars
+```
+
+### Step 5: Environment Variables
+```
+ELICIT: Environment Variables
+
+What environment variables does this service need?
+(Enter comma-separated list, or 'none')
+
+Examples: API_KEY, BASE_URL, TIMEOUT_MS
+
+→ Default: none
+→ Parse: Split by comma, trim whitespace
+→ Generate: .env.example entries
+```
+
+---
+
+## Implementation Steps
+
+### Step 1: Validate Inputs
+```javascript
+// Validate service_name
+const namePattern = /^[a-z][a-z0-9-]*$/;
+if (!namePattern.test(serviceName)) {
+  throw new Error(`Invalid service name: ${serviceName}. Use kebab-case.`);
+}
+
+// Check uniqueness
+const targetDir = `.aios-core/infrastructure/services/${serviceName}/`;
+if (fs.existsSync(targetDir)) {
+  throw new Error(`Service '${serviceName}' already exists.`);
+}
+```
+
+### Step 2: Load Templates
+```javascript
+const templateDir = '.aios-core/development/templates/service-template/';
+const templates = [
+  'README.md.hbs',
+  'index.ts.hbs',
+  'types.ts.hbs',
+  'errors.ts.hbs',
+  'package.json.hbs',
+  'tsconfig.json',      // Static (no .hbs)
+  'jest.config.js',     // Static (no .hbs)
+  '__tests__/index.test.ts.hbs'
+];
+
+// Conditional: client.ts.hbs only for api-integration
+if (serviceType === 'api-integration') {
+  templates.push('client.ts.hbs');
+}
+```
+
+### Step 3: Prepare Template Context
+```javascript
+const context = {
+  serviceName: serviceName,                    // kebab-case
+  pascalCase: toPascalCase(serviceName),       // PascalCase
+  camelCase: toCamelCase(serviceName),         // camelCase
+  description: description,
+  isApiIntegration: serviceType === 'api-integration',
+  hasAuth: hasAuth,
+  envVars: envVars.map(v => ({
+    name: v,
+    description: `${v} environment variable`
+  })),
+  storyId: 'WIS-11',
+  createdAt: new Date().toISOString().split('T')[0]
+};
+```
+
+### Step 4: Generate Files
+```javascript
+// Create target directory
+fs.mkdirSync(targetDir, { recursive: true });
+fs.mkdirSync(`${targetDir}__tests__/`, { recursive: true });
+
+// Process each template
+for (const templateFile of templates) {
+  const templatePath = `${templateDir}${templateFile}`;
+  const isHandlebars = templateFile.endsWith('.hbs');
+
+  // Determine output filename
+  const outputFile = isHandlebars
+    ? templateFile.replace('.hbs', '')
+    : templateFile;
+  const outputPath = `${targetDir}${outputFile}`;
+
+  if (isHandlebars) {
+    // Render Handlebars template
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const compiled = Handlebars.compile(template);
+    const content = compiled(context);
+    fs.writeFileSync(outputPath, content);
+  } else {
+    // Copy static file
+    fs.copyFileSync(templatePath, outputPath);
+  }
+}
+```
+
+### Step 5: Post-Generation
+```bash
+# Navigate to service directory
+cd .aios-core/infrastructure/services/{service_name}/
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+```
+
+---
+
+## Handlebars Helpers Required
+
+The following helpers must be available:
+
+```javascript
+Handlebars.registerHelper('pascalCase', (str) => {
+  return str.split('-').map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+});
+
+Handlebars.registerHelper('camelCase', (str) => {
+  const pascal = str.split('-').map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+});
+
+Handlebars.registerHelper('kebabCase', (str) => {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+});
+
+Handlebars.registerHelper('upperCase', (str) => {
+  return str.toUpperCase().replace(/-/g, '_');
+});
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] All template files generated successfully
+    tipo: post-condition
+    blocker: true
+    validação: Verify all expected files exist in target directory
+
+  - [ ] TypeScript compiles without errors
+    tipo: post-condition
+    blocker: false
+    validação: Run npm run build, check exit code
+
+  - [ ] Tests pass
+    tipo: post-condition
+    blocker: false
+    validação: Run npm test, check exit code
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Service name exists | Directory already present | Prompt for different name |
+| Template not found | WIS-10 not installed | Error: "Run WIS-10 first" |
+| npm install fails | Network/package issues | Warning, continue without deps |
+| Build fails | TypeScript errors | Warning, show errors, continue |
+| Invalid name format | Name not kebab-case | Re-prompt with validation error |
+
+**Error Recovery Strategy:**
+```javascript
+// Atomic generation - rollback on failure
+try {
+  generateAllFiles(targetDir, templates, context);
+} catch (error) {
+  // Clean up partial files
+  if (fs.existsSync(targetDir)) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+  throw error;
+}
+```
+
+---
+
+## Performance
+
+```yaml
+duration_expected: 5-30s (excluding npm install)
+cost_estimated: $0.002-0.005
+token_usage: ~1,000-2,000 tokens
+```
+
+---
+
+## Success Output
+
+```
+============================================
+ SERVICE CREATED SUCCESSFULLY
+============================================
+
+ Service: {service_name}
+ Type: {service_type}
+ Location: .aios-core/infrastructure/services/{service_name}/
+
+ Files Created:
+   README.md
+   index.ts
+   types.ts
+   errors.ts
+   client.ts (if api-integration)
+   package.json
+   tsconfig.json
+   jest.config.js
+   __tests__/index.test.ts
+
+ Next Steps:
+   1. cd .aios-core/infrastructure/services/{service_name}
+   2. Review generated code
+   3. Implement service methods in index.ts
+   4. Add tests in __tests__/
+   5. Update environment variables as needed
+
+============================================
+```
+
+---
+
+## Metadata
+
+```yaml
+story: WIS-11
+version: 1.0.0
+created: 2025-12-24
+author: "@dev (Dex)"
+dependencies:
+  templates:
+    - service-template/ (from WIS-10)
+  tasks: []
+tags:
+  - service-generation
+  - scaffolding
+  - handlebars
+  - typescript
+```