From 5a1d51a4295c7e31a789fef73b2a358c5e0510f8 Mon Sep 17 00:00:00 2001
From: mindesbunister <github_service@egonetix.de>
Date: Fri, 14 Nov 2025 11:43:50 +0100
Subject: [PATCH] docs: add Nextcloud Deck sync instructions to
 copilot-instructions

- Added item #13 to 'When Making Changes' section for mandatory Deck updates
- Added new section 'Project-Specific Patterns #5: Nextcloud Deck Roadmap Sync'
- Documents when to sync, how to use scripts, stack mapping, card structure
- Includes best practices: dry-run first, manual deletion required, no duplicates

Integration complete:
- 21 cards: 3 initiatives + 18 phases
- Proper distribution: Backlog (6), Planning (1), In Progress (10), Complete (4)
- No duplicates verified
---
 .github/copilot-instructions.md | 49 +++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ba514d5..abfe4d3 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -810,6 +810,48 @@ const orderParams = {
 }
 ```
 
+### 5. Nextcloud Deck Roadmap Sync
+**Purpose:** Visual kanban board for tracking optimization roadmap progress
+
+**Key Components:**
+- `scripts/discover-deck-ids.sh` - Find Nextcloud Deck board/stack IDs
+- `scripts/sync-roadmap-to-deck.py` - Sync roadmap files to Deck cards
+- `docs/NEXTCLOUD_DECK_SYNC.md` - Complete documentation
+
+**Workflow:**
+```bash
+# One-time setup (already done)
+bash scripts/discover-deck-ids.sh  # Creates /tmp/deck-config.json
+
+# Sync roadmap to Deck (creates/updates cards)
+python3 scripts/sync-roadmap-to-deck.py --init
+
+# Always dry-run first to preview changes
+python3 scripts/sync-roadmap-to-deck.py --init --dry-run
+```
+
+**Stack Mapping:**
+- 📥 **Backlog:** Future phases, ideas, ML work (status: FUTURE)
+- 📋 **Planning:** Next phases, ready to implement (status: PENDING, NEXT)
+- 🚀 **In Progress:** Currently active work (status: CURRENT, IN PROGRESS, DEPLOYED)
+- ✅ **Complete:** Finished phases (status: COMPLETE)
+
+**Card Structure:**
+- 3 high-level initiative cards (from `OPTIMIZATION_MASTER_ROADMAP.md`)
+- 18 detailed phase cards (from individual roadmap files)
+- Total: 21 cards tracking all optimization work
+
+**When to Sync:**
+- After completing a phase (update markdown status → re-sync)
+- When starting new phase (move card in Deck UI)
+- Weekly during active development to keep visual state current
+
+**Important Notes:**
+- API doesn't support duplicate detection - always use `--dry-run` first
+- Manual card deletion required (API returns 405 on DELETE)
+- Code blocks auto-removed from descriptions (prevent API errors)
+- Card titles cleaned (no markdown, emojis removed for readability)
+
 ## Testing Commands
 
 ```bash
@@ -1389,6 +1431,13 @@ if (!enabled) {
       ```
     - Types: `feat:` (feature), `fix:` (bug fix), `docs:` (documentation), `refactor:` (code restructure)
     - This is NOT optional - code exists only when committed and pushed
+13. **NEXTCLOUD DECK SYNC (MANDATORY):** After completing phases or making significant roadmap progress:
+    - Update roadmap markdown files with new status (🔄 IN PROGRESS, ✅ COMPLETE, 🔜 NEXT)
+    - Run sync to update Deck cards: `python3 scripts/sync-roadmap-to-deck.py --init`
+    - Move cards between stacks in Nextcloud Deck UI to reflect progress visually
+    - Backlog (📥) → Planning (📋) → In Progress (🚀) → Complete (✅)
+    - Keep Deck in sync with actual work - it's the visual roadmap tracker
+    - Documentation: `docs/NEXTCLOUD_DECK_SYNC.md`
 
 ## Development Roadmap