unraid-docker-manager/.planning/phases/10-workflow-modularization/10-03-PLAN.md

---
phase: 10-workflow-modularization
plan: 03
type: execute
wave: 2
depends_on: [10-01]
files_modified: [n8n-workflow.json, n8n-container-actions.json]
autonomous: true

must_haves:
  truths:
    - "Container start via text and inline works"
    - "Container stop via text and inline works"
    - "Container restart via text and inline works"
    - "Simple actions exist in one place (sub-workflow)"
  artifacts:
    - path: "n8n-container-actions.json"
      provides: "Container actions sub-workflow (start/stop/restart)"
      contains: "executeWorkflowTrigger"
    - path: "n8n-workflow.json"
      provides: "Main workflow calling actions sub-workflow"
      contains: "executeWorkflow"
  key_links:
    - from: "n8n-workflow.json"
      to: "n8n-container-actions.json"
      via: "Execute Sub-workflow node"
      pattern: "executeWorkflow.*container-actions"
---

<objective>
Extract container simple actions (start/stop/restart) into a dedicated sub-workflow.

Purpose: Like the update flow, start/stop/restart actions are handled in both text command and callback paths. Extracting to a sub-workflow creates a single source of truth for container state changes and supports MOD-01/MOD-02 requirements.

Output: New container-actions sub-workflow JSON file and updated main workflow that calls it from both text and callback paths.
</objective>

<execution_context>
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/10-workflow-modularization/10-RESEARCH.md
@.planning/phases/10-workflow-modularization/10-01-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create container-actions sub-workflow</name>
  <files>n8n-container-actions.json</files>
  <action>
Create a new sub-workflow file `n8n-container-actions.json` that encapsulates container start/stop/restart operations.

**Input contract (Execute Sub-workflow Trigger with defined fields):**
```json
{
  "containerId": "string - Docker container ID",
  "containerName": "string - Container name for messages",
  "action": "string - 'start' | 'stop' | 'restart'",
  "chatId": "number - Telegram chat ID",
  "messageId": "number - Message ID for inline edits (0 for text mode)",
  "responseMode": "string - 'text' or 'inline'"
}
```

**Flow to implement:**
1. Route based on action type (Switch node)
2. For each action:
   - Call Docker API endpoint (/containers/{id}/start, /stop, /restart)
   - Handle success response
   - Handle error response
3. Format result message
4. Return result (or send message directly if simpler)

**Output contract:**
```json
{
  "success": "boolean",
  "message": "string - Result message for user",
  "action": "string - Which action was performed",
  "containerName": "string"
}
```

**Implementation notes:**
- Use "Define using fields" schema type for input contract
- Stop and restart require confirmation in the caller (main workflow handles confirmation dialogs)
- This sub-workflow executes the action AFTER confirmation is received
- Include proper error handling for API failures
- Message formatting should match existing bot style (emoji + container name + result)
  </action>
  <verify>
- JSON file is valid: `python3 -c "import json; json.load(open('n8n-container-actions.json'))"`
- Contains "executeWorkflowTrigger" node
- Has proper input schema with all 6 fields
- Has Switch node routing to start/stop/restart paths
  </verify>
  <done>Container actions sub-workflow created with proper input/output contracts</done>
</task>

<task type="auto">
  <name>Task 2: Wire main workflow to use actions sub-workflow</name>
  <files>n8n-workflow.json</files>
  <action>
Modify the main workflow to call the container-actions sub-workflow for start/stop/restart operations.

**Changes needed:**

1. **Text command path (immediate actions - start/restart):**
   - Find where text commands route to start/restart handlers
   - Replace inline action execution with:
     a. Code node to prepare sub-workflow input
     b. Execute Sub-workflow node pointing to container-actions workflow
   - Keep confirmation handling in main workflow (stop still needs confirmation)

2. **Text command path (stop with confirmation):**
   - Keep confirmation dialog handling in main workflow
   - After confirmation received, call sub-workflow with action='stop'

3. **Callback/inline path (immediate actions):**
   - Find where callback routes to start/restart handlers
   - Replace inline execution with Execute Sub-workflow call

4. **Callback/inline path (stop with confirmation):**
   - Keep confirmation keyboard generation in main workflow
   - After confirmation callback received, call sub-workflow with action='stop'

5. **Batch action path:**
   - Find where batch operations execute individual actions
   - Route through the sub-workflow for consistency

**Key principle:** Confirmation dialogs stay in main workflow. Only the actual Docker API call moves to sub-workflow.

**Execute Sub-workflow node configuration:**
```json
{
  "parameters": {
    "source": "database",
    "workflowId": "<will be set after import>",
    "mode": "once",
    "options": {
      "waitForSubWorkflow": true
    }
  },
  "type": "n8n-nodes-base.executeWorkflow"
}
```
  </action>
  <verify>
- Main workflow JSON is valid
- Contains "executeWorkflow" node(s) for action paths
- Confirmation dialogs still work (handled in main workflow)
  </verify>
  <done>Main workflow updated to call container-actions sub-workflow</done>
</task>

<task type="auto">
  <name>Task 3: Deploy and verify action functionality</name>
  <files>n8n-workflow.json, n8n-container-actions.json</files>
  <action>
Deploy the actions sub-workflow and updated main workflow, then verify all action paths work.

**Deployment steps:**
1. Import container-actions sub-workflow to n8n via API
2. Note the workflow ID assigned by n8n
3. Update main workflow's Execute Sub-workflow node(s) with correct workflow ID
4. Deploy main workflow update to n8n via API

**Verification tests:**

1. **Text command actions:**
   - "start <container>" - Should start and confirm
   - "stop <container>" - Should prompt for confirmation, then stop
   - "restart <container>" - Should restart and confirm

2. **Inline keyboard actions:**
   - Use /status and select a container
   - Test Start button (on stopped container)
   - Test Stop button (should show confirmation)
   - Test Restart button

3. **Batch actions:**
   - Select 2 containers for batch stop
   - Verify confirmation and execution work
  </action>
  <verify>
- Sub-workflow imported and has valid ID in n8n
- Main workflow deployed with correct sub-workflow reference
- Text commands work: start, stop (with confirmation), restart
- Inline buttons work: Start, Stop (with confirmation), Restart
- Batch operations work for start/stop/restart
  </verify>
  <done>Actions sub-workflow deployed and all action paths verified working</done>
</task>

</tasks>

<verification>
1. n8n-container-actions.json exists and is valid JSON
2. Sub-workflow has proper Execute Sub-workflow Trigger with input schema
3. Main workflow contains Execute Sub-workflow nodes for actions
4. Text command "start <container>" works
5. Text command "stop <container>" with confirmation works
6. Text command "restart <container>" works
7. Inline keyboard Start/Stop/Restart buttons work
8. Stop confirmation dialog works in both text and inline modes
9. Batch start/stop/restart operations work
</verification>

<success_criteria>
- Container actions (start/stop/restart) exist in ONE place (sub-workflow)
- Both text and inline action paths use the sub-workflow
- Confirmation dialogs still function correctly
- All action functionality works as before
</success_criteria>

<output>
After completion, create `.planning/phases/10-workflow-modularization/10-03-SUMMARY.md`
</output>