aios-core 1.0.0

package/.aios-core/core/docs/session-update-pattern.md

@@ -0,0 +1,314 @@
+# Session Update Pattern
+
+**Integration Guide for Story 6.1.4**
+
+## Overview
+
+The session update pattern enables intelligent greeting adaptation by tracking command execution history and agent transitions. This allows AIOS to provide contextual greetings that reflect workflow continuity.
+
+## Architecture
+
+```
+[Agent Activation] → [Generate Greeting] → [Execute Command] → [Update Session] → [Next Activation]
+                            ↑                                          ↓
+                            └─────────── Session State ───────────────┘
+```
+
+## Integration Points
+
+### 1. Command Execution Wrapper
+
+All agent commands should be wrapped with session updates:
+
+```javascript
+const { updateSessionAfterCommand } = require('./.aios-core/scripts/command-execution-hook');
+
+async function executeCommand(agentId, commandName, commandFn) {
+  try {
+    const result = await commandFn();
+    
+    // Update session after successful execution
+    await updateSessionAfterCommand(agentId, commandName, { result });
+    
+    return result;
+  } catch (error) {
+    // Still update session even on error
+    await updateSessionAfterCommand(agentId, commandName, { 
+      result: { error: error.message } 
+    });
+    throw error;
+  }
+}
+```
+
+### 2. Agent Transition Tracking
+
+When switching agents, record the transition:
+
+```javascript
+const { updateSessionAfterCommand } = require('./.aios-core/scripts/command-execution-hook');
+
+async function switchAgent(fromAgent, toAgent) {
+  await updateSessionAfterCommand(toAgent, 'agent-activation', {
+    previousAgent: fromAgent
+  });
+}
+```
+
+### 3. Session-Aware Greeting
+
+The greeting system automatically uses session state:
+
+```javascript
+const GreetingBuilder = require('./.aios-core/development/scripts/greeting-builder');
+const builder = new GreetingBuilder();
+
+// Session context is loaded automatically
+const greeting = await builder.buildGreeting(agentDef, { conversationHistory: [] });
+console.log(greeting);
+```
+
+## Session State Structure
+
+```json
+{
+  "sessionType": "workflow",
+  "currentAgent": "dev",
+  "previousAgent": "qa",
+  "commandHistory": [
+    {
+      "command": "review",
+      "agent": "qa",
+      "timestamp": 1234567890,
+      "success": true
+    },
+    {
+      "command": "apply-qa-fixes",
+      "agent": "dev",
+      "timestamp": 1234567900,
+      "success": true
+    }
+  ],
+  "agentTransitions": [
+    {
+      "from": "qa",
+      "to": "dev",
+      "timestamp": 1234567895
+    }
+  ],
+  "createdAt": 1234567800,
+  "lastUpdated": 1234567900
+}
+```
+
+## Session Types
+
+### New Session
+- **Criteria:** No command history
+- **Greeting:** Full introduction, all commands, project status
+- **Use Case:** First interaction in conversation
+
+### Existing Session
+- **Criteria:** 1-2 commands in history
+- **Greeting:** Quick commands only, abbreviated status
+- **Use Case:** User returning to same agent
+
+### Workflow Session
+- **Criteria:** 3+ commands OR agent transitions
+- **Greeting:** Minimal presentation, workflow suggestions
+- **Use Case:** Multi-agent collaboration flow
+
+## Implementation Checklist
+
+### Phase 1: Core Integration (Story 6.1.4)
+- [x] Create `command-execution-hook.js`
+- [x] Update `generate-greeting.js` to load session
+- [x] Modify `greeting-builder.js` to adapt to session type
+- [ ] Document pattern (this file)
+
+### Phase 2: Agent Integration (Future)
+- [ ] Wrap QA commands with session updates
+- [ ] Wrap Dev commands with session updates
+- [ ] Wrap PM/PO/SM commands with session updates
+- [ ] Add agent transition tracking to `/AIOS/agents/*` commands
+
+### Phase 3: Advanced Features (Future)
+- [ ] Workflow pattern detection (e.g., "QA → Dev → QA" cycle)
+- [ ] Smart command suggestions based on history
+- [ ] Session persistence across conversations
+- [ ] Analytics dashboard for common workflows
+
+## Usage Examples
+
+### Example 1: Single Agent Session
+
+```javascript
+// First activation
+await updateSessionAfterCommand('dev', 'agent-activation');
+// → sessionType: 'new'
+
+// Execute command
+await updateSessionAfterCommand('dev', 'develop-yolo');
+// → sessionType: 'existing'
+
+// Next activation shows abbreviated greeting
+const GreetingBuilder = require('./.aios-core/development/scripts/greeting-builder');
+const builder = new GreetingBuilder();
+const greeting = await builder.buildGreeting(devAgent, { conversationHistory });
+// Uses 'existing' session type
+```
+
+### Example 2: Multi-Agent Workflow
+
+```javascript
+// QA reviews code
+await updateSessionAfterCommand('qa', 'review');
+// → sessionType: 'existing'
+
+// QA finds issues
+await updateSessionAfterCommand('qa', 'gate');
+// → sessionType: 'existing'
+
+// Switch to Dev
+await updateSessionAfterCommand('dev', 'agent-activation', {
+  previousAgent: 'qa'
+});
+// → sessionType: 'workflow' (agent transition detected)
+
+// Dev applies fixes
+await updateSessionAfterCommand('dev', 'apply-qa-fixes');
+// → sessionType: 'workflow'
+
+// Next greeting shows workflow context
+const GreetingBuilder = require('./.aios-core/development/scripts/greeting-builder');
+const builder = new GreetingBuilder();
+const greeting = await builder.buildGreeting(devAgent, { conversationHistory });
+// Includes: "Continuing from @qa review..."
+```
+
+## Performance Considerations
+
+### Session File Location
+- **Path:** `.aios-core/.session/current-session.json`
+- **Size:** ~1-2KB (with history limit)
+- **I/O:** Read on greeting, write after command
+- **Impact:** <10ms per operation
+
+### Caching Strategy
+Session state is not cached (always fresh reads) to ensure accuracy across:
+- Multiple terminal sessions
+- Concurrent agent activations
+- Manual session edits
+
+### Error Handling
+All session operations are non-blocking:
+- Failed reads → Default to 'new' session
+- Failed writes → Log warning, continue execution
+- Corrupted JSON → Reset to empty session
+
+## Testing
+
+### Unit Tests
+```bash
+node tests/unit/command-execution-hook.test.js
+```
+
+### Integration Tests
+```bash
+node tests/integration/session-workflow.test.js
+```
+
+### Manual Testing
+```bash
+# Clear session
+rm .aios-core/.session/current-session.json
+
+# Test new session greeting
+node .aios-core/development/scripts/test-greeting-system.js
+
+# Simulate command
+node -e "require('./.aios-core/scripts/command-execution-hook').updateSessionAfterCommand('dev', 'develop-yolo')"
+
+# Test existing session (command history exists)
+node .aios-core/development/scripts/test-greeting-system.js
+```
+
+## Troubleshooting
+
+### Session Not Updating
+**Symptom:** Greetings always show "new" session
+**Solution:** Check session file permissions and path
+
+```bash
+ls -la .aios-core/.session/
+cat .aios-core/.session/current-session.json
+```
+
+### Wrong Session Type
+**Symptom:** Workflow session detected too early/late
+**Solution:** Adjust thresholds in `determineSessionType()`
+
+```javascript
+// In command-execution-hook.js
+function determineSessionType(commandHistory) {
+  if (commandHistory.length >= 3) { // Adjust this threshold
+    return 'workflow';
+  }
+  // ...
+}
+```
+
+### Commands Not Tracked
+**Symptom:** Command history empty
+**Solution:** Ensure commands call `updateSessionAfterCommand()`
+
+```javascript
+// Add to command wrapper
+await updateSessionAfterCommand(agentId, commandName);
+```
+
+## Migration Notes
+
+### From Inline Greeting Logic
+Old approach (deprecated):
+```javascript
+// STEP 3: Generate contextual greeting using inline logic
+// 1. Detect session type from conversation history...
+```
+
+New approach (Story 6.1.4):
+```javascript
+// STEP 3: Build intelligent greeting using GreetingBuilder
+const GreetingBuilder = require('./.aios-core/development/scripts/greeting-builder');
+const builder = new GreetingBuilder();
+const greeting = await builder.buildGreeting(agentDef, { conversationHistory });
+```
+
+### Backward Compatibility
+- Session updates are optional (system defaults to 'new')
+- Agents work without integration (degraded UX only)
+- No breaking changes to existing commands
+
+## Future Enhancements
+
+### Planned (Post-Story 6.1.4)
+1. **Workflow Pattern Library:** Detect common sequences (e.g., "review → fix → test")
+2. **Smart Suggestions:** Recommend next command based on history
+3. **Session Analytics:** Track which workflows are most common
+4. **Cross-Conversation Persistence:** Link sessions across Claude conversations
+
+### Under Consideration
+- Session branching for parallel workflows
+- Command rollback/undo tracking
+- Session export for debugging
+- Real-time session dashboard
+
+---
+
+**Related Documentation:**
+- [Story 6.1.4 Implementation](../../stories/aios migration/story-6.1.4.md)
+- [Agent Configuration Guide](../config/agent-config-requirements.yaml)
+- [Greeting System Architecture](./greeting-system-architecture.md)
+
+**Last Updated:** 2025-01-18 (Story 6.1.4)
+

package/.aios-core/core/docs/template-syntax.md

@@ -0,0 +1,267 @@
+# Template Variable Syntax Guide
+
+## Overview
+
+The Synkra AIOS template system uses a simple yet powerful variable substitution syntax that allows for dynamic content generation in agents, tasks, and workflows.
+
+## Basic Variable Substitution
+
+Variables are enclosed in double curly braces:
+
+```
+{{VARIABLE_NAME}}
+```
+
+### Example:
+```yaml
+agent:
+  name: {{AGENT_NAME}}
+  title: {{AGENT_TITLE}}
+  icon: {{AGENT_ICON}}
+```
+
+## Conditional Blocks
+
+Conditionals allow content to be included or excluded based on boolean variables:
+
+```
+{{#IF_VARIABLE}}
+Content to include if VARIABLE is true
+{{/IF_VARIABLE}}
+```
+
+### Example:
+```yaml
+{{#IF_SECURITY}}
+security:
+  level: {{SECURITY_LEVEL}}
+  requiresApproval: {{REQUIRES_APPROVAL}}
+{{/IF_SECURITY}}
+```
+
+## Loops
+
+Loops iterate over arrays to generate repeated content:
+
+```
+{{#EACH_ITEMS}}
+  - {{ITEM}}
+{{/EACH_ITEMS}}
+```
+
+### Loop Variables:
+- `{{ITEM}}` - Current item value
+- `{{INDEX}}` - Current item index (0-based)
+- `{{#IF_FIRST}}` - True for first item
+- `{{#IF_LAST}}` - True for last item
+- `{{#UNLESS_LAST}}` - True for all except last item
+
+### Example with Objects:
+```yaml
+commands:
+{{#EACH_COMMANDS}}
+  - name: {{COMMAND_NAME}}
+    description: {{COMMAND_DESCRIPTION}}
+    {{#IF_COMMAND_PARAMS}}
+    parameters:
+    {{#EACH_COMMAND_PARAMS}}
+      - {{PARAM_NAME}}: {{PARAM_TYPE}}
+    {{/EACH_COMMAND_PARAMS}}
+    {{/IF_COMMAND_PARAMS}}
+{{/EACH_COMMANDS}}
+```
+
+## Nested Structures
+
+Templates support nested conditionals and loops:
+
+```yaml
+{{#IF_WORKFLOWS}}
+workflows:
+{{#EACH_WORKFLOWS}}
+  - id: {{WORKFLOW_ID}}
+    name: {{WORKFLOW_NAME}}
+    {{#IF_WORKFLOW_STEPS}}
+    steps:
+    {{#EACH_WORKFLOW_STEPS}}
+      - name: {{STEP_NAME}}
+        task: {{STEP_TASK}}
+        {{#IF_STEP_CONDITION}}
+        condition: {{STEP_CONDITION}}
+        {{/IF_STEP_CONDITION}}
+    {{/EACH_WORKFLOW_STEPS}}
+    {{/IF_WORKFLOW_STEPS}}
+{{/EACH_WORKFLOWS}}
+{{/IF_WORKFLOWS}}
+```
+
+## Special Characters
+
+### Escaping Braces
+To include literal braces in your output, escape them with backslashes:
+
+```
+This is a literal \{{variable}} that won't be replaced
+```
+
+### Handling Quotes
+Variables containing quotes are automatically handled:
+
+```yaml
+description: "{{DESCRIPTION}}"
+```
+
+If `DESCRIPTION` contains quotes, they will be properly escaped.
+
+## Variable Naming Conventions
+
+1. **Use UPPERCASE_WITH_UNDERSCORES** for all variables
+2. **Conditional variables** should start with `IF_`
+3. **Loop variables** should start with `EACH_`
+4. **Boolean negation** uses `UNLESS_`
+
+### Standard Variable Prefixes:
+- `IF_` - Boolean conditions
+- `EACH_` - Array iterations
+- `UNLESS_` - Negative conditions
+- `HAS_` - Existence checks
+- `IS_` - State checks
+
+## Common Template Variables
+
+### Agent Templates:
+- `AGENT_NAME` - Lowercase hyphenated name
+- `AGENT_TITLE` - Human-readable title
+- `AGENT_ID` - Unique identifier
+- `AGENT_ICON` - Emoji or icon
+- `WHEN_TO_USE` - Usage description
+- `EACH_COMMANDS` - Command array
+- `IF_PERSONA` - Has persona configuration
+- `PERSONA_TONE` - Communication tone
+- `PERSONA_VERBOSITY` - Response detail level
+
+### Task Templates:
+- `TASK_ID` - Task identifier
+- `TASK_TITLE` - Task title
+- `AGENT_NAME` - Associated agent
+- `TASK_DESCRIPTION` - Task description
+- `EACH_STEPS` - Process steps
+- `EACH_PREREQUISITES` - Requirements
+- `EACH_INPUTS` - Input parameters
+
+### Workflow Templates:
+- `WORKFLOW_ID` - Workflow identifier
+- `WORKFLOW_NAME` - Workflow name
+- `WORKFLOW_TYPE` - sequential/parallel
+- `EACH_STEPS` - Workflow steps
+- `TRIGGER_TYPE` - Trigger mechanism
+
+## Advanced Features
+
+### Conditional with Defaults
+```yaml
+priority: {{#IF_PRIORITY}}{{PRIORITY}}{{/IF_PRIORITY}}{{#UNLESS_PRIORITY}}medium{{/UNLESS_PRIORITY}}
+```
+
+### Complex Object Arrays
+```yaml
+{{#EACH_COMPONENTS}}
+- type: {{COMPONENT_TYPE}}
+  name: {{COMPONENT_NAME}}
+  {{#IF_COMPONENT_CONFIG}}
+  config:
+    {{#EACH_CONFIG_ITEMS}}
+    {{CONFIG_KEY}}: {{CONFIG_VALUE}}
+    {{/EACH_CONFIG_ITEMS}}
+  {{/IF_COMPONENT_CONFIG}}
+{{/EACH_COMPONENTS}}
+```
+
+### Preserving Indentation
+The template engine preserves indentation within loops:
+
+```yaml
+services:
+{{#EACH_SERVICES}}
+  - name: {{SERVICE_NAME}}
+    port: {{SERVICE_PORT}}
+    {{#IF_SERVICE_ENV}}
+    environment:
+    {{#EACH_SERVICE_ENV_VARS}}
+      {{ENV_KEY}}: {{ENV_VALUE}}
+    {{/EACH_SERVICE_ENV_VARS}}
+    {{/IF_SERVICE_ENV}}
+{{/EACH_SERVICES}}
+```
+
+## Best Practices
+
+1. **Always validate variable names** before template processing
+2. **Use meaningful variable names** that describe their content
+3. **Group related variables** with common prefixes
+4. **Document required vs optional variables** in templates
+5. **Test templates with edge cases** (empty arrays, missing values)
+
+## Error Handling
+
+The template engine handles errors gracefully:
+- Missing variables are left as-is: `{{MISSING_VAR}}`
+- Malformed conditionals are preserved in output
+- Empty arrays result in no output for that section
+- Null/undefined values are converted to empty strings
+
+## Examples
+
+### Complete Agent Template Example:
+```yaml
+# {{AGENT_TITLE}}
+
+**Agent ID:** {{AGENT_ID}}  
+**Agent Name:** {{AGENT_NAME}}
+
+## When to Use
+{{WHEN_TO_USE}}
+
+## Icon
+{{AGENT_ICON}}
+
+{{#IF_COMMANDS}}
+## Commands
+{{#EACH_COMMANDS}}
+- `{{COMMAND_NAME}}`: {{COMMAND_DESCRIPTION}}
+{{/EACH_COMMANDS}}
+{{/IF_COMMANDS}}
+
+{{#IF_PERSONA}}
+## Persona
+**Tone:** {{PERSONA_TONE}}  
+**Verbosity:** {{PERSONA_VERBOSITY}}
+{{#IF_PERSONA_INSTRUCTIONS}}
+
+### Special Instructions
+{{PERSONA_INSTRUCTIONS}}
+{{/IF_PERSONA_INSTRUCTIONS}}
+{{/IF_PERSONA}}
+
+{{#IF_SECURITY}}
+## Security Configuration
+**Level:** {{SECURITY_LEVEL}}  
+**Requires Approval:** {{REQUIRES_APPROVAL}}
+{{/IF_SECURITY}}
+```
+
+## Troubleshooting
+
+### Common Issues:
+
+1. **Variables not replaced**: Check for typos in variable names
+2. **Conditionals not working**: Ensure closing tags match opening tags
+3. **Loops producing no output**: Verify array variable exists and has items
+4. **Indentation issues**: Check that loop content maintains consistent spacing
+5. **Escaped characters appearing**: Use double backslashes for literal output
+
+### Debug Mode:
+Enable template debugging by setting `DEBUG_TEMPLATES=true` to see:
+- Variable resolution process
+- Conditional evaluation
+- Loop iteration details