From 25dd3ab2d2793a3ccf7f60b8f9c3b5796a358b56 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 4 Feb 2026 20:20:29 -0500 Subject: [PATCH] docs(10.1): create phase plan Phase 10.1: Aggressive Workflow Modularization - 5 plan(s) in 3 wave(s) - Wave 1: Foundation (rename files, analyze boundaries, user approval) - Wave 2: 3 parallel extractions (batch-ui, status, confirmation) - Wave 3: Integration verification and UAT - Ready for execution Co-Authored-By: Claude Opus 4.5 --- .planning/ROADMAP.md | 14 +- .../10.1-01-PLAN.md | 173 +++++++++++++ .../10.1-02-PLAN.md | 217 ++++++++++++++++ .../10.1-03-PLAN.md | 201 +++++++++++++++ .../10.1-04-PLAN.md | 204 +++++++++++++++ .../10.1-05-PLAN.md | 239 ++++++++++++++++++ 6 files changed, 1043 insertions(+), 5 deletions(-) create mode 100644 .planning/phases/10.1-aggressive-workflow-modularization/10.1-01-PLAN.md create mode 100644 .planning/phases/10.1-aggressive-workflow-modularization/10.1-02-PLAN.md create mode 100644 .planning/phases/10.1-aggressive-workflow-modularization/10.1-03-PLAN.md create mode 100644 .planning/phases/10.1-aggressive-workflow-modularization/10.1-04-PLAN.md create mode 100644 .planning/phases/10.1-aggressive-workflow-modularization/10.1-05-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 9989dd8..fbac9d1 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -45,16 +45,20 @@ Plans: ### Phase 10.1: Aggressive Workflow Modularization (INSERTED) -**Goal:** Decompose main workflow to minimal trigger/auth/routing with domain sub-workflows +**Goal:** Decompose main workflow to minimal trigger/auth/routing (~50-80 nodes) with domain sub-workflows **Dependencies:** Phase 10 (initial modularization complete) **Requirements:** MOD-03 (new) -**Plans:** 0 plans +**Plans:** 5 plans Plans: -- [ ] TBD (run /gsd:plan-phase 10.1 to break down) +- [ ] 10.1-01-PLAN.md — Rename sub-workflows, analyze domain boundaries, get user approval +- [ ] 10.1-02-PLAN.md — Extract Batch UI sub-workflow (~50 nodes) +- [ ] 10.1-03-PLAN.md — Extract Container Status sub-workflow (~10-15 nodes) +- [ ] 10.1-04-PLAN.md — Extract Confirmation sub-workflow (~15-20 nodes) +- [ ] 10.1-05-PLAN.md — Integration verification and UAT **Success Criteria:** 1. Main workflow contains only: trigger, auth, keyword routing, sub-workflow dispatch @@ -156,7 +160,7 @@ Plans: | 8 | Inline Keyboard Infrastructure | v1.1 | Complete | | 9 | Batch Operations | v1.1 | Complete | | 10 | Workflow Modularization | v1.2 | Complete | -| 10.1 | Aggressive Workflow Modularization | v1.2 | Pending (INSERTED) | +| 10.1 | Aggressive Workflow Modularization | v1.2 | Planned | | 10.2 | Better Logging & Log Management | v1.2 | Pending (INSERTED) | | 11 | Update All & Callback Limits | v1.2 | Pending | | 12 | Polish & Audit | v1.2 | Pending | @@ -165,4 +169,4 @@ Plans: **v1.2 Coverage:** 12+ requirements mapped across 7 phases --- -*Updated: 2026-02-04 — Phase 10 complete (all 7 plans, verified)* +*Updated: 2026-02-04 — Phase 10.1 planned (5 plans in 3 waves)* diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-PLAN.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-PLAN.md new file mode 100644 index 0000000..13d3125 --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-PLAN.md @@ -0,0 +1,173 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - n8n-container-update.json + - n8n-container-actions.json + - n8n-container-logs.json + - n8n-update.json + - n8n-actions.json + - n8n-logs.json +autonomous: false + +must_haves: + truths: + - "Existing sub-workflows renamed to shorter pattern" + - "Domain boundaries analyzed and documented" + - "User has approved extraction boundaries before work begins" + artifacts: + - path: "n8n-update.json" + provides: "Renamed container update sub-workflow" + contains: "Container Update" + - path: "n8n-actions.json" + provides: "Renamed container actions sub-workflow" + contains: "Container Actions" + - path: "n8n-logs.json" + provides: "Renamed container logs sub-workflow" + contains: "Container Logs" + key_links: + - from: "n8n-workflow.json" + to: "sub-workflows" + via: "Execute Workflow nodes unchanged (IDs stable)" + pattern: "executeWorkflow" +--- + + +Rename existing sub-workflows to shorter naming pattern and analyze main workflow for optimal domain boundaries. + +Purpose: Establish consistent naming convention and get user approval on extraction plan before modifying main workflow. +Output: Renamed sub-workflow files, documented domain analysis, user-approved extraction boundaries. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-RESEARCH.md +@n8n-workflow.json +@n8n-container-update.json +@n8n-container-actions.json +@n8n-container-logs.json + + + + + + Task 1: Rename existing sub-workflows to shorter pattern + + n8n-container-update.json -> n8n-update.json + n8n-container-actions.json -> n8n-actions.json + n8n-container-logs.json -> n8n-logs.json + + +Rename the three existing sub-workflow files to match the locked decision for shorter naming: +- `git mv n8n-container-update.json n8n-update.json` +- `git mv n8n-container-actions.json n8n-actions.json` +- `git mv n8n-container-logs.json n8n-logs.json` + +NOTE: The workflow IDs in n8n remain the same (assigned by n8n on import). Only the file names change. +The main workflow's Execute Workflow nodes reference by ID, not filename, so no main workflow changes needed. + + +- `ls n8n-*.json` shows: n8n-workflow.json, n8n-update.json, n8n-actions.json, n8n-logs.json +- `git status` shows renamed files +- Old filenames no longer exist + + Three sub-workflow files renamed to shorter pattern. Git tracks the renames. + + + + Task 2: Analyze main workflow and document domain boundaries + n8n-workflow.json (read only) + +Analyze the main workflow (192 nodes) to identify optimal extraction boundaries. For each candidate domain: + +1. Count nodes in the domain +2. Identify entry/exit points (which nodes connect to main workflow) +3. Check for internal dependencies (does domain reference nodes outside itself?) +4. Assess cohesion (does domain represent single user-facing outcome?) + +Expected domains to analyze: +- **Batch UI**: ~50 nodes (batch selection keyboard, navigation, toggle, execution dispatch) +- **Container Status**: ~10-15 nodes (container list, pagination, status display) +- **Confirmation**: ~15-20 nodes (stop confirmation, update confirmation, expiry handling) +- **Telegram responses**: ~21 nodes (evaluate: does centralization add value?) + +For each domain, document: +- Node count +- Entry nodes (where main workflow calls into domain) +- Exit nodes (where domain returns to main workflow) +- External dependencies (what data/nodes does domain need from outside?) +- Extraction feasibility (yes/no with reasoning) + +Create analysis output showing: +1. Proposed extractions with node counts +2. Expected main workflow node count after extraction +3. Domains NOT recommended for extraction (with reasoning) +4. Potential issues or complications + + +Analysis output includes: +- At least 3 candidate domains evaluated +- Node counts for each domain +- Clear recommendation (extract vs keep) +- Expected final main workflow size (target: 50-80 nodes) + + Domain boundary analysis complete with extraction recommendations documented. + + + + Approve domain boundaries for extraction + +Before extracting domains to sub-workflows, user approval is needed on which domains to extract and how they should be structured. This is per CONTEXT.md: "Claude analyzes workflow and proposes optimal domain boundaries (user approves)". + +The analysis from Task 2 will be presented with recommendations. + + + + + + + Review the domain analysis and respond: "approved", "modify: [changes]", or "skip: [domains]" + + + + + +- [ ] Old filenames (n8n-container-*.json) no longer exist +- [ ] New filenames (n8n-update.json, n8n-actions.json, n8n-logs.json) exist +- [ ] Domain analysis documented with clear recommendations +- [ ] User has approved extraction boundaries + + + +1. Sub-workflow files renamed to shorter pattern +2. Domain boundary analysis complete +3. User approval received for extraction plan +4. Ready to proceed with domain extractions in Wave 2 + + + +After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-SUMMARY.md` + diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-PLAN.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-PLAN.md new file mode 100644 index 0000000..2cb181b --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-PLAN.md @@ -0,0 +1,217 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 02 +type: execute +wave: 2 +depends_on: ["10.1-01"] +files_modified: + - n8n-workflow.json + - n8n-batch-ui.json +autonomous: true + +must_haves: + truths: + - "Batch selection keyboard appears when user enters batch mode" + - "User can toggle containers on/off in batch selection" + - "User can navigate pagination in batch selection" + - "User can execute batch actions (stop/restart/update)" + - "Batch summary shows results after execution" + artifacts: + - path: "n8n-batch-ui.json" + provides: "Batch UI orchestration sub-workflow" + contains: "Execute Workflow Trigger" + - path: "n8n-workflow.json" + provides: "Main workflow with batch UI extraction" + key_links: + - from: "n8n-workflow.json" + to: "n8n-batch-ui.json" + via: "Execute Workflow node" + pattern: "executeWorkflow.*batch" + - from: "n8n-batch-ui.json" + to: "n8n-actions.json" + via: "Execute Workflow node for batch actions" + pattern: "executeWorkflow" + - from: "n8n-batch-ui.json" + to: "n8n-update.json" + via: "Execute Workflow node for batch updates" + pattern: "executeWorkflow" +--- + + +Extract batch UI nodes from main workflow into dedicated n8n-batch-ui.json sub-workflow. + +Purpose: Remove ~40-50 nodes from main workflow by extracting the cohesive batch selection/navigation/execution domain. +Output: New n8n-batch-ui.json sub-workflow, updated main workflow with batch nodes extracted. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-SUMMARY.md +@n8n-workflow.json +@n8n-actions.json +@n8n-update.json + + + + + + Task 1: Create n8n-batch-ui.json sub-workflow with extracted batch nodes + n8n-batch-ui.json (new) + +Create new sub-workflow containing all batch UI related nodes from main workflow. + +**Input contract (Execute Workflow Trigger):** +- chatId: number (required) +- messageId: number (optional, 0 for new message) +- callbackData: string (the callback data triggering batch action) +- responseMode: string ('text' or 'callback') + +**Nodes to extract** (all nodes with "Batch" in name + related batch state nodes): +- Build Batch Keyboard, Build Batch Select Keyboard, Edit Batch Select Keyboard, Edit To Batch Select Keyboard +- Rebuild Batch Select Keyboard, Send Batch Confirmation, Send Batch Start Message, Send Batch Summary +- Build Batch Select Stop Confirmation, Build Batch Stop Confirmation, Build Batch Stop Expired +- Check Batch Stop Expired, Send Batch Stop Confirmation, Send Batch Stop Expired, Delete Batch Confirm Message +- Delete Batch Select Message, Delete Batch Stop Cancel Message +- Handle Batch Toggle, Handle Batch Clear, Handle Batch Exec, Handle Batch Action Result Sub +- Handle Batch Update Result, Execute Batch Action Sub-workflow, Execute Batch Update +- Initialize Batch State, Is Batch Command, Is Batch Complete, Match Batch Containers +- Needs Batch Confirmation, Prepare Batch Action Input, Prepare Batch Cancel Return +- Prepare Batch Exec, Prepare Batch Loop, Prepare Batch Nav, Prepare Batch Stop Exec +- Prepare Batch Update Input, Prepare Immediate Batch Exec, Prepare Update All Batch +- Route Batch Action, Route Batch Loop Action, Detect Batch Command, Get Containers for Batch +- Fetch Containers For Batch Mode, Answer Batch* nodes (all Answer Batch callbacks) + +**Structure:** +1. Execute Workflow Trigger (entry point) +2. Parse Input (validate and extract callback data) +3. Route Batch Action (switch on callback type: toggle, clear, exec, nav, cancel) +4. Domain logic for each branch +5. Return structured result to main workflow + +**Output contract (return to main workflow):** +```javascript +{ + success: true/false, + action: 'toggle|clear|exec|nav|cancel|summary', + // For keyboard updates: + keyboard: {...} || null, + text: "message text", + // For execution results: + results: [{containerId, containerName, success, message}], + // Error info: + error: "error message" || null +} +``` + +**Important:** Sub-workflow should call existing single-container sub-workflows (n8n-actions.json, n8n-update.json) for actual container operations in batch loops. + + +- `cat n8n-batch-ui.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Nodes: {len(d.get(\"nodes\",[]))}')"` shows node count +- Sub-workflow has Execute Workflow Trigger node +- Sub-workflow has Execute Workflow nodes calling n8n-actions.json and n8n-update.json + + n8n-batch-ui.json created with all batch UI nodes extracted from main workflow structure. + + + + Task 2: Update main workflow to call batch UI sub-workflow + n8n-workflow.json + +Modify main workflow to replace batch nodes with Execute Workflow call to n8n-batch-ui.json. + +1. **Remove extracted batch nodes** from main workflow (all nodes identified in Task 1) + +2. **Add Execute Workflow node** ("Execute Batch UI"): + - Source: database + - WorkflowId: use TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder (same pattern as logs) + - Mode: once + - waitForSubWorkflow: true + - Input: { chatId, messageId, callbackData, responseMode } + +3. **Update routing** in main workflow: + - Route Callback should route batch callbacks (bsel:, bexec:, bnav:, bclear:, bcancel:) to new Execute Batch UI node + - Handle result from sub-workflow (success/failure, keyboard updates, error messages) + +4. **Add result handler** after Execute Batch UI: + - If result has keyboard: send/edit Telegram message with keyboard + - If result has error: send error message + - If result has summary: send summary message + +5. **Preserve Answer Callback nodes** in main workflow for the batch callbacks, OR move them to sub-workflow if they're tightly coupled with batch logic. + +**Data flow:** +Main receives callback -> Route Callback -> Execute Batch UI sub-workflow -> Return result -> Send Telegram response + +**Verification after changes:** +- Count nodes in main workflow (should be ~140-150 after this extraction) +- Verify Route Callback still has proper branches + + +- `cat n8n-workflow.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Main workflow nodes: {len(d.get(\"nodes\",[]))}')"` shows reduced count (~140-150) +- Main workflow has "Execute Batch UI" node +- No batch-related nodes remain in main workflow except routing entry point +- TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder is searchable + + Main workflow updated with batch nodes extracted and replaced by sub-workflow call. + + + + Task 3: Create backup and commit extraction + n8n-workflow.json.backup-batch + +1. Create explicit backup before committing (per CONTEXT.md rollback strategy): + `cp n8n-workflow.json n8n-workflow.json.backup-batch` + +2. Verify the extraction is complete: + - Main workflow node count reduced by ~40-50 + - n8n-batch-ui.json exists with extracted nodes + - No orphan references in main workflow + +3. Commit the extraction: + ```bash + git add n8n-workflow.json n8n-batch-ui.json n8n-workflow.json.backup-batch + git commit -m "feat(10.1-02): extract batch UI to sub-workflow + + - Created n8n-batch-ui.json with ~45 batch-related nodes + - Main workflow reduced from 192 to ~145 nodes + - Batch UI sub-workflow calls n8n-actions.json and n8n-update.json for operations + - Added TODO_DEPLOY_BATCH_UI_WORKFLOW placeholder for n8n import" + ``` + + +- Backup file exists: `ls n8n-workflow.json.backup-batch` +- Git commit created with extraction changes +- `git log -1` shows commit message about batch extraction + + Batch UI extraction committed with backup file for rollback if needed. + + + + + +- [ ] n8n-batch-ui.json exists with Execute Workflow Trigger +- [ ] Main workflow node count reduced by ~40-50 nodes +- [ ] Main workflow has Execute Batch UI node with TODO placeholder +- [ ] Backup file created before commit +- [ ] Git commit records the extraction + + + +1. New n8n-batch-ui.json sub-workflow created with all batch UI logic +2. Main workflow reduced from 192 to ~140-150 nodes +3. Sub-workflow properly calls existing action/update sub-workflows +4. Backup created for rollback capability +5. Changes committed to git + + + +After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-SUMMARY.md` + diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-03-PLAN.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-03-PLAN.md new file mode 100644 index 0000000..851b825 --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-03-PLAN.md @@ -0,0 +1,201 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 03 +type: execute +wave: 2 +depends_on: ["10.1-01"] +files_modified: + - n8n-workflow.json + - n8n-status.json +autonomous: true + +must_haves: + truths: + - "User can type 'list' to see container list with pagination" + - "User can tap container in list to see status/actions" + - "Pagination buttons (prev/next) work correctly" + - "Container status shows correct running state" + artifacts: + - path: "n8n-status.json" + provides: "Container status and list sub-workflow" + contains: "Execute Workflow Trigger" + - path: "n8n-workflow.json" + provides: "Main workflow with status extraction" + key_links: + - from: "n8n-workflow.json" + to: "n8n-status.json" + via: "Execute Workflow node" + pattern: "executeWorkflow.*status" +--- + + +Extract container status and list nodes from main workflow into dedicated n8n-status.json sub-workflow. + +Purpose: Remove ~10-15 nodes from main workflow by extracting the container list and status display domain. +Output: New n8n-status.json sub-workflow, updated main workflow with list/status nodes extracted. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-SUMMARY.md +@n8n-workflow.json + + + + + + Task 1: Create n8n-status.json sub-workflow with extracted list/status nodes + n8n-status.json (new) + +Create new sub-workflow containing container list and status display nodes. + +**Input contract (Execute Workflow Trigger):** +- chatId: number (required) +- messageId: number (optional, 0 for new message) +- action: string ('list' | 'status' | 'paginate') +- containerId: string (optional, for status action) +- containerName: string (optional, for status action) +- page: number (optional, for pagination, default 1) +- responseMode: string ('text' or 'callback') + +**Nodes to extract** (list/pagination related): +- Docker List Containers, Docker List for Action, Docker List for Update +- Get Containers For List, Prepare List Fetch +- Build Container List Keyboard, Build Paginated List +- Edit Container List, Send Container List +- Answer List Callback + +Also consider extracting status display nodes: +- Get Single Container, Check Single Container +- Build Container Submenu, Build Container Submenu Direct +- Send Container Submenu, Send Container Submenu Direct +- Prepare Container Fetch + +**Structure:** +1. Execute Workflow Trigger (entry point) +2. Parse Input (validate action type) +3. Switch on action type (list vs status vs paginate) +4. For list: Query Docker, build paginated list keyboard +5. For status: Get container details, build submenu +6. Return structured result + +**Output contract:** +```javascript +{ + success: true/false, + action: 'list|status|paginate', + // For list: + keyboard: {...}, + text: "message text", + totalContainers: number, + currentPage: number, + totalPages: number, + // For status: + container: { id, name, state, image, ports }, + keyboard: {...}, + text: "container status text", + // Error: + error: "error message" || null +} +``` + + +- `cat n8n-status.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Nodes: {len(d.get(\"nodes\",[]))}')"` shows node count (~10-15) +- Sub-workflow has Execute Workflow Trigger node +- Sub-workflow has Docker HTTP requests for container queries + + n8n-status.json created with container list and status nodes extracted. + + + + Task 2: Update main workflow to call status sub-workflow + n8n-workflow.json + +Modify main workflow to replace list/status nodes with Execute Workflow call. + +1. **Remove extracted list/status nodes** from main workflow + +2. **Add Execute Workflow node** ("Execute Container Status"): + - Source: database + - WorkflowId: use TODO_DEPLOY_STATUS_WORKFLOW placeholder + - Mode: once + - waitForSubWorkflow: true + - Input: { chatId, messageId, action, containerId, containerName, page, responseMode } + +3. **Update routing** in main workflow: + - Keyword Router should route "list" command to Execute Container Status with action='list' + - Route Callback should route list pagination callbacks (list:page:N) to Execute Container Status with action='paginate' + - Container selection callbacks should route to Execute Container Status with action='status' + +4. **Add result handler** after Execute Container Status: + - If result has keyboard: send/edit Telegram message with keyboard + - If result has error: send error message + +**Note:** This extraction may be smaller than batch UI. If analysis from 10.1-01 shows fewer than 8 nodes in this domain, consider whether extraction is worthwhile per the "don't extract 2-3 node groups" decision. If close to threshold, proceed with extraction for consistency. + + +- Main workflow has "Execute Container Status" node +- No list/pagination nodes remain in main workflow except routing +- TODO_DEPLOY_STATUS_WORKFLOW placeholder exists + + Main workflow updated with status nodes extracted and replaced by sub-workflow call. + + + + Task 3: Create backup and commit extraction + n8n-workflow.json.backup-status + +1. Create explicit backup: + `cp n8n-workflow.json n8n-workflow.json.backup-status` + +2. Verify the extraction: + - Main workflow node count reduced by ~10-15 from previous state + - n8n-status.json exists with extracted nodes + - No orphan references + +3. Commit the extraction: + ```bash + git add n8n-workflow.json n8n-status.json n8n-workflow.json.backup-status + git commit -m "feat(10.1-03): extract container status to sub-workflow + + - Created n8n-status.json with list and status display nodes + - Handles container list, pagination, and single container status + - Added TODO_DEPLOY_STATUS_WORKFLOW placeholder" + ``` + + +- Backup file exists +- Git commit created + + Status extraction committed with backup. + + + + + +- [ ] n8n-status.json exists with Execute Workflow Trigger +- [ ] Main workflow node count further reduced +- [ ] Main workflow has Execute Container Status node +- [ ] Backup file created +- [ ] Git commit records the extraction + + + +1. New n8n-status.json sub-workflow created +2. Main workflow reduced by ~10-15 additional nodes +3. List and status display functionality extracted cleanly +4. Backup created for rollback +5. Changes committed to git + + + +After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-03-SUMMARY.md` + diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-PLAN.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-PLAN.md new file mode 100644 index 0000000..9ba48f0 --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-PLAN.md @@ -0,0 +1,204 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 04 +type: execute +wave: 2 +depends_on: ["10.1-01"] +files_modified: + - n8n-workflow.json + - n8n-confirmation.json +autonomous: true + +must_haves: + truths: + - "Stop confirmation dialog appears before stopping containers" + - "Update confirmation dialog appears for multi-container updates" + - "Expired confirmations show 'session expired' message" + - "Confirm/cancel buttons work correctly" + artifacts: + - path: "n8n-confirmation.json" + provides: "Confirmation dialog sub-workflow" + contains: "Execute Workflow Trigger" + - path: "n8n-workflow.json" + provides: "Main workflow with confirmation extraction" + key_links: + - from: "n8n-workflow.json" + to: "n8n-confirmation.json" + via: "Execute Workflow node" + pattern: "executeWorkflow.*confirm" +--- + + +Extract confirmation dialog nodes from main workflow into dedicated n8n-confirmation.json sub-workflow. + +Purpose: Remove ~15-20 nodes from main workflow by extracting the confirmation dialog domain. +Output: New n8n-confirmation.json sub-workflow, updated main workflow with confirmation nodes extracted. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-01-SUMMARY.md +@n8n-workflow.json +@n8n-actions.json + + + + + + Task 1: Create n8n-confirmation.json sub-workflow with extracted confirmation nodes + n8n-confirmation.json (new) + +Create new sub-workflow containing confirmation dialog nodes. + +**Input contract (Execute Workflow Trigger):** +- chatId: number (required) +- messageId: number (required, for editing message) +- action: string ('show_stop' | 'show_update' | 'confirm' | 'cancel' | 'check_expired') +- containerId: string (optional) +- containerName: string (optional) +- containerIds: array (optional, for multi-container) +- confirmationToken: string (optional, for verifying non-expired) +- responseMode: string + +**Nodes to extract** (confirmation related - excluding batch confirmations which stay in batch-ui): +- Build Stop Confirmation, Build Update Confirmation, Build Update All Confirmation +- Check Confirm Expired, Handle Confirm Expired, Send Expired Confirm +- Edit To Stop Confirmation, Send Stop Confirmation, Send Update Confirmation, Send Update All Confirmation +- Answer Confirm Callback, Answer Cancel Confirm Callback +- Build Confirmed Stop Command, Prepare Confirmed Stop, Prepare Confirmed Stop Input +- Execute Confirmed Stop, Execute Confirmed Stop Action +- Format Confirmed Stop Result, Handle Confirmed Stop Result, Send Confirmed Stop Result +- Route Confirm Action + +**NOTE:** Batch confirmations (Build Batch Stop Confirmation, etc.) should stay in n8n-batch-ui.json since they're part of batch flow. This sub-workflow handles single-container confirmations and "update all" confirmations. + +**Structure:** +1. Execute Workflow Trigger (entry point) +2. Parse Input (validate action type) +3. Switch on action type +4. For show_stop: Build confirmation keyboard, return for main to send +5. For confirm: Validate not expired, execute action via sub-workflow call +6. For cancel: Return cancellation result +7. For check_expired: Validate confirmation token age + +**Output contract:** +```javascript +{ + success: true/false, + action: 'show_stop|show_update|confirm|cancel|expired', + // For show: + keyboard: {...}, + text: "confirmation text", + confirmationToken: "uuid for expiry tracking", + // For confirm: + executed: true/false, + result: { containerId, containerName, newState }, + // For expired: + expired: true/false, + // Error: + error: "error message" || null +} +``` + +**Important:** For confirmed stop/restart actions, this sub-workflow should call n8n-actions.json to perform the actual container action. + + +- `cat n8n-confirmation.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Nodes: {len(d.get(\"nodes\",[]))}')"` shows node count (~15-20) +- Sub-workflow has Execute Workflow Trigger node +- Sub-workflow has Execute Workflow node calling n8n-actions.json + + n8n-confirmation.json created with confirmation dialog nodes extracted. + + + + Task 2: Update main workflow to call confirmation sub-workflow + n8n-workflow.json + +Modify main workflow to replace confirmation nodes with Execute Workflow call. + +1. **Remove extracted confirmation nodes** from main workflow + (Keep batch confirmation nodes if they're still in main workflow - they belong in batch-ui) + +2. **Add Execute Workflow node** ("Execute Confirmation"): + - Source: database + - WorkflowId: use TODO_DEPLOY_CONFIRMATION_WORKFLOW placeholder + - Mode: once + - waitForSubWorkflow: true + - Input: { chatId, messageId, action, containerId, containerName, confirmationToken, responseMode } + +3. **Update routing** in main workflow: + - Route Callback should route confirmation callbacks (confirm:*, cancel:*) to Execute Confirmation + - Stop command should route to Execute Confirmation with action='show_stop' + +4. **Add result handler** after Execute Confirmation: + - If result.expired: show expired message + - If result.executed: show result message + - If result has keyboard: send/edit confirmation dialog + + +- Main workflow has "Execute Confirmation" node +- No single-container confirmation nodes remain in main workflow +- TODO_DEPLOY_CONFIRMATION_WORKFLOW placeholder exists + + Main workflow updated with confirmation nodes extracted. + + + + Task 3: Create backup and commit extraction + n8n-workflow.json.backup-confirm + +1. Create explicit backup: + `cp n8n-workflow.json n8n-workflow.json.backup-confirm` + +2. Verify the extraction: + - Main workflow node count reduced by ~15-20 from previous state + - n8n-confirmation.json exists with extracted nodes + - No orphan references + +3. Commit the extraction: + ```bash + git add n8n-workflow.json n8n-confirmation.json n8n-workflow.json.backup-confirm + git commit -m "feat(10.1-04): extract confirmation dialogs to sub-workflow + + - Created n8n-confirmation.json with stop/update confirmation nodes + - Handles confirmation display, expiry checking, and action execution + - Calls n8n-actions.json for confirmed stop/restart + - Added TODO_DEPLOY_CONFIRMATION_WORKFLOW placeholder" + ``` + + +- Backup file exists +- Git commit created + + Confirmation extraction committed with backup. + + + + + +- [ ] n8n-confirmation.json exists with Execute Workflow Trigger +- [ ] Main workflow node count further reduced +- [ ] Main workflow has Execute Confirmation node +- [ ] Backup file created +- [ ] Git commit records the extraction + + + +1. New n8n-confirmation.json sub-workflow created +2. Main workflow reduced by ~15-20 additional nodes +3. Confirmation dialog functionality extracted cleanly +4. Backup created for rollback +5. Changes committed to git + + + +After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-SUMMARY.md` + diff --git a/.planning/phases/10.1-aggressive-workflow-modularization/10.1-05-PLAN.md b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-05-PLAN.md new file mode 100644 index 0000000..9e3c496 --- /dev/null +++ b/.planning/phases/10.1-aggressive-workflow-modularization/10.1-05-PLAN.md @@ -0,0 +1,239 @@ +--- +phase: 10.1-aggressive-workflow-modularization +plan: 05 +type: execute +wave: 3 +depends_on: ["10.1-02", "10.1-03", "10.1-04"] +files_modified: + - n8n-workflow.json +autonomous: false + +must_haves: + truths: + - "Main workflow contains only trigger, auth, routing, and sub-workflow dispatch" + - "All container operations work via sub-workflows" + - "Main workflow is under 100 nodes (target: 50-80)" + - "All sub-workflows have consistent input/output contracts" + - "User has verified all functionality works correctly" + artifacts: + - path: "n8n-workflow.json" + provides: "Minimal orchestrator workflow" + - path: "n8n-batch-ui.json" + provides: "Batch UI sub-workflow" + - path: "n8n-status.json" + provides: "Container status sub-workflow" + - path: "n8n-confirmation.json" + provides: "Confirmation dialog sub-workflow" + key_links: + - from: "n8n-workflow.json" + to: "all sub-workflows" + via: "Execute Workflow nodes with TODO placeholders" + pattern: "TODO_DEPLOY.*WORKFLOW" +--- + + +Verify all extractions work together, clean up main workflow, and perform user acceptance testing. + +Purpose: Ensure the modularized architecture is complete and all functionality works correctly. +Output: Verified working system, documentation of final state, UAT sign-off. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-CONTEXT.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-02-SUMMARY.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-03-SUMMARY.md +@.planning/phases/10.1-aggressive-workflow-modularization/10.1-04-SUMMARY.md +@n8n-workflow.json +@n8n-batch-ui.json +@n8n-status.json +@n8n-confirmation.json + + + + + + Task 1: Verify main workflow structure and node count + n8n-workflow.json (read only) + +Analyze final main workflow state: + +1. Count total nodes (target: 50-80) +2. Verify main workflow contains only: + - Telegram Trigger (1 node) + - Authentication checks (2 nodes) + - Keyword routing (5-10 nodes) + - Execute Workflow calls to sub-workflows (6-8 nodes) + - Result handlers after sub-workflow calls (10-15 nodes) + - Error handling (2-3 nodes) + +3. List all Execute Workflow nodes and their targets: + - Execute Text Update -> n8n-update.json + - Execute Callback Update -> n8n-update.json + - Execute Action -> n8n-actions.json + - Execute Text Logs -> n8n-logs.json + - Execute Batch UI -> n8n-batch-ui.json + - Execute Container Status -> n8n-status.json + - Execute Confirmation -> n8n-confirmation.json + +4. Check for orphan nodes (nodes with no connections) + +5. Verify all TODO_DEPLOY_*_WORKFLOW placeholders are documented + +Output a summary: +- Final node count +- Node breakdown by category +- List of Execute Workflow nodes +- Any issues found + + +- Node count verified and documented +- No orphan nodes +- All sub-workflow calls identified + + Main workflow structure verified and documented. + + + + Task 2: Create deployment documentation + DEPLOY-SUBWORKFLOWS.md (new) + +Create deployment documentation for the new sub-workflow architecture. + +Content: +```markdown +# Sub-workflow Deployment Guide + +## Overview + +Phase 10.1 extracted main workflow from 192 nodes to ~XX nodes by creating domain sub-workflows. + +## Sub-workflows + +| File | Purpose | Deploy Order | +|------|---------|--------------| +| n8n-update.json | Container update operations | 1 (already deployed) | +| n8n-actions.json | Container start/stop/restart | 2 (already deployed) | +| n8n-logs.json | Container log retrieval | 3 (already deployed) | +| n8n-batch-ui.json | Batch selection UI | 4 | +| n8n-status.json | Container list/status | 5 | +| n8n-confirmation.json | Confirmation dialogs | 6 | + +## Deployment Steps + +### For each new sub-workflow (batch-ui, status, confirmation): + +1. Import the JSON file into n8n +2. Note the workflow ID assigned by n8n +3. Search main workflow for the TODO placeholder: + - `TODO_DEPLOY_BATCH_UI_WORKFLOW` + - `TODO_DEPLOY_STATUS_WORKFLOW` + - `TODO_DEPLOY_CONFIRMATION_WORKFLOW` +4. Replace placeholder with actual workflow ID +5. Re-import main workflow + +### Existing Sub-workflows (already deployed) + +- Container Update: ID `7AvTzLtKXM2hZTio92_mC` +- Container Actions: ID `fYSZS5PkH0VSEaT5` +- Container Logs: ID `oE7aO2GhbksXDEIw` + +## Rollback + +Backup files created during extraction: +- `n8n-workflow.json.backup-batch` - Before batch extraction +- `n8n-workflow.json.backup-status` - Before status extraction +- `n8n-workflow.json.backup-confirm` - Before confirmation extraction + +To rollback, copy the appropriate backup file to n8n-workflow.json and re-import. + +## Architecture + +\`\`\` +n8n-workflow.json (orchestrator) +├── Trigger + Auth + Routing +├── Execute Update -> n8n-update.json +├── Execute Actions -> n8n-actions.json +├── Execute Logs -> n8n-logs.json +├── Execute Batch UI -> n8n-batch-ui.json +│ ├── (calls n8n-update.json for batch updates) +│ └── (calls n8n-actions.json for batch actions) +├── Execute Status -> n8n-status.json +└── Execute Confirmation -> n8n-confirmation.json + └── (calls n8n-actions.json for confirmed actions) +\`\`\` +``` + + +- DEPLOY-SUBWORKFLOWS.md exists +- Contains all sub-workflow files and placeholders +- Contains deployment steps and rollback instructions + + Deployment documentation created. + + + + +Complete workflow modularization: +- Main workflow reduced from 192 to ~XX nodes +- 3 new sub-workflows extracted (batch-ui, status, confirmation) +- Total of 6 sub-workflows in the system +- Deployment documentation created + + +**NOTE:** Full UAT requires deploying sub-workflows to n8n. For now, verify: + +1. **File structure check:** + - `ls n8n-*.json` should show 7 files (workflow + 6 sub-workflows) + - Main workflow has expected reduced node count + +2. **JSON validity:** + - All JSON files parse correctly + - All sub-workflows have Execute Workflow Trigger + +3. **Deployment placeholders:** + - Search n8n-workflow.json for "TODO_DEPLOY" - should find 3 new placeholders + - Existing workflow IDs still referenced correctly + +4. **After n8n deployment (when ready):** + - Test `/list` command - should show container list + - Test `/stop ` - should show confirmation + - Test batch mode: `/stop` then select multiple containers + - Test update flow + - Test logs command + +Respond with: +- "approved" if structure looks correct +- "issues: [description]" if problems found + + Type "approved" or describe issues found + + + + + +- [ ] Main workflow node count documented +- [ ] All sub-workflow files exist +- [ ] Deployment documentation created +- [ ] No orphan nodes in main workflow +- [ ] User has verified structure (deployment verification deferred to n8n import) + + + +1. Main workflow reduced to target size (50-80 nodes) +2. 6 sub-workflows total (3 existing + 3 new) +3. All TODO placeholders documented +4. Deployment guide created +5. User sign-off on structure + + + +After completion, create `.planning/phases/10.1-aggressive-workflow-modularization/10.1-05-SUMMARY.md` +