docs(05): create phase plan

Phase 05: Polish & Deploy - 3 plans in 3 waves - 1 parallel (Wave 1), 2 sequential (Waves 2-3) - Ready for execution Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 21:00:51 -05:00
parent 4c09d61943
commit b7cefd931e
4 changed files with 539 additions and 0 deletions
@@ -0,0 +1,203 @@
+---
+phase: 05-polish-deploy
+plan: 03
+type: execute
+wave: 3
+depends_on: [05-02]
+files_modified: [README.md, n8n-workflow.json]
+autonomous: false
+
+must_haves:
+  truths:
+    - "README has step-by-step deployment instructions"
+    - "README documents credential creation in n8n"
+    - "README documents Docker socket setup for n8n container"
+    - "All 6 commands tested end-to-end via Telegram"
+  artifacts:
+    - path: "README.md"
+      provides: "Deployment guide"
+      min_lines: 50
+      contains: "Installation"
+    - path: "n8n-workflow.json"
+      provides: "Production-ready workflow"
+  key_links:
+    - from: "README.md"
+      to: "n8n credentials"
+      via: "documentation"
+      pattern: "telegramAuth"
+---
+
+<objective>
+Write deployment README and perform end-to-end testing of complete bot functionality.
+
+Purpose: Enable users to deploy the bot on their own Unraid servers with clear instructions.
+Output: Complete README, verified workflow, production-ready deployment package.
+</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/STATE.md
+@.planning/phases/05-polish-deploy/05-CONTEXT.md
+@.planning/phases/05-polish-deploy/05-RESEARCH.md
+@.planning/phases/05-polish-deploy/05-01-SUMMARY.md
+@.planning/phases/05-polish-deploy/05-02-SUMMARY.md
+@n8n-workflow.json
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Write deployment README</name>
+  <files>README.md</files>
+  <action>
+Replace the stub README with a complete deployment guide. Per CONTEXT.md: "README only - step-by-step instructions in markdown" and "No troubleshooting section - focused on initial setup only".
+
+Structure (following RESEARCH.md template):
+
+# Docker Manager Bot
+
+One-line description: Telegram bot for managing Docker containers on Unraid.
+
+## Prerequisites
+
+- Unraid server with Docker enabled
+- n8n container running on Unraid
+- Telegram Bot Token (from @BotFather)
+- Your Telegram User ID (from @userinfobot)
+
+## Installation
+
+### 1. Configure n8n Container
+
+Document the Docker run flags needed:
+```bash
+docker run -d \
+  --name n8n \
+  --group-add 281 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /path/to/curl:/usr/bin/curl:ro \
+  n8nio/n8n
+```
+
+Explain:
+- `--group-add 281` for Docker socket access
+- Socket mount requirement
+- Static curl binary mount (hardened n8n image)
+
+### 2. Create n8n Credentials
+
+**Telegram API credential:**
+- Type: Telegram API
+- Access Token: your bot token from @BotFather
+
+**Telegram Auth credential:**
+- Type: Header Auth (or custom)
+- Field: userId = your Telegram user ID
+
+### 3. Import Workflow
+
+- Copy n8n-workflow.json to server
+- In n8n: Workflows -> Import from File
+- Map credentials when prompted
+
+### 4. Activate Workflow
+
+- Open workflow
+- Click Active toggle
+- Test with "status" message
+
+## Usage
+
+List the 6 commands:
+- status - View all containers
+- start <name> - Start container
+- stop <name> - Stop container
+- restart <name> - Restart container
+- update <name> - Pull and recreate container
+- logs <name> [lines] - View container logs
+
+Mention persistent menu buttons available.
+
+Per CONTEXT.md: No troubleshooting section.
+  </action>
+  <verify>
+README exists at root.
+Contains all 4 installation sections.
+No troubleshooting section.
+Markdown renders correctly.
+  </verify>
+  <done>
+Complete deployment guide in README.md.
+Step-by-step instructions for fresh Unraid installation.
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: End-to-end testing</name>
+  <what-built>
+Complete Docker Manager Bot:
+- Keyword routing (no Claude dependency)
+- Persistent Telegram menu
+- All 6 container commands
+- Terse error messages
+- Credential-based auth
+  </what-built>
+  <how-to-verify>
+Test each command via Telegram bot:
+
+1. **Menu:** Send /start or any unknown text
+   - Expected: Persistent keyboard appears with 6 buttons
+
+2. **Status:** Tap Status button or type "status"
+   - Expected: List of containers with status indicators
+
+3. **Start:** Type "start <stopped-container-name>"
+   - Expected: Container starts, confirmation message
+
+4. **Stop:** Type "stop <running-container-name>"
+   - Expected: Container stops, confirmation message
+
+5. **Restart:** Type "restart <container-name>"
+   - Expected: Container restarts, confirmation message
+
+6. **Update:** Type "update <container-name>"
+   - Expected: Image pulled, container recreated (or silent if no update)
+
+7. **Logs:** Type "logs <container-name>"
+   - Expected: Last 50 log lines displayed
+
+8. **Error handling:** Stop n8n's Docker socket access briefly
+   - Expected: "Cannot connect to Docker" (not stack trace)
+
+9. **Auth:** Message bot from different Telegram account
+   - Expected: No response (silent ignore per Phase 1 decision)
+  </how-to-verify>
+  <resume-signal>Type "approved" if all tests pass, or describe which tests failed</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+1. README exists and has all required sections
+2. All 6 commands work end-to-end
+3. Persistent menu functions correctly
+4. Error messages are terse
+5. Unauthorized users get no response
+6. Workflow exports without sensitive data
+</verification>
+
+<success_criteria>
+- Fresh user can follow README to deploy bot
+- All container management commands functional
+- Bot ready for production use on Unraid
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-polish-deploy/05-03-SUMMARY.md`
+</output>