create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/audit-utilities.md

@@ -0,0 +1,358 @@
+---
+
+# audit-utilities
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOX Task Format V1.0)
+
+```yaml
+task: auditUtilities()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** code-analyzer
+  - **Purpose:** Static code analysis and metrics
+  - **Source:** .aiox-core/utils/code-analyzer.js
+
+- **Tool:** file-system
+  - **Purpose:** Recursive directory traversal
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aiox-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+## Configuration Dependencies
+
+This task requires the following configuration keys from `core-config.yaml`:
+
+- **`devStoryLocation`**: Location of story files (typically docs/stories)
+
+- **`qaLocation`**: QA output directory (typically docs/qa) - Required to write quality reports and gate files
+
+**Loading Config:**
+```javascript
+const yaml = require('js-yaml');
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(__dirname, '../../.aiox-core/core-config.yaml');
+const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+const dev_story_location = config.devStoryLocation;
+const qaLocation = config.qaLocation || 'docs/qa'; // qaLocation
+```
+
+## Purpose
+
+Systematically audit all utilities in `.aiox-core/scripts/` to determine their functional status, classify them as WORKING/FIXABLE/DEPRECATED, and generate actionable recommendations for maintenance and cleanup.
+
+## Classification Criteria
+
+### ✅ WORKING
+- Executes without errors
+- Dependencies installed
+- Integrated with at least one agent/task
+- Documentation exists (inline or external)
+
+### 🔧 FIXABLE
+- Executes with minor errors (missing deps, syntax fixes)
+- Core logic sound, needs integration
+- Fix effort estimated <4 hours
+- Concept valuable enough to justify fix
+
+### 🗑️ DEPRECATED
+- Non-functional, major rewrites needed
+- Obsolete concept (replaced by better approach)
+- Fix effort >8 hours
+- Low value relative to effort
+
+## Execution Steps
+
+### Step 1: Run Automated Testing
+
+Execute the test-utilities.js script to test all utilities:
+
+```bash
+node .aiox-core/scripts/test-utilities.js
+```
+
+This will:
+- Attempt to require() each utility
+- Check for missing dependencies
+- Test exported functions
+- Classify as WORKING/FIXABLE/DEPRECATED based on errors
+
+### Step 2: Verify Integration Status
+
+Run integration scan to find utility usage:
+
+```bash
+# For each utility, count references in agents and tasks
+for util in .aiox-core/scripts/*.js; do
+  name=$(basename $util .js)
+  count=$(grep -r "$name" .aiox-core/agents .aiox-core/tasks Squads 2>/dev/null | wc -l)
+  echo "$name: $count references"
+done
+```
+
+### Step 3: Manual Classification Review
+
+For utilities with ambiguous status:
+- Review source code quality
+- Estimate completion percentage
+- Assess concept value
+- Calculate fix effort estimate
+
+### Step 4: Generate Priority Scoring
+
+For FIXABLE utilities, calculate priority score:
+
+```
+Priority Score = (Integration Count × 10) + (Completion % × 5) - (Fix Hours)
+```
+
+Higher scores = higher priority for fixing
+
+### Step 5: Make Story 3.19 Decision
+
+Determine if memory-layer capabilities exist:
+- Search for memory-related utilities
+- IF found AND classified FIXABLE:
+  - Estimate fix effort vs 20h threshold
+  - Assess core functionality completion (>60%?)
+  - Recommend GO/NO-GO/DEFER
+
+### Step 6: Generate Audit Report
+
+Create comprehensive report with:
+- Summary statistics (X WORKING, Y FIXABLE, Z DEPRECATED)
+- Per-utility details (status, errors, integration count, recommendation)
+- Fix priority list (ranked FIXABLE utilities)
+- Cleanup list (DEPRECATED utilities to remove)
+- Story 3.19 activation recommendation
+
+## Output
+
+**Primary**: `UTILITIES-AUDIT-REPORT.md` in project root or docs/
+
+**Format**:
+```markdown
+# Framework Utilities Audit Report
+
+## Executive Summary
+- Total Utilities: X
+- ✅ WORKING: Y (Z%)
+- 🔧 FIXABLE: A (B%)
+- 🗑️ DEPRECATED: C (D%)
+
+## Detailed Findings
+
+### WORKING Utilities
+...
+
+### FIXABLE Utilities (Priority Ranked)
+...
+
+### DEPRECATED Utilities (Cleanup Candidates)
+...
+
+## Story 3.19 Decision
+...
+```
+
+## Success Criteria
+
+- All 81 utilities audited without crashes
+- Classification is consistent and reproducible
+- Integration counts accurate
+- Report is actionable for Story 3.18 (cleanup)
+- Story 3.19 decision has clear rationale
+
+## Notes
+
+- Run from project root directory
+- Requires Node.js environment
+- May take 5-10 minutes for full audit
+- Some utilities may have circular dependencies - handle gracefully

package/template/.aiox-core/development/tasks/blocks/README.md

@@ -0,0 +1,178 @@
+# AIOX Task Blocks System
+
+> **Version:** 1.0.0
+> **Purpose:** Atomic, reusable components for task workflows
+
+## Overview
+
+Blocks are small, focused units of functionality that can be included in multiple tasks. They follow the DRY (Don't Repeat Yourself) principle and provide consistent behavior across the AIOX framework.
+
+## Directory Structure
+
+```
+.aiox-core/development/tasks/blocks/
+├── README.md                  # This file
+├── context-loading.md         # Load project context (git, gotchas, config)
+├── execution-pattern.md       # Task blocking patterns + anti-patterns
+├── agent-prompt-template.md   # Standardized agent invocation template
+├── execution-modes.md         # Standard YOLO/Interactive/Pre-Flight modes (future)
+├── pre-post-conditions.md     # Standard validation blocks (future)
+└── error-handling.md          # Common error patterns (future)
+```
+
+## How to Include a Block
+
+### Method 1: Markdown Include Comment
+
+Use HTML comments with Include directive:
+
+```markdown
+<!-- Include: blocks/context-loading.md -->
+```
+
+With parameters:
+
+```markdown
+<!-- Include: blocks/context-loading.md -->
+<!-- Parameters: category=frontend, include_git=false -->
+```
+
+### Method 2: YAML Reference
+
+In task frontmatter:
+
+```yaml
+---
+blocks:
+  - id: context-loading
+    params:
+      category: supabase
+      include_gotchas: true
+---
+```
+
+### Method 3: Programmatic (JavaScript)
+
+```javascript
+const { loadBlock, executeBlock } = require('.aiox-core/utils/block-loader');
+
+// Load block definition
+const block = await loadBlock('context-loading');
+
+// Execute with parameters
+const result = await executeBlock(block, {
+  category: 'auth',
+  include_git: true
+});
+```
+
+## Block Anatomy
+
+Each block file follows this structure:
+
+```markdown
+# Block: {Name}
+
+> **Block ID:** `{kebab-case-id}`
+> **Version:** {semver}
+> **Type:** Reusable Include Block
+
+## Purpose
+{One-line description}
+
+## Input
+{Table of parameters with types, defaults, descriptions}
+
+## Output
+{Table of output fields with types and descriptions}
+
+## Execution Steps
+{YAML or pseudocode defining the steps}
+
+## Usage
+{Examples of how to include the block}
+
+## Files Accessed
+{Table of files the block reads/writes}
+
+## Error Handling
+{Table of errors and behaviors}
+
+## Notes
+{Additional context}
+```
+
+## Naming Conventions
+
+| Convention | Example | Description |
+|------------|---------|-------------|
+| Block ID | `context-loading` | Kebab-case, descriptive |
+| File name | `context-loading.md` | Same as block ID with `.md` |
+| Parameters | `include_git` | Snake_case for clarity |
+| Outputs | `git.status` | Dot notation for nested |
+
+## Design Principles
+
+### 1. Single Responsibility
+Each block does ONE thing well. If a block needs to do multiple things, split it.
+
+### 2. Idempotent
+Running a block multiple times produces the same result (for read operations).
+
+### 3. Fail Gracefully
+Blocks should not halt task execution on minor errors. Log warnings and provide defaults.
+
+### 4. Under 50 Lines
+Keep blocks concise. If a block exceeds 50 lines of content, consider splitting.
+
+### 5. Clear Contract
+Every block must define:
+- Input parameters (with types and defaults)
+- Output fields (with types)
+- Files accessed
+- Error behavior
+
+## Available Blocks
+
+| Block | Purpose | Used By |
+|-------|---------|---------|
+| `context-loading` | Load git state, gotchas, preferences, config | dev-develop-story, create-next-story, qa-review-story |
+| `execution-pattern` | Task blocking patterns (sequential/parallel/mixed) + anti-patterns | enhance-workflow, execute-epic, deep-strategic-planning, refactor-workflow, clone-mind, mind-research, squad-creator, bob-orchestrator |
+| `agent-prompt-template` | Standardized template for spawning AIOX agents | Any skill/task that invokes agents via Task tool |
+
+## Lines Saved (ROI)
+
+When a block is adopted, it replaces duplicated code across tasks:
+
+| Block | Lines per task | Tasks using | Total lines saved |
+|-------|----------------|-------------|-------------------|
+| `context-loading` | ~15-20 | 8+ tasks | ~120-160 lines |
+| `execution-pattern` | ~35 | 8+ skills | ~280 lines |
+| `agent-prompt-template` | ~15-20 | 10+ skills | ~150-200 lines |
+| `execution-modes` | ~25-30 | ALL tasks | ~2500+ lines |
+
+## Creating a New Block
+
+1. **Identify repetition**: Find a pattern appearing in 2+ tasks
+2. **Extract the pattern**: Copy to `blocks/{name}.md`
+3. **Parameterize**: Make configurable inputs
+4. **Document**: Follow the block anatomy template
+5. **Test**: Verify in at least 2 tasks
+6. **Update this README**: Add to Available Blocks table
+
+## Future Blocks (Candidates)
+
+Based on task analysis, these patterns appear frequently:
+
+| Pattern | Occurrences | Candidate Block |
+|---------|-------------|-----------------|
+| Execution Modes (YOLO/Interactive/Pre-Flight) | ALL tasks | `execution-modes.md` |
+| Pre/Post Conditions | ALL tasks | `validation-conditions.md` |
+| Performance Metrics | ALL tasks | `performance-metrics.md` |
+| Error Handling Strategy | ALL tasks | `error-handling.md` |
+| Tool Dependencies | 80%+ tasks | `tool-dependencies.md` |
+
+---
+
+*AIOX Task Blocks System v1.1.0*
+*Blocks: context-loading, execution-pattern, agent-prompt-template (extracted from observed patterns)*

package/template/.aiox-core/development/tasks/blocks/agent-prompt-template.md

@@ -0,0 +1,115 @@
+# Block: Agent Prompt Template
+
+> **Block ID:** `agent-prompt-template`
+> **Version:** 1.0.0
+> **Type:** Reusable Include Block
+
+## Purpose
+
+Standardized template for spawning AIOX agents with consistent structure. Ensures all agent invocations follow the same persona loading, context, mission, and output pattern.
+
+## Input
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `agent_name` | string | Yes | - | Agent's display name (e.g., "Aria", "Max") |
+| `agent_role` | string | Yes | - | Agent's role title (e.g., "Architect", "Dev") |
+| `agent_file_path` | string | Yes | - | Path to agent definition file |
+| `context_category` | string | No | `null` | Category for context-loading block (e.g., "Architecture,Security") |
+| `mission_description` | string | Yes | - | What the agent must accomplish |
+| `output_path` | string | Yes | - | Where to save the result |
+| `output_format` | string | No | `markdown` | Expected format (markdown, yaml, json) |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prompt` | string | Complete agent prompt ready for Task tool |
+
+## Core Template
+
+```markdown
+You are {agent_name}, the AIOX {agent_role}. Read your complete agent file at:
+{agent_file_path}
+
+Adopt {agent_name}'s persona, voice, and expertise.
+
+<!-- Include: blocks/context-loading.md -->
+<!-- Parameters: category={context_category} -->
+
+## Context
+
+{context_from_user}
+
+## Mission
+
+{mission_description}
+
+## Output
+
+Save complete result to: {output_path}
+
+Format: {output_format}
+
+After saving, send a message to the team lead with a summary.
+```
+
+## Usage
+
+### Include in Skill File
+
+```markdown
+<!-- Include: blocks/agent-prompt-template.md -->
+<!-- Parameters:
+  agent_name=Aria,
+  agent_role=Architect,
+  agent_file_path=.claude/commands/AIOX/agents/architect.md,
+  context_category=Architecture,
+  mission_description=Design the authentication module,
+  output_path=docs/architecture/auth-design.md,
+  output_format=markdown
+-->
+```
+
+### Programmatic Usage
+
+```javascript
+const { loadBlock, renderTemplate } = require('.aiox-core/utils/block-loader');
+
+const template = await loadBlock('agent-prompt-template');
+const prompt = await renderTemplate(template, {
+  agent_name: 'Aria',
+  agent_role: 'Architect',
+  agent_file_path: '.claude/commands/AIOX/agents/architect.md',
+  context_category: 'Architecture',
+  context_from_user: 'We need to design auth for a multi-tenant SaaS.',
+  mission_description: 'Create detailed authentication architecture document.',
+  output_path: 'docs/architecture/auth-design.md',
+  output_format: 'markdown'
+});
+
+// Use with Task tool
+Task({ prompt, subagent_type: 'general-purpose' });
+```
+
+## Files Accessed
+
+| File | Purpose |
+|------|---------|
+| Agent file at `{agent_file_path}` | Agent persona and capabilities |
+| Via `context-loading` block | Git state, gotchas, preferences |
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| Missing required parameter | Block fails with validation error |
+| Agent file not found | Agent reads empty, continues with defaults |
+| Invalid output_format | Default to `markdown` |
+
+## Notes
+
+- Template is under 20 lines of core content
+- Composes with `context-loading` block for project context
+- Consistent "send message to team lead" ending for orchestration
+- Works with both sequential and parallel agent invocation patterns