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
Default agent behavior: when intent is ambiguous in this repo, proceed in **library mode** and ask clarifying questions only if strong CLI/service signals appear.
16
+
17
+
## Copilot Fast Path (Read First)
18
+
19
+
Use this file to optimize for safe, high-quality, low-friction contributions in this Node.js module template.
20
+
21
+
- Build for a **library package**, not a CLI or long-running app.
22
+
- Use **ESM only** (`import` / `export`) and follow neostandard style.
23
+
- Write JavaScript with **clear JSDoc types** so declarations can be generated and type-checked.
24
+
- Keep `index.js` minimal and focused on re-exports from `lib/`.
25
+
- Start with **local repository context first** (existing code + tests), then use MCP tools when external/current guidance is needed.
26
+
- Validate before finishing: run checks/tests (`npm test` or equivalent scoped checks).
27
+
- When behavior, scope, or risk is unclear, ask clarifying questions early instead of guessing.
28
+
29
+
## Priority Rules: MUST, SHOULD, ASK FIRST, NEVER
30
+
31
+
If rules conflict, follow `MUST` over `SHOULD`. If uncertainty remains, use `ask_questions` before making risky changes.
32
+
33
+
### MUST
34
+
35
+
- Use ESM syntax only; do not introduce CommonJS.
36
+
- Keep changes minimal, targeted, and consistent with existing file structure and style.
37
+
- Add or update tests when behavior changes.
38
+
- Validate changes with lint/type/test checks before finalizing.
39
+
- Prefer local patterns first; use MCP research for unknown APIs, external docs, and non-obvious decisions.
40
+
41
+
### SHOULD
42
+
43
+
- Prefer built-in Node.js APIs and avoid unnecessary dependencies.
44
+
- Keep functions small, explicit, and documented with JSDoc.
45
+
- Ask multiple focused MCP questions (2–4) rather than one broad question for unfamiliar domains.
46
+
- Explain non-obvious implementation choices briefly in comments or PR notes.
47
+
48
+
### ASK FIRST
49
+
50
+
- Adding or replacing runtime dependencies.
51
+
- Changing public API shape, exported names, or package entry points.
52
+
- Large refactors, file moves, or renames beyond the immediate task.
53
+
- Disabling checks, removing tests, or altering CI-related behavior.
54
+
55
+
### NEVER
56
+
57
+
- Mix module systems (`require` / `module.exports` in runtime code).
58
+
- Bypass failing checks silently or claim validation that was not run.
59
+
- Commit auto-generated declaration artifacts that repository policy says not to commit.
60
+
- Guess requirements when clarification can be obtained quickly.
61
+
3
62
## Overview
4
63
5
64
This repository is a **template for creating Node.js library modules** - packages that provide reusable functionality to other projects. It implements best practices for modern Node.js module development with TypeScript types in JavaScript, ESM modules, and comprehensive testing.
@@ -11,78 +70,84 @@ Use this template when creating:
11
70
-**Shared code modules** used across multiple projects
12
71
-**Packages with no CLI or server components**
13
72
14
-
### Related Templates
73
+
### Project Snapshot (Architecture + Workflow)
15
74
16
-
Consider these alternatives depending on your project type:
75
+
-`index.js` re-exports from `lib/main.js`; keep entrypoint surface minimal.
- Building web servers, REST APIs, or GraphQL services
44
-
- Creating background workers or daemons
45
-
- Need long-running processes or services
46
-
47
-
### Project Architecture
48
-
49
-
```mermaid
50
-
graph LR
51
-
A[index.js] -->|exports| B[lib/main.js]
52
-
B --> C[Implementation]
53
-
D[index.d.ts] -->|types| C
54
-
E[test/*.spec.js] -->|validates| C
55
-
56
-
F[TypeScript] -->|generates| D
57
-
G[ESLint] -->|validates| C
58
-
H[Mocha+Chai] -->|runs| E
59
-
60
-
style A fill:#FFE4B5
61
-
style D fill:#E0BBE4
62
-
style E fill:#B4E7CE
63
-
```
82
+
## MCP-Assisted Research Workflow for Copilot
64
83
65
-
### Development Workflow
66
-
67
-
```mermaid
68
-
sequenceDiagram
69
-
participant Dev as Developer
70
-
participant Git as Git Hooks
71
-
participant CI as GitHub Actions
72
-
73
-
Dev->>Dev: Make code changes
74
-
Dev->>Dev: npm test (local)
75
-
Dev->>Git: git commit
76
-
Git->>Git: Run husky hooks
77
-
Git->>Dev: ✓ Hooks passed
78
-
Dev->>CI: git push
79
-
CI->>CI: Run lint workflow
80
-
CI->>CI: Run test workflow
81
-
CI->>CI: Run TypeScript checks
82
-
CI->>Dev: ✓ All checks passed
83
-
```
84
+
Use MCP tools proactively to improve implementation quality and speed, especially when working with unfamiliar dependencies, protocols, or external systems.
84
85
85
-
---
86
+
### Working Pattern (Strong Advisory)
87
+
88
+
1.**Start local first**
89
+
- Read relevant files and tests in this repository first.
90
+
- Confirm existing patterns before introducing new approaches.
91
+
92
+
2.**Use MCP for uncertainty or external knowledge**
93
+
- If the task depends on current docs, ecosystem practices, or repository-specific behavior not obvious from local code, default to MCP research before coding.
94
+
- Ask multiple targeted questions (typically 2–4) instead of one broad question.
95
+
96
+
3.**Clarify ambiguities before implementation**
97
+
- If requirements, scope, or expected behavior are unclear, use `ask_questions` early rather than guessing.
98
+
99
+
4.**Apply and verify**
100
+
- Convert findings into concrete code and tests.
101
+
- Validate with linting, type checks, and test runs.
102
+
103
+
### Tool Selection by Trigger
104
+
105
+
| Trigger | Prefer | Example Outcome | Provider |
106
+
|------|------|-----------------|
107
+
| Need current external facts or docs |`tavily_search`| Find authoritative and up-to-date references | Tavily MCP server |
108
+
| Need structured content from a specific URL |`tavily_extract`| Pull relevant sections from docs/pages for implementation details | Tavily MCP server |
109
+
| Need repository-specific architectural or usage guidance |`ask_question`| Get targeted answers grounded in a repository's docs/wiki | DeepWiki MCP server |
110
+
| Requirements or assumptions are ambiguous |`askQuestion`| Resolve uncertainty before making code changes | VSCode built in tool |
111
+
112
+
### Example MCP Usage Scenarios
113
+
114
+
| Scenario | Use this tool (or sequence) | Example prompt | What to do with result |
115
+
|---|---|---|---|
116
+
| Integrating a new library and you need current best practices |`tavily_search`| "Latest best practices for validating unknown JSON in Node.js ESM libraries" | Use results to select a validation approach and reflect it in code + tests |
117
+
| You already have official docs URL and need implementation details |`tavily_extract`| "Extract sections on authentication middleware options and error handling" | Translate extracted sections into concrete function signatures and edge-case tests |
118
+
| You need repository-specific guidance before using a dependency |`ask_question`| "In owner/repo, which helpers are recommended for nested object access and type guards?" | Prefer repository-recommended utilities over custom ad hoc implementations |
119
+
| Acceptance criteria are unclear before coding |`askQuestion`| "Should invalid input throw, return null, or return Result-style errors?" | Lock behavior expectations first, then implement to that contract |
0 commit comments