You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* docs: add instruction files consolidation analysis
- Analyzed 5 instruction files for duplication and consolidation opportunities
- Identified 28% duplication across files
- Proposed consolidation strategy reducing to 3 files
- Recommended single source of truth approach with documentation references
* docs: add ADR 004 for agents.md standard investigation
- Document investigation of agents.md standard for AI agent instructions
- Defer adoption pending verification of Claude Code and Copilot support
- Propose interim duplication reduction strategy
- Schedule future research and re-evaluation timeline
* docs: consolidate instruction files and reduce duplication
- Add comprehensive Markdown Standards section to contributing.md as single source of truth
- Update all instruction files to reference contributing.md instead of duplicating standards
- Streamline copilot-instructions.md to quick reference with links to full documentation
- Update CLAUDE.md to reference documentation site and reduce duplication
- Eliminates 28% content duplication across instruction files
- Establishes clear documentation hierarchy and references
* docs: clarify to use local markdown files instead of web URLs
- Update all instruction files to reference local markdown files in docs-site/docs/
- Clarify that web URLs are for human reference only
- AI agents should read from local source files, not fetch from web
- Improves performance and reliability of documentation lookups
- Ensures agents see latest changes including unpushed updates
* docs: update ADR 004 to reject agents.md standard
- Change status from 'Proposed' to 'Rejected'
- Claude Code has official CLAUDE.md standard, not agents.md
- No evidence of agents.md support in Claude Code or GitHub Copilot
- Document successful consolidation approach using references
- Keep door open for future re-evaluation if tool support emerges
* docs: fix broken link in ADR 004 causing Docusaurus build failure
- Remove broken link to instruction-files-analysis.md (outside docs directory)
- Replace with note mentioning file location in repository root
- Docusaurus build now succeeds
* Update .github/copilot-instructions.md
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
* docs: remove instruction-files-analysis.md
- Analysis document no longer needed
- Findings documented in ADR 004
- Consolidation work complete
* docs: add documentation consolidation to v2.6.14 release notes
- Add entry for AI agent instruction files consolidation work
- Eliminates 28% content duplication through reference-based approach
---------
Co-authored-by: Claude <[email protected]>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
> **This is a quick reference for GitHub Copilot.** For comprehensive developer documentation including architecture, code standards, testing strategy, and detailed guidelines:
5
+
> -**Local Documentation**: See markdown files in `docs-site/docs/` directory (these are the source files)
6
+
> -**Web Documentation**: [Teams for Linux Documentation Site](https://ismaelmartinez.github.io/teams-for-linux/) (for human reference)
> **Important**: Read documentation from local markdown files in `docs-site/docs/` rather than fetching from the web.
12
+
3
13
## Project Overview
4
14
5
-
Teams for Linux is an Electron-based desktop application that wraps the Microsoft Teams web app, providing a native desktop experience for Linux users. The app enhances the web version with features like custom CSS, custom backgrounds, system notifications, and deep integration with the desktop environment.
15
+
Teams for Linux is an Electron-based desktop application that wraps the Microsoft Teams web app, providing a native desktop experience for Linux userswith enhanced features like custom CSS, system notifications, and deep desktop integration.
6
16
7
-
## Project Vision & Refactoring Goals
17
+
## Quick Reference
8
18
9
-
The project is currently undergoing a strategic effort to improve its architecture, maintainability, and developer experience. Key goals include:
19
+
### Essential Commands
10
20
11
-
-**Increased Modularity:** Refactoring the monolithic `app/index.js` into smaller, single-responsibility modules (e.g., for IPC handling, command-line parsing, notification management).
12
-
-**Modernization:** Adopting modern JavaScript features (`async/await`, `const`/`let`) and simplifying patterns (e.g., class private fields).
13
-
-**Robustness:** Implementing comprehensive error handling, structured logging, and centralized state management.
14
-
-**Testability:** Introducing a formal testing framework to build a suite of unit and integration tests.
15
-
-**Clarity:** Enhancing documentation across all levels of the project.
21
+
```bash
22
+
npm start # Development mode with trace warnings
23
+
npm run lint # ESLint validation (mandatory before commits)
24
+
npm run test:e2e # End-to-end tests with Playwright
25
+
npm run pack # Development build without packaging
26
+
npm run dist:linux # Build Linux packages (AppImage, deb, rpm, snap)
27
+
```
16
28
17
-
When contributing, please align your changes with these goals.
29
+
### Key File Locations
18
30
19
-
## Architecture & Key Components
31
+
-**Entry Point**: `app/index.js` - Main Electron process (being refactored - avoid adding new code here)
-**Documentation**: `docs-site/docs/` - Docusaurus documentation site
20
36
21
-
### Main Application Structure
37
+
### Code Standards Quick List
22
38
23
-
-**Entry Point**: `app/index.js` - Main Electron process. **Note:** This file is being actively refactored. New functionalities should be placed in separate, dedicated modules rather than being added here directly.
24
-
-**Configuration**: `app/appConfiguration/` - Centralized configuration management. See `docs/configuration.md` for a detailed breakdown of all options.
25
-
-**Main Window**: `app/mainAppWindow/` - Manages the main `BrowserWindow` and the Teams web app wrapper.
26
-
-**Browser Tools**: `app/browser/tools/` - Client-side scripts injected into the Teams web interface.
39
+
- ❌ **NO `var`** - Use `const` by default, `let` for reassignment only
40
+
- ✅ **Use `async/await`** instead of promise chains
41
+
- ✅ **Private fields** - Use JavaScript `#property` syntax for class members
42
+
- ✅ **Arrow functions** for concise callbacks
43
+
- ✅ **Run `npm run lint`** before all commits (mandatory)
27
44
28
-
### Key Documentation
45
+
### Critical Warnings
29
46
30
-
-**Architecture Diagrams**: See `docs/README.md` for visual overviews of the system.
31
-
-**Configuration Details**: See `docs/configuration.md`.
32
-
-**IPC API**: See `docs/ipc-api.md` for a list of all IPC channels.
33
-
-**Module-specific READMEs**: Each subdirectory in `app/` should have a `README.md` explaining its purpose and interactions.
47
+
> [!IMPORTANT]
48
+
> **TrayIconRenderer IPC Initialization** - The `trayIconRenderer` module MUST be included in the IPC initialization list in `app/browser/preload.js`. This has been accidentally removed multiple times in git history. See issue #1902 and CLAUDE.md for details.
34
49
35
-
## Development Patterns
50
+
```javascript
51
+
// REQUIRED in app/browser/preload.js
52
+
if (module.name==="settings"||module.name==="theme"||module.name==="trayIconRenderer"||module.name==="mqttStatusMonitor") {
53
+
moduleInstance.init(config, ipcRenderer);
54
+
}
55
+
```
36
56
37
-
### Configuration Management
57
+
##Project Architecture
38
58
39
-
- All configuration is managed through the `AppConfiguration` class.
40
-
-**Guiding Principle:** Treat the configuration object as immutable after startup. Changes should be managed via methods within `AppConfiguration` to ensure consistency.
41
-
- For class properties, prefer standard JavaScript private fields (`#property`) over `WeakMap` for simplicity and readability.
59
+
```mermaid
60
+
graph TD
61
+
A[app/index.js] --> B[Configuration System]
62
+
A --> C[Window Management]
63
+
A --> D[IPC Handlers]
64
+
A --> E[System Integration]
42
65
43
-
### State Management
66
+
B --> F[config.json Files]
67
+
C --> G[Browser Window]
68
+
D --> H[Renderer Process]
69
+
E --> I[OS Features]
44
70
45
-
- Avoid using global variables.
46
-
- For state shared between modules (e.g., `userStatus`, `aboutBlankRequestCount`), create or use a dedicated state management module to provide controlled access and modification methods.
- IPC API Documentation: `docs-site/docs/development/ipc-api.md`
79
+
- Module-specific READMEs in `app/` subdirectories
49
80
50
-
-**Current State:** IPC is handled via `ipcMain.on` and `ipcMain.handle` calls, primarily in `app/index.js`.
51
-
-**Future Direction:** We are moving towards a centralized event bus or IPC abstraction layer to improve structure and maintainability. New IPC channels should be well-documented in `docs/ipc-api.md`.
81
+
## Development Patterns
52
82
53
-
### Modern JavaScript Practices
83
+
### Configuration Management
54
84
55
-
-**`var` is disallowed.** Use `const` by default and `let` only when a variable must be reassigned.
56
-
- Use `async/await` for all asynchronous operations instead of promise chains (`.then()`).
57
-
- Use arrow functions for concise callbacks.
85
+
- All configuration managed through `AppConfiguration` class
86
+
- Treat config as **immutable after startup**
87
+
- Changes via AppConfiguration methods only
88
+
- See `docs-site/docs/configuration.md` for details
58
89
59
90
### Error Handling & Logging
60
91
61
-
- Implement a robust error handling strategy using `try-catch` blocks in `async` functions.
62
-
- Aim for graceful degradation and provide clear user feedback for errors.
63
-
- Use `electron-log` for structured logging. Ensure log levels are used consistently and avoid logging sensitive information.
64
-
65
-
## Documentation
66
-
67
-
-**A Core Responsibility:** Documentation is not an afterthought; it is a core part of the development process.
68
-
-**Update as You Go:** When you make a code change, update the relevant documentation in the same pull request.
69
-
-**Module READMEs:** Ensure the `README.md` in the module you are working on is up-to-date.
70
-
-**Code Comments:** Add comments sparingly. Focus on the _why_ behind complex, non-obvious, or unusual code, not the _what_. Use JSDoc for public APIs.
71
-
-**Central Docs:** For changes affecting configuration, IPC, or overall architecture, update the corresponding documents in the `/docs` directory.
72
-
73
-
## Documentation Strategy
92
+
- Use try-catch blocks in async functions
93
+
- Aim for graceful degradation
94
+
- Use `electron-log` for structured logging
95
+
- Avoid logging sensitive information
74
96
75
-
The project is transitioning its documentation platform to Docusaurus. This involves:
76
-
- Migrating existing Markdown content to a Docusaurus project structure.
77
-
- Utilizing Docusaurus's built-in features for search, navigation, versioning, and internationalization.
78
-
- Implementing a GitHub Actions workflow for automated build and deployment of the Docusaurus site to GitHub Pages.
79
-
- This shift aims to provide a more robust, feature-rich, and maintainable documentation experience.
80
-
-**Rationale for Docusaurus (vs. MkDocs) for In-App Documentation:** While both generate static sites, Docusaurus's JavaScript/React foundation aligns seamlessly with the project's existing Electron (Node.js/JavaScript) stack. This provides a more cohesive and extensible ecosystem for future development, customization, and potential interaction between the app and its bundled documentation.
97
+
### IPC Communication
81
98
82
-
## Markdown Standards
99
+
- Use `ipcMain.handle` for request-response patterns
100
+
- Use `ipcMain.on` for fire-and-forget notifications
101
+
- Document all new IPC channels in `docs-site/docs/development/ipc-api.md`
83
102
84
-
When creating or updating documentation, leverage existing markdown library features instead of building custom solutions:
103
+
### Defensive Coding
85
104
86
-
-**Table of Contents:** Use GitHub's `<!-- toc -->` element for automatic TOC generation instead of manual lists
87
-
-**Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]`) for important information, warnings, and critical notes
88
-
-**Code Blocks:** Use proper syntax highlighting with language identifiers (e.g., `javascript, `bash)
89
-
-**Tables:** Use standard markdown tables with proper alignment for structured data
90
-
-**Checkboxes:** Use standard GitHub checkbox syntax `- [ ]` and `- [x]` for task tracking and checklists
91
-
-**Links:** Use relative paths for internal documentation links and absolute URLs for external resources
92
-
-**Collapsible Sections:** Use GitHub's `<details>` and `<summary>` elements for optional or lengthy information
93
-
-**Diagrams:** Consider GitHub's Mermaid support for flowcharts, sequence diagrams, and architecture diagrams when applicable
105
+
- Browser scripts must be defensive - Teams DOM can change without notice
106
+
- Implement proper null checks and error handling
107
+
- Test across different platforms when possible
94
108
95
-
## Build & Development
109
+
## Testing & Quality
96
110
97
-
### Key Commands
111
+
-**Linting**: Run `npm run lint` before commits (mandatory)
112
+
-**E2E Tests**: Run `npm run test:e2e` - each test uses clean state
113
+
-**Manual Testing**: Use `npm start` for development testing
114
+
-**CI/CD**: GitHub Actions validates all PRs
98
115
99
-
```bash
100
-
npm start # Development mode with trace warnings
101
-
npm run lint # ESLint validation
102
-
npm run dist:linux # Build Linux packages (AppImage, deb, rpm, snap)
103
-
npm run pack # Development build without packaging
104
-
```
116
+
For testing strategy details, see `docs-site/docs/development/contributing.md` (Testing section)
105
117
106
-
### Build Configuration
118
+
##Documentation
107
119
108
-
-**electron-builder** config in `package.json` under the `"build"` section.
109
-
- Release process is automated via GitHub Actions (`.github/workflows/build.yml`).
120
+
> [!IMPORTANT]
121
+
> **Documentation is a core responsibility** - update relevant documentation in the same PR as code changes.
110
122
111
-
##Testing & Quality
123
+
### What to Update
112
124
113
-
-**Linting**: ESLint with custom config (`eslint.config.mjs`) is mandatory.
114
-
-**Security**: Snyk and CodeQL for vulnerability scanning.
115
-
-**CI/CD**: GitHub Actions for build validation and releases.
116
-
-**Unit & Integration Testing**: The project currently lacks sufficient test coverage. A key goal is to introduce a testing framework (e.g., Jest) and build out a comprehensive test suite. Contributions in this area are highly encouraged.
125
+
-**Module READMEs**: Update when changing module functionality
126
+
-**IPC Documentation**: Document new IPC channels in `docs-site/docs/development/ipc-api.md`
127
+
-**Architecture Docs**: Update for architectural changes
128
+
-**Configuration**: Document new config options in `docs-site/docs/configuration.md`
129
+
-**ADRs**: Create Architecture Decision Records for significant technical decisions in `docs-site/docs/development/adr/`
117
130
118
-
##Common Patterns
131
+
### Documentation Platform
119
132
120
-
-**Single Instance**: The app uses `app.requestSingleInstanceLock()` to ensure only one instance is running.
121
-
-**Command Line Switches**: The app processes various command-line switches. Logic for this is being centralized from `app/index.js` into a dedicated module.
122
-
-**Defensive Coding:** Browser scripts should be written defensively, as the Teams web app DOM can change without notice.
133
+
The project uses **Docusaurus** for documentation:
134
+
-**Source Files**: All documentation is in `docs-site/docs/` directory
135
+
-**Local Development**: `cd docs-site && npm run start`
136
+
-**Deployment**: Automated via GitHub Actions to GitHub Pages
137
+
-**Search**: Client-side search using @easyops-cn/docusaurus-search-local
138
+
-**Standards**: See `docs-site/docs/development/contributing.md` (Markdown Standards section)
123
139
124
140
## External Dependencies
125
141
@@ -128,4 +144,18 @@ npm run pack # Development build without packaging
-**Audio**: node-sound (optional, for notification sounds)
130
146
131
-
When working on this codebase, always consider cross-platform compatibility and the fact that the Teams web interface can change independently of this application.
Copy file name to clipboardExpand all lines: .github/instructions/create-prd.instructions.md
+1-8Lines changed: 1 addition & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -64,14 +64,7 @@ Assume the primary reader of the PRD is a **junior developer**. Therefore, requi
64
64
65
65
## Markdown Standards
66
66
67
-
When creating PRDs, leverage existing markdown library features instead of building custom solutions:
68
-
69
-
-**Table of Contents:** Use GitHub's `<!-- toc -->` element for automatic TOC generation instead of manual lists
70
-
-**Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, etc.) for important information
71
-
-**Code Blocks:** Use proper syntax highlighting with language identifiers
72
-
-**Tables:** Use standard markdown tables with proper alignment
73
-
-**Links:** Use relative paths for internal documentation links
74
-
-**Diagrams:** Consider GitHub's Mermaid support for flowcharts and diagrams when applicable
67
+
For comprehensive markdown standards, see the Markdown Standards section in `docs-site/docs/development/contributing.md` (the source file for the [web documentation](https://ismaelmartinez.github.io/teams-for-linux/development/contributing#markdown-standards)).
Copy file name to clipboardExpand all lines: .github/instructions/generate-tasks.instructions.md
+1-9Lines changed: 1 addition & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -124,15 +124,7 @@ This section captures enhancements and non-critical features that could be imple
124
124
125
125
## Markdown Standards
126
126
127
-
When creating task lists, leverage existing markdown library features instead of building custom solutions:
128
-
129
-
-**Table of Contents:** Use GitHub's `<!-- toc -->` element for automatic TOC generation if task list becomes long
130
-
-**Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]`) for critical information
131
-
-**Code Blocks:** Use proper syntax highlighting with language identifiers for commands and code snippets
132
-
-**Tables:** Use standard markdown tables for structured data comparison
133
-
-**Checkboxes:** Use standard GitHub checkbox syntax `- [ ]` and `- [x]` for task tracking
134
-
-**Links:** Use relative paths for internal documentation and issue references
135
-
-**Diagrams:** Consider GitHub's Mermaid support for complex workflow or architecture diagrams when helpful
127
+
For comprehensive markdown standards, see the Markdown Standards section in `docs-site/docs/development/contributing.md` (the source file for the [web documentation](https://ismaelmartinez.github.io/teams-for-linux/development/contributing#markdown-standards)).
Copy file name to clipboardExpand all lines: .github/instructions/process-tasks-list.instructions.md
+1-8Lines changed: 1 addition & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,14 +70,7 @@ Guidelines for managing task lists in markdown files to track progress on comple
70
70
71
71
## Markdown Standards
72
72
73
-
When updating task lists, leverage existing markdown library features instead of building custom solutions:
74
-
75
-
- **Checkboxes:** Use standard GitHub checkbox syntax `- [ ]` and `- [x]` for task progress tracking
76
-
- **Callouts:** Use GitHub's alert syntax (`> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]`) for important status updates or warnings
77
-
- **Code Blocks:** Use proper syntax highlighting for commands, file paths, and code snippets
78
-
- **Tables:** Use standard markdown tables for structured status reporting or file listings
79
-
- **Links:** Use relative paths for internal documentation and absolute URLs for external resources
80
-
- **Collapsible Sections:** Use GitHub's `<details>` elements for optional or lengthy information
73
+
For comprehensive markdown standards, see the Markdown Standards section in `docs-site/docs/development/contributing.md` (the source file for the [web documentation](https://ismaelmartinez.github.io/teams-for-linux/development/contributing#markdown-standards)).
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?v=4&size=40){kind=avatar}
0 commit comments