aiox-core 5.0.0

package/.aiox-core/scripts/aiox-doc-template.md

@@ -0,0 +1,325 @@
+# AIOX Document Template Specification
+
+## Overview
+
+AIOX document templates are defined in YAML format to drive interactive document generation and agent interaction. Templates separate structure definition from content generation, making them both human and LLM-agent-friendly.
+
+## Template Structure
+
+```yaml
+template:
+  id: template-identifier
+  name: Human Readable Template Name
+  version: 1.0
+  output:
+    format: markdown
+    filename: default-path/to/{{filename}}.md
+    title: "{{variable}} Document Title"
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+
+sections:
+  - id: section-id
+    title: Section Title
+    instruction: |
+      Detailed instructions for the LLM on how to handle this section
+    # ... additional section properties
+```
+
+## Core Fields
+
+### Template Metadata
+
+- **id**: Unique identifier for the template
+- **name**: Human-readable name displayed in UI
+- **version**: Template version for tracking changes
+- **output.format**: Default "markdown" for document templates
+- **output.filename**: Default output file path (can include variables)
+- **output.title**: Document title (becomes H1 in markdown)
+
+### Workflow Configuration
+
+- **workflow.mode**: Default interaction mode ("interactive" or "yolo")
+- **workflow.elicitation**: Elicitation task to use ("advanced-elicitation")
+
+## Section Properties
+
+### Required Fields
+
+- **id**: Unique section identifier
+- **title**: Section heading text
+- **instruction**: Detailed guidance for LLM on handling this section
+
+### Optional Fields
+
+#### Content Control
+
+- **type**: Content type hint for structured sections
+- **template**: Fixed template text for section content
+- **item_template**: Template for repeatable items within section
+- **prefix**: Prefix for numbered items (e.g., "FR", "NFR")
+
+#### Behavior Flags
+
+- **elicit**: Boolean - Apply elicitation after section rendered
+- **repeatable**: Boolean - Section can be repeated multiple times
+- **condition**: String - Condition for including section (e.g., "has ui requirements")
+
+#### Agent Permissions
+
+- **owner**: String - Agent role that initially creates/populates this section
+- **editors**: Array - List of agent roles allowed to modify this section
+- **readonly**: Boolean - Section cannot be modified after initial creation
+
+#### Content Guidance
+
+- **examples**: Array of example content (not included in output)
+- **choices**: Object with choice options for common decisions
+- **placeholder**: Default placeholder text
+
+#### Structure
+
+- **sections**: Array of nested child sections
+
+## Supported Types
+
+### Content Types
+
+- **bullet-list**: Unordered list items
+- **numbered-list**: Ordered list with optional prefix
+- **paragraphs**: Free-form paragraph text
+- **table**: Structured table data
+- **code-block**: Code or configuration blocks
+- **template-text**: Fixed template with variable substitution
+- **mermaid**: Mermaid diagram with specified type and details
+
+### Special Types
+
+- **repeatable-container**: Container for multiple instances
+- **conditional-block**: Content shown based on conditions
+- **choice-selector**: Present choices to user
+
+## Advanced Features
+
+### Variable Substitution
+
+Use `{{variable_name}}` in titles, templates, and content:
+
+```yaml
+title: "Epic {{epic_number}} {{epic_title}}"
+template: "As a {{user_type}}, I want {{action}}, so that {{benefit}}."
+```
+
+### Conditional Sections
+
+```yaml
+- id: ui-section
+  title: User Interface Design
+  condition: Project has UX/UI Requirements
+  instruction: Only include if project has UI components
+```
+
+### Choice Integration
+
+```yaml
+choices:
+  architecture: [Monolith, Microservices, Serverless]
+  testing: [Unit Only, Unit + Integration, Full Pyramid]
+```
+
+### Mermaid Diagrams
+
+```yaml
+- id: system-architecture
+  title: System Architecture Diagram
+  type: mermaid
+  instruction: Create a system architecture diagram showing key components and data flow
+  mermaid_type: flowchart
+  details: |
+    Show the following components:
+    - User interface layer
+    - API gateway
+    - Core services
+    - Database layer
+    - External integrations
+```
+
+**Supported mermaid_type values:**
+
+**Core Diagram Types:**
+
+- `flowchart` - Flow charts and process diagrams
+- `sequenceDiagram` - Sequence diagrams for interactions
+- `classDiagram` - Class relationship diagrams (UML)
+- `stateDiagram` - State transition diagrams
+- `erDiagram` - Entity relationship diagrams
+- `gantt` - Gantt charts for timelines
+- `pie` - Pie charts for data visualization
+
+**Advanced Diagram Types:**
+
+- `journey` - User journey maps
+- `mindmap` - Mindmaps for brainstorming
+- `timeline` - Timeline diagrams for chronological events
+- `quadrantChart` - Quadrant charts for data categorization
+- `xyChart` - XY charts (bar charts, line charts)
+- `sankey` - Sankey diagrams for flow visualization
+
+**Specialized Types:**
+
+- `c4Context` - C4 context diagrams (experimental)
+- `requirement` - Requirement diagrams
+- `packet` - Network packet diagrams
+- `block` - Block diagrams
+- `kanban` - Kanban boards
+
+### Agent Permissions Example
+
+```yaml
+- id: story-details
+  title: Story
+  owner: scrum-master
+  editors: [scrum-master]
+  readonly: false
+  sections:
+    - id: dev-notes
+      title: Dev Notes
+      owner: dev-agent
+      editors: [dev-agent]
+      readonly: false
+      instruction: Implementation notes and technical details
+    - id: qa-results
+      title: QA Results
+      owner: qa-agent
+      editors: [qa-agent]
+      readonly: true
+      instruction: Quality assurance test results
+```
+
+### Repeatable Sections
+
+```yaml
+- id: epic-details
+  title: Epic {{epic_number}} {{epic_title}}
+  repeatable: true
+  sections:
+    - id: story
+      title: Story {{epic_number}}.{{story_number}} {{story_title}}
+      repeatable: true
+      sections:
+        - id: criteria
+          title: Acceptance Criteria
+          type: numbered-list
+          item_template: "{{criterion_number}}: {{criteria}}"
+          repeatable: true
+```
+
+### Examples with Code Blocks
+
+````yaml
+examples:
+  - "FR6: The system must authenticate users within 2 seconds"
+  - |
+    ```mermaid
+    sequenceDiagram
+        participant User
+        participant API
+        participant DB
+        User->>API: POST /login
+        API->>DB: Validate credentials
+        DB-->>API: User data
+        API-->>User: JWT token
+    ```
+  - |
+    **Architecture Decision Record**
+
+    **Decision**: Use PostgreSQL for primary database
+    **Rationale**: ACID compliance and JSON support needed
+    **Consequences**: Requires database management expertise
+````
+
+## Section Hierarchy
+
+Templates define the complete document structure starting with the first H2 - each level in is the next H#:
+
+```yaml
+sections:
+  - id: overview
+    title: Project Overview
+    sections:
+      - id: goals
+        title: Goals
+      - id: scope
+        title: Scope
+        sections:
+          - id: in-scope
+            title: In Scope
+          - id: out-scope
+            title: Out of Scope
+```
+
+## Processing Flow
+
+1. **Parse Template**: Load and validate YAML structure
+2. **Initialize Workflow**: Set interaction mode and elicitation
+3. **Process Sections**: Handle each section in order:
+   - Check conditions
+   - Apply instructions
+   - Generate content
+   - Handle choices and variables
+   - Apply elicitation if specified
+   - Process nested sections
+4. **Generate Output**: Create clean markdown document
+
+## Best Practices
+
+### Template Design
+
+- Keep instructions clear and specific
+- Use examples for complex content
+- Structure sections logically
+- Include all necessary guidance for LLM
+
+### Content Instructions
+
+- Be explicit about expected format
+- Include reasoning for decisions
+- Specify interaction patterns
+- Reference other documents when needed
+
+### Variable Naming
+
+- Use descriptive variable names
+- Follow consistent naming conventions
+- Document expected variable values
+
+### Examples Usage
+
+- Provide concrete examples for complex sections
+- Include both simple and complex cases
+- Use realistic project scenarios
+- Include code blocks and diagrams when helpful
+
+## Validation
+
+Templates should be validated for:
+
+- Valid YAML syntax
+- Required fields present
+- Consistent section IDs
+- Proper nesting structure
+- Valid variable references
+
+## Migration from Legacy
+
+When converting from markdown+frontmatter templates:
+
+1. Extract embedded `[[LLM:]]` instructions to `instruction` fields
+2. Convert `<<REPEAT>>` blocks to `repeatable: true` sections
+3. Extract `^^CONDITIONS^^` to `condition` fields
+4. Move `@{examples}` to `examples` arrays
+5. Convert `{{placeholders}}` to proper variable syntax
+
+This specification ensures templates are both human-readable and machine-processable while maintaining the flexibility needed for complex document generation.

package/.aiox-core/scripts/batch-migrate-phase1.ps1

@@ -0,0 +1,36 @@
+# Phase 1 - Batch migrate critical tasks
+
+$tasks = @(
+  'create-next-story.md',
+  'brownfield-create-story.md', 
+  'brownfield-create-epic.md',
+  'create-agent.md',
+  'modify-agent.md',
+  'create-task.md',
+  'qa-gate.md',
+  'qa-test-design.md',
+  'execute-checklist.md',
+  'correct-course.md',
+  'create-doc.md',
+  'shard-doc.md'
+)
+
+$successCount = 0
+$failCount = 0
+
+foreach ($task in $tasks) {
+  Write-Host "`n=== Migrating $task ===" -ForegroundColor Cyan
+  node .aiox-core/scripts/migrate-task-to-v2.js ".aiox-core/tasks/$task"
+  
+  if ($LASTEXITCODE -eq 0 -or $LASTEXITCODE -eq 1) {
+    $successCount++
+  } else {
+    $failCount++
+    Write-Host "Failed to migrate $task" -ForegroundColor Red
+  }
+}
+
+Write-Host "`n=== Phase 1 Migration Complete ===" -ForegroundColor Green
+Write-Host "Success: $successCount" -ForegroundColor Green
+Write-Host "Failed: $failCount" -ForegroundColor $(if ($failCount -gt 0) { 'Red' } else { 'Green' })
+

package/.aiox-core/scripts/batch-migrate-phase2.ps1

@@ -0,0 +1,88 @@
+# Phase 2 - Batch migrate agent-specific tasks (50 tasks)
+
+$tasks = @(
+  # Dev Agent Tasks (5 new - 2 already done in Phase 1)
+  'dev-apply-qa-fixes.md',
+  'dev-improve-code-quality.md',
+  'dev-optimize-performance.md',
+  'dev-suggest-refactoring.md',
+  'dev-backlog-debt.md',
+  
+  # QA Agent Tasks (8 new - 2 already done in Phase 1)
+  'qa-generate-tests.md',
+  'qa-nfr-assess.md',
+  'qa-risk-profile.md',
+  'qa-trace-requirements.md',
+  'qa-review-proposal.md',
+  'qa-review-story.md',
+  'qa-run-tests.md',
+  'qa-backlog-add-followup.md',
+  
+  # PO/PM/SM Agent Tasks (12 tasks)
+  'po-pull-story.md',
+  'po-pull-story-from-clickup.md',
+  'po-sync-story.md',
+  'po-sync-story-to-clickup.md',
+  'po-manage-story-backlog.md',
+  'po-backlog-add.md',
+  'po-stories-index.md',
+  'sm-create-next-story.md',
+  'pr-automation.md',
+  'release-management.md',
+  'calculate-roi.md',
+  'collaborative-edit.md',
+  
+  # Architect/Analyst Tasks (7 tasks)
+  'analyze-framework.md',
+  'architect-analyze-impact.md',
+  'analyst-facilitate-brainstorming.md',
+  'advanced-elicitation.md',
+  'create-deep-research-prompt.md',
+  'analyze-performance.md',
+  
+  # UX/Data/DevOps Tasks (14 tasks)
+  'ux-create-wireframe.md',
+  'ux-ds-scan-artifact.md',
+  'ux-user-research.md',
+  'db-apply-migration.md',
+  'db-bootstrap.md',
+  'db-dry-run.md',
+  'db-env-check.md',
+  'db-snapshot.md',
+  'github-devops-github-pr-automation.md',
+  'github-devops-pre-push-quality-gate.md',
+  'github-devops-repository-cleanup.md',
+  'github-devops-version-management.md',
+  'ci-cd-configuration.md',
+  'security-scan.md'
+)
+
+Write-Host "Phase 2: Migrating $($tasks.Count) agent-specific tasks..." -ForegroundColor Cyan
+Write-Host ""
+
+$successCount = 0
+$failCount = 0
+$startTime = Get-Date
+
+foreach ($task in $tasks) {
+  Write-Host "Migrating: $task" -ForegroundColor Yellow
+  node .aiox-core/scripts/migrate-task-to-v2.js ".aiox-core/tasks/$task" 2>&1 | Out-Null
+  
+  if ($LASTEXITCODE -eq 0 -or $LASTEXITCODE -eq 1) {
+    $successCount++
+    Write-Host "  OK" -ForegroundColor Green
+  } else {
+    $failCount++
+    Write-Host "  FAILED" -ForegroundColor Red
+  }
+}
+
+$endTime = Get-Date
+$duration = $endTime - $startTime
+
+Write-Host ""
+Write-Host "=== Phase 2 Migration Complete ===" -ForegroundColor Green
+Write-Host "Success: $successCount" -ForegroundColor Green
+Write-Host "Failed: $failCount" -ForegroundColor $(if ($failCount -gt 0) { 'Red' } else { 'Green' })
+Write-Host "Duration: $($duration.TotalSeconds) seconds" -ForegroundColor Cyan
+

package/.aiox-core/scripts/batch-migrate-phase3.ps1

@@ -0,0 +1,45 @@
+# Phase 3 - Batch migrate remaining utility & support tasks
+
+# Get all remaining non-compliant tasks
+$allTasks = Get-ChildItem .aiox-core/tasks/*.md | Where-Object { $_.Name -notlike '*v1-backup*' } | ForEach-Object { $_.Name }
+
+Write-Host "Finding non-compliant tasks..." -ForegroundColor Cyan
+
+$nonCompliantTasks = @()
+
+foreach ($task in $allTasks) {
+  $result = node .aiox-core/scripts/validate-task-v2.js ".aiox-core/tasks/$task" 2>&1
+  if ($LASTEXITCODE -ne 0) {
+    $nonCompliantTasks += $task
+  }
+}
+
+Write-Host "Phase 3: Migrating $($nonCompliantTasks.Count) remaining tasks..." -ForegroundColor Cyan
+Write-Host ""
+
+$successCount = 0
+$failCount = 0
+$startTime = Get-Date
+
+foreach ($task in $nonCompliantTasks) {
+  Write-Host "Migrating: $task" -ForegroundColor Yellow
+  node .aiox-core/scripts/migrate-task-to-v2.js ".aiox-core/tasks/$task" 2>&1 | Out-Null
+  
+  if ($LASTEXITCODE -eq 0 -or $LASTEXITCODE -eq 1) {
+    $successCount++
+    Write-Host "  OK" -ForegroundColor Green
+  } else {
+    $failCount++
+    Write-Host "  FAILED" -ForegroundColor Red
+  }
+}
+
+$endTime = Get-Date
+$duration = $endTime - $startTime
+
+Write-Host ""
+Write-Host "=== Phase 3 Migration Complete ===" -ForegroundColor Green
+Write-Host "Success: $successCount" -ForegroundColor Green
+Write-Host "Failed: $failCount" -ForegroundColor $(if ($failCount -gt 0) { 'Red' } else { 'Green' })
+Write-Host "Duration: $($duration.TotalSeconds) seconds" -ForegroundColor Cyan
+

package/.aiox-core/scripts/command-execution-hook.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Command Execution Hook
+ * 
+ * Updates session state after command execution for workflow continuity.
+ * 
+ * Responsibilities:
+ * - Track command execution history
+ * - Update session type (new → existing → workflow)
+ * - Record agent transitions
+ * - Enable intelligent greeting adaptation
+ * 
+ * Usage:
+ *   const { updateSessionAfterCommand } = require('./command-execution-hook');
+ *   await updateSessionAfterCommand(agentId, commandName);
+ * 
+ * Part of Story 6.1.4: Unified Greeting System Integration
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Session state storage location
+ */
+const SESSION_DIR = path.join(process.cwd(), '.aiox-core', '.session');
+const SESSION_FILE = path.join(SESSION_DIR, 'current-session.json');
+
+/**
+ * Maximum command history to keep
+ */
+const MAX_HISTORY_LENGTH = 10;
+
+/**
+ * Update session state after command execution
+ * 
+ * @param {string} agentId - Current agent ID
+ * @param {string} commandName - Executed command name
+ * @param {Object} options - Optional metadata
+ * @param {string} options.previousAgent - Previous agent (for transitions)
+ * @param {any} options.result - Command execution result
+ * @returns {Promise<Object>} Updated session state
+ */
+async function updateSessionAfterCommand(agentId, commandName, options = {}) {
+  try {
+    // Ensure session directory exists
+    await fs.mkdir(SESSION_DIR, { recursive: true });
+    
+    // Load current session or create new
+    const session = await loadSession();
+    
+    // Update command history
+    const commandEntry = {
+      command: commandName,
+      agent: agentId,
+      timestamp: Date.now(),
+      success: options.result !== undefined ? !options.result.error : true,
+    };
+    
+    session.commandHistory = session.commandHistory || [];
+    session.commandHistory.push(commandEntry);
+    
+    // Keep only last MAX_HISTORY_LENGTH commands
+    if (session.commandHistory.length > MAX_HISTORY_LENGTH) {
+      session.commandHistory = session.commandHistory.slice(-MAX_HISTORY_LENGTH);
+    }
+    
+    // Update session type based on history
+    session.sessionType = determineSessionType(session.commandHistory);
+    
+    // Track agent transitions
+    if (options.previousAgent && options.previousAgent !== agentId) {
+      session.previousAgent = options.previousAgent;
+      session.agentTransitions = session.agentTransitions || [];
+      session.agentTransitions.push({
+        from: options.previousAgent,
+        to: agentId,
+        timestamp: Date.now(),
+      });
+    }
+    
+    // Update current agent
+    session.currentAgent = agentId;
+    session.lastUpdated = Date.now();
+    
+    // Save session
+    await saveSession(session);
+    
+    return session;
+    
+  } catch (error) {
+    console.warn('[command-execution-hook] Failed to update session:', error.message);
+    // Non-blocking: return empty session on error
+    return {
+      sessionType: 'new',
+      currentAgent: agentId,
+      commandHistory: [],
+      lastUpdated: Date.now(),
+    };
+  }
+}
+
+/**
+ * Load current session from disk
+ * @private
+ * @returns {Promise<Object>} Session object
+ */
+async function loadSession() {
+  try {
+    const content = await fs.readFile(SESSION_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      // New session
+      return {
+        sessionType: 'new',
+        commandHistory: [],
+        createdAt: Date.now(),
+        lastUpdated: Date.now(),
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save session to disk
+ * @private
+ * @param {Object} session - Session object to save
+ */
+async function saveSession(session) {
+  await fs.writeFile(
+    SESSION_FILE,
+    JSON.stringify(session, null, 2),
+    'utf8',
+  );
+}
+
+/**
+ * Determine session type based on command history
+ * @private
+ * @param {Array} commandHistory - Command history array
+ * @returns {string} Session type (new|existing|workflow)
+ */
+function determineSessionType(commandHistory) {
+  if (!commandHistory || commandHistory.length === 0) {
+    return 'new';
+  }
+  
+  if (commandHistory.length === 1) {
+    return 'existing';
+  }
+  
+  // Workflow detection: 3+ commands or agent transitions
+  if (commandHistory.length >= 3) {
+    return 'workflow';
+  }
+  
+  return 'existing';
+}
+
+/**
+ * Get current session state
+ * 
+ * @returns {Promise<Object>} Current session
+ */
+async function getCurrentSession() {
+  try {
+    return await loadSession();
+  } catch (error) {
+    console.warn('[command-execution-hook] Failed to load session:', error.message);
+    return {
+      sessionType: 'new',
+      commandHistory: [],
+      createdAt: Date.now(),
+      lastUpdated: Date.now(),
+    };
+  }
+}
+
+/**
+ * Clear current session (for testing or manual reset)
+ * 
+ * @returns {Promise<void>}
+ */
+async function clearSession() {
+  try {
+    await fs.unlink(SESSION_FILE);
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+module.exports = {
+  updateSessionAfterCommand,
+  getCurrentSession,
+  clearSession,
+};
+