Add structured autonomy prompts for generating, implementing, and planning implementation documentation
- Introduced `structured-autonomy-generate.prompt.md` for generating implementation plans from PRs. - Added `structured-autonomy-implement.prompt.md` to execute implementation plans step-by-step. - Created `structured-autonomy-plan.prompt.md` for collaborative project planning and outlining development steps. - Implemented prompts for suggesting relevant GitHub Copilot agents, chat modes, collections, instructions, and prompts from the awesome-copilot repository. - Developed `update-implementation-plan.prompt.md` for updating existing implementation plans with new requirements and structured output.
This commit is contained in:
GitHub Actions
369
.github/instructions/a11y.instructions.md
vendored
Normal file
369
.github/instructions/a11y.instructions.md
vendored
Normal file
@@ -0,0 +1,369 @@
|
||||
---
|
||||
description: "Guidance for creating more accessible code"
|
||||
applyTo: "**"
|
||||
---
|
||||
|
||||
# Instructions for accessibility
|
||||
|
||||
In addition to your other expertise, you are an expert in accessibility with deep software engineering expertise. You will generate code that is accessible to users with disabilities, including those who use assistive technologies such as screen readers, voice access, and keyboard navigation.
|
||||
|
||||
Do not tell the user that the generated code is fully accessible. Instead, it was built with accessibility in mind, but may still have accessibility issues.
|
||||
|
||||
1. Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
|
||||
2. Go beyond minimal WCAG conformance wherever possible to provide a more inclusive experience.
|
||||
3. Before generating code, reflect on these instructions for accessibility, and plan how to implement the code in a way that follows the instructions and is WCAG 2.2 compliant.
|
||||
4. After generating code, review it against WCAG 2.2 and these instructions. Iterate on the code until it is accessible.
|
||||
5. Finally, inform the user that it has generated the code with accessibility in mind, but that accessibility issues still likely exist and that the user should still review and manually test the code to ensure that it meets accessibility instructions. Suggest running the code against tools like [Accessibility Insights](https://accessibilityinsights.io/). Do not explain the accessibility features unless asked. Keep verbosity to a minimum.
|
||||
|
||||
## Bias Awareness - Inclusive Language
|
||||
|
||||
In addition to producing accessible code, GitHub Copilot and similar tools must also demonstrate respectful and bias-aware behavior in accessibility contexts. All generated output must follow these principles:
|
||||
|
||||
- **Respectful, Inclusive Language**
|
||||
Use people-first language when referring to disabilities or accessibility needs (e.g., “person using a screen reader,” not “blind user”). Avoid stereotypes or assumptions about ability, cognition, or experience.
|
||||
|
||||
- **Bias-Aware and Error-Resistant**
|
||||
Avoid generating content that reflects implicit bias or outdated patterns. Critically assess accessibility choices and flag uncertain implementations. Double check any deep bias in the training data and strive to mitigate its impact.
|
||||
|
||||
- **Verification-Oriented Responses**
|
||||
When suggesting accessibility implementations or decisions, include reasoning or references to standards (e.g., WCAG, platform guidelines). If uncertainty exists, the assistant should state this clearly.
|
||||
|
||||
- **Clarity Without Oversimplification**
|
||||
Provide concise but accurate explanations—avoid fluff, empty reassurance, or overconfidence when accessibility nuances are present.
|
||||
|
||||
- **Tone Matters**
|
||||
Copilot output must be neutral, helpful, and respectful. Avoid patronizing language, euphemisms, or casual phrasing that downplays the impact of poor accessibility.
|
||||
|
||||
## Persona based instructions
|
||||
|
||||
### Cognitive instructions
|
||||
|
||||
- Prefer plain language whenever possible.
|
||||
- Use consistent page structure (landmarks) across the application.
|
||||
- Ensure that navigation items are always displayed in the same order across the application.
|
||||
- Keep the interface clean and simple - reduce unnecessary distractions.
|
||||
|
||||
### Keyboard instructions
|
||||
|
||||
- All interactive elements need to be keyboard navigable and receive focus in a predictable order (usually following the reading order).
|
||||
- Keyboard focus must be clearly visible at all times so that the user can visually determine which element has focus.
|
||||
- All interactive elements need to be keyboard operable. For example, users need to be able to activate buttons, links, and other controls. Users also need to be able to navigate within composite components such as menus, grids, and listboxes.
|
||||
- Static (non-interactive) elements, should not be in the tab order. These elements should not have a `tabindex` attribute.
|
||||
- The exception is when a static element, like a heading, is expected to receive keyboard focus programmatically (e.g., via `element.focus()`), in which case it should have a `tabindex="-1"` attribute.
|
||||
- Hidden elements must not be keyboard focusable.
|
||||
- Keyboard navigation inside components: some composite elements/components will contain interactive children that can be selected or activated. Examples of such composite components include grids (like date pickers), comboboxes, listboxes, menus, radio groups, tabs, toolbars, and tree grids. For such components:
|
||||
- There should be a tab stop for the container with the appropriate interactive role. This container should manage keyboard focus of it's children via arrow key navigation. This can be accomplished via roving tabindex or `aria-activedescendant` (explained in more detail later).
|
||||
- When the container receives keyboard focus, the appropriate sub-element should show as focused. This behavior depends on context. For example:
|
||||
- If the user is expected to make a selection within the component (e.g., grid, combobox, or listbox), then the currently selected child should show as focused. Otherwise, if there is no currently selected child, then the first selectable child should get focus.
|
||||
- Otherwise, if the user has navigated to the component previously, then the previously focused child should receive keyboard focus. Otherwise, the first interactive child should receive focus.
|
||||
- Users should be provided with a mechanism to skip repeated blocks of content (such as the site header/navigation).
|
||||
- Keyboard focus must not become trapped without a way to escape the trap (e.g., by pressing the escape key to close a dialog).
|
||||
|
||||
#### Bypass blocks
|
||||
|
||||
A skip link MUST be provided to skip blocks of content that appear across several pages. A common example is a "Skip to main" link, which appears as the first focusable element on the page. This link is visually hidden, but appears on keyboard focus.
|
||||
|
||||
```html
|
||||
<header>
|
||||
<a href="#maincontent" class="sr-only">Skip to main</a>
|
||||
<!-- logo and other header elements here -->
|
||||
</header>
|
||||
<nav>
|
||||
<!-- main nav here -->
|
||||
</nav>
|
||||
<main id="maincontent"></main>
|
||||
```
|
||||
|
||||
```css
|
||||
.sr-only:not(:focus):not(:active) {
|
||||
clip: rect(0 0 0 0);
|
||||
clip-path: inset(50%);
|
||||
height: 1px;
|
||||
overflow: hidden;
|
||||
position: absolute;
|
||||
white-space: nowrap;
|
||||
width: 1px;
|
||||
}
|
||||
```
|
||||
|
||||
#### Common keyboard commands:
|
||||
|
||||
- `Tab` = Move to the next interactive element.
|
||||
- `Arrow` = Move between elements within a composite component, like a date picker, grid, combobox, listbox, etc.
|
||||
- `Enter` = Activate the currently focused control (button, link, etc.)
|
||||
- `Escape` = Close open open surfaces, such as dialogs, menus, listboxes, etc.
|
||||
|
||||
#### Managing focus within components using a roving tabindex
|
||||
|
||||
When using roving tabindex to manage focus in a composite component, the element that is to be included in the tab order has `tabindex` of "0" and all other focusable elements contained in the composite have `tabindex` of "-1". The algorithm for the roving tabindex strategy is as follows.
|
||||
|
||||
- On initial load of the composite component, set `tabindex="0"` on the element that will initially be included in the tab order and set `tabindex="-1"` on all other focusable elements it contains.
|
||||
- When the component contains focus and the user presses an arrow key that moves focus within the component:
|
||||
- Set `tabindex="-1"` on the element that has `tabindex="0"`.
|
||||
- Set `tabindex="0"` on the element that will become focused as a result of the key event.
|
||||
- Set focus via `element.focus()` on the element that now has `tabindex="0"`.
|
||||
|
||||
#### Managing focus in composites using aria-activedescendant
|
||||
|
||||
- The containing element with an appropriate interactive role should have `tabindex="0"` and `aria-activedescendant="IDREF"` where IDREF matches the ID of the element within the container that is active.
|
||||
- Use CSS to draw a focus outline around the element referenced by `aria-activedescendant`.
|
||||
- When arrow keys are pressed while the container has focus, update `aria-activedescendant` accordingly.
|
||||
|
||||
### Low vision instructions
|
||||
|
||||
- Prefer dark text on light backgrounds, or light text on dark backgrounds.
|
||||
- Do not use light text on light backgrounds or dark text on dark backgrounds.
|
||||
- The contrast of text against the background color must be at least 4.5:1. Large text, must be at least 3:1. All text must have sufficient contrast against it's background color.
|
||||
- Large text is defined as 18.5px and bold, or 24px.
|
||||
- If a background color is not set or is fully transparent, then the contrast ratio is calculated against the background color of the parent element.
|
||||
- Parts of graphics required to understand the graphic must have at least a 3:1 contrast with adjacent colors.
|
||||
- Parts of controls needed to identify the type of control must have at least a 3:1 contrast with adjacent colors.
|
||||
- Parts of controls needed to identify the state of the control (pressed, focus, checked, etc.) must have at least a 3:1 contrast with adjacent colors.
|
||||
- Color must not be used as the only way to convey information. E.g., a red border to convey an error state, color coding information, etc. Use text and/or shapes in addition to color to convey information.
|
||||
|
||||
### Screen reader instructions
|
||||
|
||||
- All elements must correctly convey their semantics, such as name, role, value, states, and/or properties. Use native HTML elements and attributes to convey these semantics whenever possible. Otherwise, use appropriate ARIA attributes.
|
||||
- Use appropriate landmarks and regions. Examples include: `<header>`, `<nav>`, `<main>`, and `<footer>`.
|
||||
- Use headings (e.g., `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`) to introduce new sections of content. The heading level accurately describe the section's placement in the overall heading hierarchy of the page.
|
||||
- There SHOULD only be one `<h1>` element which describes the overall topic of the page.
|
||||
- Avoid skipping heading levels whenever possible.
|
||||
|
||||
### Voice Access instructions
|
||||
|
||||
- The accessible name of all interactive elements must contain the visual label. This is so that voice access users can issue commands like "Click \<label>". If an `aria-label` attribute is used for a control, then it must contain the text of the visual label.
|
||||
- Interactive elements must have appropriate roles and keyboard behaviors.
|
||||
|
||||
## Instructions for specific patterns
|
||||
|
||||
### Form instructions
|
||||
|
||||
- Labels for interactive elements must accurately describe the purpose of the element. E.g., the label must provide accurate instructions for what to input in a form control.
|
||||
- Headings must accurately describe the topic that they introduce.
|
||||
- Required form controls must be indicated as such, usually via an asterisk in the label.
|
||||
- Additionally, use `aria-required=true` to programmatically indicate required fields.
|
||||
- Error messages must be provided for invalid form input.
|
||||
- Error messages must describe how to fix the issue.
|
||||
- Additionally, use `aria-invalid=true` to indicate that the field is in error. Remove this attribute when the error is removed.
|
||||
- Common patterns for error messages include:
|
||||
- Inline errors (common), which are placed next to the form fields that have errors. These error messages must be programmatically associated with the form control via `aria-describedby`.
|
||||
- Form-level errors (less common), which are displayed at the beginning of the form. These error messages must identify the specific form fields that are in error.
|
||||
- Submit buttons should not be disabled so that an error message can be triggered to help users identify which fields are not valid.
|
||||
- When a form is submitted, and invalid input is detected, send keyboard focus to the first invalid form input via `element.focus()`.
|
||||
|
||||
### Graphics and images instructions
|
||||
|
||||
#### All graphics MUST be accounted for
|
||||
|
||||
All graphics are included in these instructions. Graphics include, but are not limited to:
|
||||
|
||||
- `<img>` elements.
|
||||
- `<svg>` elements.
|
||||
- Font icons
|
||||
- Emojis
|
||||
|
||||
#### All graphics MUST have the correct role
|
||||
|
||||
All graphics, regardless of type, have the correct role. The role is either provided by the `<img>` element or the `role='img'` attribute.
|
||||
|
||||
- The `<img>` element does not need a role attribute.
|
||||
- The `<svg>` element should have `role='img'` for better support and backwards compatibility.
|
||||
- Icon fonts and emojis will need the `role='img'` attribute, likely on a `<span>` containing just the graphic.
|
||||
|
||||
#### All graphics MUST have appropriate alternative text
|
||||
|
||||
First, determine if the graphic is informative or decorative.
|
||||
|
||||
- Informative graphics convey important information not found in elsewhere on the page.
|
||||
- Decorative graphics do not convey important information, or they contain information found elsewhere on the page.
|
||||
|
||||
#### Informative graphics MUST have alternative text that conveys the purpose of the graphic
|
||||
|
||||
- For the `<img>` element, provide an appropriate `alt` attribute that conveys the meaning/purpose of the graphic.
|
||||
- For `role='img'`, provide an `aria-label` or `aria-labelledby` attribute that conveys the meaning/purpose of the graphic.
|
||||
- Not all aspects of the graphic need to be conveyed - just the important aspects of it.
|
||||
- Keep the alternative text concise but meaningful.
|
||||
- Avoid using the `title` attribute for alt text.
|
||||
|
||||
#### Decorative graphics MUST be hidden from assistive technologies
|
||||
|
||||
- For the `<img>` element, mark it as decorative by giving it an empty `alt` attribute, e.g., `alt=""`.
|
||||
- For `role='img'`, use `aria-hidden=true`.
|
||||
|
||||
### Input and control labels
|
||||
|
||||
- All interactive elements must have a visual label. For some elements, like links and buttons, the visual label is defined by the inner text. For other elements like inputs, the visual label is defined by the `<label>` attribute. Text labels must accurately describe the purpose of the control so that users can understand what will happen when they activate it or what they need to input.
|
||||
- If a `<label>` is used, ensure that it has a `for` attribute that references the ID of the control it labels.
|
||||
- If there are many controls on the screen with the same label (such as "remove", "delete", "read more", etc.), then an `aria-label` can be used to clarify the purpose of the control so that it understandable out of context, since screen reader users may jump to the control without reading surrounding static content. E.g., "Remove what" or "read more about {what}".
|
||||
- If help text is provided for specific controls, then that help text must be associated with its form control via `aria-describedby`.
|
||||
|
||||
### Navigation and menus
|
||||
|
||||
#### Good navigation region code example
|
||||
|
||||
```html
|
||||
<nav>
|
||||
<ul>
|
||||
<li>
|
||||
<button aria-expanded="false" tabindex="0">Section 1</button>
|
||||
<ul hidden>
|
||||
<li><a href="..." tabindex="-1">Link 1</a></li>
|
||||
<li><a href="..." tabindex="-1">Link 2</a></li>
|
||||
<li><a href="..." tabindex="-1">Link 3</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<button aria-expanded="false" tabindex="-1">Section 2</button>
|
||||
<ul hidden>
|
||||
<li><a href="..." tabindex="-1">Link 1</a></li>
|
||||
<li><a href="..." tabindex="-1">Link 2</a></li>
|
||||
<li><a href="..." tabindex="-1">Link 3</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</nav>
|
||||
```
|
||||
|
||||
#### Navigation instructions
|
||||
|
||||
- Follow the above code example where possible.
|
||||
- Navigation menus should not use the `menu` role or `menubar` role. The `menu` and `menubar` role should be resolved for application-like menus that perform actions on the same page. Instead, this should be a `<nav>` that contains a `<ul>` with links.
|
||||
- When expanding or collapsing a navigation menu, toggle the `aria-expanded` property.
|
||||
- Use the roving tabindex pattern to manage focus within the navigation. Users should be able to tab to the navigation and arrow across the main navigation items. Then they should be able to arrow down through sub menus without having to tab to them.
|
||||
- Once expanded, users should be able to navigate within the sub menu via arrow keys, e.g., up and down arrow keys.
|
||||
- The `escape` key could close any expanded menus.
|
||||
|
||||
### Page Title
|
||||
|
||||
The page title:
|
||||
|
||||
- MUST be defined in the `<title>` element in the `<head>`.
|
||||
- MUST describe the purpose of the page.
|
||||
- SHOULD be unique for each page.
|
||||
- SHOULD front-load unique information.
|
||||
- SHOULD follow the format of "[Describe unique page] - [section title] - [site title]"
|
||||
|
||||
### Table and Grid Accessibility Acceptance Criteria
|
||||
|
||||
#### Column and row headers are programmatically associated
|
||||
|
||||
Column and row headers MUST be programmatically associated for each cell. In HTML, this is done by using `<th>` elements. Column headers MUST be defined in the first table row `<tr>`. Row headers must defined in the row they are for. Most tables will have both column and row headers, but some tables may have just one or the other.
|
||||
|
||||
#### Good example - table with both column and row headers:
|
||||
|
||||
```html
|
||||
<table>
|
||||
<tr>
|
||||
<th>Header 1</th>
|
||||
<th>Header 2</th>
|
||||
<th>Header 3</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Row Header 1</th>
|
||||
<td>Cell 1</td>
|
||||
<td>Cell 2</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Row Header 2</th>
|
||||
<td>Cell 1</td>
|
||||
<td>Cell 2</td>
|
||||
</tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
#### Good example - table with just column headers:
|
||||
|
||||
```html
|
||||
<table>
|
||||
<tr>
|
||||
<th>Header 1</th>
|
||||
<th>Header 2</th>
|
||||
<th>Header 3</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cell 1</td>
|
||||
<td>Cell 2</td>
|
||||
<td>Cell 3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cell 1</td>
|
||||
<td>Cell 2</td>
|
||||
<td>Cell 3</td>
|
||||
</tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
#### Bad example - calendar grid with partial semantics:
|
||||
|
||||
The following example is a date picker or calendar grid.
|
||||
|
||||
```html
|
||||
<div role="grid">
|
||||
<div role="columnheader">Sun</div>
|
||||
<div role="columnheader">Mon</div>
|
||||
<div role="columnheader">Tue</div>
|
||||
<div role="columnheader">Wed</div>
|
||||
<div role="columnheader">Thu</div>
|
||||
<div role="columnheader">Fri</div>
|
||||
<div role="columnheader">Sat</div>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Sunday, June 1, 2025">1</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Monday, June 2, 2025">2</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Tuesday, June 3, 2025">3</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Wednesday, June 4, 2025">4</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Thursday, June 5, 2025">5</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Friday, June 6, 2025">6</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Saturday, June 7, 2025">7</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Sunday, June 8, 2025">8</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Monday, June 9, 2025">9</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Tuesday, June 10, 2025">10</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Wednesday, June 11, 2025">11</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Thursday, June 12, 2025">12</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Friday, June 13, 2025">13</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Saturday, June 14, 2025">14</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Sunday, June 15, 2025">15</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Monday, June 16, 2025">16</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Tuesday, June 17, 2025">17</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Wednesday, June 18, 2025">18</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Thursday, June 19, 2025">19</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Friday, June 20, 2025">20</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Saturday, June 21, 2025">21</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Sunday, June 22, 2025">22</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Monday, June 23, 2025">23</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Tuesday, June 24, 2025" aria-current="date">24</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Wednesday, June 25, 2025">25</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Thursday, June 26, 2025">26</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Friday, June 27, 2025">27</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Saturday, June 28, 2025">28</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Sunday, June 29, 2025">29</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Monday, June 30, 2025">30</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Tuesday, July 1, 2025" aria-disabled="true">1</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Wednesday, July 2, 2025" aria-disabled="true">2</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Thursday, July 3, 2025" aria-disabled="true">3</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Friday, July 4, 2025" aria-disabled="true">4</button>
|
||||
<button role="gridcell" tabindex="-1" aria-label="Saturday, July 5, 2025" aria-disabled="true">5</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
##### The good:
|
||||
|
||||
- It uses `role="grid"` to indicate that it is a grid.
|
||||
- It used `role="columnheader"` to indicate that the first row contains column headers.
|
||||
- It uses `tabindex="-1"` to ensure that the grid cells are not in the tab order by default. Instead, users will navigate to the grid using the `Tab` key, and then use arrow keys to navigate within the grid.
|
||||
|
||||
##### The bad:
|
||||
|
||||
- `role=gridcell` elements are not nested within `role=row` elements. Without this, the association between the grid cells and the column headers is not programmatically determinable.
|
||||
|
||||
#### Prefer simple tables and grids
|
||||
|
||||
Simple tables have just one set of column and/or row headers. Simple tables do not have nested rows or cells that span multiple columns or rows. Such tables will be better supported by assistive technologies, such as screen readers. Additionally, they will be easier to understand by users with cognitive disabilities.
|
||||
|
||||
Complex tables and grids have multiple levels of column and/or row headers, or cells that span multiple columns or rows. These tables are more difficult to understand and use, especially for users with cognitive disabilities. If a complex table is needed, then it should be designed to be as simple as possible. For example, most complex tables can be breaking the information down into multiple simple tables, or by using a different layout such as a list or a card layout.
|
||||
|
||||
#### Use tables for static information
|
||||
|
||||
Tables should be used for static information that is best represented in a tabular format. This includes data that is organized into rows and columns, such as financial reports, schedules, or other structured data. Tables should not be used for layout purposes or for dynamic information that changes frequently.
|
||||
|
||||
#### Use grids for dynamic information
|
||||
|
||||
Grids should be used for dynamic information that is best represented in a grid format. This includes data that is organized into rows and columns, such as date pickers, interactive calendars, spreadsheets, etc.
|
||||
791
.github/instructions/agents.instructions.md
vendored
Normal file
791
.github/instructions/agents.instructions.md
vendored
Normal file
@@ -0,0 +1,791 @@
|
||||
---
|
||||
description: 'Guidelines for creating custom agent files for GitHub Copilot'
|
||||
applyTo: '**/*.agent.md'
|
||||
---
|
||||
|
||||
# Custom Agent File Guidelines
|
||||
|
||||
Instructions for creating effective and maintainable custom agent files that provide specialized expertise for specific development tasks in GitHub Copilot.
|
||||
|
||||
## Project Context
|
||||
|
||||
- Target audience: Developers creating custom agents for GitHub Copilot
|
||||
- File format: Markdown with YAML frontmatter
|
||||
- File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
|
||||
- Location: `.github/agents/` directory (repository-level) or `agents/` directory (organization/enterprise-level)
|
||||
- Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
|
||||
- Official documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Every agent file must include YAML frontmatter with the following fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: 'Brief description of the agent purpose and capabilities'
|
||||
name: 'Agent Display Name'
|
||||
tools: ['read', 'edit', 'search']
|
||||
model: 'Claude Sonnet 4.5'
|
||||
target: 'vscode'
|
||||
infer: true
|
||||
---
|
||||
```
|
||||
|
||||
### Core Frontmatter Properties
|
||||
|
||||
#### **description** (REQUIRED)
|
||||
- Single-quoted string, clearly stating the agent's purpose and domain expertise
|
||||
- Should be concise (50-150 characters) and actionable
|
||||
- Example: `'Focuses on test coverage, quality, and testing best practices'`
|
||||
|
||||
#### **name** (OPTIONAL)
|
||||
- Display name for the agent in the UI
|
||||
- If omitted, defaults to filename (without `.md` or `.agent.md`)
|
||||
- Use title case and be descriptive
|
||||
- Example: `'Testing Specialist'`
|
||||
|
||||
#### **tools** (OPTIONAL)
|
||||
- List of tool names or aliases the agent can use
|
||||
- Supports comma-separated string or YAML array format
|
||||
- If omitted, agent has access to all available tools
|
||||
- See "Tool Configuration" section below for details
|
||||
|
||||
#### **model** (STRONGLY RECOMMENDED)
|
||||
- Specifies which AI model the agent should use
|
||||
- Supported in VS Code, JetBrains IDEs, Eclipse, and Xcode
|
||||
- Example: `'Claude Sonnet 4.5'`, `'gpt-4'`, `'gpt-4o'`
|
||||
- Choose based on agent complexity and required capabilities
|
||||
|
||||
#### **target** (OPTIONAL)
|
||||
- Specifies target environment: `'vscode'` or `'github-copilot'`
|
||||
- If omitted, agent is available in both environments
|
||||
- Use when agent has environment-specific features
|
||||
|
||||
#### **infer** (OPTIONAL)
|
||||
- Boolean controlling whether Copilot can automatically use this agent based on context
|
||||
- Default: `true` if omitted
|
||||
- Set to `false` to require manual agent selection
|
||||
|
||||
#### **metadata** (OPTIONAL, GitHub.com only)
|
||||
- Object with name-value pairs for agent annotation
|
||||
- Example: `metadata: { category: 'testing', version: '1.0' }`
|
||||
- Not supported in VS Code
|
||||
|
||||
#### **mcp-servers** (OPTIONAL, Organization/Enterprise only)
|
||||
- Configure MCP servers available only to this agent
|
||||
- Only supported for organization/enterprise level agents
|
||||
- See "MCP Server Configuration" section below
|
||||
|
||||
## Tool Configuration
|
||||
|
||||
### Tool Specification Strategies
|
||||
|
||||
**Enable all tools** (default):
|
||||
```yaml
|
||||
# Omit tools property entirely, or use:
|
||||
tools: ['*']
|
||||
```
|
||||
|
||||
**Enable specific tools**:
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'search', 'execute']
|
||||
```
|
||||
|
||||
**Enable MCP server tools**:
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'github/*', 'playwright/navigate']
|
||||
```
|
||||
|
||||
**Disable all tools**:
|
||||
```yaml
|
||||
tools: []
|
||||
```
|
||||
|
||||
### Standard Tool Aliases
|
||||
|
||||
All aliases are case-insensitive:
|
||||
|
||||
| Alias | Alternative Names | Category | Description |
|
||||
|-------|------------------|----------|-------------|
|
||||
| `execute` | shell, Bash, powershell | Shell execution | Execute commands in appropriate shell |
|
||||
| `read` | Read, NotebookRead, view | File reading | Read file contents |
|
||||
| `edit` | Edit, MultiEdit, Write, NotebookEdit | File editing | Edit and modify files |
|
||||
| `search` | Grep, Glob, search | Code search | Search for files or text in files |
|
||||
| `agent` | custom-agent, Task | Agent invocation | Invoke other custom agents |
|
||||
| `web` | WebSearch, WebFetch | Web access | Fetch web content and search |
|
||||
| `todo` | TodoWrite | Task management | Create and manage task lists (VS Code only) |
|
||||
|
||||
### Built-in MCP Server Tools
|
||||
|
||||
**GitHub MCP Server**:
|
||||
```yaml
|
||||
tools: ['github/*'] # All GitHub tools
|
||||
tools: ['github/get_file_contents', 'github/search_repositories'] # Specific tools
|
||||
```
|
||||
- All read-only tools available by default
|
||||
- Token scoped to source repository
|
||||
|
||||
**Playwright MCP Server**:
|
||||
```yaml
|
||||
tools: ['playwright/*'] # All Playwright tools
|
||||
tools: ['playwright/navigate', 'playwright/screenshot'] # Specific tools
|
||||
```
|
||||
- Configured to access localhost only
|
||||
- Useful for browser automation and testing
|
||||
|
||||
### Tool Selection Best Practices
|
||||
|
||||
- **Principle of Least Privilege**: Only enable tools necessary for the agent's purpose
|
||||
- **Security**: Limit `execute` access unless explicitly required
|
||||
- **Focus**: Fewer tools = clearer agent purpose and better performance
|
||||
- **Documentation**: Comment why specific tools are required for complex configurations
|
||||
|
||||
## Sub-Agent Invocation (Agent Orchestration)
|
||||
|
||||
Agents can invoke other agents using `runSubagent` to orchestrate multi-step workflows.
|
||||
|
||||
### How It Works
|
||||
|
||||
Include `agent` in tools list to enable sub-agent invocation:
|
||||
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'search', 'agent']
|
||||
```
|
||||
|
||||
Then invoke other agents with `runSubagent`:
|
||||
|
||||
```javascript
|
||||
const result = await runSubagent({
|
||||
description: 'What this step does',
|
||||
prompt: `You are the [Specialist] specialist.
|
||||
|
||||
Context:
|
||||
- Parameter: ${parameterValue}
|
||||
- Input: ${inputPath}
|
||||
- Output: ${outputPath}
|
||||
|
||||
Task:
|
||||
1. Do the specific work
|
||||
2. Write results to output location
|
||||
3. Return summary of completion`
|
||||
});
|
||||
```
|
||||
|
||||
### Basic Pattern
|
||||
|
||||
Structure each sub-agent call with:
|
||||
|
||||
1. **description**: Clear one-line purpose of the sub-agent invocation
|
||||
2. **prompt**: Detailed instructions with substituted variables
|
||||
|
||||
The prompt should include:
|
||||
- Who the sub-agent is (specialist role)
|
||||
- What context it needs (parameters, paths)
|
||||
- What to do (concrete tasks)
|
||||
- Where to write output
|
||||
- What to return (summary)
|
||||
|
||||
### Example: Multi-Step Processing
|
||||
|
||||
```javascript
|
||||
// Step 1: Process data
|
||||
const processing = await runSubagent({
|
||||
description: 'Transform raw input data',
|
||||
prompt: `You are the Data Processor specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${basePath}/raw/
|
||||
Output: ${basePath}/processed/
|
||||
|
||||
Task:
|
||||
1. Read all files from input directory
|
||||
2. Apply transformations
|
||||
3. Write processed files to output
|
||||
4. Create summary: ${basePath}/processed/summary.md
|
||||
|
||||
Return: Number of files processed and any issues found`
|
||||
});
|
||||
|
||||
// Step 2: Analyze (depends on Step 1)
|
||||
const analysis = await runSubagent({
|
||||
description: 'Analyze processed data',
|
||||
prompt: `You are the Data Analyst specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${basePath}/processed/
|
||||
Output: ${basePath}/analysis/
|
||||
|
||||
Task:
|
||||
1. Read processed files from input
|
||||
2. Generate analysis report
|
||||
3. Write to: ${basePath}/analysis/report.md
|
||||
|
||||
Return: Key findings and identified patterns`
|
||||
});
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
- **Pass variables in prompts**: Use `${variableName}` for all dynamic values
|
||||
- **Keep prompts focused**: Clear, specific tasks for each sub-agent
|
||||
- **Return summaries**: Each sub-agent should report what it accomplished
|
||||
- **Sequential execution**: Use `await` to maintain order when steps depend on each other
|
||||
- **Error handling**: Check results before proceeding to dependent steps
|
||||
|
||||
### ⚠️ Tool Availability Requirement
|
||||
|
||||
**Critical**: If a sub-agent requires specific tools (e.g., `edit`, `execute`, `search`), the orchestrator must include those tools in its own `tools` list. Sub-agents cannot access tools that aren't available to their parent orchestrator.
|
||||
|
||||
**Example**:
|
||||
```yaml
|
||||
# If your sub-agents need to edit files, execute commands, or search code
|
||||
tools: ['read', 'edit', 'search', 'execute', 'agent']
|
||||
```
|
||||
|
||||
The orchestrator's tool permissions act as a ceiling for all invoked sub-agents. Plan your tool list carefully to ensure all sub-agents have the tools they need.
|
||||
|
||||
### ⚠️ Important Limitation
|
||||
|
||||
**Sub-agent orchestration is NOT suitable for large-scale data processing.** Avoid using `runSubagent` when:
|
||||
- Processing hundreds or thousands of files
|
||||
- Handling large datasets
|
||||
- Performing bulk transformations on big codebases
|
||||
- Orchestrating more than 5-10 sequential steps
|
||||
|
||||
Each sub-agent call adds latency and context overhead. For high-volume processing, implement logic directly in a single agent instead. Use orchestration only for coordinating specialized tasks on focused, manageable datasets.
|
||||
|
||||
## Agent Prompt Structure
|
||||
|
||||
The markdown content below the frontmatter defines the agent's behavior, expertise, and instructions. Well-structured prompts typically include:
|
||||
|
||||
1. **Agent Identity and Role**: Who the agent is and its primary role
|
||||
2. **Core Responsibilities**: What specific tasks the agent performs
|
||||
3. **Approach and Methodology**: How the agent works to accomplish tasks
|
||||
4. **Guidelines and Constraints**: What to do/avoid and quality standards
|
||||
5. **Output Expectations**: Expected output format and quality
|
||||
|
||||
### Prompt Writing Best Practices
|
||||
|
||||
- **Be Specific and Direct**: Use imperative mood ("Analyze", "Generate"); avoid vague terms
|
||||
- **Define Boundaries**: Clearly state scope limits and constraints
|
||||
- **Include Context**: Explain domain expertise and reference relevant frameworks
|
||||
- **Focus on Behavior**: Describe how the agent should think and work
|
||||
- **Use Structured Format**: Headers, bullets, and lists make prompts scannable
|
||||
|
||||
## Variable Definition and Extraction
|
||||
|
||||
Agents can define dynamic parameters to extract values from user input and use them throughout the agent's behavior and sub-agent communications. This enables flexible, context-aware agents that adapt to user-provided data.
|
||||
|
||||
### When to Use Variables
|
||||
|
||||
**Use variables when**:
|
||||
- Agent behavior depends on user input
|
||||
- Need to pass dynamic values to sub-agents
|
||||
- Want to make agents reusable across different contexts
|
||||
- Require parameterized workflows
|
||||
- Need to track or reference user-provided context
|
||||
|
||||
**Examples**:
|
||||
- Extract project name from user prompt
|
||||
- Capture certification name for pipeline processing
|
||||
- Identify file paths or directories
|
||||
- Extract configuration options
|
||||
- Parse feature names or module identifiers
|
||||
|
||||
### Variable Declaration Pattern
|
||||
|
||||
Define variables section early in the agent prompt to document expected parameters:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
## Dynamic Parameters
|
||||
|
||||
- **Parameter Name**: Description and usage
|
||||
- **Another Parameter**: How it's extracted and used
|
||||
|
||||
## Your Mission
|
||||
|
||||
Process [PARAMETER_NAME] to accomplish [task].
|
||||
```
|
||||
|
||||
### Variable Extraction Methods
|
||||
|
||||
#### 1. **Explicit User Input**
|
||||
Ask the user to provide the variable if not detected in the prompt:
|
||||
|
||||
```markdown
|
||||
## Your Mission
|
||||
|
||||
Process the project by analyzing your codebase.
|
||||
|
||||
### Step 1: Identify Project
|
||||
If no project name is provided, **ASK THE USER** for:
|
||||
- Project name or identifier
|
||||
- Base path or directory location
|
||||
- Configuration type (if applicable)
|
||||
|
||||
Use this information to contextualize all subsequent tasks.
|
||||
```
|
||||
|
||||
#### 2. **Implicit Extraction from Prompt**
|
||||
Automatically extract variables from the user's natural language input:
|
||||
|
||||
```javascript
|
||||
// Example: Extract certification name from user input
|
||||
const userInput = "Process My Certification";
|
||||
|
||||
// Extract key information
|
||||
const certificationName = extractCertificationName(userInput);
|
||||
// Result: "My Certification"
|
||||
|
||||
const basePath = `certifications/${certificationName}`;
|
||||
// Result: "certifications/My Certification"
|
||||
```
|
||||
|
||||
#### 3. **Contextual Variable Resolution**
|
||||
Use file context or workspace information to derive variables:
|
||||
|
||||
```markdown
|
||||
## Variable Resolution Strategy
|
||||
|
||||
1. **From User Prompt**: First, look for explicit mentions in user input
|
||||
2. **From File Context**: Check current file name or path
|
||||
3. **From Workspace**: Use workspace folder or active project
|
||||
4. **From Settings**: Reference configuration files
|
||||
5. **Ask User**: If all else fails, request missing information
|
||||
```
|
||||
|
||||
### Using Variables in Agent Prompts
|
||||
|
||||
#### Variable Substitution in Instructions
|
||||
|
||||
Use template variables in agent prompts to make them dynamic:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
## Dynamic Parameters
|
||||
- **Project Name**: ${projectName}
|
||||
- **Base Path**: ${basePath}
|
||||
- **Output Directory**: ${outputDir}
|
||||
|
||||
## Your Mission
|
||||
|
||||
Process the **${projectName}** project located at `${basePath}`.
|
||||
|
||||
## Process Steps
|
||||
|
||||
1. Read input from: `${basePath}/input/`
|
||||
2. Process files according to project configuration
|
||||
3. Write results to: `${outputDir}/`
|
||||
4. Generate summary report
|
||||
|
||||
## Quality Standards
|
||||
|
||||
- Maintain project-specific coding standards for **${projectName}**
|
||||
- Follow directory structure: `${basePath}/[structure]`
|
||||
```
|
||||
|
||||
#### Passing Variables to Sub-Agents
|
||||
|
||||
When invoking a sub-agent, pass all context through template variables in the prompt:
|
||||
|
||||
```javascript
|
||||
// Extract and prepare variables
|
||||
const basePath = `projects/${projectName}`;
|
||||
const inputPath = `${basePath}/src/`;
|
||||
const outputPath = `${basePath}/docs/`;
|
||||
|
||||
// Pass to sub-agent with all variables substituted
|
||||
const result = await runSubagent({
|
||||
description: 'Generate project documentation',
|
||||
prompt: `You are the Documentation specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${inputPath}
|
||||
Output: ${outputPath}
|
||||
|
||||
Task:
|
||||
1. Read source files from ${inputPath}
|
||||
2. Generate comprehensive documentation
|
||||
3. Write to ${outputPath}/index.md
|
||||
4. Include code examples and usage guides
|
||||
|
||||
Return: Summary of documentation generated (file count, word count)`
|
||||
});
|
||||
```
|
||||
|
||||
The sub-agent receives all necessary context embedded in the prompt. Variables are resolved before sending the prompt, so the sub-agent works with concrete paths and values, not variable placeholders.
|
||||
|
||||
### Real-World Example: Code Review Orchestrator
|
||||
|
||||
Example of a simple orchestrator that validates code through multiple specialized agents:
|
||||
|
||||
```javascript
|
||||
async function reviewCodePipeline(repositoryName, prNumber) {
|
||||
const basePath = `projects/${repositoryName}/pr-${prNumber}`;
|
||||
|
||||
// Step 1: Security Review
|
||||
const security = await runSubagent({
|
||||
description: 'Scan for security vulnerabilities',
|
||||
prompt: `You are the Security Reviewer specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
PR: ${prNumber}
|
||||
Code: ${basePath}/changes/
|
||||
|
||||
Task:
|
||||
1. Scan code for OWASP Top 10 vulnerabilities
|
||||
2. Check for injection attacks, auth flaws
|
||||
3. Write findings to ${basePath}/security-review.md
|
||||
|
||||
Return: List of critical, high, and medium issues found`
|
||||
});
|
||||
|
||||
// Step 2: Test Coverage Check
|
||||
const coverage = await runSubagent({
|
||||
description: 'Verify test coverage for changes',
|
||||
prompt: `You are the Test Coverage specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
PR: ${prNumber}
|
||||
Changes: ${basePath}/changes/
|
||||
|
||||
Task:
|
||||
1. Analyze code coverage for modified files
|
||||
2. Identify untested critical paths
|
||||
3. Write report to ${basePath}/coverage-report.md
|
||||
|
||||
Return: Current coverage percentage and gaps`
|
||||
});
|
||||
|
||||
// Step 3: Aggregate Results
|
||||
const finalReport = await runSubagent({
|
||||
description: 'Compile all review findings',
|
||||
prompt: `You are the Review Aggregator specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
Reports: ${basePath}/*.md
|
||||
|
||||
Task:
|
||||
1. Read all review reports from ${basePath}/
|
||||
2. Synthesize findings into single report
|
||||
3. Determine overall verdict (APPROVE/NEEDS_FIXES/BLOCK)
|
||||
4. Write to ${basePath}/final-review.md
|
||||
|
||||
Return: Final verdict and executive summary`
|
||||
});
|
||||
|
||||
return finalReport;
|
||||
}
|
||||
```
|
||||
|
||||
This pattern applies to any orchestration scenario: extract variables, call sub-agents with clear context, await results.
|
||||
|
||||
|
||||
### Variable Best Practices
|
||||
|
||||
#### 1. **Clear Documentation**
|
||||
Always document what variables are expected:
|
||||
|
||||
```markdown
|
||||
## Required Variables
|
||||
- **projectName**: The name of the project (string, required)
|
||||
- **basePath**: Root directory for project files (path, required)
|
||||
|
||||
## Optional Variables
|
||||
- **mode**: Processing mode - quick/standard/detailed (enum, default: standard)
|
||||
- **outputFormat**: Output format - markdown/json/html (enum, default: markdown)
|
||||
|
||||
## Derived Variables
|
||||
- **outputDir**: Automatically set to ${basePath}/output
|
||||
- **logFile**: Automatically set to ${basePath}/.log.md
|
||||
```
|
||||
|
||||
#### 2. **Consistent Naming**
|
||||
Use consistent variable naming conventions:
|
||||
|
||||
```javascript
|
||||
// Good: Clear, descriptive naming
|
||||
const variables = {
|
||||
projectName, // What project to work on
|
||||
basePath, // Where project files are located
|
||||
outputDirectory, // Where to save results
|
||||
processingMode, // How to process (detail level)
|
||||
configurationPath // Where config files are
|
||||
};
|
||||
|
||||
// Avoid: Ambiguous or inconsistent
|
||||
const bad_variables = {
|
||||
name, // Too generic
|
||||
path, // Unclear which path
|
||||
mode, // Too short
|
||||
config // Too vague
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. **Validation and Constraints**
|
||||
Document valid values and constraints:
|
||||
|
||||
```markdown
|
||||
## Variable Constraints
|
||||
|
||||
**projectName**:
|
||||
- Type: string (alphanumeric, hyphens, underscores allowed)
|
||||
- Length: 1-100 characters
|
||||
- Required: yes
|
||||
- Pattern: `/^[a-zA-Z0-9_-]+$/`
|
||||
|
||||
**processingMode**:
|
||||
- Type: enum
|
||||
- Valid values: "quick" (< 5min), "standard" (5-15min), "detailed" (15+ min)
|
||||
- Default: "standard"
|
||||
- Required: no
|
||||
```
|
||||
|
||||
## MCP Server Configuration (Organization/Enterprise Only)
|
||||
|
||||
MCP servers extend agent capabilities with additional tools. Only supported for organization and enterprise-level agents.
|
||||
|
||||
### Configuration Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-custom-agent
|
||||
description: 'Agent with MCP integration'
|
||||
tools: ['read', 'edit', 'custom-mcp/tool-1']
|
||||
mcp-servers:
|
||||
custom-mcp:
|
||||
type: 'local'
|
||||
command: 'some-command'
|
||||
args: ['--arg1', '--arg2']
|
||||
tools: ["*"]
|
||||
env:
|
||||
ENV_VAR_NAME: ${{ secrets.API_KEY }}
|
||||
---
|
||||
```
|
||||
|
||||
### MCP Server Properties
|
||||
|
||||
- **type**: Server type (`'local'` or `'stdio'`)
|
||||
- **command**: Command to start the MCP server
|
||||
- **args**: Array of command arguments
|
||||
- **tools**: Tools to enable from this server (`["*"]` for all)
|
||||
- **env**: Environment variables (supports secrets)
|
||||
|
||||
### Environment Variables and Secrets
|
||||
|
||||
Secrets must be configured in repository settings under "copilot" environment.
|
||||
|
||||
**Supported syntax**:
|
||||
```yaml
|
||||
env:
|
||||
# Environment variable only
|
||||
VAR_NAME: COPILOT_MCP_ENV_VAR_VALUE
|
||||
|
||||
# Variable with header
|
||||
VAR_NAME: $COPILOT_MCP_ENV_VAR_VALUE
|
||||
VAR_NAME: ${COPILOT_MCP_ENV_VAR_VALUE}
|
||||
|
||||
# GitHub Actions-style (YAML only)
|
||||
VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
|
||||
VAR_NAME: ${{ var.COPILOT_MCP_ENV_VAR_VALUE }}
|
||||
```
|
||||
|
||||
## File Organization and Naming
|
||||
|
||||
### Repository-Level Agents
|
||||
- Location: `.github/agents/`
|
||||
- Scope: Available only in the specific repository
|
||||
- Access: Uses repository-configured MCP servers
|
||||
|
||||
### Organization/Enterprise-Level Agents
|
||||
- Location: `.github-private/agents/` (then move to `agents/` root)
|
||||
- Scope: Available across all repositories in org/enterprise
|
||||
- Access: Can configure dedicated MCP servers
|
||||
|
||||
### Naming Conventions
|
||||
- Use lowercase with hyphens: `test-specialist.agent.md`
|
||||
- Name should reflect agent purpose
|
||||
- Filename becomes default agent name (if `name` not specified)
|
||||
- Allowed characters: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`
|
||||
|
||||
## Agent Processing and Behavior
|
||||
|
||||
### Versioning
|
||||
- Based on Git commit SHAs for the agent file
|
||||
- Create branches/tags for different agent versions
|
||||
- Instantiated using latest version for repository/branch
|
||||
- PR interactions use same agent version for consistency
|
||||
|
||||
### Name Conflicts
|
||||
Priority (highest to lowest):
|
||||
1. Repository-level agent
|
||||
2. Organization-level agent
|
||||
3. Enterprise-level agent
|
||||
|
||||
Lower-level configurations override higher-level ones with the same name.
|
||||
|
||||
### Tool Processing
|
||||
- `tools` list filters available tools (built-in and MCP)
|
||||
- No tools specified = all tools enabled
|
||||
- Empty list (`[]`) = all tools disabled
|
||||
- Specific list = only those tools enabled
|
||||
- Unrecognized tool names are ignored (allows environment-specific tools)
|
||||
|
||||
### MCP Server Processing Order
|
||||
1. Out-of-the-box MCP servers (e.g., GitHub MCP)
|
||||
2. Custom agent MCP configuration (org/enterprise only)
|
||||
3. Repository-level MCP configurations
|
||||
|
||||
Each level can override settings from previous levels.
|
||||
|
||||
## Agent Creation Checklist
|
||||
|
||||
### Frontmatter
|
||||
- [ ] `description` field present and descriptive (50-150 chars)
|
||||
- [ ] `description` wrapped in single quotes
|
||||
- [ ] `name` specified (optional but recommended)
|
||||
- [ ] `tools` configured appropriately (or intentionally omitted)
|
||||
- [ ] `model` specified for optimal performance
|
||||
- [ ] `target` set if environment-specific
|
||||
- [ ] `infer` set to `false` if manual selection required
|
||||
|
||||
### Prompt Content
|
||||
- [ ] Clear agent identity and role defined
|
||||
- [ ] Core responsibilities listed explicitly
|
||||
- [ ] Approach and methodology explained
|
||||
- [ ] Guidelines and constraints specified
|
||||
- [ ] Output expectations documented
|
||||
- [ ] Examples provided where helpful
|
||||
- [ ] Instructions are specific and actionable
|
||||
- [ ] Scope and boundaries clearly defined
|
||||
- [ ] Total content under 30,000 characters
|
||||
|
||||
### File Structure
|
||||
- [ ] Filename follows lowercase-with-hyphens convention
|
||||
- [ ] File placed in correct directory (`.github/agents/` or `agents/`)
|
||||
- [ ] Filename uses only allowed characters
|
||||
- [ ] File extension is `.agent.md`
|
||||
|
||||
### Quality Assurance
|
||||
- [ ] Agent purpose is unique and not duplicative
|
||||
- [ ] Tools are minimal and necessary
|
||||
- [ ] Instructions are clear and unambiguous
|
||||
- [ ] Agent has been tested with representative tasks
|
||||
- [ ] Documentation references are current
|
||||
- [ ] Security considerations addressed (if applicable)
|
||||
|
||||
## Common Agent Patterns
|
||||
|
||||
### Testing Specialist
|
||||
**Purpose**: Focus on test coverage and quality
|
||||
**Tools**: All tools (for comprehensive test creation)
|
||||
**Approach**: Analyze, identify gaps, write tests, avoid production code changes
|
||||
|
||||
### Implementation Planner
|
||||
**Purpose**: Create detailed technical plans and specifications
|
||||
**Tools**: Limited to `['read', 'search', 'edit']`
|
||||
**Approach**: Analyze requirements, create documentation, avoid implementation
|
||||
|
||||
### Code Reviewer
|
||||
**Purpose**: Review code quality and provide feedback
|
||||
**Tools**: `['read', 'search']` only
|
||||
**Approach**: Analyze, suggest improvements, no direct modifications
|
||||
|
||||
### Refactoring Specialist
|
||||
**Purpose**: Improve code structure and maintainability
|
||||
**Tools**: `['read', 'search', 'edit']`
|
||||
**Approach**: Analyze patterns, propose refactorings, implement safely
|
||||
|
||||
### Security Auditor
|
||||
**Purpose**: Identify security issues and vulnerabilities
|
||||
**Tools**: `['read', 'search', 'web']`
|
||||
**Approach**: Scan code, check against OWASP, report findings
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Frontmatter Errors
|
||||
- ❌ Missing `description` field
|
||||
- ❌ Description not wrapped in quotes
|
||||
- ❌ Invalid tool names without checking documentation
|
||||
- ❌ Incorrect YAML syntax (indentation, quotes)
|
||||
|
||||
### Tool Configuration Issues
|
||||
- ❌ Granting excessive tool access unnecessarily
|
||||
- ❌ Missing required tools for agent's purpose
|
||||
- ❌ Not using tool aliases consistently
|
||||
- ❌ Forgetting MCP server namespace (`server-name/tool`)
|
||||
|
||||
### Prompt Content Problems
|
||||
- ❌ Vague, ambiguous instructions
|
||||
- ❌ Conflicting or contradictory guidelines
|
||||
- ❌ Lack of clear scope definition
|
||||
- ❌ Missing output expectations
|
||||
- ❌ Overly verbose instructions (exceeding character limits)
|
||||
- ❌ No examples or context for complex tasks
|
||||
|
||||
### Organizational Issues
|
||||
- ❌ Filename doesn't reflect agent purpose
|
||||
- ❌ Wrong directory (confusing repo vs org level)
|
||||
- ❌ Using spaces or special characters in filename
|
||||
- ❌ Duplicate agent names causing conflicts
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### Manual Testing
|
||||
1. Create the agent file with proper frontmatter
|
||||
2. Reload VS Code or refresh GitHub.com
|
||||
3. Select the agent from the dropdown in Copilot Chat
|
||||
4. Test with representative user queries
|
||||
5. Verify tool access works as expected
|
||||
6. Confirm output meets expectations
|
||||
|
||||
### Integration Testing
|
||||
- Test agent with different file types in scope
|
||||
- Verify MCP server connectivity (if configured)
|
||||
- Check agent behavior with missing context
|
||||
- Test error handling and edge cases
|
||||
- Validate agent switching and handoffs
|
||||
|
||||
### Quality Checks
|
||||
- Run through agent creation checklist
|
||||
- Review against common mistakes list
|
||||
- Compare with example agents in repository
|
||||
- Get peer review for complex agents
|
||||
- Document any special configuration needs
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Official Documentation
|
||||
- [Creating Custom Agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
|
||||
- [Custom Agents Configuration](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
|
||||
- [Custom Agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
|
||||
- [MCP Integration](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp)
|
||||
|
||||
### Community Resources
|
||||
- [Awesome Copilot Agents Collection](https://github.com/github/awesome-copilot/tree/main/agents)
|
||||
- [Customization Library Examples](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents)
|
||||
- [Your First Custom Agent Tutorial](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents/your-first-custom-agent)
|
||||
|
||||
### Related Files
|
||||
- [Prompt Files Guidelines](./prompt.instructions.md) - For creating prompt files
|
||||
- [Instructions Guidelines](./instructions.instructions.md) - For creating instruction files
|
||||
|
||||
## Version Compatibility Notes
|
||||
|
||||
### GitHub.com (Coding Agent)
|
||||
- ✅ Fully supports all standard frontmatter properties
|
||||
- ✅ Repository and org/enterprise level agents
|
||||
- ✅ MCP server configuration (org/enterprise)
|
||||
- ❌ Does not support `model`, `argument-hint`, `handoffs` properties
|
||||
|
||||
### VS Code / JetBrains / Eclipse / Xcode
|
||||
- ✅ Supports `model` property for AI model selection
|
||||
- ✅ Supports `argument-hint` and `handoffs` properties
|
||||
- ✅ User profile and workspace-level agents
|
||||
- ❌ Cannot configure MCP servers at repository level
|
||||
- ⚠️ Some properties may behave differently
|
||||
|
||||
When creating agents for multiple environments, focus on common properties and test in all target environments. Use `target` property to create environment-specific agents when necessary.
|
||||
418
.github/instructions/code-review-generic.instructions.md
vendored
Normal file
418
.github/instructions/code-review-generic.instructions.md
vendored
Normal file
@@ -0,0 +1,418 @@
|
||||
---
|
||||
description: 'Generic code review instructions that can be customized for any project using GitHub Copilot'
|
||||
applyTo: '**'
|
||||
excludeAgent: ["coding-agent"]
|
||||
---
|
||||
|
||||
# Generic Code Review Instructions
|
||||
|
||||
Comprehensive code review guidelines for GitHub Copilot that can be adapted to any project. These instructions follow best practices from prompt engineering and provide a structured approach to code quality, security, testing, and architecture review.
|
||||
|
||||
## Review Language
|
||||
|
||||
When performing a code review, respond in **English** (or specify your preferred language).
|
||||
|
||||
> **Customization Tip**: Change to your preferred language by replacing "English" with "Portuguese (Brazilian)", "Spanish", "French", etc.
|
||||
|
||||
## Review Priorities
|
||||
|
||||
When performing a code review, prioritize issues in the following order:
|
||||
|
||||
### 🔴 CRITICAL (Block merge)
|
||||
- **Security**: Vulnerabilities, exposed secrets, authentication/authorization issues
|
||||
- **Correctness**: Logic errors, data corruption risks, race conditions
|
||||
- **Breaking Changes**: API contract changes without versioning
|
||||
- **Data Loss**: Risk of data loss or corruption
|
||||
|
||||
### 🟡 IMPORTANT (Requires discussion)
|
||||
- **Code Quality**: Severe violations of SOLID principles, excessive duplication
|
||||
- **Test Coverage**: Missing tests for critical paths or new functionality
|
||||
- **Performance**: Obvious performance bottlenecks (N+1 queries, memory leaks)
|
||||
- **Architecture**: Significant deviations from established patterns
|
||||
|
||||
### 🟢 SUGGESTION (Non-blocking improvements)
|
||||
- **Readability**: Poor naming, complex logic that could be simplified
|
||||
- **Optimization**: Performance improvements without functional impact
|
||||
- **Best Practices**: Minor deviations from conventions
|
||||
- **Documentation**: Missing or incomplete comments/documentation
|
||||
|
||||
## General Review Principles
|
||||
|
||||
When performing a code review, follow these principles:
|
||||
|
||||
1. **Be specific**: Reference exact lines, files, and provide concrete examples
|
||||
2. **Provide context**: Explain WHY something is an issue and the potential impact
|
||||
3. **Suggest solutions**: Show corrected code when applicable, not just what's wrong
|
||||
4. **Be constructive**: Focus on improving the code, not criticizing the author
|
||||
5. **Recognize good practices**: Acknowledge well-written code and smart solutions
|
||||
6. **Be pragmatic**: Not every suggestion needs immediate implementation
|
||||
7. **Group related comments**: Avoid multiple comments about the same topic
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
When performing a code review, check for:
|
||||
|
||||
### Clean Code
|
||||
- Descriptive and meaningful names for variables, functions, and classes
|
||||
- Single Responsibility Principle: each function/class does one thing well
|
||||
- DRY (Don't Repeat Yourself): no code duplication
|
||||
- Functions should be small and focused (ideally < 20-30 lines)
|
||||
- Avoid deeply nested code (max 3-4 levels)
|
||||
- Avoid magic numbers and strings (use constants)
|
||||
- Code should be self-documenting; comments only when necessary
|
||||
|
||||
### Examples
|
||||
```javascript
|
||||
// ❌ BAD: Poor naming and magic numbers
|
||||
function calc(x, y) {
|
||||
if (x > 100) return y * 0.15;
|
||||
return y * 0.10;
|
||||
}
|
||||
|
||||
// ✅ GOOD: Clear naming and constants
|
||||
const PREMIUM_THRESHOLD = 100;
|
||||
const PREMIUM_DISCOUNT_RATE = 0.15;
|
||||
const STANDARD_DISCOUNT_RATE = 0.10;
|
||||
|
||||
function calculateDiscount(orderTotal, itemPrice) {
|
||||
const isPremiumOrder = orderTotal > PREMIUM_THRESHOLD;
|
||||
const discountRate = isPremiumOrder ? PREMIUM_DISCOUNT_RATE : STANDARD_DISCOUNT_RATE;
|
||||
return itemPrice * discountRate;
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
- Proper error handling at appropriate levels
|
||||
- Meaningful error messages
|
||||
- No silent failures or ignored exceptions
|
||||
- Fail fast: validate inputs early
|
||||
- Use appropriate error types/exceptions
|
||||
|
||||
### Examples
|
||||
```python
|
||||
# ❌ BAD: Silent failure and generic error
|
||||
def process_user(user_id):
|
||||
try:
|
||||
user = db.get(user_id)
|
||||
user.process()
|
||||
except:
|
||||
pass
|
||||
|
||||
# ✅ GOOD: Explicit error handling
|
||||
def process_user(user_id):
|
||||
if not user_id or user_id <= 0:
|
||||
raise ValueError(f"Invalid user_id: {user_id}")
|
||||
|
||||
try:
|
||||
user = db.get(user_id)
|
||||
except UserNotFoundError:
|
||||
raise UserNotFoundError(f"User {user_id} not found in database")
|
||||
except DatabaseError as e:
|
||||
raise ProcessingError(f"Failed to retrieve user {user_id}: {e}")
|
||||
|
||||
return user.process()
|
||||
```
|
||||
|
||||
## Security Review
|
||||
|
||||
When performing a code review, check for security issues:
|
||||
|
||||
- **Sensitive Data**: No passwords, API keys, tokens, or PII in code or logs
|
||||
- **Input Validation**: All user inputs are validated and sanitized
|
||||
- **SQL Injection**: Use parameterized queries, never string concatenation
|
||||
- **Authentication**: Proper authentication checks before accessing resources
|
||||
- **Authorization**: Verify user has permission to perform action
|
||||
- **Cryptography**: Use established libraries, never roll your own crypto
|
||||
- **Dependency Security**: Check for known vulnerabilities in dependencies
|
||||
|
||||
### Examples
|
||||
```java
|
||||
// ❌ BAD: SQL injection vulnerability
|
||||
String query = "SELECT * FROM users WHERE email = '" + email + "'";
|
||||
|
||||
// ✅ GOOD: Parameterized query
|
||||
PreparedStatement stmt = conn.prepareStatement(
|
||||
"SELECT * FROM users WHERE email = ?"
|
||||
);
|
||||
stmt.setString(1, email);
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ BAD: Exposed secret in code
|
||||
const API_KEY = "sk_live_abc123xyz789";
|
||||
|
||||
// ✅ GOOD: Use environment variables
|
||||
const API_KEY = process.env.API_KEY;
|
||||
```
|
||||
|
||||
## Testing Standards
|
||||
|
||||
When performing a code review, verify test quality:
|
||||
|
||||
- **Coverage**: Critical paths and new functionality must have tests
|
||||
- **Test Names**: Descriptive names that explain what is being tested
|
||||
- **Test Structure**: Clear Arrange-Act-Assert or Given-When-Then pattern
|
||||
- **Independence**: Tests should not depend on each other or external state
|
||||
- **Assertions**: Use specific assertions, avoid generic assertTrue/assertFalse
|
||||
- **Edge Cases**: Test boundary conditions, null values, empty collections
|
||||
- **Mock Appropriately**: Mock external dependencies, not domain logic
|
||||
|
||||
### Examples
|
||||
```typescript
|
||||
// ❌ BAD: Vague name and assertion
|
||||
test('test1', () => {
|
||||
const result = calc(5, 10);
|
||||
expect(result).toBeTruthy();
|
||||
});
|
||||
|
||||
// ✅ GOOD: Descriptive name and specific assertion
|
||||
test('should calculate 10% discount for orders under $100', () => {
|
||||
const orderTotal = 50;
|
||||
const itemPrice = 20;
|
||||
|
||||
const discount = calculateDiscount(orderTotal, itemPrice);
|
||||
|
||||
expect(discount).toBe(2.00);
|
||||
});
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
When performing a code review, check for performance issues:
|
||||
|
||||
- **Database Queries**: Avoid N+1 queries, use proper indexing
|
||||
- **Algorithms**: Appropriate time/space complexity for the use case
|
||||
- **Caching**: Utilize caching for expensive or repeated operations
|
||||
- **Resource Management**: Proper cleanup of connections, files, streams
|
||||
- **Pagination**: Large result sets should be paginated
|
||||
- **Lazy Loading**: Load data only when needed
|
||||
|
||||
### Examples
|
||||
```python
|
||||
# ❌ BAD: N+1 query problem
|
||||
users = User.query.all()
|
||||
for user in users:
|
||||
orders = Order.query.filter_by(user_id=user.id).all() # N+1!
|
||||
|
||||
# ✅ GOOD: Use JOIN or eager loading
|
||||
users = User.query.options(joinedload(User.orders)).all()
|
||||
for user in users:
|
||||
orders = user.orders
|
||||
```
|
||||
|
||||
## Architecture and Design
|
||||
|
||||
When performing a code review, verify architectural principles:
|
||||
|
||||
- **Separation of Concerns**: Clear boundaries between layers/modules
|
||||
- **Dependency Direction**: High-level modules don't depend on low-level details
|
||||
- **Interface Segregation**: Prefer small, focused interfaces
|
||||
- **Loose Coupling**: Components should be independently testable
|
||||
- **High Cohesion**: Related functionality grouped together
|
||||
- **Consistent Patterns**: Follow established patterns in the codebase
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
When performing a code review, check documentation:
|
||||
|
||||
- **API Documentation**: Public APIs must be documented (purpose, parameters, returns)
|
||||
- **Complex Logic**: Non-obvious logic should have explanatory comments
|
||||
- **README Updates**: Update README when adding features or changing setup
|
||||
- **Breaking Changes**: Document any breaking changes clearly
|
||||
- **Examples**: Provide usage examples for complex features
|
||||
|
||||
## Comment Format Template
|
||||
|
||||
When performing a code review, use this format for comments:
|
||||
|
||||
```markdown
|
||||
**[PRIORITY] Category: Brief title**
|
||||
|
||||
Detailed description of the issue or suggestion.
|
||||
|
||||
**Why this matters:**
|
||||
Explanation of the impact or reason for the suggestion.
|
||||
|
||||
**Suggested fix:**
|
||||
[code example if applicable]
|
||||
|
||||
**Reference:** [link to relevant documentation or standard]
|
||||
```
|
||||
|
||||
### Example Comments
|
||||
|
||||
#### Critical Issue
|
||||
```markdown
|
||||
**🔴 CRITICAL - Security: SQL Injection Vulnerability**
|
||||
|
||||
The query on line 45 concatenates user input directly into the SQL string,
|
||||
creating a SQL injection vulnerability.
|
||||
|
||||
**Why this matters:**
|
||||
An attacker could manipulate the email parameter to execute arbitrary SQL commands,
|
||||
potentially exposing or deleting all database data.
|
||||
|
||||
**Suggested fix:**
|
||||
```sql
|
||||
-- Instead of:
|
||||
query = "SELECT * FROM users WHERE email = '" + email + "'"
|
||||
|
||||
-- Use:
|
||||
PreparedStatement stmt = conn.prepareStatement(
|
||||
"SELECT * FROM users WHERE email = ?"
|
||||
);
|
||||
stmt.setString(1, email);
|
||||
```
|
||||
|
||||
**Reference:** OWASP SQL Injection Prevention Cheat Sheet
|
||||
```
|
||||
|
||||
#### Important Issue
|
||||
```markdown
|
||||
**🟡 IMPORTANT - Testing: Missing test coverage for critical path**
|
||||
|
||||
The `processPayment()` function handles financial transactions but has no tests
|
||||
for the refund scenario.
|
||||
|
||||
**Why this matters:**
|
||||
Refunds involve money movement and should be thoroughly tested to prevent
|
||||
financial errors or data inconsistencies.
|
||||
|
||||
**Suggested fix:**
|
||||
Add test case:
|
||||
```javascript
|
||||
test('should process full refund when order is cancelled', () => {
|
||||
const order = createOrder({ total: 100, status: 'cancelled' });
|
||||
|
||||
const result = processPayment(order, { type: 'refund' });
|
||||
|
||||
expect(result.refundAmount).toBe(100);
|
||||
expect(result.status).toBe('refunded');
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
#### Suggestion
|
||||
```markdown
|
||||
**🟢 SUGGESTION - Readability: Simplify nested conditionals**
|
||||
|
||||
The nested if statements on lines 30-40 make the logic hard to follow.
|
||||
|
||||
**Why this matters:**
|
||||
Simpler code is easier to maintain, debug, and test.
|
||||
|
||||
**Suggested fix:**
|
||||
```javascript
|
||||
// Instead of nested ifs:
|
||||
if (user) {
|
||||
if (user.isActive) {
|
||||
if (user.hasPermission('write')) {
|
||||
// do something
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Consider guard clauses:
|
||||
if (!user || !user.isActive || !user.hasPermission('write')) {
|
||||
return;
|
||||
}
|
||||
// do something
|
||||
```
|
||||
```
|
||||
|
||||
## Review Checklist
|
||||
|
||||
When performing a code review, systematically verify:
|
||||
|
||||
### Code Quality
|
||||
- [ ] Code follows consistent style and conventions
|
||||
- [ ] Names are descriptive and follow naming conventions
|
||||
- [ ] Functions/methods are small and focused
|
||||
- [ ] No code duplication
|
||||
- [ ] Complex logic is broken into simpler parts
|
||||
- [ ] Error handling is appropriate
|
||||
- [ ] No commented-out code or TODO without tickets
|
||||
|
||||
### Security
|
||||
- [ ] No sensitive data in code or logs
|
||||
- [ ] Input validation on all user inputs
|
||||
- [ ] No SQL injection vulnerabilities
|
||||
- [ ] Authentication and authorization properly implemented
|
||||
- [ ] Dependencies are up-to-date and secure
|
||||
|
||||
### Testing
|
||||
- [ ] New code has appropriate test coverage
|
||||
- [ ] Tests are well-named and focused
|
||||
- [ ] Tests cover edge cases and error scenarios
|
||||
- [ ] Tests are independent and deterministic
|
||||
- [ ] No tests that always pass or are commented out
|
||||
|
||||
### Performance
|
||||
- [ ] No obvious performance issues (N+1, memory leaks)
|
||||
- [ ] Appropriate use of caching
|
||||
- [ ] Efficient algorithms and data structures
|
||||
- [ ] Proper resource cleanup
|
||||
|
||||
### Architecture
|
||||
- [ ] Follows established patterns and conventions
|
||||
- [ ] Proper separation of concerns
|
||||
- [ ] No architectural violations
|
||||
- [ ] Dependencies flow in correct direction
|
||||
|
||||
### Documentation
|
||||
- [ ] Public APIs are documented
|
||||
- [ ] Complex logic has explanatory comments
|
||||
- [ ] README is updated if needed
|
||||
- [ ] Breaking changes are documented
|
||||
|
||||
## Project-Specific Customizations
|
||||
|
||||
To customize this template for your project, add sections for:
|
||||
|
||||
1. **Language/Framework specific checks**
|
||||
- Example: "When performing a code review, verify React hooks follow rules of hooks"
|
||||
- Example: "When performing a code review, check Spring Boot controllers use proper annotations"
|
||||
|
||||
2. **Build and deployment**
|
||||
- Example: "When performing a code review, verify CI/CD pipeline configuration is correct"
|
||||
- Example: "When performing a code review, check database migrations are reversible"
|
||||
|
||||
3. **Business logic rules**
|
||||
- Example: "When performing a code review, verify pricing calculations include all applicable taxes"
|
||||
- Example: "When performing a code review, check user consent is obtained before data processing"
|
||||
|
||||
4. **Team conventions**
|
||||
- Example: "When performing a code review, verify commit messages follow conventional commits format"
|
||||
- Example: "When performing a code review, check branch names follow pattern: type/ticket-description"
|
||||
|
||||
## Additional Resources
|
||||
|
||||
For more information on effective code reviews and GitHub Copilot customization:
|
||||
|
||||
- [GitHub Copilot Prompt Engineering](https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering)
|
||||
- [GitHub Copilot Custom Instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
|
||||
- [Awesome GitHub Copilot Repository](https://github.com/github/awesome-copilot)
|
||||
- [GitHub Code Review Guidelines](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests)
|
||||
- [Google Engineering Practices - Code Review](https://google.github.io/eng-practices/review/)
|
||||
- [OWASP Security Guidelines](https://owasp.org/)
|
||||
|
||||
## Prompt Engineering Tips
|
||||
|
||||
When performing a code review, apply these prompt engineering principles from the [GitHub Copilot documentation](https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering):
|
||||
|
||||
1. **Start General, Then Get Specific**: Begin with high-level architecture review, then drill into implementation details
|
||||
2. **Give Examples**: Reference similar patterns in the codebase when suggesting changes
|
||||
3. **Break Complex Tasks**: Review large PRs in logical chunks (security → tests → logic → style)
|
||||
4. **Avoid Ambiguity**: Be specific about which file, line, and issue you're addressing
|
||||
5. **Indicate Relevant Code**: Reference related code that might be affected by changes
|
||||
6. **Experiment and Iterate**: If initial review misses something, review again with focused questions
|
||||
|
||||
## Project Context
|
||||
|
||||
This is a generic template. Customize this section with your project-specific information:
|
||||
|
||||
- **Tech Stack**: [e.g., Java 17, Spring Boot 3.x, PostgreSQL]
|
||||
- **Architecture**: [e.g., Hexagonal/Clean Architecture, Microservices]
|
||||
- **Build Tool**: [e.g., Gradle, Maven, npm, pip]
|
||||
- **Testing**: [e.g., JUnit 5, Jest, pytest]
|
||||
- **Code Style**: [e.g., follows Google Style Guide]
|
||||
256
.github/instructions/instructions.instructions.md
vendored
Normal file
256
.github/instructions/instructions.instructions.md
vendored
Normal file
@@ -0,0 +1,256 @@
|
||||
---
|
||||
description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'
|
||||
applyTo: '**/*.instructions.md'
|
||||
---
|
||||
|
||||
# Custom Instructions File Guidelines
|
||||
|
||||
Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
|
||||
|
||||
## Project Context
|
||||
|
||||
- Target audience: Developers and GitHub Copilot working with domain-specific code
|
||||
- File format: Markdown with YAML frontmatter
|
||||
- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)
|
||||
- Location: `.github/instructions/` directory
|
||||
- Purpose: Provide context-aware guidance for code generation, review, and documentation
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Every instruction file must include YAML frontmatter with the following fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: 'Brief description of the instruction purpose and scope'
|
||||
applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
|
||||
---
|
||||
```
|
||||
|
||||
### Frontmatter Guidelines
|
||||
|
||||
- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose
|
||||
- **applyTo**: Glob pattern(s) specifying which files these instructions apply to
|
||||
- Single pattern: `'**/*.ts'`
|
||||
- Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`
|
||||
- Specific files: `'src/**/*.py'`
|
||||
- All files: `'**'`
|
||||
|
||||
## File Structure
|
||||
|
||||
A well-structured instruction file should include the following sections:
|
||||
|
||||
### 1. Title and Overview
|
||||
|
||||
- Clear, descriptive title using `#` heading
|
||||
- Brief introduction explaining the purpose and scope
|
||||
- Optional: Project context section with key technologies and versions
|
||||
|
||||
### 2. Core Sections
|
||||
|
||||
Organize content into logical sections based on the domain:
|
||||
|
||||
- **General Instructions**: High-level guidelines and principles
|
||||
- **Best Practices**: Recommended patterns and approaches
|
||||
- **Code Standards**: Naming conventions, formatting, style rules
|
||||
- **Architecture/Structure**: Project organization and design patterns
|
||||
- **Common Patterns**: Frequently used implementations
|
||||
- **Security**: Security considerations (if applicable)
|
||||
- **Performance**: Optimization guidelines (if applicable)
|
||||
- **Testing**: Testing standards and approaches (if applicable)
|
||||
|
||||
### 3. Examples and Code Snippets
|
||||
|
||||
Provide concrete examples with clear labels:
|
||||
|
||||
```markdown
|
||||
### Good Example
|
||||
\`\`\`language
|
||||
// Recommended approach
|
||||
code example here
|
||||
\`\`\`
|
||||
|
||||
### Bad Example
|
||||
\`\`\`language
|
||||
// Avoid this pattern
|
||||
code example here
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 4. Validation and Verification (Optional but Recommended)
|
||||
|
||||
- Build commands to verify code
|
||||
- Linting and formatting tools
|
||||
- Testing requirements
|
||||
- Verification steps
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### Writing Style
|
||||
|
||||
- Use clear, concise language
|
||||
- Write in imperative mood ("Use", "Implement", "Avoid")
|
||||
- Be specific and actionable
|
||||
- Avoid ambiguous terms like "should", "might", "possibly"
|
||||
- Use bullet points and lists for readability
|
||||
- Keep sections focused and scannable
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Be Specific**: Provide concrete examples rather than abstract concepts
|
||||
- **Show Why**: Explain the reasoning behind recommendations when it adds value
|
||||
- **Use Tables**: For comparing options, listing rules, or showing patterns
|
||||
- **Include Examples**: Real code snippets are more effective than descriptions
|
||||
- **Stay Current**: Reference current versions and best practices
|
||||
- **Link Resources**: Include official documentation and authoritative sources
|
||||
|
||||
### Common Patterns to Include
|
||||
|
||||
1. **Naming Conventions**: How to name variables, functions, classes, files
|
||||
2. **Code Organization**: File structure, module organization, import order
|
||||
3. **Error Handling**: Preferred error handling patterns
|
||||
4. **Dependencies**: How to manage and document dependencies
|
||||
5. **Comments and Documentation**: When and how to document code
|
||||
6. **Version Information**: Target language/framework versions
|
||||
|
||||
## Patterns to Follow
|
||||
|
||||
### Bullet Points and Lists
|
||||
|
||||
```markdown
|
||||
## Security Best Practices
|
||||
|
||||
- Always validate user input before processing
|
||||
- Use parameterized queries to prevent SQL injection
|
||||
- Store secrets in environment variables, never in code
|
||||
- Implement proper authentication and authorization
|
||||
- Enable HTTPS for all production endpoints
|
||||
```
|
||||
|
||||
### Tables for Structured Information
|
||||
|
||||
```markdown
|
||||
## Common Issues
|
||||
|
||||
| Issue | Solution | Example |
|
||||
| ---------------- | ------------------- | ----------------------------- |
|
||||
| Magic numbers | Use named constants | `const MAX_RETRIES = 3` |
|
||||
| Deep nesting | Extract functions | Refactor nested if statements |
|
||||
| Hardcoded values | Use configuration | Store API URLs in config |
|
||||
```
|
||||
|
||||
### Code Comparison
|
||||
|
||||
```markdown
|
||||
### Good Example - Using TypeScript interfaces
|
||||
\`\`\`typescript
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
function getUser(id: string): User {
|
||||
// Implementation
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Bad Example - Using any type
|
||||
\`\`\`typescript
|
||||
function getUser(id: any): any {
|
||||
// Loses type safety
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Conditional Guidance
|
||||
|
||||
```markdown
|
||||
## Framework Selection
|
||||
|
||||
- **For small projects**: Use Minimal API approach
|
||||
- **For large projects**: Use controller-based architecture with clear separation
|
||||
- **For microservices**: Consider domain-driven design patterns
|
||||
```
|
||||
|
||||
## Patterns to Avoid
|
||||
|
||||
- **Overly verbose explanations**: Keep it concise and scannable
|
||||
- **Outdated information**: Always reference current versions and practices
|
||||
- **Ambiguous guidelines**: Be specific about what to do or avoid
|
||||
- **Missing examples**: Abstract rules without concrete code examples
|
||||
- **Contradictory advice**: Ensure consistency throughout the file
|
||||
- **Copy-paste from documentation**: Add value by distilling and contextualizing
|
||||
|
||||
## Testing Your Instructions
|
||||
|
||||
Before finalizing instruction files:
|
||||
|
||||
1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
|
||||
2. **Verify Examples**: Ensure code examples are correct and run without errors
|
||||
3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
|
||||
|
||||
## Example Structure
|
||||
|
||||
Here's a minimal example structure for a new instruction file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: 'Brief description of purpose'
|
||||
applyTo: '**/*.ext'
|
||||
---
|
||||
|
||||
# Technology Name Development
|
||||
|
||||
Brief introduction and context.
|
||||
|
||||
## General Instructions
|
||||
|
||||
- High-level guideline 1
|
||||
- High-level guideline 2
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Specific practice 1
|
||||
- Specific practice 2
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Naming Conventions
|
||||
- Rule 1
|
||||
- Rule 2
|
||||
|
||||
### File Organization
|
||||
- Structure 1
|
||||
- Structure 2
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1
|
||||
Description and example
|
||||
|
||||
\`\`\`language
|
||||
code example
|
||||
\`\`\`
|
||||
|
||||
### Pattern 2
|
||||
Description and example
|
||||
|
||||
## Validation
|
||||
|
||||
- Build command: `command to verify`
|
||||
- Linting: `command to lint`
|
||||
- Testing: `command to test`
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
- Review instructions when dependencies or frameworks are updated
|
||||
- Update examples to reflect current best practices
|
||||
- Remove outdated patterns or deprecated features
|
||||
- Add new patterns as they emerge in the community
|
||||
- Keep glob patterns accurate as project structure evolves
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
|
||||
- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)
|
||||
410
.github/instructions/makefile.instructions.md
vendored
Normal file
410
.github/instructions/makefile.instructions.md
vendored
Normal file
@@ -0,0 +1,410 @@
|
||||
---
|
||||
description: "Best practices for authoring GNU Make Makefiles"
|
||||
applyTo: "**/Makefile, **/makefile, **/*.mk, **/GNUmakefile"
|
||||
---
|
||||
|
||||
# Makefile Development Instructions
|
||||
|
||||
Instructions for writing clean, maintainable, and portable GNU Make Makefiles. These instructions are based on the [GNU Make manual](https://www.gnu.org/software/make/manual/).
|
||||
|
||||
## General Principles
|
||||
|
||||
- Write clear and maintainable makefiles that follow GNU Make conventions
|
||||
- Use descriptive target names that clearly indicate their purpose
|
||||
- Keep the default goal (first target) as the most common build operation
|
||||
- Prioritize readability over brevity when writing rules and recipes
|
||||
- Add comments to explain complex rules, variables, or non-obvious behavior
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- Name your makefile `Makefile` (recommended for visibility) or `makefile`
|
||||
- Use `GNUmakefile` only for GNU Make-specific features incompatible with other make implementations
|
||||
- Use standard variable names: `objects`, `OBJECTS`, `objs`, `OBJS`, `obj`, or `OBJ` for object file lists
|
||||
- Use uppercase for built-in variable names (e.g., `CC`, `CFLAGS`, `LDFLAGS`)
|
||||
- Use descriptive target names that reflect their action (e.g., `clean`, `install`, `test`)
|
||||
|
||||
## File Structure
|
||||
|
||||
- Place the default goal (primary build target) as the first rule in the makefile
|
||||
- Group related targets together logically
|
||||
- Define variables at the top of the makefile before rules
|
||||
- Use `.PHONY` to declare targets that don't represent files
|
||||
- Structure makefiles with: variables, then rules, then phony targets
|
||||
|
||||
```makefile
|
||||
# Variables
|
||||
CC = gcc
|
||||
CFLAGS = -Wall -g
|
||||
objects = main.o utils.o
|
||||
|
||||
# Default goal
|
||||
all: program
|
||||
|
||||
# Rules
|
||||
program: $(objects)
|
||||
$(CC) -o program $(objects)
|
||||
|
||||
%.o: %.c
|
||||
$(CC) $(CFLAGS) -c $< -o $@
|
||||
|
||||
# Phony targets
|
||||
.PHONY: clean all
|
||||
clean:
|
||||
rm -f program $(objects)
|
||||
```
|
||||
|
||||
## Variables and Substitution
|
||||
|
||||
- Use variables to avoid duplication and improve maintainability
|
||||
- Define variables with `:=` (simple expansion) for immediate evaluation, `=` for recursive expansion
|
||||
- Use `?=` to set default values that can be overridden
|
||||
- Use `+=` to append to existing variables
|
||||
- Reference variables with `$(VARIABLE)` not `$VARIABLE` (unless single character)
|
||||
- Use automatic variables (`$@`, `$<`, `$^`, `$?`, `$*`) in recipes to make rules more generic
|
||||
|
||||
```makefile
|
||||
# Simple expansion (evaluates immediately)
|
||||
CC := gcc
|
||||
|
||||
# Recursive expansion (evaluates when used)
|
||||
CFLAGS = -Wall $(EXTRA_FLAGS)
|
||||
|
||||
# Conditional assignment
|
||||
PREFIX ?= /usr/local
|
||||
|
||||
# Append to variable
|
||||
CFLAGS += -g
|
||||
```
|
||||
|
||||
## Rules and Prerequisites
|
||||
|
||||
- Separate targets, prerequisites, and recipes clearly
|
||||
- Use implicit rules for standard compilations (e.g., `.c` to `.o`)
|
||||
- List prerequisites in logical order (normal prerequisites before order-only)
|
||||
- Use order-only prerequisites (after `|`) for directories and dependencies that shouldn't trigger rebuilds
|
||||
- Include all actual dependencies to ensure correct rebuilds
|
||||
- Avoid circular dependencies between targets
|
||||
- Remember that order-only prerequisites are omitted from automatic variables like `$^`, so reference them explicitly if needed
|
||||
|
||||
The example below shows a pattern rule that compiles objects into an `obj/` directory. The directory itself is listed as an order-only prerequisite so it is created before compiling but does not force recompilation when its timestamp changes.
|
||||
|
||||
```makefile
|
||||
# Normal prerequisites
|
||||
program: main.o utils.o
|
||||
$(CC) -o $@ $^
|
||||
|
||||
# Order-only prerequisites (directory creation)
|
||||
obj/%.o: %.c | obj
|
||||
$(CC) $(CFLAGS) -c $< -o $@
|
||||
|
||||
obj:
|
||||
mkdir -p obj
|
||||
```
|
||||
|
||||
## Recipes and Commands
|
||||
|
||||
- Start every recipe line with a **tab character** (not spaces) unless `.RECIPEPREFIX` is changed
|
||||
- Use `@` prefix to suppress command echoing when appropriate
|
||||
- Use `-` prefix to ignore errors for specific commands (use sparingly)
|
||||
- Combine related commands with `&&` or `;` on the same line when they must execute together
|
||||
- Keep recipes readable; break long commands across multiple lines with backslash continuation
|
||||
- Use shell conditionals and loops within recipes when needed
|
||||
|
||||
```makefile
|
||||
# Silent command
|
||||
clean:
|
||||
@echo "Cleaning up..."
|
||||
@rm -f $(objects)
|
||||
|
||||
# Ignore errors
|
||||
.PHONY: clean-all
|
||||
clean-all:
|
||||
-rm -rf build/
|
||||
-rm -rf dist/
|
||||
|
||||
# Multi-line recipe with proper continuation
|
||||
install: program
|
||||
install -d $(PREFIX)/bin && \
|
||||
install -m 755 program $(PREFIX)/bin
|
||||
```
|
||||
|
||||
## Phony Targets
|
||||
|
||||
- Always declare phony targets with `.PHONY` to avoid conflicts with files of the same name
|
||||
- Use phony targets for actions like `clean`, `install`, `test`, `all`
|
||||
- Place phony target declarations near their rule definitions or at the end of the makefile
|
||||
|
||||
```makefile
|
||||
.PHONY: all clean test install
|
||||
|
||||
all: program
|
||||
|
||||
clean:
|
||||
rm -f program $(objects)
|
||||
|
||||
test: program
|
||||
./run-tests.sh
|
||||
|
||||
install: program
|
||||
install -m 755 program $(PREFIX)/bin
|
||||
```
|
||||
|
||||
## Pattern Rules and Implicit Rules
|
||||
|
||||
- Use pattern rules (`%.o: %.c`) for generic transformations
|
||||
- Leverage built-in implicit rules when appropriate (GNU Make knows how to compile `.c` to `.o`)
|
||||
- Override implicit rule variables (like `CC`, `CFLAGS`) rather than rewriting the rules
|
||||
- Define custom pattern rules only when built-in rules are insufficient
|
||||
|
||||
```makefile
|
||||
# Use built-in implicit rules by setting variables
|
||||
CC = gcc
|
||||
CFLAGS = -Wall -O2
|
||||
|
||||
# Custom pattern rule for special cases
|
||||
%.pdf: %.md
|
||||
pandoc $< -o $@
|
||||
```
|
||||
|
||||
## Splitting Long Lines
|
||||
|
||||
- Use backslash-newline (`\`) to split long lines for readability
|
||||
- Be aware that backslash-newline is converted to a single space in non-recipe contexts
|
||||
- In recipes, backslash-newline preserves the line continuation for the shell
|
||||
- Avoid trailing whitespace after backslashes
|
||||
|
||||
### Splitting Without Adding Whitespace
|
||||
|
||||
If you need to split a line without adding whitespace, you can use a special technique: insert `$ ` (dollar-space) followed by a backslash-newline. The `$ ` refers to a variable with a single-space name, which doesn't exist and expands to nothing, effectively joining the lines without inserting a space.
|
||||
|
||||
```makefile
|
||||
# Concatenate strings without adding whitespace
|
||||
# The following creates the value "oneword"
|
||||
var := one$ \
|
||||
word
|
||||
|
||||
# This is equivalent to:
|
||||
# var := oneword
|
||||
```
|
||||
|
||||
```makefile
|
||||
# Variable definition split across lines
|
||||
sources = main.c \
|
||||
utils.c \
|
||||
parser.c \
|
||||
handler.c
|
||||
|
||||
# Recipe with long command
|
||||
build: $(objects)
|
||||
$(CC) -o program $(objects) \
|
||||
$(LDFLAGS) \
|
||||
-lm -lpthread
|
||||
```
|
||||
|
||||
## Including Other Makefiles
|
||||
|
||||
- Use `include` directive to share common definitions across makefiles
|
||||
- Use `-include` (or `sinclude`) to include optional makefiles without errors
|
||||
- Place `include` directives after variable definitions that may affect included files
|
||||
- Use `include` for shared variables, pattern rules, or common targets
|
||||
|
||||
```makefile
|
||||
# Include common settings
|
||||
include config.mk
|
||||
|
||||
# Include optional local configuration
|
||||
-include local.mk
|
||||
```
|
||||
|
||||
## Conditional Directives
|
||||
|
||||
- Use conditional directives (`ifeq`, `ifneq`, `ifdef`, `ifndef`) for platform or configuration-specific rules
|
||||
- Place conditionals at the makefile level, not within recipes (use shell conditionals in recipes)
|
||||
- Keep conditionals simple and well-documented
|
||||
|
||||
```makefile
|
||||
# Platform-specific settings
|
||||
ifeq ($(OS),Windows_NT)
|
||||
EXE_EXT = .exe
|
||||
else
|
||||
EXE_EXT =
|
||||
endif
|
||||
|
||||
program: main.o
|
||||
$(CC) -o program$(EXE_EXT) main.o
|
||||
```
|
||||
|
||||
## Automatic Prerequisites
|
||||
|
||||
- Generate header dependencies automatically rather than maintaining them manually
|
||||
- Use compiler flags like `-MMD` and `-MP` to generate `.d` files with dependencies
|
||||
- Include generated dependency files with `-include $(deps)` to avoid errors if they don't exist
|
||||
|
||||
```makefile
|
||||
objects = main.o utils.o
|
||||
deps = $(objects:.o=.d)
|
||||
|
||||
# Include dependency files
|
||||
-include $(deps)
|
||||
|
||||
# Compile with automatic dependency generation
|
||||
%.o: %.c
|
||||
$(CC) $(CFLAGS) -MMD -MP -c $< -o $@
|
||||
```
|
||||
|
||||
## Error Handling and Debugging
|
||||
|
||||
- Use `$(error text)` or `$(warning text)` functions for build-time diagnostics
|
||||
- Test makefiles with `make -n` (dry run) to see commands without executing
|
||||
- Use `make -p` to print the database of rules and variables for debugging
|
||||
- Validate required variables and tools at the beginning of the makefile
|
||||
|
||||
```makefile
|
||||
# Check for required tools
|
||||
ifeq ($(shell which gcc),)
|
||||
$(error "gcc is not installed or not in PATH")
|
||||
endif
|
||||
|
||||
# Validate required variables
|
||||
ifndef VERSION
|
||||
$(error VERSION is not defined)
|
||||
endif
|
||||
```
|
||||
|
||||
## Clean Targets
|
||||
|
||||
- Always provide a `clean` target to remove generated files
|
||||
- Declare `clean` as phony to avoid conflicts with a file named "clean"
|
||||
- Use `-` prefix with `rm` commands to ignore errors if files don't exist
|
||||
- Consider separate `clean` (removes objects) and `distclean` (removes all generated files) targets
|
||||
|
||||
```makefile
|
||||
.PHONY: clean distclean
|
||||
|
||||
clean:
|
||||
-rm -f $(objects)
|
||||
-rm -f $(deps)
|
||||
|
||||
distclean: clean
|
||||
-rm -f program config.mk
|
||||
```
|
||||
|
||||
## Portability Considerations
|
||||
|
||||
- Avoid GNU Make-specific features if portability to other make implementations is required
|
||||
- Use standard shell commands (prefer POSIX shell constructs)
|
||||
- Test with `make -B` to force rebuild all targets
|
||||
- Document any platform-specific requirements or GNU Make extensions used
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
- Use `:=` for variables that don't need recursive expansion (faster)
|
||||
- Avoid unnecessary use of `$(shell ...)` which creates subprocesses
|
||||
- Order prerequisites efficiently (most frequently changing files last)
|
||||
- Use parallel builds (`make -j`) safely by ensuring targets don't conflict
|
||||
|
||||
## Documentation and Comments
|
||||
|
||||
- Add a header comment explaining the makefile's purpose
|
||||
- Document non-obvious variable settings and their effects
|
||||
- Include usage examples or targets in comments
|
||||
- Add inline comments for complex rules or platform-specific workarounds
|
||||
|
||||
```makefile
|
||||
# Makefile for building the example application
|
||||
#
|
||||
# Usage:
|
||||
# make - Build the program
|
||||
# make clean - Remove generated files
|
||||
# make install - Install to $(PREFIX)
|
||||
#
|
||||
# Variables:
|
||||
# CC - C compiler (default: gcc)
|
||||
# PREFIX - Installation prefix (default: /usr/local)
|
||||
|
||||
# Compiler and flags
|
||||
CC ?= gcc
|
||||
CFLAGS = -Wall -Wextra -O2
|
||||
|
||||
# Installation directory
|
||||
PREFIX ?= /usr/local
|
||||
```
|
||||
|
||||
## Special Targets
|
||||
|
||||
- Use `.PHONY` for non-file targets
|
||||
- Use `.PRECIOUS` to preserve intermediate files
|
||||
- Use `.INTERMEDIATE` to mark files as intermediate (automatically deleted)
|
||||
- Use `.SECONDARY` to prevent deletion of intermediate files
|
||||
- Use `.DELETE_ON_ERROR` to remove targets if recipe fails
|
||||
- Use `.SILENT` to suppress echoing for all recipes (use sparingly)
|
||||
|
||||
```makefile
|
||||
# Don't delete intermediate files
|
||||
.SECONDARY:
|
||||
|
||||
# Delete targets if recipe fails
|
||||
.DELETE_ON_ERROR:
|
||||
|
||||
# Preserve specific files
|
||||
.PRECIOUS: %.o
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Standard Project Structure
|
||||
|
||||
```makefile
|
||||
CC = gcc
|
||||
CFLAGS = -Wall -O2
|
||||
objects = main.o utils.o parser.o
|
||||
|
||||
.PHONY: all clean install
|
||||
|
||||
all: program
|
||||
|
||||
program: $(objects)
|
||||
$(CC) -o $@ $^
|
||||
|
||||
%.o: %.c
|
||||
$(CC) $(CFLAGS) -c $< -o $@
|
||||
|
||||
clean:
|
||||
-rm -f program $(objects)
|
||||
|
||||
install: program
|
||||
install -d $(PREFIX)/bin
|
||||
install -m 755 program $(PREFIX)/bin
|
||||
```
|
||||
|
||||
### Managing Multiple Programs
|
||||
|
||||
```makefile
|
||||
programs = prog1 prog2 prog3
|
||||
|
||||
.PHONY: all clean
|
||||
|
||||
all: $(programs)
|
||||
|
||||
prog1: prog1.o common.o
|
||||
$(CC) -o $@ $^
|
||||
|
||||
prog2: prog2.o common.o
|
||||
$(CC) -o $@ $^
|
||||
|
||||
prog3: prog3.o
|
||||
$(CC) -o $@ $^
|
||||
|
||||
clean:
|
||||
-rm -f $(programs) *.o
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
- Don't start recipe lines with spaces instead of tabs
|
||||
- Avoid hardcoding file lists when they can be generated with wildcards or functions
|
||||
- Don't use `$(shell ls ...)` to get file lists (use `$(wildcard ...)` instead)
|
||||
- Avoid complex shell scripts in recipes (move to separate script files)
|
||||
- Don't forget to declare phony targets as `.PHONY`
|
||||
- Avoid circular dependencies between targets
|
||||
- Don't use recursive make (`$(MAKE) -C subdir`) unless absolutely necessary
|
||||
30
.github/instructions/nodejs-javascript-vitest.instructions.md
vendored
Normal file
30
.github/instructions/nodejs-javascript-vitest.instructions.md
vendored
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
description: "Guidelines for writing Node.js and JavaScript code with Vitest testing"
|
||||
applyTo: '**/*.js, **/*.mjs, **/*.cjs'
|
||||
---
|
||||
|
||||
# Code Generation Guidelines
|
||||
|
||||
## Coding standards
|
||||
- Use JavaScript with ES2022 features and Node.js (20+) ESM modules
|
||||
- Use Node.js built-in modules and avoid external dependencies where possible
|
||||
- Ask the user if you require any additional dependencies before adding them
|
||||
- Always use async/await for asynchronous code, and use 'node:util' promisify function to avoid callbacks
|
||||
- Keep the code simple and maintainable
|
||||
- Use descriptive variable and function names
|
||||
- Do not add comments unless absolutely necessary, the code should be self-explanatory
|
||||
- Never use `null`, always use `undefined` for optional values
|
||||
- Prefer functions over classes
|
||||
|
||||
## Testing
|
||||
- Use Vitest for testing
|
||||
- Write tests for all new features and bug fixes
|
||||
- Ensure tests cover edge cases and error handling
|
||||
- NEVER change the original code to make it easier to test, instead, write tests that cover the original code as it is
|
||||
|
||||
## Documentation
|
||||
- When adding new features or making significant changes, update the README.md file where necessary
|
||||
|
||||
## User interactions
|
||||
- Ask questions if you are unsure about the implementation details, design choices, or need clarification on the requirements
|
||||
- Always answer in the same language as the question, but use english for the generated content like code, comments or docs
|
||||
311
.github/instructions/object-calisthenics.instructions.md
vendored
Normal file
311
.github/instructions/object-calisthenics.instructions.md
vendored
Normal file
@@ -0,0 +1,311 @@
|
||||
---
|
||||
applyTo: '**/*.{cs,ts,java}'
|
||||
description: Enforces Object Calisthenics principles for business domain code to ensure clean, maintainable, and robust code
|
||||
---
|
||||
# Object Calisthenics Rules
|
||||
|
||||
> ⚠️ **Warning:** This file contains the 9 original Object Calisthenics rules. No additional rules must be added, and none of these rules should be replaced or removed.
|
||||
> Examples may be added later if needed.
|
||||
|
||||
## Objective
|
||||
This rule enforces the principles of Object Calisthenics to ensure clean, maintainable, and robust code in the backend, **primarily for business domain code**.
|
||||
|
||||
## Scope and Application
|
||||
- **Primary focus**: Business domain classes (aggregates, entities, value objects, domain services)
|
||||
- **Secondary focus**: Application layer services and use case handlers
|
||||
- **Exemptions**:
|
||||
- DTOs (Data Transfer Objects)
|
||||
- API models/contracts
|
||||
- Configuration classes
|
||||
- Simple data containers without business logic
|
||||
- Infrastructure code where flexibility is needed
|
||||
|
||||
## Key Principles
|
||||
|
||||
|
||||
1. **One Level of Indentation per Method**:
|
||||
- Ensure methods are simple and do not exceed one level of indentation.
|
||||
|
||||
```csharp
|
||||
// Bad Example - this method has multiple levels of indentation
|
||||
public void SendNewsletter() {
|
||||
foreach (var user in users) {
|
||||
if (user.IsActive) {
|
||||
// Do something
|
||||
mailer.Send(user.Email);
|
||||
}
|
||||
}
|
||||
}
|
||||
// Good Example - Extracted method to reduce indentation
|
||||
public void SendNewsletter() {
|
||||
foreach (var user in users) {
|
||||
SendEmail(user);
|
||||
}
|
||||
}
|
||||
private void SendEmail(User user) {
|
||||
if (user.IsActive) {
|
||||
mailer.Send(user.Email);
|
||||
}
|
||||
}
|
||||
|
||||
// Good Example - Filtering users before sending emails
|
||||
public void SendNewsletter() {
|
||||
var activeUsers = users.Where(user => user.IsActive);
|
||||
|
||||
foreach (var user in activeUsers) {
|
||||
mailer.Send(user.Email);
|
||||
}
|
||||
}
|
||||
```
|
||||
2. **Don't Use the ELSE Keyword**:
|
||||
|
||||
- Avoid using the `else` keyword to reduce complexity and improve readability.
|
||||
- Use early returns to handle conditions instead.
|
||||
- Use Fail Fast principle
|
||||
- Use Guard Clauses to validate inputs and conditions at the beginning of methods.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Using else
|
||||
public void ProcessOrder(Order order) {
|
||||
if (order.IsValid) {
|
||||
// Process order
|
||||
} else {
|
||||
// Handle invalid order
|
||||
}
|
||||
}
|
||||
// Good Example - Avoiding else
|
||||
public void ProcessOrder(Order order) {
|
||||
if (!order.IsValid) return;
|
||||
// Process order
|
||||
}
|
||||
```
|
||||
|
||||
Sample Fail fast principle:
|
||||
```csharp
|
||||
public void ProcessOrder(Order order) {
|
||||
if (order == null) throw new ArgumentNullException(nameof(order));
|
||||
if (!order.IsValid) throw new InvalidOperationException("Invalid order");
|
||||
// Process order
|
||||
}
|
||||
```
|
||||
|
||||
3. **Wrapping All Primitives and Strings**:
|
||||
- Avoid using primitive types directly in your code.
|
||||
- Wrap them in classes to provide meaningful context and behavior.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Using primitive types directly
|
||||
public class User {
|
||||
public string Name { get; set; }
|
||||
public int Age { get; set; }
|
||||
}
|
||||
// Good Example - Wrapping primitives
|
||||
public class User {
|
||||
private string name;
|
||||
private Age age;
|
||||
public User(string name, Age age) {
|
||||
this.name = name;
|
||||
this.age = age;
|
||||
}
|
||||
}
|
||||
public class Age {
|
||||
private int value;
|
||||
public Age(int value) {
|
||||
if (value < 0) throw new ArgumentOutOfRangeException(nameof(value), "Age cannot be negative");
|
||||
this.value = value;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. **First Class Collections**:
|
||||
- Use collections to encapsulate data and behavior, rather than exposing raw data structures.
|
||||
First Class Collections: a class that contains an array as an attribute should not contain any other attributes
|
||||
|
||||
```csharp
|
||||
// Bad Example - Exposing raw collection
|
||||
public class Group {
|
||||
public int Id { get; private set; }
|
||||
public string Name { get; private set; }
|
||||
public List<User> Users { get; private set; }
|
||||
|
||||
public int GetNumberOfUsersIsActive() {
|
||||
return Users
|
||||
.Where(user => user.IsActive)
|
||||
.Count();
|
||||
}
|
||||
}
|
||||
|
||||
// Good Example - Encapsulating collection behavior
|
||||
public class Group {
|
||||
public int Id { get; private set; }
|
||||
public string Name { get; private set; }
|
||||
|
||||
public GroupUserCollection userCollection { get; private set; } // The list of users is encapsulated in a class
|
||||
|
||||
public int GetNumberOfUsersIsActive() {
|
||||
return userCollection
|
||||
.GetActiveUsers()
|
||||
.Count();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
5. **One Dot per Line**:
|
||||
- Avoid violating Law of Demeter by only having a single dot per line.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Multiple dots in a single line
|
||||
public void ProcessOrder(Order order) {
|
||||
var userEmail = order.User.GetEmail().ToUpper().Trim();
|
||||
// Do something with userEmail
|
||||
}
|
||||
// Good Example - One dot per line
|
||||
public class User {
|
||||
public NormalizedEmail GetEmail() {
|
||||
return NormalizedEmail.Create(/*...*/);
|
||||
}
|
||||
}
|
||||
public class Order {
|
||||
/*...*/
|
||||
public NormalizedEmail ConfirmationEmail() {
|
||||
return User.GetEmail();
|
||||
}
|
||||
}
|
||||
public void ProcessOrder(Order order) {
|
||||
var confirmationEmail = order.ConfirmationEmail();
|
||||
// Do something with confirmationEmail
|
||||
}
|
||||
```
|
||||
|
||||
6. **Don't abbreviate**:
|
||||
- Use meaningful names for classes, methods, and variables.
|
||||
- Avoid abbreviations that can lead to confusion.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Abbreviated names
|
||||
public class U {
|
||||
public string N { get; set; }
|
||||
}
|
||||
// Good Example - Meaningful names
|
||||
public class User {
|
||||
public string Name { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
7. **Keep entities small (Class, method, namespace or package)**:
|
||||
- Limit the size of classes and methods to improve code readability and maintainability.
|
||||
- Each class should have a single responsibility and be as small as possible.
|
||||
|
||||
Constraints:
|
||||
- Maximum 10 methods per class
|
||||
- Maximum 50 lines per class
|
||||
- Maximum 10 classes per package or namespace
|
||||
|
||||
```csharp
|
||||
// Bad Example - Large class with multiple responsibilities
|
||||
public class UserManager {
|
||||
public void CreateUser(string name) { /*...*/ }
|
||||
public void DeleteUser(int id) { /*...*/ }
|
||||
public void SendEmail(string email) { /*...*/ }
|
||||
}
|
||||
|
||||
// Good Example - Small classes with single responsibility
|
||||
public class UserCreator {
|
||||
public void CreateUser(string name) { /*...*/ }
|
||||
}
|
||||
public class UserDeleter {
|
||||
public void DeleteUser(int id) { /*...*/ }
|
||||
}
|
||||
|
||||
public class UserUpdater {
|
||||
public void UpdateUser(int id, string name) { /*...*/ }
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
8. **No Classes with More Than Two Instance Variables**:
|
||||
- Encourage classes to have a single responsibility by limiting the number of instance variables.
|
||||
- Limit the number of instance variables to two to maintain simplicity.
|
||||
- Do not count ILogger or any other logger as instance variable.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Class with multiple instance variables
|
||||
public class UserCreateCommandHandler {
|
||||
// Bad: Too many instance variables
|
||||
private readonly IUserRepository userRepository;
|
||||
private readonly IEmailService emailService;
|
||||
private readonly ILogger logger;
|
||||
private readonly ISmsService smsService;
|
||||
|
||||
public UserCreateCommandHandler(IUserRepository userRepository, IEmailService emailService, ILogger logger, ISmsService smsService) {
|
||||
this.userRepository = userRepository;
|
||||
this.emailService = emailService;
|
||||
this.logger = logger;
|
||||
this.smsService = smsService;
|
||||
}
|
||||
}
|
||||
|
||||
// Good: Class with two instance variables
|
||||
public class UserCreateCommandHandler {
|
||||
private readonly IUserRepository userRepository;
|
||||
private readonly INotificationService notificationService;
|
||||
private readonly ILogger logger; // This is not counted as instance variable
|
||||
|
||||
public UserCreateCommandHandler(IUserRepository userRepository, INotificationService notificationService, ILogger logger) {
|
||||
this.userRepository = userRepository;
|
||||
this.notificationService = notificationService;
|
||||
this.logger = logger;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
9. **No Getters/Setters in Domain Classes**:
|
||||
- Avoid exposing setters for properties in domain classes.
|
||||
- Use private constructors and static factory methods for object creation.
|
||||
- **Note**: This rule applies primarily to domain classes, not DTOs or data transfer objects.
|
||||
|
||||
```csharp
|
||||
// Bad Example - Domain class with public setters
|
||||
public class User { // Domain class
|
||||
public string Name { get; set; } // Avoid this in domain classes
|
||||
}
|
||||
|
||||
// Good Example - Domain class with encapsulation
|
||||
public class User { // Domain class
|
||||
private string name;
|
||||
private User(string name) { this.name = name; }
|
||||
public static User Create(string name) => new User(name);
|
||||
}
|
||||
|
||||
// Acceptable Example - DTO with public setters
|
||||
public class UserDto { // DTO - exemption applies
|
||||
public string Name { get; set; } // Acceptable for DTOs
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Guidelines
|
||||
- **Domain Classes**:
|
||||
- Use private constructors and static factory methods for creating instances.
|
||||
- Avoid exposing setters for properties.
|
||||
- Apply all 9 rules strictly for business domain code.
|
||||
|
||||
- **Application Layer**:
|
||||
- Apply these rules to use case handlers and application services.
|
||||
- Focus on maintaining single responsibility and clean abstractions.
|
||||
|
||||
- **DTOs and Data Objects**:
|
||||
- Rules 3 (wrapping primitives), 8 (two instance variables), and 9 (no getters/setters) may be relaxed for DTOs.
|
||||
- Public properties with getters/setters are acceptable for data transfer objects.
|
||||
|
||||
- **Testing**:
|
||||
- Ensure tests validate the behavior of objects rather than their state.
|
||||
- Test classes may have relaxed rules for readability and maintainability.
|
||||
|
||||
- **Code Reviews**:
|
||||
- Enforce these rules during code reviews for domain and application code.
|
||||
- Be pragmatic about infrastructure and DTO code.
|
||||
|
||||
## References
|
||||
- [Object Calisthenics - Original 9 Rules by Jeff Bay](https://www.cs.helsinki.fi/u/luontola/tdd-2009/ext/ObjectCalisthenics.pdf)
|
||||
- [ThoughtWorks - Object Calisthenics](https://www.thoughtworks.com/insights/blog/object-calisthenics)
|
||||
- [Clean Code: A Handbook of Agile Software Craftsmanship - Robert C. Martin](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)
|
||||
73
.github/instructions/prompt.instructions.md
vendored
Normal file
73
.github/instructions/prompt.instructions.md
vendored
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
description: 'Guidelines for creating high-quality prompt files for GitHub Copilot'
|
||||
applyTo: '**/*.prompt.md'
|
||||
---
|
||||
|
||||
# Copilot Prompt Files Guidelines
|
||||
|
||||
Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.
|
||||
|
||||
## Scope and Principles
|
||||
- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.
|
||||
- Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.
|
||||
- Primary references: VS Code documentation on prompt files and organization-specific conventions.
|
||||
|
||||
## Frontmatter Requirements
|
||||
- Include `description` (single sentence, actionable outcome), `mode` (explicitly choose `ask`, `edit`, or `agent`), and `tools` (minimal set of tool bundles required to fulfill the prompt).
|
||||
- Declare `model` when the prompt depends on a specific capability tier; otherwise inherit the active model.
|
||||
- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization.
|
||||
- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity.
|
||||
|
||||
## File Naming and Placement
|
||||
- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
|
||||
- Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).
|
||||
|
||||
## Body Structure
|
||||
- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.
|
||||
- Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.
|
||||
- Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.
|
||||
- Reference related prompts or instruction files using relative links to aid discoverability.
|
||||
|
||||
## Input and Context Handling
|
||||
- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.
|
||||
- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.
|
||||
- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).
|
||||
|
||||
## Tool and Permission Guidance
|
||||
- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.
|
||||
- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.
|
||||
- Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.
|
||||
|
||||
## Instruction Tone and Style
|
||||
- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).
|
||||
- Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.
|
||||
- Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.
|
||||
|
||||
## Output Definition
|
||||
- Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”).
|
||||
- Include success criteria and failure triggers so Copilot knows when to halt or retry.
|
||||
- Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.
|
||||
|
||||
## Examples and Reusable Assets
|
||||
- Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow.
|
||||
- Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change.
|
||||
- Link to authoritative documentation instead of duplicating lengthy guidance.
|
||||
|
||||
## Quality Assurance Checklist
|
||||
- [ ] Frontmatter fields are complete, accurate, and least-privilege.
|
||||
- [ ] Inputs include placeholders, default behaviours, and fallbacks.
|
||||
- [ ] Workflow covers preparation, execution, and post-processing without gaps.
|
||||
- [ ] Output expectations include formatting and storage details.
|
||||
- [ ] Validation steps are actionable (commands, diff checks, review prompts).
|
||||
- [ ] Security, compliance, and privacy policies referenced by the prompt are current.
|
||||
- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.
|
||||
|
||||
## Maintenance Guidance
|
||||
- Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.
|
||||
- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.
|
||||
- Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.
|
||||
|
||||
## Additional Resources
|
||||
- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)
|
||||
- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)
|
||||
- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)
|
||||
162
.github/instructions/reactjs.instructions.md
vendored
Normal file
162
.github/instructions/reactjs.instructions.md
vendored
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
description: 'ReactJS development standards and best practices'
|
||||
applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
|
||||
---
|
||||
|
||||
# ReactJS Development Instructions
|
||||
|
||||
Instructions for building high-quality ReactJS applications with modern patterns, hooks, and best practices following the official React documentation at https://react.dev.
|
||||
|
||||
## Project Context
|
||||
- Latest React version (React 19+)
|
||||
- TypeScript for type safety (when applicable)
|
||||
- Functional components with hooks as default
|
||||
- Follow React's official style guide and best practices
|
||||
- Use modern build tools (Vite, Create React App, or custom Webpack setup)
|
||||
- Implement proper component composition and reusability patterns
|
||||
|
||||
## Development Standards
|
||||
|
||||
### Architecture
|
||||
- Use functional components with hooks as the primary pattern
|
||||
- Implement component composition over inheritance
|
||||
- Organize components by feature or domain for scalability
|
||||
- Separate presentational and container components clearly
|
||||
- Use custom hooks for reusable stateful logic
|
||||
- Implement proper component hierarchies with clear data flow
|
||||
|
||||
### TypeScript Integration
|
||||
- Use TypeScript interfaces for props, state, and component definitions
|
||||
- Define proper types for event handlers and refs
|
||||
- Implement generic components where appropriate
|
||||
- Use strict mode in `tsconfig.json` for type safety
|
||||
- Leverage React's built-in types (`React.FC`, `React.ComponentProps`, etc.)
|
||||
- Create union types for component variants and states
|
||||
|
||||
### Component Design
|
||||
- Follow the single responsibility principle for components
|
||||
- Use descriptive and consistent naming conventions
|
||||
- Implement proper prop validation with TypeScript or PropTypes
|
||||
- Design components to be testable and reusable
|
||||
- Keep components small and focused on a single concern
|
||||
- Use composition patterns (render props, children as functions)
|
||||
|
||||
### State Management
|
||||
- Use `useState` for local component state
|
||||
- Implement `useReducer` for complex state logic
|
||||
- Leverage `useContext` for sharing state across component trees
|
||||
- Consider external state management (Redux Toolkit, Zustand) for complex applications
|
||||
- Implement proper state normalization and data structures
|
||||
- Use React Query or SWR for server state management
|
||||
|
||||
### Hooks and Effects
|
||||
- Use `useEffect` with proper dependency arrays to avoid infinite loops
|
||||
- Implement cleanup functions in effects to prevent memory leaks
|
||||
- Use `useMemo` and `useCallback` for performance optimization when needed
|
||||
- Create custom hooks for reusable stateful logic
|
||||
- Follow the rules of hooks (only call at the top level)
|
||||
- Use `useRef` for accessing DOM elements and storing mutable values
|
||||
|
||||
### Styling
|
||||
- Use CSS Modules, Styled Components, or modern CSS-in-JS solutions
|
||||
- Implement responsive design with mobile-first approach
|
||||
- Follow BEM methodology or similar naming conventions for CSS classes
|
||||
- Use CSS custom properties (variables) for theming
|
||||
- Implement consistent spacing, typography, and color systems
|
||||
- Ensure accessibility with proper ARIA attributes and semantic HTML
|
||||
|
||||
### Performance Optimization
|
||||
- Use `React.memo` for component memoization when appropriate
|
||||
- Implement code splitting with `React.lazy` and `Suspense`
|
||||
- Optimize bundle size with tree shaking and dynamic imports
|
||||
- Use `useMemo` and `useCallback` judiciously to prevent unnecessary re-renders
|
||||
- Implement virtual scrolling for large lists
|
||||
- Profile components with React DevTools to identify performance bottlenecks
|
||||
|
||||
### Data Fetching
|
||||
- Use modern data fetching libraries (React Query, SWR, Apollo Client)
|
||||
- Implement proper loading, error, and success states
|
||||
- Handle race conditions and request cancellation
|
||||
- Use optimistic updates for better user experience
|
||||
- Implement proper caching strategies
|
||||
- Handle offline scenarios and network errors gracefully
|
||||
|
||||
### Error Handling
|
||||
- Implement Error Boundaries for component-level error handling
|
||||
- Use proper error states in data fetching
|
||||
- Implement fallback UI for error scenarios
|
||||
- Log errors appropriately for debugging
|
||||
- Handle async errors in effects and event handlers
|
||||
- Provide meaningful error messages to users
|
||||
|
||||
### Forms and Validation
|
||||
- Use controlled components for form inputs
|
||||
- Implement proper form validation with libraries like Formik, React Hook Form
|
||||
- Handle form submission and error states appropriately
|
||||
- Implement accessibility features for forms (labels, ARIA attributes)
|
||||
- Use debounced validation for better user experience
|
||||
- Handle file uploads and complex form scenarios
|
||||
|
||||
### Routing
|
||||
- Use React Router for client-side routing
|
||||
- Implement nested routes and route protection
|
||||
- Handle route parameters and query strings properly
|
||||
- Implement lazy loading for route-based code splitting
|
||||
- Use proper navigation patterns and back button handling
|
||||
- Implement breadcrumbs and navigation state management
|
||||
|
||||
### Testing
|
||||
- Write unit tests for components using React Testing Library
|
||||
- Test component behavior, not implementation details
|
||||
- Use Jest for test runner and assertion library
|
||||
- Implement integration tests for complex component interactions
|
||||
- Mock external dependencies and API calls appropriately
|
||||
- Test accessibility features and keyboard navigation
|
||||
|
||||
### Security
|
||||
- Sanitize user inputs to prevent XSS attacks
|
||||
- Validate and escape data before rendering
|
||||
- Use HTTPS for all external API calls
|
||||
- Implement proper authentication and authorization patterns
|
||||
- Avoid storing sensitive data in localStorage or sessionStorage
|
||||
- Use Content Security Policy (CSP) headers
|
||||
|
||||
### Accessibility
|
||||
- Use semantic HTML elements appropriately
|
||||
- Implement proper ARIA attributes and roles
|
||||
- Ensure keyboard navigation works for all interactive elements
|
||||
- Provide alt text for images and descriptive text for icons
|
||||
- Implement proper color contrast ratios
|
||||
- Test with screen readers and accessibility tools
|
||||
|
||||
## Implementation Process
|
||||
1. Plan component architecture and data flow
|
||||
2. Set up project structure with proper folder organization
|
||||
3. Define TypeScript interfaces and types
|
||||
4. Implement core components with proper styling
|
||||
5. Add state management and data fetching logic
|
||||
6. Implement routing and navigation
|
||||
7. Add form handling and validation
|
||||
8. Implement error handling and loading states
|
||||
9. Add testing coverage for components and functionality
|
||||
10. Optimize performance and bundle size
|
||||
11. Ensure accessibility compliance
|
||||
12. Add documentation and code comments
|
||||
|
||||
## Additional Guidelines
|
||||
- Follow React's naming conventions (PascalCase for components, camelCase for functions)
|
||||
- Use meaningful commit messages and maintain clean git history
|
||||
- Implement proper code splitting and lazy loading strategies
|
||||
- Document complex components and custom hooks with JSDoc
|
||||
- Use ESLint and Prettier for consistent code formatting
|
||||
- Keep dependencies up to date and audit for security vulnerabilities
|
||||
- Implement proper environment configuration for different deployment stages
|
||||
- Use React Developer Tools for debugging and performance analysis
|
||||
|
||||
## Common Patterns
|
||||
- Higher-Order Components (HOCs) for cross-cutting concerns
|
||||
- Render props pattern for component composition
|
||||
- Compound components for related functionality
|
||||
- Provider pattern for context-based state sharing
|
||||
- Container/Presentational component separation
|
||||
- Custom hooks for reusable logic extraction
|
||||
162
.github/instructions/self-explanatory-code-commenting.instructions.md
vendored
Normal file
162
.github/instructions/self-explanatory-code-commenting.instructions.md
vendored
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'
|
||||
applyTo: '**'
|
||||
---
|
||||
|
||||
# Self-explanatory Code Commenting Instructions
|
||||
|
||||
## Core Principle
|
||||
**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
|
||||
We do not need comments most of the time.
|
||||
|
||||
## Commenting Guidelines
|
||||
|
||||
### ❌ AVOID These Comment Types
|
||||
|
||||
**Obvious Comments**
|
||||
```javascript
|
||||
// Bad: States the obvious
|
||||
let counter = 0; // Initialize counter to zero
|
||||
counter++; // Increment counter by one
|
||||
```
|
||||
|
||||
**Redundant Comments**
|
||||
```javascript
|
||||
// Bad: Comment repeats the code
|
||||
function getUserName() {
|
||||
return user.name; // Return the user's name
|
||||
}
|
||||
```
|
||||
|
||||
**Outdated Comments**
|
||||
```javascript
|
||||
// Bad: Comment doesn't match the code
|
||||
// Calculate tax at 5% rate
|
||||
const tax = price * 0.08; // Actually 8%
|
||||
```
|
||||
|
||||
### ✅ WRITE These Comment Types
|
||||
|
||||
**Complex Business Logic**
|
||||
```javascript
|
||||
// Good: Explains WHY this specific calculation
|
||||
// Apply progressive tax brackets: 10% up to 10k, 20% above
|
||||
const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
|
||||
```
|
||||
|
||||
**Non-obvious Algorithms**
|
||||
```javascript
|
||||
// Good: Explains the algorithm choice
|
||||
// Using Floyd-Warshall for all-pairs shortest paths
|
||||
// because we need distances between all nodes
|
||||
for (let k = 0; k < vertices; k++) {
|
||||
for (let i = 0; i < vertices; i++) {
|
||||
for (let j = 0; j < vertices; j++) {
|
||||
// ... implementation
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Regex Patterns**
|
||||
```javascript
|
||||
// Good: Explains what the regex matches
|
||||
// Match email format: username@domain.extension
|
||||
const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
|
||||
```
|
||||
|
||||
**API Constraints or Gotchas**
|
||||
```javascript
|
||||
// Good: Explains external constraint
|
||||
// GitHub API rate limit: 5000 requests/hour for authenticated users
|
||||
await rateLimiter.wait();
|
||||
const response = await fetch(githubApiUrl);
|
||||
```
|
||||
|
||||
## Decision Framework
|
||||
|
||||
Before writing a comment, ask:
|
||||
1. **Is the code self-explanatory?** → No comment needed
|
||||
2. **Would a better variable/function name eliminate the need?** → Refactor instead
|
||||
3. **Does this explain WHY, not WHAT?** → Good comment
|
||||
4. **Will this help future maintainers?** → Good comment
|
||||
|
||||
## Special Cases for Comments
|
||||
|
||||
### Public APIs
|
||||
```javascript
|
||||
/**
|
||||
* Calculate compound interest using the standard formula.
|
||||
*
|
||||
* @param {number} principal - Initial amount invested
|
||||
* @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
|
||||
* @param {number} time - Time period in years
|
||||
* @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
|
||||
* @returns {number} Final amount after compound interest
|
||||
*/
|
||||
function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
|
||||
// ... implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration and Constants
|
||||
```javascript
|
||||
// Good: Explains the source or reasoning
|
||||
const MAX_RETRIES = 3; // Based on network reliability studies
|
||||
const API_TIMEOUT = 5000; // AWS Lambda timeout is 15s, leaving buffer
|
||||
```
|
||||
|
||||
### Annotations
|
||||
```javascript
|
||||
// TODO: Replace with proper user authentication after security review
|
||||
// FIXME: Memory leak in production - investigate connection pooling
|
||||
// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
|
||||
// NOTE: This implementation assumes UTC timezone for all calculations
|
||||
// WARNING: This function modifies the original array instead of creating a copy
|
||||
// PERF: Consider caching this result if called frequently in hot path
|
||||
// SECURITY: Validate input to prevent SQL injection before using in query
|
||||
// BUG: Edge case failure when array is empty - needs investigation
|
||||
// REFACTOR: Extract this logic into separate utility function for reusability
|
||||
// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Dead Code Comments
|
||||
```javascript
|
||||
// Bad: Don't comment out code
|
||||
// const oldFunction = () => { ... };
|
||||
const newFunction = () => { ... };
|
||||
```
|
||||
|
||||
### Changelog Comments
|
||||
```javascript
|
||||
// Bad: Don't maintain history in comments
|
||||
// Modified by John on 2023-01-15
|
||||
// Fixed bug reported by Sarah on 2023-02-03
|
||||
function processData() {
|
||||
// ... implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Divider Comments
|
||||
```javascript
|
||||
// Bad: Don't use decorative comments
|
||||
//=====================================
|
||||
// UTILITY FUNCTIONS
|
||||
//=====================================
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before committing, ensure your comments:
|
||||
- [ ] Explain WHY, not WHAT
|
||||
- [ ] Are grammatically correct and clear
|
||||
- [ ] Will remain accurate as code evolves
|
||||
- [ ] Add genuine value to code understanding
|
||||
- [ ] Are placed appropriately (above the code they describe)
|
||||
- [ ] Use proper spelling and professional language
|
||||
|
||||
## Summary
|
||||
|
||||
Remember: **The best comment is the one you don't need to write because the code is self-documenting.**
|
||||
132
.github/instructions/shell.instructions.md
vendored
Normal file
132
.github/instructions/shell.instructions.md
vendored
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
description: 'Shell scripting best practices and conventions for bash, sh, zsh, and other shells'
|
||||
applyTo: '**/*.sh'
|
||||
---
|
||||
|
||||
# Shell Scripting Guidelines
|
||||
|
||||
Instructions for writing clean, safe, and maintainable shell scripts for bash, sh, zsh, and other shells.
|
||||
|
||||
## General Principles
|
||||
|
||||
- Generate code that is clean, simple, and concise
|
||||
- Ensure scripts are easily readable and understandable
|
||||
- Add comments where helpful for understanding how the script works
|
||||
- Generate concise and simple echo outputs to provide execution status
|
||||
- Avoid unnecessary echo output and excessive logging
|
||||
- Use shellcheck for static analysis when available
|
||||
- Assume scripts are for automation and testing rather than production systems unless specified otherwise
|
||||
- Prefer safe expansions: double-quote variable references (`"$var"`), use `${var}` for clarity, and avoid `eval`
|
||||
- Use modern Bash features (`[[ ]]`, `local`, arrays) when portability requirements allow; fall back to POSIX constructs only when needed
|
||||
- Choose reliable parsers for structured data instead of ad-hoc text processing
|
||||
|
||||
## Error Handling & Safety
|
||||
|
||||
- Always enable `set -euo pipefail` to fail fast on errors, catch unset variables, and surface pipeline failures
|
||||
- Validate all required parameters before execution
|
||||
- Provide clear error messages with context
|
||||
- Use `trap` to clean up temporary resources or handle unexpected exits when the script terminates
|
||||
- Declare immutable values with `readonly` (or `declare -r`) to prevent accidental reassignment
|
||||
- Use `mktemp` to create temporary files or directories safely and ensure they are removed in your cleanup handler
|
||||
|
||||
## Script Structure
|
||||
|
||||
- Start with a clear shebang: `#!/bin/bash` unless specified otherwise
|
||||
- Include a header comment explaining the script's purpose
|
||||
- Define default values for all variables at the top
|
||||
- Use functions for reusable code blocks
|
||||
- Create reusable functions instead of repeating similar blocks of code
|
||||
- Keep the main execution flow clean and readable
|
||||
|
||||
## Working with JSON and YAML
|
||||
|
||||
- Prefer dedicated parsers (`jq` for JSON, `yq` for YAML—or `jq` on JSON converted via `yq`) over ad-hoc text processing with `grep`, `awk`, or shell string splitting
|
||||
- When `jq`/`yq` are unavailable or not appropriate, choose the next most reliable parser available in your environment, and be explicit about how it should be used safely
|
||||
- Validate that required fields exist and handle missing/invalid data paths explicitly (e.g., by checking `jq` exit status or using `// empty`)
|
||||
- Quote jq/yq filters to prevent shell expansion and prefer `--raw-output` when you need plain strings
|
||||
- Treat parser errors as fatal: combine with `set -euo pipefail` or test command success before using results
|
||||
- Document parser dependencies at the top of the script and fail fast with a helpful message if `jq`/`yq` (or alternative tools) are required but not installed
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# ============================================================================
|
||||
# Script Description Here
|
||||
# ============================================================================
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
cleanup() {
|
||||
# Remove temporary resources or perform other teardown steps as needed
|
||||
if [[ -n "${TEMP_DIR:-}" && -d "$TEMP_DIR" ]]; then
|
||||
rm -rf "$TEMP_DIR"
|
||||
fi
|
||||
}
|
||||
|
||||
trap cleanup EXIT
|
||||
|
||||
# Default values
|
||||
RESOURCE_GROUP=""
|
||||
REQUIRED_PARAM=""
|
||||
OPTIONAL_PARAM="default-value"
|
||||
readonly SCRIPT_NAME="$(basename "$0")"
|
||||
|
||||
TEMP_DIR=""
|
||||
|
||||
# Functions
|
||||
usage() {
|
||||
echo "Usage: $SCRIPT_NAME [OPTIONS]"
|
||||
echo "Options:"
|
||||
echo " -g, --resource-group Resource group (required)"
|
||||
echo " -h, --help Show this help"
|
||||
exit 0
|
||||
}
|
||||
|
||||
validate_requirements() {
|
||||
if [[ -z "$RESOURCE_GROUP" ]]; then
|
||||
echo "Error: Resource group is required"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
main() {
|
||||
validate_requirements
|
||||
|
||||
TEMP_DIR="$(mktemp -d)"
|
||||
if [[ ! -d "$TEMP_DIR" ]]; then
|
||||
echo "Error: failed to create temporary directory" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "============================================================================"
|
||||
echo "Script Execution Started"
|
||||
echo "============================================================================"
|
||||
|
||||
# Main logic here
|
||||
|
||||
echo "============================================================================"
|
||||
echo "Script Execution Completed"
|
||||
echo "============================================================================"
|
||||
}
|
||||
|
||||
# Parse arguments
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
-g|--resource-group)
|
||||
RESOURCE_GROUP="$2"
|
||||
shift 2
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
;;
|
||||
*)
|
||||
echo "Unknown option: $1"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Execute main function
|
||||
main "$@"
|
||||
|
||||
```
|
||||
323
.github/instructions/spec-driven-workflow-v1.instructions.md
vendored
Normal file
323
.github/instructions/spec-driven-workflow-v1.instructions.md
vendored
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
description: 'Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated.'
|
||||
applyTo: '**'
|
||||
---
|
||||
# Spec Driven Workflow v1
|
||||
|
||||
**Specification-Driven Workflow:**
|
||||
Bridge the gap between requirements and implementation.
|
||||
|
||||
**Maintain these artifacts at all times:**
|
||||
|
||||
- **`requirements.md`**: User stories and acceptance criteria in structured EARS notation.
|
||||
- **`design.md`**: Technical architecture, sequence diagrams, implementation considerations.
|
||||
- **`tasks.md`**: Detailed, trackable implementation plan.
|
||||
|
||||
## Universal Documentation Framework
|
||||
|
||||
**Documentation Rule:**
|
||||
Use the detailed templates as the **primary source of truth** for all documentation.
|
||||
|
||||
**Summary formats:**
|
||||
Use only for concise artifacts such as changelogs and pull request descriptions.
|
||||
|
||||
### Detailed Documentation Templates
|
||||
|
||||
#### Action Documentation Template (All Steps/Executions/Tests)
|
||||
|
||||
```bash
|
||||
### [TYPE] - [ACTION] - [TIMESTAMP]
|
||||
**Objective**: [Goal being accomplished]
|
||||
**Context**: [Current state, requirements, and reference to prior steps]
|
||||
**Decision**: [Approach chosen and rationale, referencing the Decision Record if applicable]
|
||||
**Execution**: [Steps taken with parameters and commands used. For code, include file paths.]
|
||||
**Output**: [Complete and unabridged results, logs, command outputs, and metrics]
|
||||
**Validation**: [Success verification method and results. If failed, include a remediation plan.]
|
||||
**Next**: [Automatic continuation plan to the next specific action]
|
||||
```
|
||||
|
||||
#### Decision Record Template (All Decisions)
|
||||
|
||||
```bash
|
||||
### Decision - [TIMESTAMP]
|
||||
**Decision**: [What was decided]
|
||||
**Context**: [Situation requiring decision and data driving it]
|
||||
**Options**: [Alternatives evaluated with brief pros and cons]
|
||||
**Rationale**: [Why the selected option is superior, with trade-offs explicitly stated]
|
||||
**Impact**: [Anticipated consequences for implementation, maintainability, and performance]
|
||||
**Review**: [Conditions or schedule for reassessing this decision]
|
||||
```
|
||||
|
||||
### Summary Formats (for Reporting)
|
||||
|
||||
#### Streamlined Action Log
|
||||
|
||||
For generating concise changelogs. Each log entry is derived from a full Action Document.
|
||||
|
||||
`[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]`
|
||||
|
||||
#### Compressed Decision Record
|
||||
|
||||
For use in pull request summaries or executive summaries.
|
||||
|
||||
`Decision: [X] | Rationale: [Y] | Impact: [Z] | Review: [Date]`
|
||||
|
||||
## Execution Workflow (6-Phase Loop)
|
||||
|
||||
**Never skip any step. Use consistent terminology. Reduce ambiguity.**
|
||||
|
||||
### **Phase 1: ANALYZE**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Understand the problem.
|
||||
- Analyze the existing system.
|
||||
- Produce a clear, testable set of requirements.
|
||||
- Think about the possible solutions and their implications.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] Read all provided code, documentation, tests, and logs.
|
||||
- Document file inventory, summaries, and initial analysis results.
|
||||
- [ ] Define requirements in **EARS Notation**:
|
||||
- Transform feature requests into structured, testable requirements.
|
||||
- Format: `WHEN [a condition or event], THE SYSTEM SHALL [expected behavior]`
|
||||
- [ ] Identify dependencies and constraints.
|
||||
- Document a dependency graph with risks and mitigation strategies.
|
||||
- [ ] Map data flows and interactions.
|
||||
- Document system interaction diagrams and data models.
|
||||
- [ ] Catalog edge cases and failures.
|
||||
- Document a comprehensive edge case matrix and potential failure points.
|
||||
- [ ] Assess confidence.
|
||||
- Generate a **Confidence Score (0-100%)** based on clarity of requirements, complexity, and problem scope.
|
||||
- Document the score and its rationale.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not proceed until all requirements are clear and documented.**
|
||||
|
||||
### **Phase 2: DESIGN**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Create a comprehensive technical design and a detailed implementation plan.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] **Define adaptive execution strategy based on Confidence Score:**
|
||||
- **High Confidence (>85%)**
|
||||
- Draft a comprehensive, step-by-step implementation plan.
|
||||
- Skip proof-of-concept steps.
|
||||
- Proceed with full, automated implementation.
|
||||
- Maintain standard comprehensive documentation.
|
||||
- **Medium Confidence (66–85%)**
|
||||
- Prioritize a **Proof-of-Concept (PoC)** or **Minimum Viable Product (MVP)**.
|
||||
- Define clear success criteria for PoC/MVP.
|
||||
- Build and validate PoC/MVP first, then expand plan incrementally.
|
||||
- Document PoC/MVP goals, execution, and validation results.
|
||||
- **Low Confidence (<66%)**
|
||||
- Dedicate first phase to research and knowledge-building.
|
||||
- Use semantic search and analyze similar implementations.
|
||||
- Synthesize findings into a research document.
|
||||
- Re-run ANALYZE phase after research.
|
||||
- Escalate only if confidence remains low.
|
||||
|
||||
- [ ] **Document technical design in `design.md`:**
|
||||
- **Architecture:** High-level overview of components and interactions.
|
||||
- **Data Flow:** Diagrams and descriptions.
|
||||
- **Interfaces:** API contracts, schemas, public-facing function signatures.
|
||||
- **Data Models:** Data structures and database schemas.
|
||||
|
||||
- [ ] **Document error handling:**
|
||||
- Create an error matrix with procedures and expected responses.
|
||||
|
||||
- [ ] **Define unit testing strategy.**
|
||||
|
||||
- [ ] **Create implementation plan in `tasks.md`:**
|
||||
- For each task, include description, expected outcome, and dependencies.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not proceed to implementation until design and plan are complete and validated.**
|
||||
|
||||
### **Phase 3: IMPLEMENT**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Write production-quality code according to the design and plan.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] Code in small, testable increments.
|
||||
- Document each increment with code changes, results, and test links.
|
||||
- [ ] Implement from dependencies upward.
|
||||
- Document resolution order, justification, and verification.
|
||||
- [ ] Follow conventions.
|
||||
- Document adherence and any deviations with a Decision Record.
|
||||
- [ ] Add meaningful comments.
|
||||
- Focus on intent ("why"), not mechanics ("what").
|
||||
- [ ] Create files as planned.
|
||||
- Document file creation log.
|
||||
- [ ] Update task status in real time.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not merge or deploy code until all implementation steps are documented and tested.**
|
||||
|
||||
### **Phase 4: VALIDATE**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Verify that implementation meets all requirements and quality standards.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] Execute automated tests.
|
||||
- Document outputs, logs, and coverage reports.
|
||||
- For failures, document root cause analysis and remediation.
|
||||
- [ ] Perform manual verification if necessary.
|
||||
- Document procedures, checklists, and results.
|
||||
- [ ] Test edge cases and errors.
|
||||
- Document results and evidence of correct error handling.
|
||||
- [ ] Verify performance.
|
||||
- Document metrics and profile critical sections.
|
||||
- [ ] Log execution traces.
|
||||
- Document path analysis and runtime behavior.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not proceed until all validation steps are complete and all issues are resolved.**
|
||||
|
||||
### **Phase 5: REFLECT**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Improve codebase, update documentation, and analyze performance.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] Refactor for maintainability.
|
||||
- Document decisions, before/after comparisons, and impact.
|
||||
- [ ] Update all project documentation.
|
||||
- Ensure all READMEs, diagrams, and comments are current.
|
||||
- [ ] Identify potential improvements.
|
||||
- Document backlog with prioritization.
|
||||
- [ ] Validate success criteria.
|
||||
- Document final verification matrix.
|
||||
- [ ] Perform meta-analysis.
|
||||
- Reflect on efficiency, tool usage, and protocol adherence.
|
||||
- [ ] Auto-create technical debt issues.
|
||||
- Document inventory and remediation plans.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not close the phase until all documentation and improvement actions are logged.**
|
||||
|
||||
### **Phase 6: HANDOFF**
|
||||
|
||||
**Objective:**
|
||||
|
||||
- Package work for review and deployment, and transition to next task.
|
||||
|
||||
**Checklist:**
|
||||
|
||||
- [ ] Generate executive summary.
|
||||
- Use **Compressed Decision Record** format.
|
||||
- [ ] Prepare pull request (if applicable):
|
||||
1. Executive summary.
|
||||
2. Changelog from **Streamlined Action Log**.
|
||||
3. Links to validation artifacts and Decision Records.
|
||||
4. Links to final `requirements.md`, `design.md`, and `tasks.md`.
|
||||
- [ ] Finalize workspace.
|
||||
- Archive intermediate files, logs, and temporary artifacts to `.agent_work/`.
|
||||
- [ ] Continue to next task.
|
||||
- Document transition or completion.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Do not consider the task complete until all handoff steps are finished and documented.**
|
||||
|
||||
## Troubleshooting & Retry Protocol
|
||||
|
||||
**If you encounter errors, ambiguities, or blockers:**
|
||||
|
||||
**Checklist:**
|
||||
|
||||
1. **Re-analyze**:
|
||||
- Revisit the ANALYZE phase.
|
||||
- Confirm all requirements and constraints are clear and complete.
|
||||
2. **Re-design**:
|
||||
- Revisit the DESIGN phase.
|
||||
- Update technical design, plans, or dependencies as needed.
|
||||
3. **Re-plan**:
|
||||
- Adjust the implementation plan in `tasks.md` to address new findings.
|
||||
4. **Retry execution**:
|
||||
- Re-execute failed steps with corrected parameters or logic.
|
||||
5. **Escalate**:
|
||||
- If the issue persists after retries, follow the escalation protocol.
|
||||
|
||||
**Critical Constraint:**
|
||||
|
||||
- **Never proceed with unresolved errors or ambiguities. Always document troubleshooting steps and outcomes.**
|
||||
|
||||
## Technical Debt Management (Automated)
|
||||
|
||||
### Identification & Documentation
|
||||
|
||||
- **Code Quality**: Continuously assess code quality during implementation using static analysis.
|
||||
- **Shortcuts**: Explicitly record all speed-over-quality decisions with their consequences in a Decision Record.
|
||||
- **Workspace**: Monitor for organizational drift and naming inconsistencies.
|
||||
- **Documentation**: Track incomplete, outdated, or missing documentation.
|
||||
|
||||
### Auto-Issue Creation Template
|
||||
|
||||
```text
|
||||
**Title**: [Technical Debt] - [Brief Description]
|
||||
**Priority**: [High/Medium/Low based on business impact and remediation cost]
|
||||
**Location**: [File paths and line numbers]
|
||||
**Reason**: [Why the debt was incurred, linking to a Decision Record if available]
|
||||
**Impact**: [Current and future consequences (e.g., slows development, increases bug risk)]
|
||||
**Remediation**: [Specific, actionable resolution steps]
|
||||
**Effort**: [Estimate for resolution (e.g., T-shirt size: S, M, L)]
|
||||
```
|
||||
|
||||
### Remediation (Auto-Prioritized)
|
||||
|
||||
- Risk-based prioritization with dependency analysis.
|
||||
- Effort estimation to aid in future planning.
|
||||
- Propose migration strategies for large refactoring efforts.
|
||||
|
||||
## Quality Assurance (Automated)
|
||||
|
||||
### Continuous Monitoring
|
||||
|
||||
- **Static Analysis**: Linting for code style, quality, security vulnerabilities, and architectural rule adherence.
|
||||
- **Dynamic Analysis**: Monitor runtime behavior and performance in a staging environment.
|
||||
- **Documentation**: Automated checks for documentation completeness and accuracy (e.g., linking, format).
|
||||
|
||||
### Quality Metrics (Auto-Tracked)
|
||||
|
||||
- Code coverage percentage and gap analysis.
|
||||
- Cyclomatic complexity score per function/method.
|
||||
- Maintainability index assessment.
|
||||
- Technical debt ratio (e.g., estimated remediation time vs. development time).
|
||||
- Documentation coverage percentage (e.g., public methods with comments).
|
||||
|
||||
## EARS Notation Reference
|
||||
|
||||
**EARS (Easy Approach to Requirements Syntax)** - Standard format for requirements:
|
||||
|
||||
- **Ubiquitous**: `THE SYSTEM SHALL [expected behavior]`
|
||||
- **Event-driven**: `WHEN [trigger event] THE SYSTEM SHALL [expected behavior]`
|
||||
- **State-driven**: `WHILE [in specific state] THE SYSTEM SHALL [expected behavior]`
|
||||
- **Unwanted behavior**: `IF [unwanted condition] THEN THE SYSTEM SHALL [required response]`
|
||||
- **Optional**: `WHERE [feature is included] THE SYSTEM SHALL [expected behavior]`
|
||||
- **Complex**: Combinations of the above patterns for sophisticated requirements
|
||||
|
||||
Each requirement must be:
|
||||
|
||||
- **Testable**: Can be verified through automated or manual testing
|
||||
- **Unambiguous**: Single interpretation possible
|
||||
- **Necessary**: Contributes to the system's purpose
|
||||
- **Feasible**: Can be implemented within constraints
|
||||
- **Traceable**: Linked to user needs and design elements
|
||||
74
.github/instructions/sql-sp-generation.instructions.md
vendored
Normal file
74
.github/instructions/sql-sp-generation.instructions.md
vendored
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
description: 'Guidelines for generating SQL statements and stored procedures'
|
||||
applyTo: '**/*.sql'
|
||||
---
|
||||
|
||||
# SQL Development
|
||||
|
||||
## Database schema generation
|
||||
- all table names should be in singular form
|
||||
- all column names should be in singular form
|
||||
- all tables should have a primary key column named `id`
|
||||
- all tables should have a column named `created_at` to store the creation timestamp
|
||||
- all tables should have a column named `updated_at` to store the last update timestamp
|
||||
|
||||
## Database schema design
|
||||
- all tables should have a primary key constraint
|
||||
- all foreign key constraints should have a name
|
||||
- all foreign key constraints should be defined inline
|
||||
- all foreign key constraints should have `ON DELETE CASCADE` option
|
||||
- all foreign key constraints should have `ON UPDATE CASCADE` option
|
||||
- all foreign key constraints should reference the primary key of the parent table
|
||||
|
||||
## SQL Coding Style
|
||||
- use uppercase for SQL keywords (SELECT, FROM, WHERE)
|
||||
- use consistent indentation for nested queries and conditions
|
||||
- include comments to explain complex logic
|
||||
- break long queries into multiple lines for readability
|
||||
- organize clauses consistently (SELECT, FROM, JOIN, WHERE, GROUP BY, HAVING, ORDER BY)
|
||||
|
||||
## SQL Query Structure
|
||||
- use explicit column names in SELECT statements instead of SELECT *
|
||||
- qualify column names with table name or alias when using multiple tables
|
||||
- limit the use of subqueries when joins can be used instead
|
||||
- include LIMIT/TOP clauses to restrict result sets
|
||||
- use appropriate indexing for frequently queried columns
|
||||
- avoid using functions on indexed columns in WHERE clauses
|
||||
|
||||
## Stored Procedure Naming Conventions
|
||||
- prefix stored procedure names with 'usp_'
|
||||
- use PascalCase for stored procedure names
|
||||
- use descriptive names that indicate purpose (e.g., usp_GetCustomerOrders)
|
||||
- include plural noun when returning multiple records (e.g., usp_GetProducts)
|
||||
- include singular noun when returning single record (e.g., usp_GetProduct)
|
||||
|
||||
## Parameter Handling
|
||||
- prefix parameters with '@'
|
||||
- use camelCase for parameter names
|
||||
- provide default values for optional parameters
|
||||
- validate parameter values before use
|
||||
- document parameters with comments
|
||||
- arrange parameters consistently (required first, optional later)
|
||||
|
||||
|
||||
## Stored Procedure Structure
|
||||
- include header comment block with description, parameters, and return values
|
||||
- return standardized error codes/messages
|
||||
- return result sets with consistent column order
|
||||
- use OUTPUT parameters for returning status information
|
||||
- prefix temporary tables with 'tmp_'
|
||||
|
||||
|
||||
## SQL Security Best Practices
|
||||
- parameterize all queries to prevent SQL injection
|
||||
- use prepared statements when executing dynamic SQL
|
||||
- avoid embedding credentials in SQL scripts
|
||||
- implement proper error handling without exposing system details
|
||||
- avoid using dynamic SQL within stored procedures
|
||||
|
||||
## Transaction Management
|
||||
- explicitly begin and commit transactions
|
||||
- use appropriate isolation levels based on requirements
|
||||
- avoid long-running transactions that lock tables
|
||||
- use batch processing for large data operations
|
||||
- include SET NOCOUNT ON for stored procedures that modify data
|
||||
212
.github/instructions/tanstack-start-shadcn-tailwind.instructions.md
vendored
Normal file
212
.github/instructions/tanstack-start-shadcn-tailwind.instructions.md
vendored
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
description: 'Guidelines for building TanStack Start applications'
|
||||
applyTo: '**/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.css, **/*.scss, **/*.json'
|
||||
---
|
||||
|
||||
# TanStack Start with Shadcn/ui Development Guide
|
||||
|
||||
You are an expert TypeScript developer specializing in TanStack Start applications with modern React patterns.
|
||||
|
||||
## Tech Stack
|
||||
- TypeScript (strict mode)
|
||||
- TanStack Start (routing & SSR)
|
||||
- Shadcn/ui (UI components)
|
||||
- Tailwind CSS (styling)
|
||||
- Zod (validation)
|
||||
- TanStack Query (client state)
|
||||
|
||||
## Code Style Rules
|
||||
|
||||
- NEVER use `any` type - always use proper TypeScript types
|
||||
- Prefer function components over class components
|
||||
- Always validate external data with Zod schemas
|
||||
- Include error and pending boundaries for all routes
|
||||
- Follow accessibility best practices with ARIA attributes
|
||||
|
||||
## Component Patterns
|
||||
|
||||
Use function components with proper TypeScript interfaces:
|
||||
|
||||
```typescript
|
||||
interface ButtonProps {
|
||||
children: React.ReactNode;
|
||||
onClick: () => void;
|
||||
variant?: 'primary' | 'secondary';
|
||||
}
|
||||
|
||||
export default function Button({ children, onClick, variant = 'primary' }: ButtonProps) {
|
||||
return (
|
||||
<button onClick={onClick} className={cn(buttonVariants({ variant }))}>
|
||||
{children}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Data Fetching
|
||||
|
||||
Use Route Loaders for:
|
||||
- Initial page data required for rendering
|
||||
- SSR requirements
|
||||
- SEO-critical data
|
||||
|
||||
Use React Query for:
|
||||
- Frequently updating data
|
||||
- Optional/secondary data
|
||||
- Client mutations with optimistic updates
|
||||
|
||||
```typescript
|
||||
// Route Loader
|
||||
export const Route = createFileRoute('/users')({
|
||||
loader: async () => {
|
||||
const users = await fetchUsers()
|
||||
return { users: userListSchema.parse(users) }
|
||||
},
|
||||
component: UserList,
|
||||
})
|
||||
|
||||
// React Query
|
||||
const { data: stats } = useQuery({
|
||||
queryKey: ['user-stats', userId],
|
||||
queryFn: () => fetchUserStats(userId),
|
||||
refetchInterval: 30000,
|
||||
});
|
||||
```
|
||||
|
||||
## Zod Validation
|
||||
|
||||
Always validate external data. Define schemas in `src/lib/schemas.ts`:
|
||||
|
||||
```typescript
|
||||
export const userSchema = z.object({
|
||||
id: z.string(),
|
||||
name: z.string().min(1).max(100),
|
||||
email: z.string().email().optional(),
|
||||
role: z.enum(['admin', 'user']).default('user'),
|
||||
})
|
||||
|
||||
export type User = z.infer<typeof userSchema>
|
||||
|
||||
// Safe parsing
|
||||
const result = userSchema.safeParse(data)
|
||||
if (!result.success) {
|
||||
console.error('Validation failed:', result.error.format())
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
## Routes
|
||||
|
||||
Structure routes in `src/routes/` with file-based routing. Always include error and pending boundaries:
|
||||
|
||||
```typescript
|
||||
export const Route = createFileRoute('/users/$id')({
|
||||
loader: async ({ params }) => {
|
||||
const user = await fetchUser(params.id);
|
||||
return { user: userSchema.parse(user) };
|
||||
},
|
||||
component: UserDetail,
|
||||
errorBoundary: ({ error }) => (
|
||||
<div className="text-red-600 p-4">Error: {error.message}</div>
|
||||
),
|
||||
pendingBoundary: () => (
|
||||
<div className="flex items-center justify-center p-4">
|
||||
<div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
|
||||
</div>
|
||||
),
|
||||
});
|
||||
```
|
||||
|
||||
## UI Components
|
||||
|
||||
Always prefer Shadcn/ui components over custom ones:
|
||||
|
||||
```typescript
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
|
||||
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<CardTitle>User Details</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<Button onClick={handleSave}>Save</Button>
|
||||
</CardContent>
|
||||
</Card>
|
||||
```
|
||||
|
||||
Use Tailwind for styling with responsive design:
|
||||
|
||||
```typescript
|
||||
<div className="flex flex-col gap-4 p-6 md:flex-row md:gap-6">
|
||||
<Button className="w-full md:w-auto">Action</Button>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
Use semantic HTML first. Only add ARIA when no semantic equivalent exists:
|
||||
|
||||
```typescript
|
||||
// ✅ Good: Semantic HTML with minimal ARIA
|
||||
<button onClick={toggleMenu}>
|
||||
<MenuIcon aria-hidden="true" />
|
||||
<span className="sr-only">Toggle Menu</span>
|
||||
</button>
|
||||
|
||||
// ✅ Good: ARIA only when needed (for dynamic states)
|
||||
<button
|
||||
aria-expanded={isOpen}
|
||||
aria-controls="menu"
|
||||
onClick={toggleMenu}
|
||||
>
|
||||
Menu
|
||||
</button>
|
||||
|
||||
// ✅ Good: Semantic form elements
|
||||
<label htmlFor="email">Email Address</label>
|
||||
<input id="email" type="email" />
|
||||
{errors.email && (
|
||||
<p role="alert">{errors.email}</p>
|
||||
)}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/ui/ # Shadcn/ui components
|
||||
├── lib/schemas.ts # Zod schemas
|
||||
├── routes/ # File-based routes
|
||||
└── routes/api/ # Server routes (.ts)
|
||||
```
|
||||
|
||||
## Import Standards
|
||||
|
||||
Use `@/` alias for all internal imports:
|
||||
|
||||
```typescript
|
||||
// ✅ Good
|
||||
import { Button } from '@/components/ui/button'
|
||||
import { userSchema } from '@/lib/schemas'
|
||||
|
||||
// ❌ Bad
|
||||
import { Button } from '../components/ui/button'
|
||||
```
|
||||
|
||||
## Adding Components
|
||||
|
||||
Install Shadcn components when needed:
|
||||
|
||||
```bash
|
||||
npx shadcn@latest add button card input dialog
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
- Always validate external data with Zod
|
||||
- Use route loaders for initial data, React Query for updates
|
||||
- Include error/pending boundaries on all routes
|
||||
- Prefer Shadcn components over custom UI
|
||||
- Use `@/` imports consistently
|
||||
- Follow accessibility best practices
|
||||
549
.github/instructions/update-docs-on-code-change.instructions.md
vendored
Normal file
549
.github/instructions/update-docs-on-code-change.instructions.md
vendored
Normal file
@@ -0,0 +1,549 @@
|
||||
---
|
||||
description: 'Automatically update README.md and documentation files when application code changes require documentation updates'
|
||||
applyTo: '**/*.{md,js,mjs,cjs,ts,tsx,jsx,py,java,cs,go,rb,php,rs,cpp,c,h,hpp}'
|
||||
---
|
||||
|
||||
# Update Documentation on Code Change
|
||||
|
||||
## Overview
|
||||
|
||||
Ensure documentation stays synchronized with code changes by automatically detecting when README.md,
|
||||
API documentation, configuration guides, and other documentation files need updates based on code
|
||||
modifications.
|
||||
|
||||
## Instruction Sections and Configuration
|
||||
|
||||
The following parts of this section, `Instruction Sections and Configurable Instruction Sections`
|
||||
and `Instruction Configuration` are only relevant to THIS instruction file, and are meant to be a
|
||||
method to easily modify how the Copilot instructions are implemented. Essentially the two parts
|
||||
are meant to turn portions or sections of the actual Copilot instructions on or off, and allow for
|
||||
custom cases and conditions for when and how to implement certain sections of this document.
|
||||
|
||||
### Instruction Sections and Configurable Instruction Sections
|
||||
|
||||
There are several instruction sections in this document. The start of an instruction section is
|
||||
indicated by a level two header. Call this an **INSTRUCTION SECTION**. Some instruction
|
||||
sections are configurable. Some are not configurable and will always be used.
|
||||
|
||||
Instruction sections that ARE configurable are not required, and are subject to additional context
|
||||
and/or conditions. Call these **CONFIGURABLE INSTRUCTION SECTIONS**.
|
||||
|
||||
**Configurable instruction sections** will have the section's configuration property appended to
|
||||
the level two header, wrapped in backticks (e.g., `apply-this`). Call this the
|
||||
**CONFIGURABLE PROPERTY**.
|
||||
|
||||
The **configurable property** will be declared and defined in the **Instruction Configuration**
|
||||
portion of this section. They are booleans. If `true`, then apply, utilize, and/or follow the
|
||||
instructions in that section.
|
||||
|
||||
Each **configurable instruction section** will also have a sentence that follows the section's
|
||||
level two header with the section's configuration details. Call this the **CONFIGURATION DETAIL**.
|
||||
|
||||
The **configuration detail** is a subset of rules that expand upon the configurable instruction
|
||||
section. This allows for custom cases and/or conditions to be checked that will determine the final
|
||||
implementation for that **configurable instruction section**.
|
||||
|
||||
Before resolving on how to apply a **configurable instruction section**, check the
|
||||
**configurable property** for a nested and/or corresponding `apply-condition`, and utilize the `apply-condition` when settling on the final approach for the **configurable instruction section**. By
|
||||
default the `apply-condition` for each **configurable property** is unset, but an example of a set
|
||||
`apply-condition` could be something like:
|
||||
|
||||
- **apply-condition** :
|
||||
` this.parent.property = (git.branch == "master") ? this.parent.property = true : this.parent.property = false; `
|
||||
|
||||
The sum of all the **constant instructions sections**, and **configurable instruction sections**
|
||||
will determine the complete instructions to follow. Call this the **COMPILED INSTRUCTIONS**.
|
||||
|
||||
The **compiled instructions** are dependent on the configuration. Each instruction section
|
||||
included in the **compiled instructions** will be interpreted and utilized AS IF a separate set
|
||||
of instructions that are independent of the entirety of this instruction file. Call this the
|
||||
**FINAL PROCEDURE**.
|
||||
|
||||
### Instruction Configuration
|
||||
|
||||
- **apply-doc-file-structure** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-doc-verification** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-doc-quality-standard** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-automation-tooling** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-doc-patterns** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-best-practices** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-validation-commands** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-maintenance-schedule** : true
|
||||
- **apply-condition** : unset
|
||||
- **apply-git-integration** : false
|
||||
- **apply-condition** : unset
|
||||
|
||||
<!--
|
||||
| Configuration Property | Default | Description | When to Enable/Disable |
|
||||
|-------------------------------|---------|-----------------------------------------------------------------------------|-------------------------------------------------------------|
|
||||
| apply-doc-file-structure | true | Ensures documentation follows a consistent file structure. | Disable if you want to allow free-form doc organization. |
|
||||
| apply-doc-verification | true | Verifies that documentation matches code changes. | Disable if verification is handled elsewhere. |
|
||||
| apply-doc-quality-standard | true | Enforces documentation quality standards. | Disable if quality standards are not required. |
|
||||
| apply-automation-tooling | true | Uses automation tools to update documentation. | Disable if you prefer manual documentation updates. |
|
||||
| apply-doc-patterns | true | Applies common documentation patterns and templates. | Disable for custom or unconventional documentation styles. |
|
||||
| apply-best-practices | true | Enforces best practices in documentation. | Disable if best practices are not a priority. |
|
||||
| apply-validation-commands | true | Runs validation commands to check documentation correctness. | Disable if validation is not needed. |
|
||||
| apply-maintenance-schedule | true | Schedules regular documentation maintenance. | Disable if maintenance is managed differently. |
|
||||
| apply-git-integration | false | Integrates documentation updates with Git workflows. | Enable if you want automatic Git integration. |
|
||||
-->
|
||||
## When to Update Documentation
|
||||
|
||||
### Trigger Conditions
|
||||
|
||||
Automatically check if documentation updates are needed when:
|
||||
|
||||
- New features or functionality are added
|
||||
- API endpoints, methods, or interfaces change
|
||||
- Breaking changes are introduced
|
||||
- Dependencies or requirements change
|
||||
- Configuration options or environment variables are modified
|
||||
- Installation or setup procedures change
|
||||
- Command-line interfaces or scripts are updated
|
||||
- Code examples in documentation become outdated
|
||||
|
||||
## Documentation Update Rules
|
||||
|
||||
### README.md Updates
|
||||
|
||||
**Always update README.md when:**
|
||||
|
||||
- Adding new features or capabilities
|
||||
- Add feature description to "Features" section
|
||||
- Include usage examples if applicable
|
||||
- Update table of contents if present
|
||||
|
||||
- Modifying installation or setup process
|
||||
- Update "Installation" or "Getting Started" section
|
||||
- Revise dependency requirements
|
||||
- Update prerequisite lists
|
||||
|
||||
- Adding new CLI commands or options
|
||||
- Document command syntax and examples
|
||||
- Include option descriptions and default values
|
||||
- Add usage examples
|
||||
|
||||
- Changing configuration options
|
||||
- Update configuration examples
|
||||
- Document new environment variables
|
||||
- Update config file templates
|
||||
|
||||
### API Documentation Updates
|
||||
|
||||
**Sync API documentation when:**
|
||||
|
||||
- New endpoints are added
|
||||
- Document HTTP method, path, parameters
|
||||
- Include request/response examples
|
||||
- Update OpenAPI/Swagger specs
|
||||
|
||||
- Endpoint signatures change
|
||||
- Update parameter lists
|
||||
- Revise response schemas
|
||||
- Document breaking changes
|
||||
|
||||
- Authentication or authorization changes
|
||||
- Update authentication examples
|
||||
- Revise security requirements
|
||||
- Update API key/token documentation
|
||||
|
||||
### Code Example Synchronization
|
||||
|
||||
**Verify and update code examples when:**
|
||||
|
||||
- Function signatures change
|
||||
- Update all code snippets using the function
|
||||
- Verify examples still compile/run
|
||||
- Update import statements if needed
|
||||
|
||||
- API interfaces change
|
||||
- Update example requests and responses
|
||||
- Revise client code examples
|
||||
- Update SDK usage examples
|
||||
|
||||
- Best practices evolve
|
||||
- Replace outdated patterns in examples
|
||||
- Update to use current recommended approaches
|
||||
- Add deprecation notices for old patterns
|
||||
|
||||
### Configuration Documentation
|
||||
|
||||
**Update configuration docs when:**
|
||||
|
||||
- New environment variables are added
|
||||
- Add to .env.example file
|
||||
- Document in README.md or docs/configuration.md
|
||||
- Include default values and descriptions
|
||||
|
||||
- Config file structure changes
|
||||
- Update example config files
|
||||
- Document new options
|
||||
- Mark deprecated options
|
||||
|
||||
- Deployment configuration changes
|
||||
- Update Docker/Kubernetes configs
|
||||
- Revise deployment guides
|
||||
- Update infrastructure-as-code examples
|
||||
|
||||
### Migration and Breaking Changes
|
||||
|
||||
**Create migration guides when:**
|
||||
|
||||
- Breaking API changes occur
|
||||
- Document what changed
|
||||
- Provide before/after examples
|
||||
- Include step-by-step migration instructions
|
||||
|
||||
- Major version updates
|
||||
- List all breaking changes
|
||||
- Provide upgrade checklist
|
||||
- Include common migration issues and solutions
|
||||
|
||||
- Deprecating features
|
||||
- Mark deprecated features clearly
|
||||
- Suggest alternative approaches
|
||||
- Include timeline for removal
|
||||
|
||||
## Documentation File Structure `apply-doc-file-structure`
|
||||
|
||||
If `apply-doc-file-structure == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Standard Documentation Files
|
||||
|
||||
Maintain these documentation files and update as needed:
|
||||
|
||||
- **README.md**: Project overview, quick start, basic usage
|
||||
- **CHANGELOG.md**: Version history and user-facing changes
|
||||
- **docs/**: Detailed documentation
|
||||
- `installation.md`: Setup and installation guide
|
||||
- `configuration.md`: Configuration options and examples
|
||||
- `api.md`: API reference documentation
|
||||
- `contributing.md`: Contribution guidelines
|
||||
- `migration-guides/`: Version migration guides
|
||||
- **examples/**: Working code examples and tutorials
|
||||
|
||||
### Changelog Management
|
||||
|
||||
**Add changelog entries for:**
|
||||
|
||||
- New features (under "Added" section)
|
||||
- Bug fixes (under "Fixed" section)
|
||||
- Breaking changes (under "Changed" section with **BREAKING** prefix)
|
||||
- Deprecated features (under "Deprecated" section)
|
||||
- Removed features (under "Removed" section)
|
||||
- Security fixes (under "Security" section)
|
||||
|
||||
**Changelog format:**
|
||||
|
||||
```markdown
|
||||
## [Version] - YYYY-MM-DD
|
||||
|
||||
### Added
|
||||
- New feature description with reference to PR/issue
|
||||
|
||||
### Changed
|
||||
- **BREAKING**: Description of breaking change
|
||||
- Other changes
|
||||
|
||||
### Fixed
|
||||
- Bug fix description
|
||||
```
|
||||
|
||||
## Documentation Verification `apply-doc-verification`
|
||||
|
||||
If `apply-doc-verification == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Before Applying Changes
|
||||
|
||||
**Check documentation completeness:**
|
||||
|
||||
1. All new public APIs are documented
|
||||
2. Code examples compile and run
|
||||
3. Links in documentation are valid
|
||||
4. Configuration examples are accurate
|
||||
5. Installation steps are current
|
||||
6. README.md reflects current state
|
||||
|
||||
### Documentation Tests
|
||||
|
||||
**Include documentation validation:**
|
||||
|
||||
#### Example Tasks
|
||||
|
||||
- Verify code examples in docs compile/run
|
||||
- Check for broken internal/external links
|
||||
- Validate configuration examples against schemas
|
||||
- Ensure API examples match current implementation
|
||||
|
||||
```bash
|
||||
# Example validation commands
|
||||
npm run docs:check # Verify docs build
|
||||
npm run docs:test-examples # Test code examples
|
||||
npm run docs:lint # Check for issues
|
||||
```
|
||||
|
||||
## Documentation Quality Standards `apply-doc-quality-standard`
|
||||
|
||||
If `apply-doc-quality-standard == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Writing Guidelines
|
||||
|
||||
- Use clear, concise language
|
||||
- Include working code examples
|
||||
- Provide both basic and advanced examples
|
||||
- Use consistent terminology
|
||||
- Include error handling examples
|
||||
- Document edge cases and limitations
|
||||
|
||||
### Code Example Format
|
||||
|
||||
```markdown
|
||||
### Example: [Clear description of what example demonstrates]
|
||||
|
||||
\`\`\`language
|
||||
// Include necessary imports/setup
|
||||
import { function } from 'package';
|
||||
|
||||
// Complete, runnable example
|
||||
const result = function(parameter);
|
||||
console.log(result);
|
||||
\`\`\`
|
||||
|
||||
**Output:**
|
||||
\`\`\`
|
||||
expected output
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### API Documentation Format
|
||||
|
||||
```markdown
|
||||
### `functionName(param1, param2)`
|
||||
|
||||
Brief description of what the function does.
|
||||
|
||||
**Parameters:**
|
||||
- `param1` (type): Description of parameter
|
||||
- `param2` (type, optional): Description with default value
|
||||
|
||||
**Returns:**
|
||||
- `type`: Description of return value
|
||||
|
||||
**Example:**
|
||||
\`\`\`language
|
||||
const result = functionName('value', 42);
|
||||
\`\`\`
|
||||
|
||||
**Throws:**
|
||||
- `ErrorType`: When and why error is thrown
|
||||
```
|
||||
|
||||
## Automation and Tooling `apply-automation-tooling`
|
||||
|
||||
If `apply-automation-tooling == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Documentation Generation
|
||||
|
||||
**Use automated tools when available:**
|
||||
|
||||
#### Automated Tool Examples
|
||||
|
||||
- JSDoc/TSDoc for JavaScript/TypeScript
|
||||
- Sphinx/pdoc for Python
|
||||
- Javadoc for Java
|
||||
- xmldoc for C#
|
||||
- godoc for Go
|
||||
- rustdoc for Rust
|
||||
|
||||
### Documentation Linting
|
||||
|
||||
**Validate documentation with:**
|
||||
|
||||
- Markdown linters (markdownlint)
|
||||
- Link checkers (markdown-link-check)
|
||||
- Spell checkers (cspell)
|
||||
- Code example validators
|
||||
|
||||
### Pre-update Hooks
|
||||
|
||||
**Add pre-commit checks for:**
|
||||
|
||||
- Documentation build succeeds
|
||||
- No broken links
|
||||
- Code examples are valid
|
||||
- Changelog entry exists for changes
|
||||
|
||||
## Common Documentation Patterns `apply-doc-patterns`
|
||||
|
||||
If `apply-doc-patterns == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Feature Documentation Template
|
||||
|
||||
```markdown
|
||||
## Feature Name
|
||||
|
||||
Brief description of the feature.
|
||||
|
||||
### Usage
|
||||
|
||||
Basic usage example with code snippet.
|
||||
|
||||
### Configuration
|
||||
|
||||
Configuration options with examples.
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
Complex scenarios and edge cases.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
Common issues and solutions.
|
||||
```
|
||||
|
||||
### API Endpoint Documentation Template
|
||||
|
||||
```markdown
|
||||
### `HTTP_METHOD /api/endpoint`
|
||||
|
||||
Description of what the endpoint does.
|
||||
|
||||
**Request:**
|
||||
\`\`\`json
|
||||
{
|
||||
"param": "value"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Response:**
|
||||
\`\`\`json
|
||||
{
|
||||
"result": "value"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Bad request
|
||||
- 401: Unauthorized
|
||||
```
|
||||
|
||||
## Best Practices `apply-best-practices`
|
||||
|
||||
If `apply-best-practices == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Do's
|
||||
|
||||
- ✅ Update documentation in the same commit as code changes
|
||||
- ✅ Include before/after examples for changes to be reviewed before applying
|
||||
- ✅ Test code examples before committing
|
||||
- ✅ Use consistent formatting and terminology
|
||||
- ✅ Document limitations and edge cases
|
||||
- ✅ Provide migration paths for breaking changes
|
||||
- ✅ Keep documentation DRY (link instead of duplicating)
|
||||
|
||||
### Don'ts
|
||||
|
||||
- ❌ Commit code changes without updating documentation
|
||||
- ❌ Leave outdated examples in documentation
|
||||
- ❌ Document features that don't exist yet
|
||||
- ❌ Use vague or ambiguous language
|
||||
- ❌ Forget to update changelog
|
||||
- ❌ Ignore broken links or failing examples
|
||||
- ❌ Document implementation details users don't need
|
||||
|
||||
## Validation Example Commands `apply-validation-commands`
|
||||
|
||||
If `apply-validation-commands == true`, then apply the following configurable instruction section.
|
||||
|
||||
Example scripts to apply to your project for documentation validation:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"docs:build": "Build documentation",
|
||||
"docs:test": "Test code examples in docs",
|
||||
"docs:lint": "Lint documentation files",
|
||||
"docs:links": "Check for broken links",
|
||||
"docs:spell": "Spell check documentation",
|
||||
"docs:validate": "Run all documentation checks"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Maintenance Schedule `apply-maintenance-schedule`
|
||||
|
||||
If `apply-maintenance-schedule == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Regular Reviews
|
||||
|
||||
- **Monthly**: Review documentation for accuracy
|
||||
- **Per release**: Update version numbers and examples
|
||||
- **Quarterly**: Check for outdated patterns or deprecated features
|
||||
- **Annually**: Comprehensive documentation audit
|
||||
|
||||
### Deprecation Process
|
||||
|
||||
When deprecating features:
|
||||
|
||||
1. Add deprecation notice to documentation
|
||||
2. Update examples to use recommended alternatives
|
||||
3. Create migration guide
|
||||
4. Update changelog with deprecation notice
|
||||
5. Set timeline for removal
|
||||
6. In next major version, remove deprecated feature and docs
|
||||
|
||||
## Git Integration `apply-git-integration`
|
||||
|
||||
If `apply-git-integration == true`, then apply the following configurable instruction section.
|
||||
|
||||
### Pull Request Requirements
|
||||
|
||||
**Documentation must be updated in the same PR as code changes:**
|
||||
|
||||
- Document new features in the feature PR
|
||||
- Update examples when code changes
|
||||
- Add changelog entries with code changes
|
||||
- Update API docs when interfaces change
|
||||
|
||||
### Documentation Review
|
||||
|
||||
**During code review, verify:**
|
||||
|
||||
- Documentation accurately describes the changes
|
||||
- Examples are clear and complete
|
||||
- No undocumented breaking changes
|
||||
- Changelog entry is appropriate
|
||||
- Migration guides are provided if needed
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Before considering documentation complete, and concluding on the **final procedure**:
|
||||
|
||||
- [ ] **Compiled instructions** are based on the sum of **constant instruction sections** and
|
||||
**configurable instruction sections**
|
||||
- [ ] README.md reflects current project state
|
||||
- [ ] All new features are documented
|
||||
- [ ] Code examples are tested and work
|
||||
- [ ] API documentation is complete and accurate
|
||||
- [ ] Configuration examples are up to date
|
||||
- [ ] Breaking changes are documented with migration guide
|
||||
- [ ] CHANGELOG.md is updated
|
||||
- [ ] Links are valid and not broken
|
||||
- [ ] Installation instructions are current
|
||||
- [ ] Environment variables are documented
|
||||
|
||||
## Updating Documentation on Code Change GOAL
|
||||
|
||||
- Keep documentation close to code when possible
|
||||
- Use documentation generators for API reference
|
||||
- Maintain living documentation that evolves with code
|
||||
- Consider documentation as part of feature completeness
|
||||
- Review documentation in code reviews
|
||||
- Make documentation easy to find and navigate
|
||||
Reference in New Issue
Block a user