desktop-team-doc 0.1.0

package/content/docs/instructions/workflows/pull-request-generation.md

@@ -0,0 +1,319 @@
+# GitHub Pull Request Generator
+
+Last Updated: 2025-10-16
+
+## Agent Objective
+
+Generate a GitHub Pull Request (PR) title and description. Gather information primarily via git commands and JIRA integration. Minimize user input to confirmation or essential clarifications. Optionally, use GitHub CLI (`gh`) to create the PR.
+
+## Context Variables
+
+- `source_branch`: Current git branch. Confirm with user if unavailable.
+- `destination_branch`: Default "main". Confirm with user if ambiguous.
+- `jira_tickets_input`: JIRA ticket string (e.g., "BFD-1234", "BFD-567, BFD-778") from conversation. Confirm if ambiguous.
+- `jira_data`: Structured data from JIRA (titles, descriptions, types, comments).
+- `commit_messages`: Commit messages from `source_branch` not in `destination_branch`.
+- `diff_summary`: Git diff between `destination_branch` and `source_branch`.
+- `remote_repo_url`: URL of the git remote origin.
+- `repo_owner_and_name`: GitHub repository identifier (from `remote_repo_url`, e.g., "positivegrid/desktop").
+- `pr_type`: Inferred/confirmed (Feature, Bugfix, Refactor, Chore).
+- `pr_title_draft`: Generated PR title.
+- `pr_description_draft`: Generated PR description.
+
+## Workflow
+
+### 1. Determine Target Repositories and Scope
+
+- Identify `[target_repository_names]` from user request.
+- If not possible, Agent: "Which repository/repositories for this PR? Options:
+  1. Main (e.g., BIAS_ONE)
+  2. Submodule (e.g., BIAS_ONE_GUI)
+  3. Multiple (list them, e.g., 'BIAS_ONE, BIAS_ONE_GUI')"
+- For each `[repo_name]` in `[target_repository_names]`:
+  - Determine/confirm `[local_path_for_repo_name]` (e.g., from `.gitmodules` for submodules, or current context for main repo) and `[repo_owner_and_name_for_repo]` (e.g., by parsing output of `git config --get remote.origin.url` executed in `[local_path_for_repo_name]`). If values remain unknown or ambiguous, use pre-configuration or ask the user.
+  - Store as a list of `[repository_contexts]`, each with `name`, `local_path`, `repo_owner_and_name`.
+- Agent: "Generating PR details for: `[comma_separated_list_of_repo_names]`."
+- JIRA Ticket Input:
+  1. Deduce `jira_tickets_input` from conversation.
+  2. If not possible, deduce from current git branch name (`git rev-parse --abbrev-ref HEAD`).
+  3. If still ambiguous, use 'JIRA Ticket Query'.
+- JIRA Ticket Query (if needed): "JIRA ticket(s) for PR? (e.g., BFD-1234, comma-separate, or 'none')."
+- Perform subsequent steps for each `[repo_context]`. Indicate current repository. Manage multiple PR drafts distinctly.
+
+### 2. Global JIRA Data Retrieval (Conditional - Done Once)
+
+- If `jira_tickets_input` is not "none" (and not already fetched):
+  - Agent: "Fetching JIRA details for: `[jira_tickets_input]`."
+  - Use JIRA MCP to fetch title, description/summary, type, comments, URL(s) for `jira_tickets_input`. Store as global `jira_data`.
+  - If JIRA MCP fails/unavailable: Prompt: "JIRA tool failed. Paste title(s) and summary/description for `{{jira_tickets_input}}`." Update `jira_data`.
+- Else if `jira_data` already populated:
+  - Agent: "Using existing JIRA data for `[jira_tickets_input]`."
+
+### 3. For Each Repository Context (Gather Repository-Specific Information)
+
+- Agent: "Repository: `[repo_context.name]` (path: `[repo_context.path]`)."
+- Get `source_branch_for_repo`: `git rev-parse --abbrev-ref HEAD` (in `[repo_context.path]`).
+- Get `remote_repo_url_for_repo`: `git config --get remote.origin.url` (in `[repo_context.path]`).
+  - (Note: `repo_owner_and_name` for this repo is in `[repo_context.repo_owner_and_name]`).
+- Set `destination_branch_for_repo` (default "main"). If `jira_data` implies specific target for this repo type (e.g., hotfix branch), use it. Else, confirm: "Target branch for `[repo_context.name]` is `{{destination_branch_for_repo}}`? (y/n/custom_branch)". Update if custom.
+- Get `commit_messages_for_repo` & `diff_summary_for_repo`: `git show {{destination_branch_for_repo}}..{{source_branch_for_repo}}` (in `[repo_context.path]`).
+
+### 4. For Each Repository Context (Infer PR Type)
+
+- Infer `pr_type_for_repo` from:
+  - `source_branch_for_repo` name patterns (e.g., `feature/`, `bugfix/`, `fix/`, `chore/`, `refactor/`).
+  - JIRA ticket type(s) from global `jira_data`.
+  - Keywords in `commit_messages_for_repo`.
+  - Wording Choices: Feature, Bugfix, Refactor, Chore
+- Priority: 1. Branch name, 2. JIRA type, 3. Commits.
+- Default to "Chore" or "Refactor" if unclear. If low confidence, confirm: "For `[repo_context.name]`, PR type `{{inferred_pr_type_for_repo}}`? Confirm or suggest (Feature, Bugfix, Refactor, Chore)." Update `pr_type_for_repo`.
+
+### 5. For Each Repository Context (Code and Commit Review)
+
+- Agent: "Reviewing code/commits for `[repo_context.name]`."
+- Analyze `diff_summary_for_repo` and `commit_messages_for_repo`. Consult codebase in `[repo_context.path]` with `diff_summary_for_repo` if needed. Verify:
+  - **Task Completion**: All tasks/issues from `jira_data` (if relevant to this repo) addressed?
+  - **Wording Quality**: Typos/grammar in `diff_summary_for_repo` (comments) and `commit_messages_for_repo`?
+  - **Commit Clarity**: `commit_messages_for_repo` clear and accurate? Follow team convention `<type> BFD-<issue-number>: <subject>`?
+  - **Guideline Adherence**: Changes in `diff_summary_for_repo` meet coding standards and team conventions?
+  - **Code Integrity**: Critical errors in `diff_summary_for_repo`?
+  - **Knowledge Base Consistency**: If a Knowledge Base (KB) exists in `[repo_context.path]/.knowledge/` or documented patterns, verify if the `diff_summary_for_repo` includes corresponding KB updates that accurately reflect the code changes. If changes were made that should be documented but no KB updates are present, or if KB updates seem incomplete/incorrect, note this as an issue.
+- Report: List identified issues for `[repo_context.name]`.
+- If issues for `[repo_context.name]`: Prompt user: proceed or request fixes? If fixes requested, repeat review for this repo after user confirms.
+
+### 6. For Each Repository Context (Draft PR Title)
+
+- Agent: "Drafting title for `[repo_context.name]`."
+- `summary_for_title_for_repo`: Synthesize from `commit_messages_for_repo` and `diff_summary_for_repo` (primary), `jira_data` titles (secondary). Capitalize first letter.
+- If `jira_tickets_input` is not "none" and global `jira_data` contains ticket numbers:
+  - Format `jira_data.numbers` (e.g., keep as `BFD-XXXX`). Store as `processed_formatted_ticket_numbers` (global, once).
+  - `pr_title_draft_for_repo` = "`{{pr_type_for_repo}}/{{processed_formatted_ticket_numbers}}: {{summary_for_title_for_repo}}`"
+  - Example: `Feature/BFD-123: Add user authentication`
+- Else (no JIRA tickets):
+  - `pr_title_draft_for_repo` = "`{{pr_type_for_repo}}: {{summary_for_title_for_repo}}`"
+- Store `pr_title_draft_for_repo` for `[repo_context.name]`.
+
+### 7. For Each Repository Context (Draft PR Description)
+
+- Agent: "Drafting description for `[repo_context.name]`."
+- Initialize `pr_description_draft_for_repo`.
+
+#### Required Sections
+
+**`## Requirement`**
+
+- If `jira_tickets_input` is not "none" and global `jira_data` available:
+  - For each ticket in `jira_data`: Append `- [{{ticket.title_or_user_summary}}]({{ticket.url}})`. Use bullets if multiple. (Section identical for PRs with same JIRA tickets).
+- Else (no JIRA tickets or `jira_data` unavailable):
+  - Synthesize 1-sentence requirement from `commit_messages_for_repo` or `diff_summary_for_repo`. Append.
+
+**`## Root Cause` (Bugfix only)**
+
+- If `pr_type_for_repo` is `Bugfix`:
+  - Analyze `jira_data.description` or prompt (once globally for `{{jira_tickets_input}}`, if unclear from JIRA): "Root cause for `{{jira_tickets_input}}` (if known)?" Append.
+
+**`## How to Fix` (Bugfix only) / `## How to Implement` (Other types)**
+
+- If `pr_type_for_repo` is `Bugfix`:
+  - `## How to Fix`: Summarize changes from `commit_messages_for_repo`, `diff_summary_for_repo` (bullet points, focus on solutions). Append.
+- Else (Feature, Refactor, Chore etc.):
+  - `## How to Implement`: Summarize changes from `commit_messages_for_repo`, `diff_summary_for_repo` (bullet points). Append.
+
+**`## How to Verify`**
+
+- Analyze global `jira_data` for acceptance criteria.
+- If none, derive from `commit_messages_for_repo` (e.g., "Verify X works per commit Y for `[repo_context.name]`").
+- If unclear, prompt: "Verification steps for `[repo_context.name]`?" Append (bullet points).
+
+#### Optional Sections
+
+**`## Related PRs` (Conditional)**
+
+- Note if other PRs are being generated in this session.
+- Prompt user (once globally, e.g., during first repo's description or after all drafts): "Any *external* related PR links (not ones being generated now)? (Full URLs, comma-separated, or 'none')." If links provided, append to all relevant PR descriptions.
+
+**`## Others (Known Issues, References, Notes)` (Conditional)**
+
+- Prompt user for `[repo_context.name]`: "Other notes (known issues, references)? ('none' if empty)." If content provided, append. Else, omit section entirely.
+
+Store `pr_description_draft_for_repo` for `[repo_context.name]`.
+
+### 8. For Each Repository Context (Review, Confirmation, and PR Creation)
+
+- Agent: "Review PR Draft for `[repo_context.name]`:"
+- Present `pr_title_draft_for_repo` and `pr_description_draft_for_repo`:
+
+  ```
+  PR Draft for [repo_context.name]:
+  Title: {{pr_title_draft_for_repo}}
+  Description:
+  {{pr_description_draft_for_repo}}
+
+  Confirm to create PR, or specify modifications (e.g., 'Change title to X', 'Add Y to How to Verify').
+  ```
+
+- If modifications: Update draft for this repo, re-present. Loop until confirmed.
+- Upon Confirmation for `[repo_context.name]`:
+  - Agent: "Creating PR for `[repo_context.name]`."
+  - Use GitHub CLI (`gh`):
+    - Command: `gh pr create --repo {{repo_owner_and_name}} --base {{destination_branch_for_repo}} --head {{source_branch_for_repo}} --title "{{pr_title_for_repo}}" --body "{{pr_description_for_repo}}"`
+    - Optional flags:
+      - `--assignee @me` (assign PR to current user)
+      - `--label bug` or `--label enhancement` (based on PR type)
+      - `--draft` (if PR is work in progress)
+    - If GitHub CLI success: Report "PR for `[repo_context.name]` created: [Link]". Store link.
+    - If GitHub CLI fails: Report "GitHub CLI failed for `[repo_context.name]`: [Error]. Manual PR content provided below."
+    - If GitHub CLI unavailable: Report "GitHub CLI not found for `[repo_context.name]`. Use manual PR creation with content below."
+- After all `[repository_contexts]`, proceed to Step 9.
+
+### 9. Post PR Link(s) to JIRA (Conditional & User-Prompted - Done Once After All PRs)
+
+- Applies if PR created (CLI or manual info provided) AND `jira_tickets_input` is not 'none'.
+- Store created PR link(s). If multiple PRs for same JIRA ticket, collect all their links.
+- Prompt: "Created PR(s):\n- [Title 1](Link 1)\n- [Title 2](Link 2) (if any)\n\nAdd link(s) as comment to JIRA `{{jira_tickets_input}}`? (y/n)"
+- If user confirms 'y':
+  - Construct comment. Single PR: "Related PR: [Title](Link)". Multiple PRs: "Related PRs:\n- Repo1: [Title 1](Link 1)\n- Repo2: [Title 2](Link 2)"
+  - For each JIRA ticket in `jira_tickets_input`:
+    - Use JIRA MCP (`jira_add_comment`):
+      - Parameters: `issue_key` (specific JIRA ticket key), `comment` (constructed string).
+      - If JIRA MCP success: Report "PR link(s) added to JIRA `{{issue_key}}`."
+      - If JIRA MCP fails/unavailable for `{{issue_key}}`: Report "Failed to add PR link(s) to JIRA `{{issue_key}}`. Add manually."
+
+## PR Content Formatting Rules (Strict)
+
+### General Format
+
+- **Output Language**: English
+- **Description**: Informative, brief
+- **Headings**: Use `##` for section names (e.g., `## Requirement`)
+- **Lists**: Use `- ` for bullet points
+- **JIRA Links**: `- [Title](URL)` format
+
+### PR Title Format
+
+**With JIRA tickets:**
+
+```
+<Type>/<TICKET1>,<TICKET2>: <Summary>
+```
+
+Example: `Feature/BFD-123: Implement user authentication`
+
+**Without JIRA tickets:**
+
+```
+<Type>: <Concise Summary>
+```
+
+Example: `Refactor: Improve error handling in API layer`
+
+**Type options:**
+
+- `Feature` - New feature implementation
+- `Bugfix` - Bug fix
+- `Refactor` - Code refactoring
+- `Chore` - Maintenance tasks, dependency updates
+
+### PR Description Section Order
+
+1. `## Requirement` (Required)
+2. `## Root Cause` (Bugfix only)
+3. `## How to Fix` (Bugfix only) / `## How to Implement` (Other types)
+4. `## How to Verify` (Required)
+5. `## Related PRs` (Optional - only if applicable, omit otherwise)
+6. `## Others (Known Issues, References, Notes)` (Optional - only if applicable, omit otherwise)
+
+### Example PR Description
+
+#### For Feature PR
+
+```markdown
+## Requirement
+
+- [BFD-123: Add user authentication system](https://jira.example.com/browse/BFD-123)
+
+## How to Implement
+
+- Implemented JWT-based authentication
+- Added login/logout endpoints
+- Created middleware for protected routes
+- Added user session management
+
+## How to Verify
+
+- Test login with valid credentials
+- Verify token is stored in session
+- Test protected routes require authentication
+- Test logout clears session
+
+## Related PRs
+
+- Frontend implementation: #456
+```
+
+#### For Bugfix PR
+
+```markdown
+## Requirement
+
+- [BFD-456: Fix memory leak in audio processor](https://jira.example.com/browse/BFD-456)
+
+## Root Cause
+
+Buffer was not being released after processing, causing memory accumulation over time.
+
+## How to Fix
+
+- Added proper buffer cleanup in destructor
+- Implemented RAII pattern with smart pointers
+- Added memory pool for buffer reuse
+
+## How to Verify
+
+- Run application for extended period (> 1 hour)
+- Monitor memory usage remains stable
+- Test with various audio file sizes
+- Verify no crashes or performance degradation
+```
+
+## GitHub CLI Reference
+
+Common GitHub CLI commands for PR management:
+
+```bash
+# Create PR
+gh pr create --title "Title" --body "Description"
+
+# Create PR with labels and assignee
+gh pr create --title "Title" --body "Description" --label bug --assignee @me
+
+# Create draft PR
+gh pr create --title "Title" --body "Description" --draft
+
+# View PR status
+gh pr status
+
+# List all PRs
+gh pr list
+
+# View specific PR
+gh pr view <PR-number>
+
+# Update PR
+gh pr edit <PR-number> --title "New Title"
+```
+
+## Team Conventions Integration
+
+This PR generator follows team standards:
+
+- **Git Commit Format**: `<type> BFD-<issue-number>: <subject>` (see [git-commit.md](./git-commit.md))
+- **Coding Standards**: Verifies adherence to team conventions (see [../coding-conventions/](../coding-conventions/))
+- **Code Review**: Generated PRs should follow review guidelines (see [code-review.md](./code-review.md))
+
+## Related Resources
+
+- [Git Commit Convention](./git-commit.md) - Team commit message format
+- [Code Review Guidelines](./code-review.md) - PR review process
+- [JIRA Process](./jira-process.md) - Ticket workflow integration
+- [Team-wide Coding Conventions](../coding-conventions/team-wide.md) - Coding standards

package/content/docs/instructions/workflows/scrum-process.md

@@ -0,0 +1,104 @@
+# Desktop Team Scrum 101
+
+*Last Updated: 2025-10-16*
+
+This document defines the Desktop Team's Scrum workflow, meeting cadences, and agile practices.
+
+## Duration
+
+**Biweekly** (兩週一個 Sprint)
+
+---
+
+## Grooming or Refinement Meeting
+
+**When**: 第二週，週三下午與週五下午（若沒有需要 Refine 項目，會取消）
+
+**Participants**:
+- PO (Product Owner)
+- Scrum Master
+- Development Team
+- Stakeholder
+
+**Decision Authority**: 最終決定是 PO
+
+### Reference
+
+- [What Is the Difference Between Product Backlog Grooming and Sprint Planning?](https://hygger.io/blog/product-backlog-grooming-vs-sprint-planning/)
+
+---
+
+## Planning Meeting
+
+**When**: 第一週，週一早上 09:30，與 Daily Sync 合併
+
+**Agenda**:
+- PO 分享最初目標、展示排列過後的 PBI，回答團隊成員問題
+- Just-in-time planning: 把產品 backlog `細分` 成一組工作
+
+**Story Point Estimation** (Optional, 目前沒有使用):
+- 使用相對概念
+- 使用費式數列: 1, 2, 3, 5, 8, 13
+- 可以多人蓋牌估算，取平均
+
+---
+
+## Demo Meeting
+
+**When**: 第二週，週四下午
+
+### 流程
+
+1. 檢查 Sprint 的 story，看哪些是完成要 demo (PO 平常就要 review 完成狀態)
+2. 在 demo meeting 當下，grooming story
+
+### Q&A
+
+**如何確認有哪些 pull request:**
+
+```bash
+git log --merges <last-release-tag>..HEAD --since="2 weeks ago" --pretty=format:"%<(15)%an%ad%x09%s"
+```
+
+**何時要整理這次 sprint 沒有完成 Story:**
+
+在 Demo Meeting 時，做 Story 的 grooming
+
+**沒有做完的 story 要放到哪？**
+
+放回 backlog，grooming 後，在 planning meeting 再討論
+
+---
+
+## Retrospective Meeting
+
+**When**: 第二週，週四下午，接在 Demo Meeting 後面
+
+**Document**: [Retrospective Doc](https://docs.google.com/spreadsheets/d/16oXGosRvBbPsmdNNkqpLlLBmyv7g3WJevA_Mf9XtJXE/edit?usp=sharing)
+
+**Purpose**: ~~讚揚大會~~討論開發流程可優化的部分
+
+---
+
+## Meeting Schedule Summary
+
+| Week | Day | Time | Meeting | Participants |
+|------|-----|------|---------|--------------|
+| Week 1 | Monday | 09:30 | Planning Meeting (with Daily Sync) | PO, Scrum Master, Dev Team |
+| Week 2 | Wednesday | Afternoon | Grooming/Refinement (optional) | PO, Scrum Master, Dev Team, Stakeholder |
+| Week 2 | Thursday | Afternoon | Demo Meeting | PO, Scrum Master, Dev Team |
+| Week 2 | Thursday | After Demo | Retrospective Meeting | Scrum Master, Dev Team |
+| Week 2 | Friday | Afternoon | Grooming/Refinement (optional) | PO, Scrum Master, Dev Team, Stakeholder |
+
+---
+
+## Related Documentation
+
+- [JIRA Process](./jira-process.md) - JIRA ticket workflow and management
+- [Code Review Process](./code-review.md) - Code review guidelines
+- [Git Commit Convention](./git-commit.md) - Commit message standards
+
+---
+
+**Maintained by**: Desktop Team Scrum Master
+**Contact**: Scrum Master for process questions, PO for backlog prioritization

package/content/docs/instructions/workflows/survey-project-setup.md

@@ -0,0 +1,76 @@
+# Desktop Team Survey 專案或前期 Repo 建置
+
+*Last Updated: 2025-10-16*
+
+This document defines the process for creating survey projects or preliminary repositories for research and proof-of-concept work within the Desktop Team.
+
+## Survey 專案或前期 Repo 建置
+
+### 建立專案位置
+
+在 https://github.com/orgs/Positive-LLC/teams/desktop 底下建立專案
+
+### 專案命名規則
+
+選擇以下其中一種命名方式：
+
+1. **大寫開頭單字或全大寫單字搭配 dash**
+   - Example: `Audio-Capture-Integration-Survey`
+   - Example: `USB-MIDI-Device-Survey`
+
+2. **Camel Case**
+   - Example: `AudioCaptureIntegrationSurvey`
+   - Example: `UsbMidiDeviceSurvey`
+
+### 從現有專案改造
+
+若是從 GitHub 上找到現有的專案來改，請遵循以下步驟：
+
+1. 使用 `git clone` 下載原始專案
+2. 在 Desktop Team 組織下建立新的 repository
+3. 將專案程式碼放到 Desktop Team 底下
+
+**重要**: 確保遵守原始專案的 License 規範
+
+---
+
+## 範例專案
+
+### Survey 專案參考
+
+- [audio-capture-integration-survey](https://github.com/Positive-LLC/audio-capture-integration-survey)
+
+---
+
+## Survey 專案最佳實踐
+
+### README 內容建議
+
+每個 Survey 專案應包含：
+
+1. **Purpose**: 說明調查/研究目的
+2. **Scope**: 研究範圍和限制
+3. **Findings**: 主要發現（研究完成後更新）
+4. **References**: 參考資料和相關連結
+5. **Contributors**: 參與研究的團隊成員
+
+### 專案生命週期
+
+1. **Survey Phase**: 研究和實驗階段
+2. **Documentation**: 記錄發現和結論
+3. **Archive or Integration**:
+   - Archive: 標記為 archived 並保留作為參考
+   - Integration: 整合到正式產品專案中
+
+---
+
+## Related Documentation
+
+- [JIRA Workflow](./jira-process.md) - 如需建立對應的 JIRA ticket
+- [Git Commit Convention](./git-commit.md) - Survey 專案也應遵循 commit 規範
+- [Code Review Process](./code-review.md) - Survey 專案的程式碼審查標準
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: Team Lead for project creation permissions, Tech Lead for survey scope guidance

package/content/docs/knowledge/architecture/README.md

@@ -0,0 +1,11 @@
+# Architecture Patterns
+
+Team-wide architecture patterns and design principles.
+
+## Contents
+
+- [Audio Plugin Architecture](./audio-plugin-architecture.md)
+- [Cross-Platform Design](./cross-platform-design.md)
+- [Frontend-Native Bridge](./frontend-native-bridge.md)
+- [Native Command](./native-command.md)
+- [State Management Architecture](./state-management-architecture.md)