aios-core 3.7.0 → 3.8.0

package/.aios-core/development/tasks/patterns.md

@@ -0,0 +1,334 @@
+# Learned Patterns Management
+
+## Purpose
+
+View, manage, and review learned workflow patterns captured by the Workflow Intelligence System (WIS). Patterns are learned from successful workflow executions and boost suggestion confidence.
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: patterns()
+agent: "@dev"
+responsável: Dex (Developer)
+responsavel_type: Agente
+atomic_layer: Workflow
+
+elicit: false
+
+inputs:
+  - name: subcommand
+    type: enum
+    required: false
+    default: list
+    options: [list, stats, prune, review]
+    description: Action to perform
+
+  - name: status
+    type: enum
+    required: false
+    options: [pending, active, promoted, deprecated]
+    description: Filter patterns by status
+
+  - name: limit
+    type: number
+    required: false
+    default: 10
+    description: Maximum patterns to display
+
+  - name: help
+    type: flag
+    required: false
+    default: false
+    description: Show usage documentation
+
+outputs:
+  - name: patterns
+    type: array
+    destino: Console
+    persistido: false
+
+  - name: stats
+    type: object
+    destino: Console
+    persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Learning module is available
+    tipo: pre-condition
+    blocker: true
+    validação: Check workflow-intelligence/learning module loads
+    error_message: "Pattern learning module not available."
+
+  - [ ] Pattern storage exists
+    tipo: pre-condition
+    blocker: false
+    validação: Check .aios-core/data/learned-patterns.yaml exists
+    error_message: "No patterns stored yet."
+```
+
+---
+
+## Implementation Steps
+
+### Step 1: Check Help Flag
+```javascript
+if (args.help) {
+  displayHelp();
+  return;
+}
+```
+
+### Step 2: Load Learning Module
+```javascript
+const learning = require('.aios-core/workflow-intelligence/learning');
+const store = learning.getDefaultStore();
+```
+
+### Step 3: Execute Subcommand
+
+#### List Patterns
+```javascript
+if (args.subcommand === 'list' || !args.subcommand) {
+  const data = store.load();
+  let patterns = data.patterns;
+
+  // Filter by status if provided
+  if (args.status) {
+    patterns = patterns.filter(p => p.status === args.status);
+  }
+
+  // Sort by occurrences (descending)
+  patterns.sort((a, b) => (b.occurrences || 1) - (a.occurrences || 1));
+
+  // Limit results
+  patterns = patterns.slice(0, args.limit || 10);
+
+  displayPatternList(patterns);
+}
+```
+
+#### Show Stats
+```javascript
+if (args.subcommand === 'stats') {
+  const stats = store.getStats();
+  displayStats(stats);
+}
+```
+
+#### Prune Patterns
+```javascript
+if (args.subcommand === 'prune') {
+  const result = store.prune();
+  console.log(`✓ Pruned ${result.pruned} patterns. ${result.remaining} remaining.`);
+}
+```
+
+#### Review Patterns
+```javascript
+if (args.subcommand === 'review') {
+  const pendingPatterns = store.getByStatus('pending');
+
+  if (pendingPatterns.length === 0) {
+    console.log('No patterns pending review.');
+    return;
+  }
+
+  // Interactive review (uses elicitation)
+  for (const pattern of pendingPatterns) {
+    const action = await promptReviewAction(pattern);
+    if (action === 'quit') break;
+
+    store.updateStatus(pattern.id, action === 'promote' ? 'active' : action);
+    console.log(`✓ Pattern ${action}d.`);
+  }
+}
+```
+
+---
+
+## Help Text
+
+```text
+Usage: *patterns [subcommand] [options]
+
+Manage learned workflow patterns.
+
+Subcommands:
+  list     List all learned patterns (default)
+  stats    Show pattern statistics
+  prune    Remove stale/low-value patterns
+  review   Interactive review of pending patterns
+
+Options:
+  --status <status>  Filter by status (pending, active, promoted, deprecated)
+  --limit <n>        Limit results (default: 10)
+  --help             Show this help message
+
+Examples:
+  *patterns                          # List top 10 patterns
+  *patterns list --status active     # List active patterns only
+  *patterns stats                    # Show statistics
+  *patterns prune                    # Remove stale patterns
+  *patterns review                   # Review pending patterns
+
+Pattern Lifecycle:
+  1. pending  - Newly captured, awaiting review
+  2. active   - Validated, used in suggestions
+  3. promoted - High-value, prioritized in suggestions
+  4. deprecated - Marked for removal
+```
+
+---
+
+## Output Formats
+
+### List Output
+```text
+Learned Patterns (15 total)
+═══════════════════════════
+
+Top Patterns by Occurrence:
+1. validate-story-draft → develop → review-qa
+   Occurrences: 12 | Success: 95% | Status: promoted
+   Workflow: story_development | Last seen: 2h ago
+
+2. develop → review-qa → apply-qa-fixes
+   Occurrences: 8 | Success: 88% | Status: active
+   Workflow: story_development | Last seen: 1d ago
+
+3. create-story → validate-story-draft → develop
+   Occurrences: 6 | Success: 100% | Status: active
+   Workflow: story_creation | Last seen: 3d ago
+
+Showing 3 of 15 patterns. Use --limit to see more.
+```
+
+### Stats Output
+```text
+Pattern Learning Statistics
+═══════════════════════════
+
+Storage:
+  Total patterns: 15
+  Max patterns: 100
+  Utilization: 15%
+
+By Status:
+  Pending: 3
+  Active: 9
+  Promoted: 2
+  Deprecated: 1
+
+Quality:
+  Avg success rate: 92%
+  Total occurrences: 45
+
+Storage file: .aios-core/data/learned-patterns.yaml
+Last updated: 2025-12-26T10:30:00Z
+```
+
+### Review Output
+```text
+*patterns review
+
+Patterns Pending Review (3)
+═══════════════════════════
+
+Pattern #1: develop → run-tests → review-qa
+Occurrences: 4 | Success Rate: 100% | First Seen: 2 days ago
+[P]romote  [S]kip  [D]eprecate  [Q]uit
+
+> p
+
+✓ Pattern promoted to active status
+
+Pattern #2: create-story → develop
+Occurrences: 2 | Success Rate: 50% | First Seen: 5 days ago
+[P]romote  [S]kip  [D]eprecate  [Q]uit
+
+> d
+
+✓ Pattern deprecated
+
+Review complete. 1 promoted, 0 skipped, 1 deprecated.
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] Output displayed correctly
+    tipo: post-condition
+    blocker: false
+    validação: Verify console output matches expected format
+
+  - [ ] Storage updated for prune/review
+    tipo: post-condition
+    blocker: true
+    validação: Check learned-patterns.yaml was modified
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Learning module not found | Missing dependency | Show error message |
+| Storage file corrupt | Invalid YAML | Reset to empty, show warning |
+| No patterns found | Empty storage | Show "no patterns" message |
+| Review cancelled | User quit | Save any changes made |
+
+**Error Recovery Strategy:**
+```javascript
+try {
+  const stats = store.getStats();
+  displayStats(stats);
+} catch (error) {
+  console.error(`⚠️ Error reading patterns: ${error.message}`);
+  console.log('Try running: rm .aios-core/data/learned-patterns.yaml');
+}
+```
+
+---
+
+## Performance
+
+```yaml
+duration_expected: <50ms
+cost_estimated: $0.00 (local file only)
+token_usage: 0
+
+optimizations:
+  - Cached pattern loading (5s TTL)
+  - Lazy parsing of YAML
+  - Streamed display for large lists
+```
+
+---
+
+## Metadata
+
+```yaml
+story: WIS-5
+version: 1.0.0
+created: 2025-12-26
+author: "@dev (Dex)"
+dependencies:
+  modules:
+    - workflow-intelligence/learning
+  tasks: []
+tags:
+  - workflow-intelligence
+  - patterns
+  - learning
+  - management
+```

package/.aios-core/development/tasks/squad-creator-analyze.md

@@ -0,0 +1,315 @@
+---
+task: analyzeSquad()
+responsavel: "@squad-creator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: squad_name
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+    validacao: Squad must exist in ./squads/ directory
+
+  - campo: output_format
+    tipo: string
+    origem: User Input
+    obrigatorio: false
+    validacao: "console | markdown | json (default: console)"
+
+  - campo: verbose
+    tipo: boolean
+    origem: User Input
+    obrigatorio: false
+    validacao: "Include file details (default: false)"
+
+  - campo: suggestions
+    tipo: boolean
+    origem: User Input
+    obrigatorio: false
+    validacao: "Include improvement suggestions (default: true)"
+
+Saida:
+  - campo: analysis_report
+    tipo: object
+    destino: Console or file
+    persistido: false
+
+  - campo: component_inventory
+    tipo: object
+    destino: Return value
+    persistido: false
+
+  - campo: coverage_metrics
+    tipo: object
+    destino: Return value
+    persistido: false
+
+  - campo: suggestions
+    tipo: array
+    destino: Return value
+    persistido: false
+
+Checklist:
+  - "[ ] Validate squad exists"
+  - "[ ] Load squad.yaml manifest"
+  - "[ ] Inventory components by type"
+  - "[ ] Calculate coverage metrics"
+  - "[ ] Generate improvement suggestions"
+  - "[ ] Format and display report"
+---
+
+# Analyze Squad Task
+
+## Purpose
+
+Analyze an existing squad's structure, components, and coverage to provide insights and improvement suggestions. This task enables developers to understand what a squad contains and identify opportunities for enhancement.
+
+## Story Reference
+
+- **Story:** SQS-11 - Squad Analyze & Extend
+- **Epic:** SQS - Squad System Enhancement
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Squad exists in ./squads/ directory
+    tipo: pre-condition
+    blocker: true
+    validacao: |
+      Check if squad directory exists with valid manifest
+    error_message: "Squad not found. Use *list-squads to see available squads."
+```
+
+## Elicitation Flow
+
+```
+@squad-creator
+
+*analyze-squad
+
+? Squad name: _________________
+  (Tab to autocomplete from available squads)
+
+? Output format:
+  > 1. console (default) - Display in terminal
+    2. markdown - Save to file
+    3. json - Machine readable
+
+? Include suggestions? (Y/n): Y
+
+Analyzing squad...
+```
+
+## Execution Steps
+
+### Step 1: Validate Squad Exists
+
+```javascript
+const { SquadLoader } = require('../scripts/squad/squad-loader');
+const loader = new SquadLoader();
+
+const squadPath = path.join('./squads', squadName);
+const exists = await loader.squadExists(squadName);
+
+if (!exists) {
+  throw new Error(`Squad "${squadName}" not found. Use *list-squads to see available squads.`);
+}
+```
+
+### Step 2: Load Squad Manifest
+
+```javascript
+const manifest = await loader.loadManifest(squadName);
+
+// Extract overview
+const overview = {
+  name: manifest.name,
+  version: manifest.version,
+  author: manifest.author,
+  license: manifest.license,
+  aiosMinVersion: manifest.aios?.minVersion || 'N/A',
+  description: manifest.description
+};
+```
+
+### Step 3: Inventory Components
+
+```javascript
+const { SquadAnalyzer } = require('../scripts/squad/squad-analyzer');
+const analyzer = new SquadAnalyzer();
+
+const inventory = await analyzer.inventoryComponents(squadPath);
+
+// Expected structure:
+// {
+//   agents: ['lead-agent.md', 'helper-agent.md'],
+//   tasks: ['lead-agent-task1.md', 'lead-agent-task2.md'],
+//   workflows: [],
+//   checklists: [],
+//   templates: ['report-template.md'],
+//   tools: [],
+//   scripts: [],
+//   data: []
+// }
+```
+
+### Step 4: Calculate Coverage Metrics
+
+```javascript
+const coverage = analyzer.calculateCoverage(inventory, manifest);
+
+// Expected structure:
+// {
+//   agents: { total: 2, withTasks: 2, percentage: 100 },
+//   tasks: { total: 3, percentage: 75 },
+//   config: { hasReadme: true, hasTechStack: false, percentage: 60 },
+//   directories: { populated: 3, empty: 5, percentage: 37.5 }
+// }
+```
+
+### Step 5: Generate Suggestions
+
+```javascript
+const suggestions = analyzer.generateSuggestions(inventory, coverage);
+
+// Expected structure:
+// [
+//   { priority: 'high', message: 'Add tasks for helper-agent (currently has only 1)' },
+//   { priority: 'medium', message: 'Create workflows for common sequences' },
+//   { priority: 'low', message: 'Add checklists for validation' }
+// ]
+```
+
+### Step 6: Format and Display Report
+
+```javascript
+const report = analyzer.formatReport({
+  overview,
+  inventory,
+  coverage,
+  suggestions
+}, outputFormat);
+
+if (outputFormat === 'console') {
+  console.log(report);
+} else if (outputFormat === 'markdown') {
+  const outputPath = path.join(squadPath, 'ANALYSIS.md');
+  await fs.writeFile(outputPath, report);
+  console.log(`Analysis saved to: ${outputPath}`);
+} else if (outputFormat === 'json') {
+  console.log(JSON.stringify({ overview, inventory, coverage, suggestions }, null, 2));
+}
+```
+
+## Output Format (Console)
+
+```
+=== Squad Analysis: {squad-name} ===
+
+Overview
+  Name: {name}
+  Version: {version}
+  Author: {author}
+  License: {license}
+  AIOS Min Version: {aiosMinVersion}
+
+Components
+  Agents ({count})
+    {agent-file-1}
+    {agent-file-2}
+  Tasks ({count})
+    {task-file-1}
+    {task-file-2}
+  Workflows ({count}) {empty-indicator}
+  Checklists ({count}) {empty-indicator}
+  Templates ({count})
+  Tools ({count}) {empty-indicator}
+  Scripts ({count}) {empty-indicator}
+  Data ({count}) {empty-indicator}
+
+Coverage
+  Agents: {bar} {percentage}% ({details})
+  Tasks: {bar} {percentage}% ({details})
+  Config: {bar} {percentage}% ({details})
+  Docs: {bar} {percentage}% ({details})
+
+Suggestions
+  1. {suggestion-1}
+  2. {suggestion-2}
+  3. {suggestion-3}
+
+Next: *extend-squad {squad-name}
+```
+
+## Error Handling
+
+### Error 1: Squad Not Found
+
+```yaml
+error: SQUAD_NOT_FOUND
+cause: Squad directory does not exist
+resolution: Use *list-squads to see available squads
+recovery: Suggest *create-squad to create new squad
+```
+
+### Error 2: Invalid Manifest
+
+```yaml
+error: MANIFEST_PARSE_ERROR
+cause: squad.yaml contains invalid YAML
+resolution: Fix YAML syntax errors
+recovery: Run *validate-squad for detailed validation
+```
+
+### Error 3: Permission Denied
+
+```yaml
+error: PERMISSION_DENIED
+cause: Cannot read squad directory or files
+resolution: Check file permissions
+recovery: chmod 644 for files, 755 for directories
+```
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] Analysis report generated successfully
+    tipo: post-condition
+    blocker: false
+    validacao: |
+      Verify all components were inventoried
+    error_message: "Analysis incomplete - some components may not be listed"
+```
+
+## Dependencies
+
+- **Scripts:**
+  - `.aios-core/development/scripts/squad/squad-loader.js`
+  - `.aios-core/development/scripts/squad/squad-analyzer.js`
+
+- **Tools:**
+  - js-yaml (YAML parsing)
+  - fs (file system operations)
+
+## Metadata
+
+```yaml
+story: SQS-11
+version: 1.0.0
+created: 2025-12-26
+updated: 2025-12-26
+author: Dex (dev)
+tags:
+  - squad
+  - analysis
+  - inventory
+  - coverage
+```
+
+---
+
+*Task definition for *analyze-squad command*

package/.aios-core/development/tasks/squad-creator-create.md

@@ -92,6 +92,28 @@ Cria um novo squad seguindo a arquitetura task-first do AIOS.
 
 ## Estrutura Gerada
 
+### Com Project Configs (SQS-10)
+
+Quando o projeto tem `docs/framework/` com arquivos de config (CODING-STANDARDS.md, etc.),
+o squad referencia esses arquivos ao invés de criar cópias locais:
+
+```
+./squads/meu-dominio-squad/
+├── squad.yaml                    # Manifest (referencia docs/framework/)
+├── README.md                     # Documentacao
+├── config/
+│   └── .gitkeep                 # Configs em docs/framework/
+├── agents/
+│   └── example-agent.md         # Agente de exemplo
+├── tasks/
+│   └── example-agent-task.md    # Task de exemplo
+...
+```
+
+### Sem Project Configs (Fallback)
+
+Quando o projeto NÃO tem `docs/framework/`, cria arquivos locais:
+
 ```
 ./squads/meu-dominio-squad/
 ├── squad.yaml                    # Manifest
@@ -145,9 +167,10 @@ components:
 
 config:
   extends: extend
-  coding-standards: config/coding-standards.md
-  tech-stack: config/tech-stack.md
-  source-tree: config/source-tree.md
+  # SQS-10: References project-level files when docs/framework/ exists
+  coding-standards: ../../docs/framework/CODING-STANDARDS.md   # or config/coding-standards.md
+  tech-stack: ../../docs/framework/TECH-STACK.md               # or config/tech-stack.md
+  source-tree: ../../docs/framework/SOURCE-TREE.md             # or config/source-tree.md
 
 dependencies:
   node: []