maestro-flow 0.5.31 → 0.5.33

package/.agy/skills/skill-generator/templates/autonomous-action.md

@@ -0,0 +1,330 @@
+# Autonomous Action Template
+
+Template for action files in Autonomous execution mode.
+
+## Purpose
+
+Generate Action files for Autonomous execution mode, defining independent executable action units.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 3 (Phase Generation) | Generated when `config.execution_mode === 'autonomous'` |
+| Generation Trigger | Generate one action file for each `config.autonomous_config.actions` |
+| Output Location | `.claude/skills/{skill-name}/phases/actions/{action-id}.md` |
+
+---
+
+## Template Structure
+
+```markdown
+# Action: {{action_name}}
+
+{{action_description}}
+
+## Purpose
+
+{{purpose}}
+
+## Preconditions
+
+{{preconditions_list}}
+
+## Scripts
+
+\`\`\`yaml
+# Declare scripts used in this action (optional)
+# - script-id        # Corresponds to scripts/script-id.py or .sh
+\`\`\`
+
+## Execution
+
+\`\`\`javascript
+async function execute(state) {
+  {{execution_code}}
+
+  // Script execution example
+  // const result = await ExecuteScript('script-id', { input: state.context.data });
+  // if (!result.success) throw new Error(result.stderr);
+}
+\`\`\`
+
+## State Updates
+
+\`\`\`javascript
+return {
+  stateUpdates: {
+    {{state_updates}}
+  }
+};
+\`\`\`
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+{{error_handling_table}}
+
+## Next Actions (Hints)
+
+{{next_actions_hints}}
+```
+
+## Variable Descriptions
+
+| Variable | Description |
+|----------|-------------|
+| `{{action_name}}` | Action name |
+| `{{action_description}}` | Action description |
+| `{{purpose}}` | Detailed purpose |
+| `{{preconditions_list}}` | List of preconditions |
+| `{{execution_code}}` | Execution code |
+| `{{state_updates}}` | State updates |
+| `{{error_handling_table}}` | Error handling table |
+| `{{next_actions_hints}}` | Next action hints |
+
+## Action Lifecycle
+
+```
+State-driven execution flow:
+
+  state.status === 'pending'
+       |
+       v
+  +-- Init --+          <- 1 execution, environment preparation
+  | Create working directory
+  | Initialize context
+  | status -> running
+  +----+----+
+       |
+       v
+  +-- CRUD Loop --+     <- N iterations, core business
+  | Orchestrator selects action  |    List / Create / Edit / Delete
+  | execute(state)  |    Shared pattern: collect input -> operate context.items -> return updates
+  | Update state
+  +----+----+
+       |
+       v
+  +-- Complete --+      <- 1 execution, save results
+  | Serialize output
+  | status -> completed
+  +----------+
+
+Shared state structure:
+  state.status          -> 'pending' | 'running' | 'completed'
+  state.context.items   -> Business data array
+  state.completed_actions -> List of executed action IDs
+```
+
+## Action Type Templates
+
+### 1. Initialize Action (Init)
+
+**Trigger condition**: `state.status === 'pending'`, executes once
+
+```markdown
+# Action: Initialize
+
+Initialize Skill execution state.
+
+## Purpose
+
+Set initial state, prepare execution environment.
+
+## Preconditions
+
+- [ ] state.status === 'pending'
+
+## Execution
+
+\`\`\`javascript
+async function execute(state) {
+  run_command(\`mkdir -p "\${workDir}"\`);
+
+  return {
+    stateUpdates: {
+      status: 'running',
+      started_at: new Date().toISOString(),
+      context: { items: [], metadata: {} }
+    }
+  };
+}
+\`\`\`
+
+## Next Actions
+
+- Success: Enter main processing loop (Orchestrator selects first CRUD action)
+- Failure: action-abort
+```
+
+### 2. CRUD Actions (List / Create / Edit / Delete)
+
+**Trigger condition**: `state.status === 'running'`, loop until user exits
+
+> Example shows Create action demonstrating shared pattern. List / Edit / Delete follow same structure with different execution logic and state update fields.
+
+```markdown
+# Action: Create Item
+
+Create new item.
+
+## Purpose
+
+Collect user input, append new record to context.items.
+
+## Preconditions
+
+- [ ] state.status === 'running'
+
+## Execution
+
+\`\`\`javascript
+async function execute(state) {
+  // 1. Collect input
+  const input = await ask_question({
+    questions: [{
+      question: "Please enter item name:",
+      header: "Name",
+      multiSelect: false,
+      options: [{ label: "Manual input", description: "Enter custom name" }]
+    }]
+  });
+
+  // 2. Operate context.items (core logic differs by action type)
+  const newItem = {
+    id: Date.now().toString(),
+    name: input["Name"],
+    status: 'pending',
+    created_at: new Date().toISOString()
+  };
+
+  // 3. Return state update
+  return {
+    stateUpdates: {
+      context: {
+        ...state.context,
+        items: [...(state.context.items || []), newItem]
+      },
+      last_action: 'create'
+    }
+  };
+}
+\`\`\`
+
+## Next Actions
+
+- Continue operations: Orchestrator selects next action based on state
+- User exit: action-complete
+```
+
+**Other CRUD Actions Differences:**
+
+| Action | Core Logic | Extra Preconditions | Key State Field |
+|--------|-----------|-------------------|-----------------|
+| List | `items.forEach(-> console.log)` | None | `current_view: 'list'` |
+| Create | `items.push(newItem)` | None | `last_created_id` |
+| Edit | `items.map(-> replace matching)` | `selected_item_id !== null` | `updated_at` |
+| Delete | `items.filter(-> exclude matching)` | `selected_item_id !== null` | Confirm dialog -> execute |
+
+### 3. Complete Action
+
+**Trigger condition**: User explicitly exits or termination condition met, executes once
+
+```markdown
+# Action: Complete
+
+Complete task and exit.
+
+## Purpose
+
+Serialize final state, end Skill execution.
+
+## Preconditions
+
+- [ ] state.status === 'running'
+
+## Execution
+
+\`\`\`javascript
+async function execute(state) {
+  write_to_file(\`\${workDir}/final-output.json\`, JSON.stringify(state.context, null, 2));
+
+  const summary = {
+    total_items: state.context.items?.length || 0,
+    duration: Date.now() - new Date(state.started_at).getTime(),
+    actions_executed: state.completed_actions.length
+  };
+
+  console.log(\`Task complete: \${summary.total_items} items, \${summary.actions_executed} operations\`);
+
+  return {
+    stateUpdates: {
+      status: 'completed',
+      completed_at: new Date().toISOString(),
+      summary
+    }
+  };
+}
+\`\`\`
+
+## Next Actions
+
+- None (terminal state)
+```
+
+## Generation Function
+
+```javascript
+function generateAction(actionConfig, skillConfig) {
+  return `# Action: ${actionConfig.name}
+
+${actionConfig.description || `Execute ${actionConfig.name} operation`}
+
+## Purpose
+
+${actionConfig.purpose || 'TODO: Describe detailed purpose of this action'}
+
+## Preconditions
+
+${actionConfig.preconditions?.map(p => `- [ ] ${p}`).join('\n') || '- [ ] No special preconditions'}
+
+## Execution
+
+\`\`\`javascript
+async function execute(state) {
+  // TODO: Implement action logic
+
+  return {
+    stateUpdates: {
+      completed_actions: [...state.completed_actions, '${actionConfig.id}']
+    }
+  };
+}
+\`\`\`
+
+## State Updates
+
+\`\`\`javascript
+return {
+  stateUpdates: {
+    // TODO: Define state updates
+${actionConfig.effects?.map(e => `    // Effect: ${e}`).join('\n') || ''}
+  }
+};
+\`\`\`
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Data validation failed | Return error, no state update |
+| Execution exception | Log error, increment error_count |
+
+## Next Actions (Hints)
+
+- Success: Orchestrator decides based on state
+- Failure: Retry or action-abort
+`;
+}
+```

package/.agy/skills/skill-generator/templates/autonomous-orchestrator.md

@@ -0,0 +1,312 @@
+
+## Sub-Agent Registration (Antigravity)
+
+Before any `invoke_subagent` call below, register each sub-agent type once per session by reading the system_prompt from `<agy-agents-dir>/<name>.md` and passing it to `define_subagent`. The `<agy-agents-dir>` is:
+- global install: `~/.gemini/antigravity-cli/agents/`
+- workspace install: `<project>/.agents/agents/`
+
+- `define_subagent(name="universal-executor", description="<from agents/universal-executor.md frontmatter>", system_prompt=<contents of agents/universal-executor.md body>, enable_write_tools=true, enable_mcp_tools=true, enable_subagent_tools=false)`
+
+**ConversationId tracking**: `invoke_subagent` returns a ConversationId per spawned instance. Subsequent `send_message(Recipient=<ConversationId>, Message=...)` calls require that ConversationId — never use the role name as the recipient.
+
+---
+# Autonomous Orchestrator Template
+
+Template for orchestrator file in Autonomous execution mode.
+
+## Purpose
+
+Generate Orchestrator file for Autonomous execution mode, responsible for state-driven action selection and execution loop.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| Phase 3 (Phase Generation) | Generated when `config.execution_mode === 'autonomous'` |
+| Generation Trigger | Create orchestrator logic to manage action selection and state updates |
+| Output Location | `.claude/skills/{skill-name}/phases/orchestrator.md` |
+
+---
+
+## Important Notes
+
+> **Phase 0 is mandatory prerequisite**: Before Orchestrator starts execution loop, Phase 0 specification review must be completed first.
+>
+> When generating Orchestrator, ensure:
+> 1. Phase 0 specification review step is included in SKILL.md
+> 2. Orchestrator validates specification has been reviewed before starting execution loop
+> 3. All Action files reference related specification documents
+> 4. Architecture Overview places Phase 0 before Orchestrator
+
+## Template Structure
+
+```markdown
+# Orchestrator
+
+## Role
+
+Select and execute next action based on current state.
+
+## State Management
+
+### Read State
+
+\`\`\`javascript
+const state = JSON.parse(view_file(\`${workDir}/state.json\`));
+\`\`\`
+
+### Update State
+
+\`\`\`javascript
+function updateState(updates) {
+  const state = JSON.parse(view_file(\`${workDir}/state.json\`));
+  const newState = {
+    ...state,
+    ...updates,
+    updated_at: new Date().toISOString()
+  };
+  write_to_file(\`${workDir}/state.json\`, JSON.stringify(newState, null, 2));
+  return newState;
+}
+\`\`\`
+
+## Decision Logic
+
+\`\`\`javascript
+function selectNextAction(state) {
+  // 1. Check termination conditions
+  {{termination_checks}}
+
+  // 2. Check error limit
+  if (state.error_count >= 3) {
+    return 'action-abort';
+  }
+
+  // 3. Action selection logic
+  {{action_selection_logic}}
+
+  // 4. Default completion
+  return 'action-complete';
+}
+\`\`\`
+
+## Execution Loop
+
+\`\`\`javascript
+async function runOrchestrator() {
+  console.log('=== Orchestrator Started ===');
+
+  let iteration = 0;
+  const MAX_ITERATIONS = 100;
+
+  while (iteration < MAX_ITERATIONS) {
+    iteration++;
+
+    // 1. Read current state
+    const state = JSON.parse(view_file(\`${workDir}/state.json\`));
+    console.log(\`[Iteration ${iteration}] Status: ${state.status}\`);
+
+    // 2. Select next action
+    const actionId = selectNextAction(state);
+
+    if (!actionId) {
+      console.log('No action selected, terminating.');
+      break;
+    }
+
+    console.log(\`[Iteration ${iteration}] Executing: ${actionId}\`);
+
+    // 3. Update state: current action
+    updateState({ current_action: actionId });
+
+    // 4. Execute action
+    try {
+      const actionPrompt = view_file(\`phases/actions/${actionId}.md\`);
+
+      const result = await invoke_subagent({
+        subagent_type: 'universal-executor',
+        run_in_background: false,
+        prompt: \`
+[STATE]
+\${JSON.stringify(state, null, 2)}
+
+[ACTION]
+\${actionPrompt}
+
+[RETURN]
+Return JSON with stateUpdates field.
+\`
+      });
+
+      const actionResult = JSON.parse(result);
+
+      // 5. Update state: action completed
+      updateState({
+        current_action: null,
+        completed_actions: [...state.completed_actions, actionId],
+        ...actionResult.stateUpdates
+      });
+
+    } catch (error) {
+      // Error handling
+      updateState({
+        current_action: null,
+        errors: [...state.errors, {
+          action: actionId,
+          message: error.message,
+          timestamp: new Date().toISOString()
+        }],
+        error_count: state.error_count + 1
+      });
+    }
+  }
+
+  console.log('=== Orchestrator Finished ===');
+}
+\`\`\`
+
+## Action Catalog
+
+| Action | Purpose | Preconditions |
+|--------|---------|---------------|
+{{action_catalog_table}}
+
+## Termination Conditions
+
+{{termination_conditions_list}}
+
+## Error Recovery
+
+| Error Type | Recovery Strategy |
+|------------|-------------------|
+| Action execution failed | Retry up to 3 times |
+| State inconsistency | Rollback to last stable state |
+| User abort | Save current state, allow recovery |
+```
+
+## Variable Descriptions
+
+| Variable | Description |
+|----------|-------------|
+| `{{termination_checks}}` | Termination condition check code |
+| `{{action_selection_logic}}` | Action selection logic code |
+| `{{action_catalog_table}}` | Action directory table |
+| `{{termination_conditions_list}}` | List of termination conditions |
+
+## Generation Function
+
+```javascript
+function generateOrchestrator(config) {
+  const actions = config.autonomous_config.actions;
+  const terminations = config.autonomous_config.termination_conditions || [];
+
+  // Generate termination checks
+  const terminationChecks = terminations.map(t => {
+    const checks = {
+      'user_exit': 'if (state.status === "user_exit") return null;',
+      'error_limit': 'if (state.error_count >= 3) return "action-abort";',
+      'task_completed': 'if (state.status === "completed") return null;',
+      'max_iterations': 'if (state.iteration_count >= 100) return "action-abort";'
+    };
+    return checks[t] || `if (state.${t}) return null;`;
+  }).join('\n  ');
+
+  // Generate action selection logic
+  const actionSelectionLogic = actions.map(action => {
+    if (!action.preconditions?.length) {
+      return `// ${action.name}: No preconditions, add selection logic manually`;
+    }
+    const conditions = action.preconditions.map(p => `state.${p}`).join(' && ');
+    return `if (${conditions}) return '${action.id}';`;
+  }).join('\n  ');
+
+  // Generate action catalog table
+  const actionCatalogTable = actions.map(a =>
+    `| [${a.id}](actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} |`
+  ).join('\n');
+
+  // Generate termination conditions list
+  const terminationConditionsList = terminations.map(t => `- ${t}`).join('\n');
+
+  return template
+    .replace('{{termination_checks}}', terminationChecks)
+    .replace('{{action_selection_logic}}', actionSelectionLogic)
+    .replace('{{action_catalog_table}}', actionCatalogTable)
+    .replace('{{termination_conditions_list}}', terminationConditionsList);
+}
+```
+
+## Orchestration Strategies
+
+### 1. Priority Strategy
+
+Select action by predefined priority:
+
+```javascript
+const PRIORITY = ['action-init', 'action-process', 'action-review', 'action-complete'];
+
+function selectByPriority(state, availableActions) {
+  for (const actionId of PRIORITY) {
+    if (availableActions.includes(actionId) && checkPreconditions(actionId, state)) {
+      return actionId;
+    }
+  }
+  return null;
+}
+```
+
+### 2. User-Driven Strategy
+
+Ask user to select next action:
+
+```javascript
+async function selectByUser(state, availableActions) {
+  const response = await ask_question({
+    questions: [{
+      question: "Select next operation:",
+      header: "Operations",
+      multiSelect: false,
+      options: availableActions.map(a => ({
+        label: a.name,
+        description: a.description
+      }))
+    }]
+  });
+
+  return availableActions.find(a => a.name === response["Operations"])?.id;
+}
+```
+
+### 3. State-Driven Strategy
+
+Fully automatic decision based on state:
+
+```javascript
+function selectByState(state) {
+  // Initialization
+  if (state.status === 'pending') return 'action-init';
+
+  // Has pending items
+  if (state.pending_items?.length > 0) return 'action-process';
+
+  // Needs review
+  if (state.needs_review) return 'action-review';
+
+  // Completed
+  return 'action-complete';
+}
+```
+
+## State Machine Example
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> running: action-init
+    running --> running: action-process
+    running --> running: action-review
+    running --> completed: action-complete
+    running --> failed: action-abort
+    completed --> [*]
+    failed --> [*]
+```