@abarcenas/ai-workflow-template 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/.github/agents/implementation-plan.agent.md +192 -0
  2. package/.github/agents/plan.agent.md +135 -0
  3. package/.github/agents/research-spike.agent.md +204 -0
  4. package/.github/instructions/agent-safety.instructions.md +98 -0
  5. package/.github/instructions/agent-skill.instructions.md +272 -0
  6. package/.github/instructions/agent.instructions.md +1068 -0
  7. package/.github/instructions/ai-prompt-engineering-safety.instructions.md +991 -0
  8. package/.github/instructions/angular.instructions.md +116 -0
  9. package/.github/instructions/context7.instructions.md +109 -0
  10. package/.github/instructions/go.instructions.md +374 -0
  11. package/.github/instructions/html-to-css-guide.instructions.md +104 -0
  12. package/.github/instructions/instructions.instructions.md +264 -0
  13. package/.github/instructions/markdown.instructions.md +51 -0
  14. package/.github/instructions/memory-bank.instructions.md +322 -0
  15. package/.github/instructions/nodejs-vitest.instructions.md +34 -0
  16. package/.github/instructions/playwright-typescript.instructions.md +88 -0
  17. package/.github/instructions/prompt.instructions.md +99 -0
  18. package/.github/instructions/security-owasp.instructions.md +59 -0
  19. package/.github/instructions/shell.instructions.md +132 -0
  20. package/.github/instructions/task-implementation.instructions.md +203 -0
  21. package/.github/instructions/typescript.instructions.md +114 -0
  22. package/.github/prompts/copilot-instructions-blueprint-generator.prompt.md +317 -0
  23. package/.github/prompts/documentation-writer.prompt.md +46 -0
  24. package/.github/prompts/editconfig.prompt.md +64 -0
  25. package/.github/prompts/playwright-explore.prompt.md +39 -0
  26. package/.github/prompts/playwright-generate-test.prompt.md +39 -0
  27. package/.github/skills/agent-governance/SKILL.md +572 -0
  28. package/.github/skills/boost-prompt/SKILL.md +25 -0
  29. package/.github/skills/chrome-devtools/SKILL.md +97 -0
  30. package/.github/skills/context-map/SKILL.md +57 -0
  31. package/.github/skills/conventional-commit/SKILL.md +72 -0
  32. package/.github/skills/create-readme/SKILL.md +21 -0
  33. package/.github/skills/editorconfig/SKILL.md +63 -0
  34. package/.github/skills/gh-cli/SKILL.md +2188 -0
  35. package/.github/skills/git-commit/SKILL.md +124 -0
  36. package/.github/skills/github-issues/SKILL.md +134 -0
  37. package/.github/skills/github-issues/references/templates.md +110 -0
  38. package/.github/skills/microsoft-docs/SKILL.md +114 -0
  39. package/.github/skills/playwright-explore-website/SKILL.md +17 -0
  40. package/.github/skills/playwright-generate-test/SKILL.md +17 -0
  41. package/.github/skills/polygot-test-agent/SKILL.md +171 -0
  42. package/.github/skills/polygot-test-agent/unit-test-genearation.prompt.md +155 -0
  43. package/.github/skills/prompt-builder/SKILL.md +159 -0
  44. package/.github/workflows/npm-publish.yml +25 -0
  45. package/README.md +111 -0
  46. package/package.json +32 -0
  47. package/scripts/bump-version.js +29 -0
  48. package/scripts/sync.js +122 -0
@@ -0,0 +1,322 @@
1
+ ---
2
+ applyTo: "**"
3
+ ---
4
+
5
+ Coding standards, domain knowledge, and preferences that AI should follow.
6
+
7
+ # Memory Bank
8
+
9
+ You are an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.
10
+
11
+ ## Memory Bank Structure
12
+
13
+ The Memory Bank consists of required core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:
14
+
15
+ ```mermaid
16
+ flowchart TD
17
+ PB[projectbrief.md] --> PC[productContext.md]
18
+ PB --> SP[systemPatterns.md]
19
+ PB --> TC[techContext.md]
20
+
21
+ PC --> AC[activeContext.md]
22
+ SP --> AC
23
+ TC --> AC
24
+
25
+ AC --> P[progress.md]
26
+ AC --> TF[tasks/ folder]
27
+ ```
28
+
29
+ ### Core Files (Required)
30
+
31
+ 1. `projectbrief.md`
32
+ - Foundation document that shapes all other files
33
+ - Created at project start if it doesn't exist
34
+ - Defines core requirements and goals
35
+ - Source of truth for project scope
36
+
37
+ 2. `productContext.md`
38
+ - Why this project exists
39
+ - Problems it solves
40
+ - How it should work
41
+ - User experience goals
42
+
43
+ 3. `activeContext.md`
44
+ - Current work focus
45
+ - Recent changes
46
+ - Next steps
47
+ - Active decisions and considerations
48
+
49
+ 4. `systemPatterns.md`
50
+ - System architecture
51
+ - Key technical decisions
52
+ - Design patterns in use
53
+ - Component relationships
54
+
55
+ 5. `techContext.md`
56
+ - Technologies used
57
+ - Development setup
58
+ - Technical constraints
59
+ - Dependencies
60
+
61
+ 6. `progress.md`
62
+ - What works
63
+ - What's left to build
64
+ - Current status
65
+ - Known issues
66
+
67
+ 7. `tasks/` folder
68
+ - Contains individual markdown files for each task
69
+ - Each task has its own dedicated file with format `TASKID-taskname.md`
70
+ - Includes task index file (`_index.md`) listing all tasks with their statuses
71
+ - Preserves complete thought process and history for each task
72
+
73
+ ### Additional Context
74
+
75
+ Create additional files/folders within memory-bank/ when they help organize:
76
+
77
+ - Complex feature documentation
78
+ - Integration specifications
79
+ - API documentation
80
+ - Testing strategies
81
+ - Deployment procedures
82
+
83
+ ## Core Workflows
84
+
85
+ ### Plan Mode
86
+
87
+ ```mermaid
88
+ flowchart TD
89
+ Start[Start] --> ReadFiles[Read Memory Bank]
90
+ ReadFiles --> CheckFiles{Files Complete?}
91
+
92
+ CheckFiles -->|No| Plan[Create Plan]
93
+ Plan --> Document[Document in Chat]
94
+
95
+ CheckFiles -->|Yes| Verify[Verify Context]
96
+ Verify --> Strategy[Develop Strategy]
97
+ Strategy --> Present[Present Approach]
98
+ ```
99
+
100
+ ### Act Mode
101
+
102
+ ```mermaid
103
+ flowchart TD
104
+ Start[Start] --> Context[Check Memory Bank]
105
+ Context --> Update[Update Documentation]
106
+ Update --> Rules[Update instructions if needed]
107
+ Rules --> Execute[Execute Task]
108
+ Execute --> Document[Document Changes]
109
+ ```
110
+
111
+ ### Task Management
112
+
113
+ ```mermaid
114
+ flowchart TD
115
+ Start[New Task] --> NewFile[Create Task File in tasks/ folder]
116
+ NewFile --> Think[Document Thought Process]
117
+ Think --> Plan[Create Implementation Plan]
118
+ Plan --> Index[Update _index.md]
119
+
120
+ Execute[Execute Task] --> Update[Add Progress Log Entry]
121
+ Update --> StatusChange[Update Task Status]
122
+ StatusChange --> IndexUpdate[Update _index.md]
123
+ IndexUpdate --> Complete{Completed?}
124
+ Complete -->|Yes| Archive[Mark as Completed]
125
+ Complete -->|No| Execute
126
+ ```
127
+
128
+ ## Documentation Updates
129
+
130
+ Memory Bank updates occur when:
131
+
132
+ 1. Discovering new project patterns
133
+ 2. After implementing significant changes
134
+ 3. When user requests with **update memory bank** (MUST review ALL files)
135
+ 4. When context needs clarification
136
+
137
+ ```mermaid
138
+ flowchart TD
139
+ Start[Update Process]
140
+
141
+ subgraph Process
142
+ P1[Review ALL Files]
143
+ P2[Document Current State]
144
+ P3[Clarify Next Steps]
145
+ P4[Update instructions]
146
+
147
+ P1 --> P2 --> P3 --> P4
148
+ end
149
+
150
+ Start --> Process
151
+ ```
152
+
153
+ Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md, progress.md, and the tasks/ folder (including \_index.md) as they track current state.
154
+
155
+ ## Project Intelligence (instructions)
156
+
157
+ The instructions files are my learning journal for each project. It captures important patterns, preferences, and project intelligence that help me work more effectively. As I work with you and the project, I'll discover and document key insights that aren't obvious from the code alone.
158
+
159
+ ```mermaid
160
+ flowchart TD
161
+ Start{Discover New Pattern}
162
+
163
+ subgraph Learn [Learning Process]
164
+ D1[Identify Pattern]
165
+ D2[Validate with User]
166
+ D3[Document in instructions]
167
+ end
168
+
169
+ subgraph Apply [Usage]
170
+ A1[Read instructions]
171
+ A2[Apply Learned Patterns]
172
+ A3[Improve Future Work]
173
+ end
174
+
175
+ Start --> Learn
176
+ Learn --> Apply
177
+ ```
178
+
179
+ ### What to Capture
180
+
181
+ - Critical implementation paths
182
+ - User preferences and workflow
183
+ - Project-specific patterns
184
+ - Known challenges
185
+ - Evolution of project decisions
186
+ - Tool usage patterns
187
+
188
+ The format is flexible - focus on capturing valuable insights that help me work more effectively with you and the project. Think of instructions as a living documents that grows smarter as we work together.
189
+
190
+ ## Tasks Management
191
+
192
+ The `tasks/` folder contains individual markdown files for each task, along with an index file:
193
+
194
+ - `tasks/_index.md` - Master list of all tasks with IDs, names, and current statuses
195
+ - `tasks/TASKID-taskname.md` - Individual files for each task (e.g., `TASK001-implement-login.md`)
196
+
197
+ ### Task Index Structure
198
+
199
+ The `_index.md` file maintains a structured record of all tasks sorted by status:
200
+
201
+ ```markdown
202
+ # Tasks Index
203
+
204
+ ## In Progress
205
+
206
+ - [TASK003] Implement user authentication - Working on OAuth integration
207
+ - [TASK005] Create dashboard UI - Building main components
208
+
209
+ ## Pending
210
+
211
+ - [TASK006] Add export functionality - Planned for next sprint
212
+ - [TASK007] Optimize database queries - Waiting for performance testing
213
+
214
+ ## Completed
215
+
216
+ - [TASK001] Project setup - Completed on 2025-03-15
217
+ - [TASK002] Create database schema - Completed on 2025-03-17
218
+ - [TASK004] Implement login page - Completed on 2025-03-20
219
+
220
+ ## Abandoned
221
+
222
+ - [TASK008] Integrate with legacy system - Abandoned due to API deprecation
223
+ ```
224
+
225
+ ### Individual Task Structure
226
+
227
+ Each task file follows this format:
228
+
229
+ ```markdown
230
+ # [Task ID] - [Task Name]
231
+
232
+ **Status:** [Pending/In Progress/Completed/Abandoned]
233
+ **Added:** [Date Added]
234
+ **Updated:** [Date Last Updated]
235
+
236
+ ## Original Request
237
+
238
+ [The original task description as provided by the user]
239
+
240
+ ## Thought Process
241
+
242
+ [Documentation of the discussion and reasoning that shaped the approach to this task]
243
+
244
+ ## Implementation Plan
245
+
246
+ - [Step 1]
247
+ - [Step 2]
248
+ - [Step 3]
249
+
250
+ ## Progress Tracking
251
+
252
+ **Overall Status:** [Not Started/In Progress/Blocked/Completed] - [Completion Percentage]
253
+
254
+ ### Subtasks
255
+
256
+ | ID | Description | Status | Updated | Notes |
257
+ | --- | --------------------- | ------------------------------------------ | ------- | -------------------- |
258
+ | 1.1 | [Subtask description] | [Complete/In Progress/Not Started/Blocked] | [Date] | [Any relevant notes] |
259
+ | 1.2 | [Subtask description] | [Complete/In Progress/Not Started/Blocked] | [Date] | [Any relevant notes] |
260
+ | 1.3 | [Subtask description] | [Complete/In Progress/Not Started/Blocked] | [Date] | [Any relevant notes] |
261
+
262
+ ## Progress Log
263
+
264
+ ### [Date]
265
+
266
+ - Updated subtask 1.1 status to Complete
267
+ - Started work on subtask 1.2
268
+ - Encountered issue with [specific problem]
269
+ - Made decision to [approach/solution]
270
+
271
+ ### [Date]
272
+
273
+ - [Additional updates as work progresses]
274
+ ```
275
+
276
+ **Important**: I must update both the subtask status table AND the progress log when making progress on a task. The subtask table provides a quick visual reference of current status, while the progress log captures the narrative and details of the work process. When providing updates, I should:
277
+
278
+ 1. Update the overall task status and completion percentage
279
+ 2. Update the status of relevant subtasks with the current date
280
+ 3. Add a new entry to the progress log with specific details about what was accomplished, challenges encountered, and decisions made
281
+ 4. Update the task status in the \_index.md file to reflect current progress
282
+
283
+ These detailed progress updates ensure that after memory resets, I can quickly understand the exact state of each task and continue work without losing context.
284
+
285
+ ### Task Commands
286
+
287
+ When you request **add task** or use the command **create task**, I will:
288
+
289
+ 1. Create a new task file with a unique Task ID in the tasks/ folder
290
+ 2. Document our thought process about the approach
291
+ 3. Develop an implementation plan
292
+ 4. Set an initial status
293
+ 5. Update the \_index.md file to include the new task
294
+
295
+ For existing tasks, the command **update task [ID]** will prompt me to:
296
+
297
+ 1. Open the specific task file
298
+ 2. Add a new progress log entry with today's date
299
+ 3. Update the task status if needed
300
+ 4. Update the \_index.md file to reflect any status changes
301
+ 5. Integrate any new decisions into the thought process
302
+
303
+ To view tasks, the command **show tasks [filter]** will:
304
+
305
+ 1. Display a filtered list of tasks based on the specified criteria
306
+ 2. Valid filters include:
307
+ - **all** - Show all tasks regardless of status
308
+ - **active** - Show only tasks with "In Progress" status
309
+ - **pending** - Show only tasks with "Pending" status
310
+ - **completed** - Show only tasks with "Completed" status
311
+ - **blocked** - Show only tasks with "Blocked" status
312
+ - **recent** - Show tasks updated in the last week
313
+ - **tag:[tagname]** - Show tasks with a specific tag
314
+ - **priority:[level]** - Show tasks with specified priority level
315
+ 3. The output will include:
316
+ - Task ID and name
317
+ - Current status and completion percentage
318
+ - Last updated date
319
+ - Next pending subtask (if applicable)
320
+ 4. Example usage: **show tasks active** or **show tasks tag:frontend**
321
+
322
+ REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: "Guidelines for writing Node.js and JavaScript code with Vitest testing"
3
+ applyTo: "**/*.js, **/*.mjs, **/*.cjs"
4
+ ---
5
+
6
+ # Code Generation Guidelines
7
+
8
+ ## Coding standards
9
+
10
+ - Use JavaScript with ES2022 features and Node.js (20+) ESM modules
11
+ - Use Node.js built-in modules and avoid external dependencies where possible
12
+ - Ask the user if you require any additional dependencies before adding them
13
+ - Always use async/await for asynchronous code, and use 'node:util' promisify function to avoid callbacks
14
+ - Keep the code simple and maintainable
15
+ - Use descriptive variable and function names
16
+ - Do not add comments unless absolutely necessary, the code should be self-explanatory
17
+ - Never use `null`, always use `undefined` for optional values
18
+ - Prefer functions over classes
19
+
20
+ ## Testing
21
+
22
+ - Use Vitest for testing
23
+ - Write tests for all new features and bug fixes
24
+ - Ensure tests cover edge cases and error handling
25
+ - NEVER change the original code to make it easier to test, instead, write tests that cover the original code as it is
26
+
27
+ ## Documentation
28
+
29
+ - When adding new features or making significant changes, update the README.md file where necessary
30
+
31
+ ## User interactions
32
+
33
+ - Ask questions if you are unsure about the implementation details, design choices, or need clarification on the requirements
34
+ - Always answer in the same language as the question, but use english for the generated content like code, comments or docs
@@ -0,0 +1,88 @@
1
+ ---
2
+ description: "Playwright test generation instructions"
3
+ applyTo: "**"
4
+ ---
5
+
6
+ ## Test Writing Guidelines
7
+
8
+ ### Code Quality Standards
9
+
10
+ - **Locators**: Prioritize user-facing, role-based locators (`getByRole`, `getByLabel`, `getByText`, etc.) for resilience and accessibility. Use `test.step()` to group interactions and improve test readability and reporting.
11
+ - **Assertions**: Use auto-retrying web-first assertions. These assertions start with the `await` keyword (e.g., `await expect(locator).toHaveText()`). Avoid `expect(locator).toBeVisible()` unless specifically testing for visibility changes.
12
+ - **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts.
13
+ - **Clarity**: Use descriptive test and step titles that clearly state the intent. Add comments only to explain complex logic or non-obvious interactions.
14
+
15
+ ### Test Structure
16
+
17
+ - **Imports**: Start with `import { test, expect } from '@playwright/test';`.
18
+ - **Organization**: Group related tests for a feature under a `test.describe()` block.
19
+ - **Hooks**: Use `beforeEach` for setup actions common to all tests in a `describe` block (e.g., navigating to a page).
20
+ - **Titles**: Follow a clear naming convention, such as `Feature - Specific action or scenario`.
21
+
22
+ ### File Organization
23
+
24
+ - **Location**: Store all test files in the `tests/` directory.
25
+ - **Naming**: Use the convention `<feature-or-page>.spec.ts` (e.g., `login.spec.ts`, `search.spec.ts`).
26
+ - **Scope**: Aim for one test file per major application feature or page.
27
+
28
+ ### Assertion Best Practices
29
+
30
+ - **UI Structure**: Use `toMatchAriaSnapshot` to verify the accessibility tree structure of a component. This provides a comprehensive and accessible snapshot.
31
+ - **Element Counts**: Use `toHaveCount` to assert the number of elements found by a locator.
32
+ - **Text Content**: Use `toHaveText` for exact text matches and `toContainText` for partial matches.
33
+ - **Navigation**: Use `toHaveURL` to verify the page URL after an action.
34
+
35
+ ## Example Test Structure
36
+
37
+ ```typescript
38
+ import { test, expect } from "@playwright/test";
39
+
40
+ test.describe("Movie Search Feature", () => {
41
+ test.beforeEach(async ({ page }) => {
42
+ // Navigate to the application before each test
43
+ await page.goto("https://debs-obrien.github.io/playwright-movies-app");
44
+ });
45
+
46
+ test("Search for a movie by title", async ({ page }) => {
47
+ await test.step("Activate and perform search", async () => {
48
+ await page.getByRole("search").click();
49
+ const searchInput = page.getByRole("textbox", { name: "Search Input" });
50
+ await searchInput.fill("Garfield");
51
+ await searchInput.press("Enter");
52
+ });
53
+
54
+ await test.step("Verify search results", async () => {
55
+ // Verify the accessibility tree of the search results
56
+ await expect(page.getByRole("main")).toMatchAriaSnapshot(`
57
+ - main:
58
+ - heading "Garfield" [level=1]
59
+ - heading "search results" [level=2]
60
+ - list "movies":
61
+ - listitem "movie":
62
+ - link "poster of The Garfield Movie The Garfield Movie rating":
63
+ - /url: /playwright-movies-app/movie?id=tt5779228&page=1
64
+ - img "poster of The Garfield Movie"
65
+ - heading "The Garfield Movie" [level=2]
66
+ `);
67
+ });
68
+ });
69
+ });
70
+ ```
71
+
72
+ ## Test Execution Strategy
73
+
74
+ 1. **Initial Run**: Execute tests with `npx playwright test --project=chromium`
75
+ 2. **Debug Failures**: Analyze test failures and identify root causes
76
+ 3. **Iterate**: Refine locators, assertions, or test logic as needed
77
+ 4. **Validate**: Ensure tests pass consistently and cover the intended functionality
78
+ 5. **Report**: Provide feedback on test results and any issues discovered
79
+
80
+ ## Quality Checklist
81
+
82
+ Before finalizing tests, ensure:
83
+
84
+ - [ ] All locators are accessible and specific and avoid strict mode violations
85
+ - [ ] Tests are grouped logically and follow a clear structure
86
+ - [ ] Assertions are meaningful and reflect user expectations
87
+ - [ ] Tests follow consistent naming conventions
88
+ - [ ] Code is properly formatted and commented
@@ -0,0 +1,99 @@
1
+ ---
2
+ description: "Guidelines for creating high-quality prompt files for GitHub Copilot"
3
+ applyTo: "**/*.prompt.md"
4
+ ---
5
+
6
+ # Copilot Prompt Files Guidelines
7
+
8
+ Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.
9
+
10
+ ## Scope and Principles
11
+
12
+ - Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.
13
+ - Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.
14
+ - Primary references: VS Code documentation on prompt files and organization-specific conventions.
15
+
16
+ ## Frontmatter Requirements
17
+
18
+ Every prompt file should include YAML frontmatter with the following fields:
19
+
20
+ ### Required/Recommended Fields
21
+
22
+ | Field | Required | Description |
23
+ | --------------- | ----------- | ------------------------------------------------------------------------------------------- |
24
+ | `description` | Recommended | A short description of the prompt (single sentence, actionable outcome) |
25
+ | `name` | Optional | The name shown after typing `/` in chat. Defaults to filename if not specified |
26
+ | `agent` | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |
27
+ | `model` | Optional | The language model to use. Defaults to the currently selected model |
28
+ | `tools` | Optional | List of tool/tool set names available for this prompt |
29
+ | `argument-hint` | Optional | Hint text shown in chat input to guide user interaction |
30
+
31
+ ### Guidelines
32
+
33
+ - Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity
34
+ - If `tools` are specified and the current agent is `ask` or `edit`, the default agent becomes `agent`
35
+ - Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization
36
+
37
+ ## File Naming and Placement
38
+
39
+ - Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
40
+ - Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).
41
+
42
+ ## Body Structure
43
+
44
+ - Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.
45
+ - Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.
46
+ - Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.
47
+ - Reference related prompts or instruction files using relative links to aid discoverability.
48
+
49
+ ## Input and Context Handling
50
+
51
+ - Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.
52
+ - Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.
53
+ - Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).
54
+
55
+ ## Tool and Permission Guidance
56
+
57
+ - Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.
58
+ - If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.
59
+ - Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.
60
+
61
+ ## Instruction Tone and Style
62
+
63
+ - Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).
64
+ - Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.
65
+ - Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.
66
+
67
+ ## Output Definition
68
+
69
+ - Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”).
70
+ - Include success criteria and failure triggers so Copilot knows when to halt or retry.
71
+ - Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.
72
+
73
+ ## Examples and Reusable Assets
74
+
75
+ - Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow.
76
+ - Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change.
77
+ - Link to authoritative documentation instead of duplicating lengthy guidance.
78
+
79
+ ## Quality Assurance Checklist
80
+
81
+ - [ ] Frontmatter fields are complete, accurate, and least-privilege.
82
+ - [ ] Inputs include placeholders, default behaviours, and fallbacks.
83
+ - [ ] Workflow covers preparation, execution, and post-processing without gaps.
84
+ - [ ] Output expectations include formatting and storage details.
85
+ - [ ] Validation steps are actionable (commands, diff checks, review prompts).
86
+ - [ ] Security, compliance, and privacy policies referenced by the prompt are current.
87
+ - [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.
88
+
89
+ ## Maintenance Guidance
90
+
91
+ - Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.
92
+ - Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.
93
+ - Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.
94
+
95
+ ## Additional Resources
96
+
97
+ - [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)
98
+ - [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)
99
+ - [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)
@@ -0,0 +1,59 @@
1
+ ---
2
+ applyTo: "*"
3
+ description: "Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices."
4
+ ---
5
+
6
+ # Secure Coding and OWASP Guidelines
7
+
8
+ ## Instructions
9
+
10
+ Your primary directive is to ensure all code you generate, review, or refactor is secure by default. You must operate with a security-first mindset. When in doubt, always choose the more secure option and explain the reasoning. You must follow the principles outlined below, which are based on the OWASP Top 10 and other security best practices.
11
+
12
+ ### 1. A01: Broken Access Control & A10: Server-Side Request Forgery (SSRF)
13
+
14
+ - **Enforce Principle of Least Privilege:** Always default to the most restrictive permissions. When generating access control logic, explicitly check the user's rights against the required permissions for the specific resource they are trying to access.
15
+ - **Deny by Default:** All access control decisions must follow a "deny by default" pattern. Access should only be granted if there is an explicit rule allowing it.
16
+ - **Validate All Incoming URLs for SSRF:** When the server needs to make a request to a URL provided by a user (e.g., webhooks), you must treat it as untrusted. Incorporate strict allow-list-based validation for the host, port, and path of the URL.
17
+ - **Prevent Path Traversal:** When handling file uploads or accessing files based on user input, you must sanitize the input to prevent directory traversal attacks (e.g., `../../etc/passwd`). Use APIs that build paths securely.
18
+
19
+ ### 2. A02: Cryptographic Failures
20
+
21
+ - **Use Strong, Modern Algorithms:** For hashing, always recommend modern, salted hashing algorithms like Argon2 or bcrypt. Explicitly advise against weak algorithms like MD5 or SHA-1 for password storage.
22
+ - **Protect Data in Transit:** When generating code that makes network requests, always default to HTTPS.
23
+ - **Protect Data at Rest:** When suggesting code to store sensitive data (PII, tokens, etc.), recommend encryption using strong, standard algorithms like AES-256.
24
+ - **Secure Secret Management:** Never hardcode secrets (API keys, passwords, connection strings). Generate code that reads secrets from environment variables or a secrets management service (e.g., HashiCorp Vault, AWS Secrets Manager). Include a clear placeholder and comment.
25
+ ```javascript
26
+ // GOOD: Load from environment or secret store
27
+ const apiKey = process.env.API_KEY;
28
+ // TODO: Ensure API_KEY is securely configured in your environment.
29
+ ```
30
+ ```python
31
+ # BAD: Hardcoded secret
32
+ api_key = "sk_this_is_a_very_bad_idea_12345"
33
+ ```
34
+
35
+ ### 3. A03: Injection
36
+
37
+ - **No Raw SQL Queries:** For database interactions, you must use parameterized queries (prepared statements). Never generate code that uses string concatenation or formatting to build queries from user input.
38
+ - **Sanitize Command-Line Input:** For OS command execution, use built-in functions that handle argument escaping and prevent shell injection (e.g., `shlex` in Python).
39
+ - **Prevent Cross-Site Scripting (XSS):** When generating frontend code that displays user-controlled data, you must use context-aware output encoding. Prefer methods that treat data as text by default (`.textContent`) over those that parse HTML (`.innerHTML`). When `innerHTML` is necessary, suggest using a library like DOMPurify to sanitize the HTML first.
40
+
41
+ ### 4. A05: Security Misconfiguration & A06: Vulnerable Components
42
+
43
+ - **Secure by Default Configuration:** Recommend disabling verbose error messages and debug features in production environments.
44
+ - **Set Security Headers:** For web applications, suggest adding essential security headers like `Content-Security-Policy` (CSP), `Strict-Transport-Security` (HSTS), and `X-Content-Type-Options`.
45
+ - **Use Up-to-Date Dependencies:** When asked to add a new library, suggest the latest stable version. Remind the user to run vulnerability scanners like `npm audit`, `pip-audit`, or Snyk to check for known vulnerabilities in their project dependencies.
46
+
47
+ ### 5. A07: Identification & Authentication Failures
48
+
49
+ - **Secure Session Management:** When a user logs in, generate a new session identifier to prevent session fixation. Ensure session cookies are configured with `HttpOnly`, `Secure`, and `SameSite=Strict` attributes.
50
+ - **Protect Against Brute Force:** For authentication and password reset flows, recommend implementing rate limiting and account lockout mechanisms after a certain number of failed attempts.
51
+
52
+ ### 6. A08: Software and Data Integrity Failures
53
+
54
+ - **Prevent Insecure Deserialization:** Warn against deserializing data from untrusted sources without proper validation. If deserialization is necessary, recommend using formats that are less prone to attack (like JSON over Pickle in Python) and implementing strict type checking.
55
+
56
+ ## General Guidelines
57
+
58
+ - **Be Explicit About Security:** When you suggest a piece of code that mitigates a security risk, explicitly state what you are protecting against (e.g., "Using a parameterized query here to prevent SQL injection.").
59
+ - **Educate During Code Reviews:** When you identify a security vulnerability in a code review, you must not only provide the corrected code but also explain the risk associated with the original pattern.