docs(01): create phase plan

Phase 01: Foundation - 2 plan(s) in 2 wave(s) - Wave 1: Workflow setup (has human action checkpoint) - Wave 2: Verification (human verify checkpoints) - Ready for execution Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 18:47:27 -05:00
parent 2cb6f3a689
commit f330097906
3 changed files with 318 additions and 1 deletions
@@ -0,0 +1,189 @@
+---
+phase: 01-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - n8n-workflow.json
+autonomous: false
+user_setup:
+  - service: telegram
+    why: "Bot token required for n8n Telegram integration"
+    account_setup:
+      - task: "Create Telegram bot"
+        location: "Telegram app -> @BotFather"
+        steps:
+          - "Open Telegram, search for @BotFather"
+          - "Send /newbot"
+          - "Choose a name (e.g., 'Unraid Docker Manager')"
+          - "Choose a username (must end with 'bot', e.g., 'unraid_docker_bot')"
+          - "Copy the API token provided"
+    env_vars:
+      - name: TELEGRAM_BOT_TOKEN
+        source: "BotFather response after /newbot"
+      - name: TELEGRAM_USER_ID
+        source: "Send any message to @userinfobot to get your Telegram user ID"
+
+must_haves:
+  truths:
+    - "User can send a message to the Telegram bot"
+    - "Bot responds only to authorized user ID"
+    - "Unauthorized users receive no response (silent ignore)"
+    - "Echo response includes original message and timestamp"
+  artifacts:
+    - path: "n8n-workflow.json"
+      provides: "Complete n8n workflow definition"
+      contains: "Telegram Trigger"
+  key_links:
+    - from: "Telegram Trigger node"
+      to: "IF node"
+      via: "message.from.id check"
+      pattern: "from.id"
+    - from: "IF node (true branch)"
+      to: "Code node"
+      via: "authenticated flow"
+    - from: "Code node"
+      to: "Telegram Send node"
+      via: "echo message"
+---
+
+<objective>
+Create the n8n workflow that receives Telegram messages, authenticates the user, and echoes messages back with timestamp.
+
+Purpose: Establish the foundation for all bot communication - prove the Telegram <-> n8n round-trip works before adding Docker features.
+Output: Working n8n workflow that echoes messages back to the authorized user.
+</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/01-foundation/01-CONTEXT.md
+@.planning/phases/01-foundation/01-RESEARCH.md
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-action" gate="blocking">
+  <name>Task 1: Create Telegram Bot and Configure n8n</name>
+  <action>
+User must complete external setup before workflow can be created:
+
+1. **Create Telegram Bot:**
+   - Open Telegram, search for @BotFather
+   - Send `/newbot`
+   - Follow prompts for name (e.g., "Unraid Docker Manager")
+   - Choose username ending with 'bot' (e.g., "unraid_docker_bot")
+   - Save the API token provided
+
+2. **Get Your Telegram User ID:**
+   - In Telegram, search for @userinfobot
+   - Send any message
+   - Note your "Id" value (numeric)
+
+3. **Configure n8n Environment Variables:**
+   - Add to n8n container environment:
+     - `TELEGRAM_BOT_TOKEN=<your-bot-token>`
+     - `TELEGRAM_USER_ID=<your-user-id>`
+   - Restart n8n container if needed
+
+4. **Create Telegram Credential in n8n:**
+   - n8n UI -> Credentials -> Add -> Telegram API
+   - Paste bot token in "Access Token" field
+   - Save credential
+  </action>
+  <resume-signal>Type "done" when Telegram bot is created and n8n credential is configured</resume-signal>
+</task>
+
+<task type="auto">
+  <name>Task 2: Create n8n Workflow for Telegram Echo</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Create an n8n workflow JSON file with the following structure:
+
+**Workflow: "Docker Manager Bot"**
+
+**Node 1: Telegram Trigger**
+- Type: n8n-nodes-base.telegramTrigger
+- Updates: "message"
+- Use the Telegram API credential
+
+**Node 2: IF (User Authentication)**
+- Type: n8n-nodes-base.if
+- Condition: `{{ $json.message.from.id.toString() }}` equals `{{ $env.TELEGRAM_USER_ID }}`
+- True branch continues to echo
+- False branch: no connected nodes (silent ignore)
+
+**Node 3: Code (Format Echo)**
+- Type: n8n-nodes-base.code
+- JavaScript code:
+```javascript
+const message = $input.item.json.message;
+const timestamp = new Date().toISOString();
+const text = message.text || '(no text)';
+
+return {
+  json: {
+    chatId: message.chat.id,
+    text: `Got: ${text}\n\nProcessed: ${timestamp}`
+  }
+};
+```
+
+**Node 4: Telegram (Send Message)**
+- Type: n8n-nodes-base.telegram
+- Resource: message
+- Operation: sendMessage
+- Chat ID: `={{ $json.chatId }}`
+- Text: `={{ $json.text }}`
+- Parse Mode: HTML (for future formatting)
+
+**Connections:**
+- Telegram Trigger -> IF
+- IF (true) -> Code
+- Code -> Telegram Send
+- IF (false) -> (nothing, ends workflow)
+
+Save as `n8n-workflow.json` in the project root. This file can be imported into n8n.
+
+**Important:** The workflow JSON should be valid for n8n import. Include proper node positions for visual layout.
+  </action>
+  <verify>
+- File `n8n-workflow.json` exists
+- JSON is valid (parse without errors)
+- Contains all 4 nodes: telegramTrigger, if, code, telegram
+- IF condition references `$env.TELEGRAM_USER_ID`
+  </verify>
+  <done>
+- n8n workflow JSON file created and valid
+- All nodes properly connected
+- User ID authentication configured via environment variable
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. Workflow JSON file exists at project root
+2. JSON parses without errors
+3. All required nodes present with correct types
+4. IF node checks user ID from environment variable
+5. Code node includes timestamp in output
+</verification>
+
+<success_criteria>
+- n8n-workflow.json exists and is valid JSON
+- Workflow includes Telegram Trigger, IF (auth), Code (echo), Telegram Send
+- Authentication uses environment variable for user ID
+- Silent ignore implemented (no nodes on false branch)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
+</output>
@@ -0,0 +1,122 @@
+---
+phase: 01-foundation
+plan: 02
+type: execute
+wave: 2
+depends_on: ["01-01"]
+files_modified: []
+autonomous: false
+
+must_haves:
+  truths:
+    - "Message sent to bot receives echo response"
+    - "Echo includes original message text"
+    - "Echo includes processing timestamp"
+    - "Different Telegram user receives no response"
+  artifacts: []
+  key_links:
+    - from: "User Telegram message"
+      to: "n8n workflow"
+      via: "Telegram webhook"
+    - from: "n8n workflow"
+      to: "User Telegram"
+      via: "Telegram Bot API sendMessage"
+---
+
+<objective>
+Import the workflow into n8n and verify end-to-end Telegram communication works.
+
+Purpose: Confirm the foundation is solid before building Docker features on top.
+Output: Verified working bot that echoes messages to authorized user only.
+</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/phases/01-foundation/01-01-SUMMARY.md
+@n8n-workflow.json
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-action" gate="blocking">
+  <name>Task 1: Import and Activate Workflow in n8n</name>
+  <action>
+Import the workflow JSON into n8n:
+
+1. Open n8n UI
+2. Go to Workflows -> Import from File
+3. Select `n8n-workflow.json` from the project
+4. Review the imported workflow
+5. Ensure Telegram credential is selected in Telegram nodes
+6. Activate the workflow (toggle on)
+  </action>
+  <resume-signal>Type "activated" when workflow is imported and active in n8n</resume-signal>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Verify Authorized User Echo</name>
+  <what-built>Telegram bot that echoes messages back with timestamp</what-built>
+  <how-to-verify>
+1. Open Telegram
+2. Find your bot (search for the username you created)
+3. Send a test message: "Hello bot!"
+4. Verify you receive a response like:
+   ```
+   Got: Hello bot!
+
+   Processed: 2026-01-28T12:34:56.789Z
+   ```
+5. The timestamp should be within seconds of when you sent the message
+6. Try another message to confirm consistency
+  </how-to-verify>
+  <resume-signal>Type "working" if echo works correctly, or describe any issues</resume-signal>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Verify Unauthorized User Blocked</name>
+  <what-built>Silent ignore for unauthorized Telegram users</what-built>
+  <how-to-verify>
+**Option A (if you have another device/account):**
+1. From a different Telegram account, send a message to the bot
+2. Verify NO response is received (bot appears offline)
+3. Wait 30 seconds to confirm silence
+
+**Option B (if only one account):**
+1. Temporarily change TELEGRAM_USER_ID in n8n to a wrong value
+2. Restart n8n
+3. Send a message to the bot
+4. Verify NO response
+5. Restore correct TELEGRAM_USER_ID
+6. Restart n8n
+7. Verify echo works again
+
+The bot should give no indication it received the message from unauthorized users.
+  </how-to-verify>
+  <resume-signal>Type "secure" if unauthorized users are blocked, or describe any issues</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+1. Workflow imported and active in n8n
+2. Authorized user receives echo with timestamp
+3. Unauthorized user receives no response
+4. Bot responds within a few seconds
+</verification>
+
+<success_criteria>
+- Telegram message to bot receives echo response
+- Echo includes original message and timestamp
+- Unauthorized users get silent ignore (no response)
+- REQ-01 (send/receive messages) validated
+- REQ-09 (user ID auth) validated
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-foundation/01-02-SUMMARY.md`
+</output>