aios-core 3.6.0 → 3.8.0

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
+```

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
+```