create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/product/templates/activation-instructions-template.md

@@ -0,0 +1,258 @@
+# Agent Activation Instructions Template
+**Story**: 6.1.2.5 - Contextual Agent Load System Integration
+**Version**: 2.0 (GreetingBuilder Integration)
+**Last Updated**: 2025-11-16
+
+## Overview
+
+This template defines the canonical activation-instructions format for AIOX agents after GreetingBuilder integration (Story 6.1.2.5).
+
+**Key Change**: Replaced manual greeting STEPs (2.5-5) with intelligent `GreetingBuilder` call that adapts greetings based on session context.
+
+## Canonical Format
+
+```yaml
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
+  - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
+  - STEP 3: Build intelligent greeting using .aiox-core/development/scripts/greeting-builder.js
+           Call buildGreeting(agentDefinition, conversationHistory) which:
+           - Detects session type (new/existing/workflow) via context analysis
+           - Checks git configuration status (with 5min cache)
+           - Loads project status automatically
+           - Filters commands by visibility metadata (full/quick/key)
+           - Suggests workflow next steps if in recurring pattern
+           - Formats adaptive greeting automatically
+  - STEP 4: Display the greeting returned by GreetingBuilder
+  - STEP 5: HALT and await user input
+  - IMPORTANT: Do NOT improvise or add explanatory text beyond what is specified in greeting_levels and Quick Commands section
+  - DO NOT: Load any other agent files during activation
+  - ONLY load dependency files when user requests specific command execution
+  - The agent.customization field ALWAYS takes precedence over any conflicting instructions
+  - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written
+  - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format
+  - When listing tasks/templates or presenting options during conversations, always show as numbered options list
+  - STAY IN CHARACTER!
+  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance
+```
+
+## What Changed (Story 6.1.2.5)
+
+### BEFORE (Manual/Mechanical)
+```yaml
+- STEP 2.5: Load project status using .aiox-core/infrastructure/scripts/project-status-loader.js
+- STEP 2.6: Load session context using .aiox-core/scripts/session-context-loader.js
+- STEP 3: Greet user with EXACTLY the text from greeting_levels.named
+- STEP 3.5: Introduce yourself using format: "I'm {agent.name}..."
+- STEP 3.6: Display session context if available
+- STEP 4: Display project status from STEP 2.5
+- STEP 5: Output EXACTLY the "Quick Commands" section
+```
+
+**Problem**: Claude interpreted these as literal instructions → mechanical, rigid output
+
+### AFTER (Intelligent/Adaptive)
+```yaml
+- STEP 3: Build intelligent greeting using greeting-builder.js
+- STEP 4: Display the greeting returned by GreetingBuilder
+- STEP 5: HALT and await user input
+```
+
+**Benefit**: GreetingBuilder handles all logic internally → contextual, adaptive greetings
+
+## GreetingBuilder Parameters
+
+### Input: `agentDefinition`
+The complete agent object containing:
+- `agent.name`, `agent.id`, `agent.title`, `agent.icon`
+- `persona_profile.greeting_levels` (minimal, named, archetypal)
+- `persona.identity` (role description)
+- `commands[]` with visibility metadata
+
+### Input: `conversationHistory`
+Session context provided by Claude Code, containing:
+- Previous messages in the conversation
+- Previous agent activations
+- Recent commands executed
+
+### Output: Formatted Greeting String
+Returns complete greeting including:
+- Presentation (adapted to session type)
+- Role description (new sessions only)
+- Project status (if git configured)
+- Current context (existing/workflow sessions)
+- Workflow suggestions (workflow sessions only)
+- Filtered commands (by session type)
+- Git warning (if not configured)
+
+## Session Type Detection
+
+GreetingBuilder automatically detects three session types:
+
+### 1. New Session (Minimal Context)
+**Detection**: No conversation history or very short history
+**Greeting Style**: Full
+- ✅ Complete greeting with role description
+- ✅ Up to 12 commands (visibility: full, quick, key)
+- ✅ Project status or git warning
+- ✅ Help text: "Type *help for all commands"
+
+### 2. Existing Context (Active Session)
+**Detection**: Conversation history exists, agent switch detected
+**Greeting Style**: Quick
+- ✅ Quick greeting (no role description)
+- ✅ 6-8 commands (visibility: quick, key)
+- ✅ Current Context section (previous agent)
+- ✅ Compact project status
+
+### 3. Workflow (Recurring Pattern)
+**Detection**: Workflow pattern matched in conversation history
+**Greeting Style**: Minimal
+- ✅ Minimal greeting (e.g., "🎯 Pax ready")
+- ✅ 3-5 commands (visibility: key only)
+- ✅ Workflow Context section
+- ✅ Next-step suggestion
+- ✅ 1-line compact project status
+
+## Command Visibility Metadata
+
+Commands must include visibility metadata for filtering:
+
+```yaml
+commands:
+  - name: help
+    visibility: [full, quick, key]  # Always shown
+    description: "Show all available commands"
+
+  - name: create-story
+    visibility: [full, quick]  # Shown in new and existing sessions
+    description: "Create user story"
+
+  - name: validate-story-draft
+    visibility: [key]  # Shown only in workflow sessions
+    description: "Validate story quality"
+```
+
+**Visibility Levels:**
+- `full`: Show in new sessions (up to 12 total)
+- `quick`: Show in existing sessions (6-8 total)
+- `key`: Show in workflow sessions (3-5 total)
+
+## Git Configuration Warning
+
+If git is not configured, GreetingBuilder automatically appends:
+
+```
+⚠️  **Git Configuration Needed**
+   Your project is not connected to a git repository.
+   Run `git init` and `git remote add origin <url>` to enable version control.
+```
+
+**Configuration** (core-config.yaml):
+```yaml
+git:
+  showConfigWarning: true  # User can disable
+  cacheTimeSeconds: 300    # 5 minutes cache
+```
+
+## Performance Characteristics
+
+- **Target**: < 150ms (hard limit with timeout protection)
+- **Typical**: < 100ms average
+- **Fallback**: Simple greeting on timeout or error
+
+**Optimizations:**
+- Git config cached for 5 minutes (0ms after first check)
+- Context analysis ~20ms
+- Parallel execution of checks
+
+## Backwards Compatibility
+
+GreetingBuilder includes safety features:
+
+1. **Timeout Protection**: Falls back to simple greeting after 150ms
+2. **Error Handling**: Graceful degradation on any error
+3. **Missing Metadata**: Agents without visibility metadata show all commands
+4. **Simple Fallback**: `{greeting}\n\nType *help to see available commands.`
+
+## Migration Checklist
+
+When creating new agents or updating existing ones:
+
+- [ ] Use canonical activation-instructions format
+- [ ] Include GreetingBuilder call (STEP 3)
+- [ ] Remove manual greeting STEPs (2.5-5)
+- [ ] Add visibility metadata to all commands
+- [ ] Test with fresh Claude Code session
+- [ ] Verify fallback greeting works
+
+## Examples
+
+### New Agent Creation
+```yaml
+agent:
+  name: Nova
+  id: new-agent
+  title: New Agent Title
+  icon: 🆕
+
+persona_profile:
+  greeting_levels:
+    minimal: "🆕 Nova ready"
+    named: "🆕 Nova (Archetype) ready. Let's work together!"
+
+commands:
+  - name: help
+    visibility: [full, quick, key]
+    description: "Show all commands"
+  - name: do-thing
+    visibility: [full, quick]
+    description: "Do the thing"
+```
+
+### Testing
+1. Activate agent in fresh session → Should show full greeting
+2. Activate different agent, then return → Should show quick greeting
+3. Execute workflow command, activate next agent → Should show workflow greeting
+
+## Related Files
+
+- **GreetingBuilder**: `.aiox-core/development/scripts/greeting-builder.js`
+- **Context Detector**: `.aiox-core/core/session/context-detector.js`
+- **Git Config Detector**: `.aiox-core/infrastructure/scripts/git-config-detector.js`
+- **Workflow Navigator**: `.aiox-core/development/scripts/workflow-navigator.js`
+- **Project Status Loader**: `.aiox-core/infrastructure/scripts/project-status-loader.js`
+- **Workflow Patterns**: `.aiox-core/data/workflow-patterns.yaml`
+
+## Troubleshooting
+
+### Greeting appears mechanical
+- Check that GreetingBuilder call is in STEP 3
+- Verify old STEPs 2.5-5 are removed
+- Test with fresh Claude Code session
+
+### Commands not filtered
+- Check command visibility metadata exists
+- Verify session type detection is working
+- Check conversation history is being passed
+
+### Git warning not showing
+- Check `git.showConfigWarning: true` in core-config.yaml
+- Verify project has no git remote configured
+- Check git config cache (may be cached from previous check)
+
+### Performance issues
+- Verify greeting displays in < 150ms
+- Check git cache is enabled
+- Monitor for timeout fallbacks in logs
+
+## Version History
+
+| Version | Date | Changes | Story |
+|---------|------|---------|-------|
+| 2.0 | 2025-11-16 | GreetingBuilder integration | 6.1.2.5 |
+| 1.0 | 2025-01-15 | Manual activation STEPs | N/A |
+
+---
+
+*Template maintained by AIOX Framework Team*

package/template/.aiox-core/product/templates/adr.hbs

@@ -0,0 +1,125 @@
+---
+template_id: adr
+template_name: Architecture Decision Record
+version: 1.0
+variables:
+  - name: number
+    type: number
+    required: true
+    auto: next_adr_number
+  - name: title
+    type: string
+    required: true
+    prompt: "Title of the architectural decision:"
+  - name: status
+    type: choice
+    required: true
+    choices: [Proposed, Accepted, Deprecated, Superseded]
+    default: Proposed
+  - name: deciders
+    type: string
+    required: true
+    prompt: "Who participated in this decision? (comma-separated names):"
+  - name: context
+    type: text
+    required: true
+    prompt: "What is the context and problem that led to this decision?"
+  - name: decision
+    type: text
+    required: true
+    prompt: "What is the decision being made?"
+  - name: positiveConsequences
+    type: array
+    required: true
+    prompt: "What are the positive consequences? (comma-separated):"
+  - name: negativeConsequences
+    type: array
+    required: false
+    prompt: "What are the negative consequences/trade-offs? (comma-separated):"
+---
+
+# ADR {{padNumber number 3}}: {{title}}
+
+**Status:** {{status}}
+**Date:** {{formatDate now "YYYY-MM-DD"}}
+**Deciders:** {{deciders}}
+
+---
+
+## Context
+
+{{context}}
+
+---
+
+## Decision
+
+{{decision}}
+
+---
+
+## Consequences
+
+### Positive
+
+{{#each positiveConsequences}}
+- ✅ {{this}}
+{{/each}}
+
+### Negative
+
+{{#if negativeConsequences}}
+{{#each negativeConsequences}}
+- ⚠️ {{this}}
+{{/each}}
+{{else}}
+_No significant negative consequences identified._
+{{/if}}
+
+---
+
+{{#if alternatives}}
+## Alternatives Considered
+
+{{#each alternatives}}
+### Option {{add @index 1}}: {{this.name}}
+
+{{this.description}}
+
+| Aspect | Details |
+|--------|---------|
+| **Pros** | {{this.pros}} |
+| **Cons** | {{this.cons}} |
+| **Why Not Chosen** | {{this.whyNot}} |
+
+{{/each}}
+{{/if}}
+
+---
+
+## Related Decisions
+
+{{#if relatedADRs}}
+{{#each relatedADRs}}
+- [ADR {{this.number}}](./adr-{{padNumber this.number 3}}.md): {{this.title}}
+{{/each}}
+{{else}}
+_No related decisions._
+{{/if}}
+
+---
+
+## References
+
+{{#if references}}
+{{#each references}}
+- {{this}}
+{{/each}}
+{{else}}
+_No external references._
+{{/if}}
+
+---
+
+**Generated by:** AIOX Template Engine v2.0
+**Template Version:** adr-1.0

package/template/.aiox-core/product/templates/agent-template.yaml

@@ -0,0 +1,121 @@
+# Agent Template for Synkra AIOX
+# This template is used by aiox-developer to create new agents
+# Variables are replaced during generation: {{VARIABLE_NAME}}
+
+###############################################################################
+# NAMING CONVENTION FOR "{{AGENT_ID}}" AGENT
+###############################################################################
+#
+# CRITICAL: All dependencies specific to this agent MUST follow naming convention:
+#
+#   Workflows:  {{AGENT_ID}}-{workflow-name}.yaml
+#   Tasks:      {{AGENT_ID}}-{task-name}.md
+#   Templates:  {{AGENT_ID}}-{template-name}.yaml
+#   Checklists: {{AGENT_ID}}-{checklist-name}.md
+#   Scripts:    {{AGENT_ID}}-{script-name}.js
+#
+# Examples for this agent:
+#   ✅ {{AGENT_ID}}-greenfield-ui.yaml (workflow)
+#   ✅ {{AGENT_ID}}-user-research.md (task)
+#   ✅ {{AGENT_ID}}-report-tmpl.yaml (template)
+#   ✅ {{AGENT_ID}}-validation-checklist.md (checklist)
+#   ✅ {{AGENT_ID}}-connection-manager.js (script)
+#
+# SHARED dependencies (used by multiple agents) do NOT use agent prefix:
+#   ✅ create-doc.md (used by pm, po, sm)
+#   ✅ execute-checklist.md (used by qa, dev)
+#
+# Use *create-task command to automatically apply naming convention.
+#
+###############################################################################
+
+agent:
+  name: "{{AGENT_NAME}}"
+  id: "{{AGENT_ID}}"
+  title: "{{AGENT_TITLE}}"
+  icon: "{{AGENT_ICON}}"
+  whenToUse: "{{WHEN_TO_USE}}"
+  {{#IF_CUSTOMIZATION}}
+  customization: |
+    {{CUSTOMIZATION}}
+  {{/IF_CUSTOMIZATION}}
+
+persona:
+  role: "{{PERSONA_ROLE}}"
+  style: "{{PERSONA_STYLE}}"
+  identity: "{{PERSONA_IDENTITY}}"
+  focus: "{{PERSONA_FOCUS}}"
+  {{#IF_CORE_PRINCIPLES}}
+  core_principles:
+    {{#EACH_PRINCIPLES}}
+    - {{ITEM}}
+    {{/EACH_PRINCIPLES}}
+  {{/IF_CORE_PRINCIPLES}}
+
+commands:
+  - help: "Show available commands for this agent"
+  {{#EACH_COMMANDS}}
+  - {{COMMAND_NAME}}: "{{COMMAND_DESCRIPTION}}"
+  {{/EACH_COMMANDS}}
+  - exit: "Exit {{AGENT_NAME}} agent and return to default mode"
+
+{{#IF_DEPENDENCIES}}
+dependencies:
+  {{#IF_WORKFLOWS}}
+  workflows:
+    {{#EACH_WORKFLOW_DEPS}}
+    - {{ITEM}}
+    {{/EACH_WORKFLOW_DEPS}}
+  {{/IF_WORKFLOWS}}
+  {{#IF_TASKS}}
+  tasks:
+    {{#EACH_TASK_DEPS}}
+    - {{ITEM}}
+    {{/EACH_TASK_DEPS}}
+  {{/IF_TASKS}}
+  {{#IF_TEMPLATES}}
+  templates:
+    {{#EACH_TEMPLATE_DEPS}}
+    - {{ITEM}}
+    {{/EACH_TEMPLATE_DEPS}}
+  {{/IF_TEMPLATES}}
+  {{#IF_CHECKLISTS}}
+  checklists:
+    {{#EACH_CHECKLIST_DEPS}}
+    - {{ITEM}}
+    {{/EACH_CHECKLIST_DEPS}}
+  {{/IF_CHECKLISTS}}
+  {{#IF_DATA}}
+  data:
+    {{#EACH_DATA_DEPS}}
+    - {{ITEM}}
+    {{/EACH_DATA_DEPS}}
+  {{/IF_DATA}}
+  {{#IF_SCRIPTS}}
+  scripts:
+    {{#EACH_SCRIPTS_DEPS}}
+    - {{ITEM}}
+    {{/EACH_SCRIPTS_DEPS}}
+  {{/IF_SCRIPTS}}
+  {{#IF_TOOLS}}
+  tools:
+    {{#EACH_TOOL_DEPS}}
+    - {{ITEM}}
+    {{/EACH_TOOL_DEPS}}
+  {{/IF_TOOLS}}
+{{/IF_DEPENDENCIES}}
+
+{{#IF_ACTIVATION_INSTRUCTIONS}}
+activation-instructions: |
+  {{ACTIVATION_INSTRUCTIONS}}
+{{/IF_ACTIVATION_INSTRUCTIONS}}
+
+{{#IF_SECURITY_CONFIG}}
+security:
+  authorization: "{{SECURITY_AUTHORIZATION}}"
+  allowed_operations:
+    {{#EACH_ALLOWED_OPS}}
+    - {{ITEM}}
+    {{/EACH_ALLOWED_OPS}}
+  audit_logging: {{AUDIT_LOGGING}}
+{{/IF_SECURITY_CONFIG}} 

package/template/.aiox-core/product/templates/aiox-ai-config.yaml

@@ -0,0 +1,106 @@
+# AIOX AI Provider Configuration
+#
+# Configure AI providers (Claude Code, Gemini CLI) for AIOX operations.
+# This file controls which provider is used for different task types.
+#
+# @see Epic GEMINI-INT - Story 2: AI Provider Factory Pattern
+
+# Provider Configuration
+ai_providers:
+  # Primary provider - used by default
+  primary: claude        # Options: claude, gemini
+
+  # Fallback provider - used when primary fails
+  fallback: gemini       # Options: claude, gemini, null (no fallback)
+
+  # Task-based routing
+  # Route specific task types to preferred providers
+  routing:
+    # Simple tasks - use cheaper/faster provider
+    simple_tasks: gemini       # Code formatting, simple refactors
+
+    # Complex tasks - use more capable provider
+    complex_tasks: claude      # Architecture, security reviews
+
+    # Documentation - high volume, speed matters
+    documentation: gemini
+
+    # Code generation - balance of speed and quality
+    code_generation: gemini
+
+    # Code review - quality matters
+    code_review: claude
+
+    # Testing - straightforward tasks
+    testing: gemini
+
+    # Security - critical thinking required
+    security: claude
+
+# Claude Code Configuration
+claude:
+  # Model to use
+  model: claude-3-5-sonnet    # Options: claude-3-5-sonnet, claude-3-opus, etc.
+
+  # Execution timeout (ms)
+  timeout: 300000             # 5 minutes
+
+  # Maximum retry attempts
+  maxRetries: 3
+
+  # Skip permission prompts (use with caution)
+  dangerouslySkipPermissions: false
+
+# Gemini CLI Configuration
+gemini:
+  # Model to use
+  model: gemini-2.0-flash     # Options: gemini-2.0-flash, gemini-2.0-pro
+
+  # Execution timeout (ms)
+  timeout: 300000             # 5 minutes
+
+  # Maximum retry attempts
+  maxRetries: 3
+
+  # Enable preview features (required for Gemini 3)
+  previewFeatures: true
+
+  # Use JSON output format by default
+  jsonOutput: false
+
+# Model Switching (Story 16)
+# Automatic selection between Flash and Pro based on task complexity
+model_switching:
+  enabled: false              # Enable when Story 16 is complete
+  default_model: gemini-2.0-flash
+  complexity_threshold:
+    simple: 0.3               # < 0.3 = Flash
+    medium: 0.7               # 0.3-0.7 = Flash
+    complex: 1.0              # > 0.7 = Pro
+  quality_fallback:
+    enabled: true
+    min_score: 0.6            # If quality < 0.6, retry with Pro
+
+# Parallel Execution (Story 17)
+# Run Claude + Gemini simultaneously for better quality
+parallel_execution:
+  enabled: false              # Enable when Story 17 is complete
+  default_mode: fallback      # Options: race, consensus, best-of, merge, fallback
+
+  # Task-specific modes
+  task_modes:
+    architecture: consensus   # Both must agree on architecture
+    security: consensus       # Critical - need agreement
+    code_generation: best-of  # Pick best code
+    documentation: race       # Speed matters
+    refactoring: merge        # Combine insights
+
+  # Cost control
+  cost_control:
+    max_parallel_cost: 1.00   # Max cost for parallel run (USD)
+    fallback_on_budget: true  # Disable parallel if over budget
+
+  # Quality thresholds
+  quality_thresholds:
+    consensus_similarity: 0.85
+    merge_min_quality: 0.7