Feature/add copilot instructions

.github/instructions/DnR-protocol.md

@@ -0,0 +1,54 @@
+## Deconstruction & Re-architecture Protocol (D&R)
+
+Mục đích
+- D&R là một quy trình 3 giai đoạn để phân tích mọi input (từ một từ tới bản kế hoạch) và chuyển đổi thành các hành động có thể triển khai, an toàn và bền vững.
+
+Giai đoạn 1 — Phân rã & Hệ thống hóa (Deconstruct)
+- Mục tiêu: tách input thành các thành phần cơ bản để loại bỏ nhiễu và từng bước chuẩn hóa dữ liệu.
+- Yêu cầu đầu vào tối thiểu (Input Metadata): who, when, context, summary (1 câu), constraints.
+- Output: danh sách facts, assumptions, constraints, stakeholders.
+
+Giai đoạn 2 — Xác định Trọng tâm (Focal)
+- Mục tiêu: từ các thành phần đã chuẩn hoá, rút ra tối đa 3 trọng tâm theo tiêu chí impact × confidence.
+- Với mỗi trọng tâm cần ghi: lý do ngắn (1 câu), dữ liệu/chứng cứ (nếu có), mức độ ưu tiên (cao/trung/bình).
+
+Giai đoạn 3 — Tái kiến tạo & Tối ưu (Re-architect)
+- Mục tiêu: cho mỗi trọng tâm, đề xuất một Action Card (giải pháp chính + dự phòng) tuân thủ 4 nguyên tắc: Đơn giản, Hiệu quả, Thực dụng, An toàn.
+- Action Card (mẫu):
+  - Tiêu đề:
+  - Mô tả ngắn (1-2 câu):
+  - Giải pháp chính:
+  - Giải pháp dự phòng:
+  - 3 bước triển khai (từng bước rõ ràng):
+  - Ước lượng (effort, risk):
+  - Success metrics (1–2 chỉ số):
+
+Socratic Gate (Kiểm soát chất lượng trước khi chạy)
+- Trước khi triển khai, trả lời 1 câu hỏi Socratic trọng tâm (ví dụ: "Giả định nào nếu sai sẽ khiến giải pháp thất bại?") và hoàn thành checklist an toàn tối thiểu.
+- Checklist an toàn (bắt buộc):
+  1. Data-safety: dữ liệu nhạy cảm đã được xử lý/ẩn chưa?
+  2. Rollback plan: có kế hoạch hoàn tác nếu có lỗi không?
+  3. Monitoring: có chỉ số/alert để phát hiện sự cố không?
+
+Nguyên tắc vận hành
+- Ghi rõ mọi giả định; nếu thiếu dữ liệu then chốt, dừng và yêu cầu ít nhất 2 thông tin bổ sung.
+- Mỗi đề xuất phải có evidence hoặc một bước kiểm chứng nhanh (smoke test) trước khi triển khai rộng.
+
+Ví dụ ví dụ ngắn (áp dụng cho "tối ưu build" nhanh)
+- Input Metadata: who=devops, when=2025-10-24, summary="Build chậm", constraints="không thay đổi CI cloud".
+- Phân rã: tsc full compile, webpack bundle, network download packages.
+- Trọng tâm (Top1): Reduce full TypeScript compile time (impact cao × confidence trung).
+- Action Card: enable tsc incremental + cache tsc output; Steps: 1) bật --incremental config; 2) add cache dir to CI; 3) monitor compile time.
+- Socratic question: Nếu incremental cache bị corrupt, rollback thế nào? Trả lời: revert config và clear cache; CI vẫn chạy full compile.
+
+How to use
+- Khi muốn áp dụng D&R cho một mục tiêu, copy template "Input Metadata" vào comment/issue PR và gọi agent để trả về: (1) Phân rã, (2) Top 3 trọng tâm, (3) Action Cards cho từng trọng tâm, (4) Socratic Gate answers + checklist.
+
+Vị trí lưu & giao tiếp
+- File này là bản canonical; nếu muốn tích hợp template vào scaffolding project, đặt `files/templates/DnR-template.md` hoặc thêm vào generator trong `src/features/creators`.
+
+Cam kết
+- Mọi thay đổi code/commit/push sau khi D&R phải được bạn xác nhận tối thiểu 3 điểm (data-safety, rollback, monitoring).
+
+---
+Created by AI assistant on branch `feature/add-copilot-instructions` — không push lên remote tự động.

.github/instructions/copilot-instructions.md

@@ -0,0 +1,52 @@
+## Copilot / AI contributor instructions — vscode-python-environments
+
+Quick, actionable notes to get an AI agent productive in this repository.
+
+- Project type: VS Code extension written in TypeScript. Source under `src/` → built with `webpack` into `./dist/extension.js` (see `package.json` `main`).
+- Entry points & API: primary extension code in `src/extension.ts` and public API surface in `src/api.ts` and `src/internal.api.ts`.
+- Key directories: `src/` (core), `src/common/` (shared utilities like `localize.ts`, `logging.ts`), `managers/` (env managers), `features/` (functional areas), `examples/` (consumers), `files/templates/` (scaffolding including copilot templates).
+
+Build / test / run
+- Build for development: `npm run compile` (uses `webpack`).
+- Watch (dev): `npm run watch` (webpack watch). There is also `npm run watch-tests` (TypeScript watch for tests) and a compound VS Code task `tasks: build` that runs both watchers.
+- Compile TypeScript for tests: `npm run compile-tests` (tsc output -> `out`). `npm run pretest` runs `compile-tests` and `compile`.
+- Unit tests: `npm run unittest` (Mocha with `build/.mocha.unittests.json`). Run `npm run pretest` first if you need a fresh build.
+- Package: `npm run vsce-package` to create a VSIX (requires `vsce`).
+
+Important repo conventions & patterns
+- Localization: All user-facing strings must use the l10n/localize system. See `src/common/localize.ts` and the `l10n` folder. Do not hard-code English strings in UI code.
+- Logging: Use the extension logging utilities (`traceLog`, `traceVerbose`) in `src/common/logging.ts`. Avoid `console.log` for internal logs.
+- Settings precedence: code assumes VS Code settings precedence (folder → workspace → user). See `.github/instructions/generic.instructions.md` for details.
+- Error/UI messages: keep messages actionable and avoid spamming the same message. The repo tracks state to avoid repeated alerts (follow patterns in `src/common/persistentState.ts`).
+
+Where to change behavior
+- Contribution points are defined in `package.json` (`activationEvents`, `contributes.commands`, `configuration`). To add a new command, update `package.json` and implement command registration in `src/extension.ts` or `src/common/commands.ts`.
+- Entry build output is `./dist/extension.js`. Small runtime changes should still be made in `src/` and then built (or tested using `tsc`/`webpack` watchers).
+
+Examples & idioms for code edits
+- Add localized strings: put key in `package.nls.json`/`l10n` and use `localize('key', 'Default text')` in code.
+- Add telemetry/logging: use helpers in `src/common/telemetry/*` and `traceLog('message', { meta })` from `logging.ts`.
+- Tests: unit tests live under `test/`; many tests use mocha + sinon/typemoq/ts-mockito patterns. See `test/unittests.ts` for test harness patterns.
+
+Integration points & external deps
+- Depends on the Python extension (`ms-python.python`) contractually for some features; activation is `onLanguage:python` (see `package.json`).
+- Uses `@vscode/test-electron` and `@vscode/test-cli` in dev/test workflows.
+- Uses common node deps: `fs-extra`, `dotenv`, `@iarna/toml`, etc.
+
+When making PRs as an AI
+- Keep changes small and focused; follow existing file-level patterns (naming, async/await use, error handling helpers in `src/common/errors`).
+- Add docstrings to exported functions (see `.github/instructions/generic.instructions.md`).
+- Add localization for any user-visible string.
+- Run `npm run lint` and `npm run unittest` (or at minimum `npm run compile-tests` + `npm run compile`) before proposing changes.
+
+References (where to look)
+- `src/` for implementation details and patterns
+- `test/` for unit test examples
+- `files/templates/copilot-instructions-text/` contains example copilot templates you can reuse
+- `package.json` for scripts and contribution points
+- `.github/instructions/generic.instructions.md` for project-specific coding rules (localization, logging, docstrings)
+
+If something is unclear, ask: give the file you intend to edit and a 1–2 line summary of the change. Prefer small incremental PRs.
+
+---
+Generated/merged automatically by the AI agent. Ask for edits or to expand examples for a specific subfolder.

.github/instructions/generic.instructions.md

@@ -0,0 +1,32 @@
+---
+applyTo: '**'
+---
+
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.# Coding Instructions for vscode-python-environments
+
+## Localization
+
+-   Localize all user-facing messages using VS Code’s `l10n` API.
+-   Internal log messages do not require localization.
+
+## Logging
+
+-   Use the extension’s logging utilities (`traceLog`, `traceVerbose`) for internal logs.
+-   Do not use `console.log` or `console.warn` for logging.
+
+## Settings Precedence
+
+-   Always consider VS Code settings precedence:
+    1. Workspace folder
+    2. Workspace
+    3. User/global
+-   Remove or update settings from the highest precedence scope first.
+
+## Error Handling & User Notifications
+
+-   Avoid showing the same error message multiple times in a session; track state with a module-level variable.
+-   Use clear, actionable error messages and offer relevant buttons (e.g., "Open settings", "Close").
+
+## Documentation
+
+-   Add clear docstrings to public functions, describing their purpose, parameters, and behavior.

.github/instructions/issue-format.instructions.md

@@ -0,0 +1,84 @@
+---
+applyTo: '**/github-issues/**'
+---
+
+# Guidelines for Creating Effective GitHub Issues
+
+## Issue Format
+
+When creating GitHub issues, use the following structure to ensure clarity and ease of verification:
+
+### For Bug Reports
+
+1. **Title**: Concise description of the issue (5-10 words)
+
+2. **Problem Statement**:
+
+    - 1-2 sentences describing the issue
+    - Focus on user impact
+    - Use clear, non-technical language when possible
+
+3. **Steps to Verify Fix**:
+    - Numbered list (5-7 steps maximum)
+    - Start each step with an action verb
+    - Include expected observations
+    - Cover both success paths and cancellation/back button scenarios
+
+### For Feature Requests
+
+1. **Title**: Clear description of the requested feature
+
+2. **Need Statement**:
+
+    - 1-2 sentences describing the user need
+    - Explain why this feature would be valuable
+
+3. **Acceptance Criteria**:
+    - Bulleted list of verifiable behaviors
+    - Include how a user would confirm the feature works as expected
+
+## Examples
+
+### Bug Report Example
+
+```
+# Terminal opens prematurely with PET Resolve Environment command
+
+**Problem:** When using "Resolve Environment..." from the Python Environment Tool menu,
+the terminal opens before entering a path, creating a confusing workflow.
+
+**Steps to verify fix:**
+1. Run "Python Environments: Run Python Environment Tool in Terminal" from Command Palette
+2. Select "Resolve Environment..."
+3. Verify no terminal opens yet
+4. Enter a Python path
+5. Verify terminal only appears after path entry
+6. Try canceling at the input step - confirm no terminal appears
+```
+
+### Feature Request Example
+
+```
+# Add back button support to multi-step UI flows
+
+**Problem:** The UI flows for environment creation and Python project setup lack back button
+functionality, forcing users to cancel and restart when they need to change a previous selection.
+
+**Steps to verify implementation:**
+1. Test back button in PET workflow: Run "Python Environments: Run Python Environment Tool in Terminal",
+   select "Resolve Environment...", press back button, confirm it returns to menu
+2. Test back button in VENV creation: Run "Create environment", select VENV, press back button at various steps
+3. Test back button in CONDA creation: Create CONDA environment, use back buttons to navigate between steps
+4. Test back button in Python project flow: Add Python project, verify back functionality in project type selection
+```
+
+## Best Practices
+
+1. **Be concise**: Keep descriptions short but informative
+2. **Use active voice**: "Terminal opens prematurely" rather than "The terminal is opened prematurely"
+3. **Include context**: Mention relevant commands, UI elements, and workflows
+4. **Focus on verification**: Make steps actionable and observable
+5. **Cover edge cases**: Include cancellation paths and error scenarios
+6. **Use formatting**: Bold headings and numbered lists improve readability
+
+Remember that good issues help both developers fixing problems and testers verifying solutions.