create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/workflows/README.md

@@ -0,0 +1,88 @@
+# AIOX Workflows
+
+This directory contains workflow definitions for the Synkra AIOX framework. Workflows define multi-step processes that can be executed by AIOX agents.
+
+## Available Workflows
+
+### Development Workflows
+- **brownfield-discovery.yaml** - Comprehensive technical debt assessment for existing projects
+- **brownfield-fullstack.yaml** - Workflow for existing full-stack projects
+- **brownfield-service.yaml** - Workflow for existing service/backend projects
+- **brownfield-ui.yaml** - Workflow for existing UI/frontend projects
+- **greenfield-fullstack.yaml** - Workflow for new full-stack projects
+- **greenfield-service.yaml** - Workflow for new service/backend projects
+- **greenfield-ui.yaml** - Workflow for new UI/frontend projects
+
+### Configuration Workflows
+
+## Setup Environment Workflow
+
+The `setup-environment` workflow helps developers configure their IDE for optimal AIOX development experience.
+
+### Features
+- Backs up existing IDE configurations
+- Applies AIOX-specific development rules
+- Verifies GitHub CLI installation and authentication
+- Provides clear feedback throughout the process
+
+### Usage
+
+From the aiox-master agent:
+```
+@aiox-master
+*setup-environment
+```
+
+Or directly via npm:
+```bash
+npm run setup:environment
+```
+
+### What It Does
+2. **GitHub CLI Check** - Ensures GitHub CLI is installed and authenticated
+3. **Backup Creation** - Saves existing rules before making changes
+4. **Rule Application** - Copies AIOX-specific rules to appropriate locations
+5. **Verification** - Confirms successful setup
+
+### IDE Rule Locations
+- **Cursor**: `.cursorules`
+- **Claude Code**: `.claude/CLAUDE.md`
+
+### Requirements
+- Node.js 18+
+- One or more supported IDEs installed
+- GitHub CLI (recommended)
+
+## Creating New Workflows
+
+Workflows are defined in YAML format. See existing workflows for examples.
+
+### Workflow Structure
+```yaml
+workflow:
+  id: unique-workflow-id
+  name: Human-readable name
+  description: What this workflow does
+  type: configuration|development|deployment
+  metadata:
+    elicit: true  # If user interaction required
+    confirmation_required: true
+  sequence:
+    - step: step_slug
+      id: step-1
+      agent: responsible-agent
+      action: What this step does
+      next: next-step-id
+
+  # Optional compatibility metadata (non-executable)
+  phases:
+    - phase_1: Discovery
+    - phase_2: Execution
+```
+
+## Best Practices
+1. Keep workflows focused on a single objective
+2. Include error handling for each step
+3. Provide clear user feedback
+4. Make workflows idempotent when possible
+5. Document prerequisites and outcomes

package/template/.aiox-core/development/workflows/auto-worktree.yaml

@@ -0,0 +1,421 @@
+workflow:
+  id: auto-worktree
+  name: Auto-Worktree - Automatic Isolated Development Environment
+  version: "1.0"
+  description: >-
+    Automatically creates and manages isolated worktrees for story development.
+    Triggered when @dev starts working on a story, ensuring parallel development
+    capability and clean isolation between different development tasks.
+
+    Part of the Auto-Claude ADE (Autonomous Development Engine) infrastructure.
+
+  type: automation
+  project_types:
+    - aiox-development
+    - autonomous-development
+    - parallel-development
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              TRIGGER CONFIGURATION
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  triggers:
+    # Primary trigger: When @dev starts a story
+    - event: story_started
+      agent: dev
+      condition: projectConfig.autoWorktree.enabled === true
+      action: create_worktree
+
+    # Secondary trigger: When @po assigns a story
+    - event: story_assigned
+      agent: po
+      condition: projectConfig.autoWorktree.createOnAssign === true
+      action: create_worktree
+
+    # Manual trigger: Explicit command
+    - event: command
+      command: "*auto-worktree"
+      action: interactive_flow
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              CONFIGURATION
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  config:
+    # Enable automatic worktree creation
+    enabled: true
+
+    # Create worktree when story is assigned (before development starts)
+    createOnAssign: false
+
+    # Automatically switch to worktree after creation
+    autoSwitch: true
+
+    # Show worktree creation summary
+    verbose: true
+
+    # Cleanup stale worktrees before creating new one
+    autoCleanup: false
+
+    # Maximum worktrees before requiring cleanup
+    maxWorktrees: 10
+
+    # Days before worktree is considered stale
+    staleDays: 30
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              PRE-FLIGHT CHECKS
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  pre_flight:
+    enabled: true
+
+    checks:
+      - id: git_repo
+        description: Verify git repository
+        command: git rev-parse --is-inside-work-tree
+        blocking: true
+        error: "Not a git repository. Auto-worktree requires git."
+
+      - id: worktree_support
+        description: Verify git worktree support
+        command: git worktree list
+        blocking: true
+        error: "Git worktree not supported. Requires git >= 2.5."
+
+      - id: worktree_manager
+        description: Verify WorktreeManager available
+        file_exists: .aiox-core/infrastructure/scripts/worktree-manager.js
+        blocking: true
+        error: "WorktreeManager not found. AIOX infrastructure incomplete."
+
+      - id: check_limit
+        description: Check worktree limit not exceeded
+        script: |
+          const WorktreeManager = require('./.aiox-core/infrastructure/scripts/worktree-manager.js');
+          const manager = new WorktreeManager();
+          const count = await manager.getCount();
+          return count.total < manager.maxWorktrees;
+        blocking: false
+        warning: "Approaching worktree limit. Consider cleanup."
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              WORKFLOW SEQUENCE
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  sequence:
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 1: EXTRACT STORY CONTEXT
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: extract_story_context
+      phase: 1
+      phase_name: "Extract Context"
+      action: extract_story_info
+
+      description: >-
+        Extract story information from the trigger context.
+        Determines the story ID to use for worktree naming.
+
+      script: |
+        // Extract story ID from various sources
+        function extractStoryId(context) {
+          // From explicit parameter
+          if (context.storyId) return context.storyId;
+
+          // From story file path
+          if (context.storyFile) {
+            const match = context.storyFile.match(/story-(\d+\.\d+)/);
+            if (match) return match[1];
+          }
+
+          // From current task
+          if (context.currentTask?.storyId) return context.currentTask.storyId;
+
+          // From git branch (if following convention)
+          const branch = await execGit(['branch', '--show-current']);
+          const branchMatch = branch.match(/story[-\/](\d+\.\d+)/i);
+          if (branchMatch) return branchMatch[1];
+
+          return null;
+        }
+
+        const storyId = extractStoryId(context);
+        if (!storyId) {
+          throw new Error('Could not determine story ID. Please provide explicitly.');
+        }
+
+        return { storyId };
+
+      outputs:
+        - storyId
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 2: CHECK EXISTING WORKTREE
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: check_existing
+      phase: 2
+      phase_name: "Check Existing"
+      action: check_worktree_exists
+
+      description: >-
+        Check if a worktree already exists for this story.
+        If exists, skip creation and optionally switch to it.
+
+      script: |
+        const WorktreeManager = require('./.aiox-core/infrastructure/scripts/worktree-manager.js');
+        const manager = new WorktreeManager();
+        const exists = await manager.exists(storyId);
+
+        if (exists) {
+          const info = await manager.get(storyId);
+          return {
+            exists: true,
+            worktree: info,
+            action: config.autoSwitch ? 'switch' : 'skip'
+          };
+        }
+
+        return { exists: false, action: 'create' };
+
+      outputs:
+        - exists
+        - worktree
+        - action
+
+      on_exists:
+        log: "Worktree already exists for story {storyId}"
+        skip_to: switch_worktree
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 3: AUTO-CLEANUP (OPTIONAL)
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: auto_cleanup
+      phase: 3
+      phase_name: "Auto Cleanup"
+      action: cleanup_stale_worktrees
+      condition: config.autoCleanup === true
+
+      description: >-
+        Automatically clean up stale worktrees before creating a new one.
+        Only runs if autoCleanup is enabled in config.
+
+      script: |
+        const WorktreeManager = require('./.aiox-core/infrastructure/scripts/worktree-manager.js');
+        const manager = new WorktreeManager();
+        const removed = await manager.cleanupStale();
+
+        return {
+          cleaned: removed.length,
+          removedIds: removed
+        };
+
+      outputs:
+        - cleaned
+        - removedIds
+
+      on_cleanup:
+        log: "Cleaned up {cleaned} stale worktrees"
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 4: CREATE WORKTREE
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: create_worktree
+      phase: 4
+      phase_name: "Create Worktree"
+      action: create_isolated_worktree
+
+      description: >-
+        Create a new isolated worktree for the story.
+        Creates branch auto-claude/{storyId} and working directory.
+
+      task: create-worktree.md
+
+      inputs:
+        story_id: "{storyId}"
+
+      script: |
+        const WorktreeManager = require('./.aiox-core/infrastructure/scripts/worktree-manager.js');
+        const manager = new WorktreeManager();
+
+        try {
+          const worktree = await manager.create(storyId);
+          return {
+            success: true,
+            worktree: worktree,
+            path: worktree.path,
+            branch: worktree.branch
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: error.message
+          };
+        }
+
+      outputs:
+        - success
+        - worktree
+        - path
+        - branch
+        - error
+
+      on_success:
+        log: "Created worktree at {path}"
+
+      on_failure:
+        action: halt
+        error: "Failed to create worktree: {error}"
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 5: SWITCH TO WORKTREE (OPTIONAL)
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: switch_worktree
+      phase: 5
+      phase_name: "Switch Context"
+      action: switch_to_worktree
+      condition: config.autoSwitch === true
+
+      description: >-
+        Automatically switch working context to the new worktree.
+        Updates shell environment and notifies user.
+
+      script: |
+        const worktreePath = worktree?.path || path;
+
+        // Note: Cannot actually change parent process cwd
+        // Instead, provide instructions and set environment hint
+
+        console.log(`\n📂 Switch to worktree:`);
+        console.log(`   cd ${worktreePath}\n`);
+
+        // Set environment variable for shell integration
+        process.env.AIOX_WORKTREE = worktreePath;
+        process.env.AIOX_STORY = storyId;
+
+        return {
+          worktreePath,
+          instructions: `cd ${worktreePath}`
+        };
+
+      outputs:
+        - worktreePath
+        - instructions
+
+    # ═════════════════════════════════════════════════════════════════════════════════
+    # STEP 6: DISPLAY SUMMARY
+    # ═════════════════════════════════════════════════════════════════════════════════
+
+    - step: display_summary
+      phase: 6
+      phase_name: "Summary"
+      action: show_summary
+      condition: config.verbose === true
+
+      description: >-
+        Display workflow completion summary with worktree details
+        and next steps for the developer.
+
+      template: |
+        ╔══════════════════════════════════════════════════════════════╗
+        ║  🌲 Auto-Worktree Complete                                   ║
+        ╚══════════════════════════════════════════════════════════════╝
+
+        Story:      {storyId}
+        Worktree:   {worktree.path}
+        Branch:     {worktree.branch}
+        Status:     {worktree.status}
+
+        ─────────────────────────────────────────────────────────────────
+        📌 Quick Reference:
+
+        Navigate:   cd {worktree.path}
+        Status:     *list-worktrees
+        Merge:      *merge-worktree {storyId}
+        Remove:     *remove-worktree {storyId}
+
+        ─────────────────────────────────────────────────────────────────
+        💡 You are now working in an isolated environment.
+           Changes here won't affect the main branch until merged.
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              WORKFLOW COMPLETION
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  completion:
+    success_message: "Worktree ready for story {storyId}"
+
+    outputs:
+      - storyId
+      - worktree
+      - path
+      - branch
+
+    next_steps:
+      - "Navigate to worktree: cd {path}"
+      - "Start development in isolation"
+      - "When done: *merge-worktree {storyId}"
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              ERROR HANDLING
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  error_handling:
+    max_worktrees_reached:
+      message: "Maximum worktrees limit ({maxWorktrees}) reached"
+      suggestion: "Run *cleanup-worktrees to remove stale worktrees"
+      action: halt
+
+    worktree_creation_failed:
+      message: "Failed to create worktree"
+      suggestion: "Check git status and try again"
+      action: halt
+
+    story_id_not_found:
+      message: "Could not determine story ID"
+      suggestion: "Provide story ID explicitly: *auto-worktree STORY-42"
+      action: prompt
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              INTEGRATION
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  integration:
+    # Integration with @dev agent
+    dev_agent:
+      hook: on_story_start
+      action: trigger_workflow
+      pass_context: true
+
+    # Integration with project status
+    project_status:
+      update_on_create: true
+      field: activeWorktree
+
+    # Integration with status.json
+    status_json:
+      track_worktrees: true
+      include_in_context: true
+
+  # ═══════════════════════════════════════════════════════════════════════════════════
+  #                              METADATA
+  # ═══════════════════════════════════════════════════════════════════════════════════
+
+  metadata:
+    story: "1.4"
+    epic: "Epic 1 - Worktree Manager"
+    created: "2026-01-28"
+    author: "@architect (Aria)"
+    dependencies:
+      - worktree-manager.js
+      - create-worktree.md
+    tags:
+      - automation
+      - worktree
+      - isolation
+      - ade