feat: add GitHub Actions workflow for automatic roadmap synchronization

[konard]

🎯 Summary

This PR implements automatic synchronization of the roadmap section in README.md with the actual state of GitHub issues across the deep-assistant organization, solving issue #11.

Fixes #11

🚀 What's New

GitHub Actions Workflow

• File: .github/workflows/sync-roadmap.yml
• Schedule: Runs daily at 00:00 UTC
• Manual Trigger: Can be manually triggered from Actions tab
• Auto Trigger: Automatically runs when issues are opened, closed, reopened, edited, or deleted

Synchronization Script

• File: .github/workflows/sync-roadmap.js
• Language: Node.js (no dependencies required)
• Function: Parses README.md, fetches issue states from GitHub API, and updates checkboxes

Documentation

• File: .github/workflows/README.md
• Content: Comprehensive documentation of the workflow, how it works, and how to use it

✨ Features

1. Automatic Checkbox Updates

   • [ ] for open issues
   • [x] for closed issues

2. Multi-Repository Support

   • Works with issues from deep-assistant/master-plan
   • Works with issues from deep-assistant/telegram-bot
   • Easily extensible to other repositories

3. Smart Commit Strategy

   • Only commits when changes are detected
   • Uses meaningful commit messages
   • Preserves existing roadmap structure and formatting

4. Error Handling

   • Gracefully handles API errors
   • Defaults to "open" state if issue can't be fetched
   • Provides detailed logging for debugging

📋 How It Works

1. Detection: The script scans README.md for issue references in the format:

   [#123](https://github.com/deep-assistant/repo-name/issues/123)

2. Fetching: For each issue reference, it fetches the current state from GitHub API

3. Updating: Updates the checkbox on the task line associated with each issue:

   • Finds the task line (starts with - [ ] or - [x])
   • Updates checkbox based on issue state
   • Preserves all other formatting

4. Committing: If any changes were made, commits and pushes to the repository

🧪 Testing

The script was tested locally and correctly identifies all 45 issue references in the current README.md roadmap section:

• 37 issues from telegram-bot repository
• 8 issues from master-plan repository

📚 Usage

Automatic

The workflow runs automatically daily and on issue events. No action required.

Manual

1. Go to the repository's Actions tab
2. Select "Sync Master Plan Roadmap" workflow
3. Click "Run workflow" button

🔧 Maintenance

To add new issues to the roadmap:

1. Edit README.md manually
2. Add issue reference with format: [#number](url)
3. Add a task line above or below: - [ ] **Task Name**
4. The workflow will automatically sync checkbox states

📝 Files Changed

• ✅ .github/workflows/sync-roadmap.yml - GitHub Actions workflow configuration
• ✅ .github/workflows/sync-roadmap.js - Node.js synchronization script
• ✅ .github/workflows/README.md - Workflow documentation

🎓 Technical Details

Permissions Required:

• contents: write - To commit changes to README.md
• issues: read - To fetch issue states from GitHub API

Dependencies:

• None! Uses only Node.js built-in modules (fs, https)

API Rate Limits:

• Uses authenticated GitHub API (higher rate limits)
• Processes issues sequentially to avoid overwhelming the API
• Should stay well within rate limits even with 100+ issues

✅ Checklist

• Workflow file created and configured
• Synchronization script implemented
• Documentation added
• Local testing performed
• Code follows repository conventions
• Commit messages follow best practices
• All files tracked in git

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

📎 Log file uploaded as GitHub Gist (249KB)
🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.