aios-core 3.7.0 → 3.9.1

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/next.md

@@ -0,0 +1,294 @@
+# Next Command Suggestions
+
+## Purpose
+
+Suggest next commands based on current workflow context using the Workflow Intelligence System (WIS). Helps users navigate workflows efficiently without memorizing command sequences.
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: next()
+agent: "@dev"
+responsável: Dex (Developer)
+responsavel_type: Agente
+atomic_layer: Workflow
+
+elicit: false
+
+inputs:
+  - name: story
+    type: path
+    required: false
+    description: Explicit story path for context
+
+  - name: all
+    type: flag
+    required: false
+    default: false
+    description: Show all suggestions instead of top 3
+
+  - name: help
+    type: flag
+    required: false
+    default: false
+    description: Show usage documentation
+
+outputs:
+  - name: suggestions
+    type: array
+    destino: Console
+    persistido: false
+
+  - name: workflow_context
+    type: object
+    destino: Console
+    persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] WIS modules are available
+    tipo: pre-condition
+    blocker: false
+    validação: Check workflow-intelligence module loads
+    error_message: "WIS not available. Suggestions may be limited."
+
+  - [ ] Session state exists (optional)
+    tipo: pre-condition
+    blocker: false
+    validação: Check .aios/session-state.json exists
+    error_message: "No session history. Using project context only."
+```
+
+---
+
+## Implementation Steps
+
+### Step 1: Check Help Flag
+```javascript
+if (args.help) {
+  displayHelp();
+  return;
+}
+```
+
+### Step 2: Build Context
+```javascript
+const SuggestionEngine = require('.aios-core/workflow-intelligence/engine/suggestion-engine');
+const engine = new SuggestionEngine();
+
+// Build context from multiple sources
+const context = await engine.buildContext({
+  storyOverride: args.story,    // Explicit story path (optional)
+  autoDetect: true              // Auto-detect from session/git
+});
+```
+
+### Step 3: Get Suggestions
+```javascript
+const result = await engine.suggestNext(context);
+
+// result = {
+//   workflow: 'story_development',
+//   currentState: 'in_development',
+//   confidence: 0.92,
+//   suggestions: [
+//     { command: '*review-qa', args: '${story_path}', description: '...', confidence: 0.95, priority: 1 },
+//     ...
+//   ]
+// }
+```
+
+### Step 4: Format Output
+```javascript
+const formatter = require('.aios-core/workflow-intelligence/engine/output-formatter');
+
+// Limit to top 3 unless --all flag
+const displaySuggestions = args.all ? result.suggestions : result.suggestions.slice(0, 3);
+
+// Display formatted output
+formatter.displaySuggestions(result.workflow, result.currentState, result.confidence, displaySuggestions);
+```
+
+---
+
+## Help Text
+
+```
+Usage: *next [options]
+
+Suggests next commands based on current workflow context.
+
+Options:
+  --story <path>  Explicit story path for context
+  --all           Show all suggestions (not just top 3)
+  --help          Show this help message
+
+Examples:
+  *next                                    # Auto-detect context
+  *next --story docs/stories/v2.1/sprint-10/story-wis-3.md
+  *next --all                              # Show all suggestions
+
+How it works:
+  1. Analyzes your recent commands and current agent
+  2. Matches to known workflow patterns (story development, epic creation, etc.)
+  3. Determines your current state in the workflow
+  4. Suggests most likely next commands with confidence scores
+
+Workflow detection uses:
+  - Recent command history (last 10 commands)
+  - Current active agent
+  - Git branch and status
+  - Active story (if any)
+```
+
+---
+
+## Output Format
+
+### Standard Output
+```
+🧭 Workflow: story_development
+📍 State: in_development (confidence: 92%)
+
+Next steps:
+1. `*review-qa docs/stories/v2.1/sprint-10/story-wis-3.md` - Run QA review
+2. `*run-tests` - Execute test suite manually
+3. `*pre-push-quality-gate` - Final quality checks
+
+Type a number to execute, or press Enter to continue manually.
+```
+
+### Low Confidence Output
+```
+🧭 Workflow: unknown
+📍 State: uncertain (confidence: 35%)
+
+Possible next steps (uncertain):
+1. `*help` - Show available commands
+2. `*status` - Check project status
+
+⚠️ Low confidence - context is unclear. Try providing --story flag.
+```
+
+### No Workflow Match
+```
+🧭 Workflow: none detected
+📍 State: N/A
+
+Unable to determine workflow from current context.
+
+Try:
+  *next --story <path-to-story>
+  *help
+
+Recent commands: *develop, *run-tests
+Current agent: @dev
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] Suggestions displayed within 100ms
+    tipo: post-condition
+    blocker: false
+    validação: Measure execution time
+
+  - [ ] Output is properly formatted
+    tipo: post-condition
+    blocker: true
+    validação: Verify console output matches expected format
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| WIS module not found | Missing dependency | Fallback to generic suggestions |
+| Session state corrupt | Invalid JSON | Clear session, show warning |
+| Story path invalid | File doesn't exist | Warning, use auto-detect |
+| No workflow match | Unknown command pattern | Show "unable to determine" message |
+
+**Error Recovery Strategy:**
+```javascript
+try {
+  const result = await engine.suggestNext(context);
+  formatter.displaySuggestions(result);
+} catch (error) {
+  console.warn(`⚠️ Suggestion engine error: ${error.message}`);
+  // Fallback: show generic suggestions
+  formatter.displayFallback();
+}
+```
+
+---
+
+## Performance
+
+```yaml
+duration_expected: <100ms (target)
+cost_estimated: $0.00 (no API calls)
+token_usage: 0 (local processing only)
+
+optimizations:
+  - Workflow patterns cached (5-min TTL)
+  - Lazy loading of WIS modules
+  - Session state read once per call
+```
+
+---
+
+## Success Output
+
+```
+============================================
+ SUGGESTION ENGINE RESULTS
+============================================
+
+ Context:
+   Agent: @dev
+   Last Command: *develop
+   Story: docs/stories/v2.1/sprint-11/story-wis-3.md
+   Branch: feature/wis-3
+
+ Workflow: story_development
+ State: in_development
+ Confidence: 92%
+
+ Suggestions:
+   1. *review-qa (confidence: 95%)
+   2. *run-tests (confidence: 80%)
+   3. *pre-push-quality-gate (confidence: 75%)
+
+============================================
+```
+
+---
+
+## Metadata
+
+```yaml
+story: WIS-3
+version: 1.0.0
+created: 2025-12-25
+author: "@dev (Dex)"
+dependencies:
+  modules:
+    - workflow-intelligence (from WIS-2)
+    - core/session/context-loader
+  tasks: []
+tags:
+  - workflow-intelligence
+  - suggestions
+  - navigation
+  - context-aware
+```