Skip to content

Commit aa08d48

Browse files
shouzeshouze
committed
docs(agents): introduce .github/skills/ knowledge base, update instructions
- .github/skills/documentation.md: VitePress theme map, CSS vars, WCAG 2.1 AA patterns, responsive breakpoints, VitePress 768px quirks, validation checklist - .github/skills/feature.md: layer map, type-first design, CLI conventions, render sub-module extension playbook, test patterns - .github/skills/bug-fixing.md: extended symptom→module table, test-first patterns, minimal fix principles - .github/skills/refactoring.md: architectural invariants, safe rename playbook, module extraction pattern, knip interpretation guide - .github/skills/release.md: semver guide, CD pipeline, binary targets, blog post format, CHANGELOG rules, versioned docs snapshot mechanics - All 5 instruction files: add Skill reference header pointing to companion skill - CONTRIBUTING.md: add docs validation commands + AI agent tooling section
1 parent 4d3d183 commit aa08d48

11 files changed

+724
-2
lines changed

‎.github/instructions/bug-fixing.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ excludeAgent: "code-review"
55

66
# Bug fixing — instructions for Copilot coding agent
77

8+
> **Skill reference:** for the extended symptom → module diagnostic table, test-first patterns and minimal fix principles read `.github/skills/bug-fixing.md` first.
9+
810
Follow these steps when fixing a bug in this repository.
911

1012
## 1. Reproduce the bug before writing any fix

‎.github/instructions/documentation.instructions.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ applyTo: "docs/**"
44

55
# Documentation — instructions for Copilot coding agent
66

7+
> **Skill reference:** for deep domain knowledge (VitePress theme architecture, CSS variables, accessibility patterns, responsive patterns, full validation commands) read `.github/skills/documentation.md` first.
8+
79
Follow these conventions when writing or editing pages in the `docs/` directory.
810

911
## 1. Tool & rendering pipeline
@@ -93,9 +95,20 @@ docs/
9395
Before opening a PR for any docs change:
9496

9597
```bash
96-
bun run docs:build # must complete without errors
97-
bun run format:check # oxfmt — no formatting diff
98+
bun run docs:build # must complete without errors or dead-link warnings
99+
bun run format:check # oxfmt — no formatting diff
98100
```
99101

100102
- All internal links must resolve (VitePress reports dead links on build).
101103
- No new `bun run knip` violations (docs/\*\* is excluded but `package.json` changes are not).
104+
105+
If the PR modifies any Vue component, CSS, or page layout, also run the accessibility and responsive suites:
106+
107+
```bash
108+
bun run docs:build:a11y
109+
bun run docs:preview -- --port 4173 &
110+
bun run docs:a11y # pa11y-ci WCAG 2.1 AA — must report 0 errors
111+
bun run docs:test:responsive # Playwright — 20/20 tests green (4 viewports × 5 pages)
112+
```
113+
114+
See `.github/skills/documentation.md` for pa11y configuration details, WCAG contrast rules, accessible component patterns, and responsive breakpoint guidance.

‎.github/instructions/implement-feature.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ excludeAgent: "code-review"
55

66
# Implement feature — instructions for Copilot coding agent
77

8+
> **Skill reference:** for the full architectural layer map, type-first design patterns, CLI option conventions, render sub-module extension playbook and test strategies read `.github/skills/feature.md` first.
9+
810
Follow these steps when implementing a new feature in this repository.
911

1012
## 1. Understand the task scope before writing code

‎.github/instructions/refactoring.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ excludeAgent: "code-review"
55

66
# Refactoring — instructions for Copilot coding agent
77

8+
> **Skill reference:** for architectural invariants, safe rename playbook, module extraction patterns, characterisation test strategy and `knip` output interpretation read `.github/skills/refactoring.md` first.
9+
810
Follow these steps when refactoring existing code in this repository.
911

1012
## 1. Define the goal and scope

‎.github/instructions/release.instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ excludeAgent: "code-review"
55

66
# Release — instructions for Copilot coding agent
77

8+
> **Skill reference:** for the semver decision guide, CD pipeline mechanics, binary targets, blog post format reference and versioned docs snapshot details read `.github/skills/release.md` first.
9+
810
Follow these steps when cutting a new release of `github-code-search`.
911

1012
## 1. Determine the version bump

‎.github/skills/bug-fixing.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Bug fixing skill — github-code-search
2+
3+
Deep reference for diagnosing and fixing bugs in this codebase.
4+
This skill complements `.github/instructions/bug-fixing.instructions.md`.
5+
6+
---
7+
8+
## Symptom → module diagnostic table
9+
10+
| Symptom | Primary suspect | Secondary suspect |
11+
| --------------------------------------------------- | -------------------------------------- | ----------------------------- |
12+
| Results missing or duplicated | `src/aggregate.ts` | `src/api.ts` (pagination) |
13+
| Wrong repository grouping | `src/group.ts` | `src/aggregate.ts` |
14+
| `--exclude-repositories` / `--exclude-extracts` not working | `src/aggregate.ts` | `github-code-search.ts` (parsing) |
15+
| Markdown output malformed | `src/output.ts` | — |
16+
| JSON output missing fields or wrong shape | `src/output.ts` | `src/types.ts` (interface) |
17+
| Syntax highlighting wrong colour / wrong language | `src/render/highlight.ts` | — |
18+
| Row navigation skips or wraps incorrectly | `src/render/rows.ts` | `src/tui.ts` (key handler) |
19+
| Select-all / select-none inconsistent | `src/render/selection.ts` | `src/tui.ts` |
20+
| Filter count / stats incorrect | `src/render/filter.ts`, `src/render/summary.ts` | — |
21+
| Path filter (`/regex/`) doesn't match expected | `src/render/filter-match.ts` | `src/tui.ts` (filter state) |
22+
| API returns 0 results or stops paginating | `src/api.ts` | `src/api-utils.ts` |
23+
| Rate limit hit / 429 not retried | `src/api-utils.ts` (`fetchWithRetry`) | — |
24+
| TUI shows blank screen or wrong row | `src/tui.ts` | `src/render/rows.ts` |
25+
| Help overlay doesn't appear / has wrong keys | `src/render.ts` (`renderHelpOverlay`) | `src/tui.ts` |
26+
| Upgrade fails or replaces wrong binary | `src/upgrade.ts` | — |
27+
| Completion script wrong content | `src/completions.ts` | — |
28+
| Completion file written to wrong path | `src/completions.ts` (`getCompletionFilePath`) | env vars (`XDG_*`, `ZDOTDIR`) |
29+
| Completion not refreshed after upgrade | `src/upgrade.ts` (`refreshCompletions`) | — |
30+
| `--version` shows wrong info | `build.ts` (SHA injection) | — |
31+
| CLI option ignored or parsed wrong | `github-code-search.ts` | `src/types.ts` (`OutputType`) |
32+
33+
---
34+
35+
## Reproducing a bug
36+
37+
A complete bug report must have:
38+
39+
1. **Exact command** (redact `GITHUB_TOKEN` with `***`):
40+
```
41+
GITHUB_TOKEN=*** github-code-search query "pattern" --org acme
42+
```
43+
2. **Observed output** vs **expected output**.
44+
3. **Version string**: `github-code-search --version` → e.g. `1.8.0 (a1b2c3d · darwin/arm64)`.
45+
4. **Bun version** (when running from source): `bun --version`.
46+
47+
If the report is missing items 1 or 3, read the relevant module(s) to hypothesise the root cause before asking for more info.
48+
49+
---
50+
51+
## Test-first patterns for bugs
52+
53+
### Pure function bug (aggregate, group, output, render/*)
54+
55+
```typescript
56+
// src/aggregate.test.ts
57+
describe("applyFiltersAndExclusions — bug #N", () => {
58+
it("excludes org-prefixed repo names correctly", () => {
59+
const result = applyFiltersAndExclusions(matches, {
60+
excludeRepositories: ["acme/my-repo"], // the previously broken form
61+
});
62+
expect(result).not.toContainEqual(
63+
expect.objectContaining({ repo: "acme/my-repo" }),
64+
);
65+
});
66+
});
67+
```
68+
69+
The test must **fail** with the current code before the fix. Commit the test, then fix.
70+
71+
### api-utils bug (retry / pagination)
72+
73+
```typescript
74+
// src/api-utils.test.ts
75+
it("retries on 429 with Retry-After header", async () => {
76+
let callCount = 0;
77+
globalThis.fetch = async () => {
78+
callCount++;
79+
if (callCount === 1) {
80+
return new Response(null, {
81+
status: 429,
82+
headers: { "Retry-After": "0" },
83+
});
84+
}
85+
return new Response(JSON.stringify({ ok: true }), { status: 200 });
86+
};
87+
await fetchWithRetry("https://api.github.com/test");
88+
expect(callCount).toBe(2);
89+
});
90+
```
91+
92+
### Side-effectful bug (tui, api) — no unit test possible
93+
94+
Document manual repro steps in the PR description:
95+
96+
```markdown
97+
## Steps to reproduce (before fix)
98+
1. `GITHUB_TOKEN=... github-code-search query "foo" --org acme`
99+
2. Press `↓` past the last result
100+
3. Expected: cursor stays on last row / Expected: wraps to first row
101+
4. Observed: cursor jumps to blank row
102+
```
103+
104+
---
105+
106+
## Minimal fix principles
107+
108+
- **Touch only the root cause.** Do not opportunistically refactor neighbouring code in the same PR — it makes the fix harder to review and risks introducing new bugs.
109+
- **Respect pure/IO layering**: a fix in `aggregate.ts` must not add a `console.log` call.
110+
- **Type changes cascade**: if `src/types.ts` must change, run `bun run knip` to find all affected consumers and update them all in the same PR.
111+
- **Regression comment**: if the root cause is non-obvious, add one line above the fix:
112+
```typescript
113+
// Fix: short names ("repo") and qualified names ("org/repo") must both match — see issue #N
114+
```
115+
116+
---
117+
118+
## Validation after fix
119+
120+
```bash
121+
bun test # the previously failing test now passes; full suite still green
122+
bun run lint # oxlint — zero errors
123+
bun run format:check # oxfmt — no formatting diff
124+
bun run knip # no unused exports or imports
125+
bun run build.ts # binary compiles without errors
126+
```

‎.github/skills/documentation.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Documentation skill — github-code-search
2+
3+
Deep reference for writing and maintaining VitePress documentation in this project.
4+
This skill complements `.github/instructions/documentation.instructions.md` (the step-by-step workflow).
5+
6+
---
7+
8+
## VitePress theme architecture
9+
10+
Custom components live in `docs/.vitepress/theme/`:
11+
12+
| File / folder | Role |
13+
| ------------------------ | -------------------------------------------------------------------- |
14+
| `index.ts` | Theme entry point — imports components and global CSS |
15+
| `custom.css` | All CSS overrides — brand colours, typography, responsive, a11y |
16+
| `Layout.vue` | Root layout wrapper (adds `RichFooter`, manages slot injection) |
17+
| `TerminalDemo.vue` | Animated terminal on the hero — `aria-hidden="true"` (decorative) |
18+
| `ComparisonTable.vue` | Feature comparison table with responsive 3-column layout |
19+
| `UseCaseTabs.vue` | WAI-ARIA Tabs pattern (roving tabindex, ArrowLeft/Right/Home/End) |
20+
| `InstallSection.vue` | Install command snippets with OS tabs |
21+
| `HowItWorks.vue` | 3-step explainer with responsive card layout |
22+
| `TestimonialsSection.vue`| Community testimonials carousel |
23+
| `ProductionCta.vue` | "Used in production?" CTA banner (`<section aria-labelledby="…">`) |
24+
| `VersionBadge.vue` | Release badge — reads `version` from `package.json` at build time |
25+
| `RichFooter.vue` | Custom footer replacing VitePress default |
26+
27+
**Extending a component:**
28+
1. Locate the `.vue` file above.
29+
2. Follow the existing scoped `<style>` conventions (no global selectors inside `<style scoped>`).
30+
3. Add responsive styles inside the component's `<style>` or in `custom.css` if the rule is global.
31+
4. Never import additional NPM packages for styling — only `picocolors` (CLI) and VitePress built-ins.
32+
33+
---
34+
35+
## CSS variable system
36+
37+
Always use VitePress CSS variables — never hard-code colours in component `<style>` blocks:
38+
39+
| Variable | Meaning |
40+
| --------------------- | ------------------------------------ |
41+
| `--vp-c-brand-1` | Violet `#9933FF` / `#cc88ff` (dark) |
42+
| `--vp-c-brand-2` | Hover darkening |
43+
| `--vp-c-brand-soft` | Soft tint for backgrounds |
44+
| `--vp-c-text-1` | Primary text (≥ WCAG AA on bg) |
45+
| `--vp-c-text-2` | Secondary text (≥ WCAG AA on bg) |
46+
| `--vp-c-text-3` | **Do not use for text** — 2.87:1 contrast, fails WCAG AA |
47+
| `--vp-c-divider` | Border / separator |
48+
| `--vp-c-bg-soft` | Card / inset background |
49+
| `--vp-font-family-mono` | Monospace (code blocks) |
50+
51+
Dark mode: VitePress applies a `.dark` class on `<html>`. Use `.dark .selector { … }` — never `@media (prefers-color-scheme: dark)`.
52+
53+
---
54+
55+
## Accessibility (WCAG 2.1 AA)
56+
57+
This project maintains **zero pa11y-ci violations** at WCAG 2.1 AA level.
58+
59+
### Tool
60+
61+
```bash
62+
bun run docs:build:a11y # build with VITEPRESS_HOSTNAME=http://localhost:4173
63+
bun run docs:preview -- --port 4173 &
64+
bun run docs:a11y # pa11y-ci via sitemap — must report 0 errors
65+
```
66+
67+
Config: `.pa11yci.json`. F77 (Mermaid duplicate SVG IDs) is ignored — not blocking for AT users.
68+
69+
### Common patterns
70+
71+
| Pattern | Correct implementation |
72+
| ------------------------------------------ | ------------------------------------------------------------------ |
73+
| Landmark regions | `<section aria-labelledby="id">` + matching `id` on heading |
74+
| Icon-only buttons / links | `aria-label="Descriptive text"` |
75+
| Decorative images / SVG | `aria-hidden="true"` and no `alt` (or `alt=""`) |
76+
| External links (open in new tab) | `aria-label="Label (opens in a new tab)"` or `.sr-only` suffix |
77+
| Check / cross icons in tables | `aria-label="Yes"` / `aria-label="No"` |
78+
| Table column headers | `<th scope="col">` + `<caption class="sr-only">` on `<table>` |
79+
| Interactive tabs | Full WAI-ARIA Tabs: `role="tablist"`, `role="tab"`, `role="tabpanel"`, roving `tabindex`, keyboard nav |
80+
| Screen-reader-only text | `.sr-only` utility class defined in `custom.css` |
81+
| Focus visibility | `:focus-visible` ring defined globally in `custom.css` |
82+
83+
### Contrast minimums (WCAG AA)
84+
85+
- Normal text (< 18pt): **4.5:1**
86+
- Large text (≥ 18pt bold or ≥ 24pt): **3:1**
87+
- UI components and icons: **3:1**
88+
89+
Avoid `var(--vp-c-text-3)` for any visible text — it is ~2.87:1 against default VitePress backgrounds.
90+
91+
---
92+
93+
## Responsive (mobile-first)
94+
95+
This project maintains **zero horizontal overflow** across 4 tested viewports via Playwright.
96+
97+
### Tested viewports
98+
99+
| Label | Width | Height |
100+
| --------------- | ------ | ------ |
101+
| Galaxy S21 | 360px | 800px |
102+
| iPhone SE | 375px | 667px |
103+
| iPhone 14 | 390px | 844px |
104+
| Tablet portrait | 768px | 1024px |
105+
106+
### Tool
107+
108+
```bash
109+
bun run docs:build
110+
bun run docs:preview -- --port 4173 &
111+
bun run docs:test:responsive # 20 tests (4 viewports × 5 pages) — must all pass
112+
```
113+
114+
Config: `playwright.config.ts`. Spec: `scripts/responsive.pw.ts`. Screenshots on failure: `test-results/screenshots/` (gitignored).
115+
116+
### VitePress quirks at 768px
117+
118+
VitePress hides its hamburger at `≥768px` and shows desktop nav links — which overflow the viewport at exactly 768px on this project's config. The fix in `custom.css`:
119+
120+
```css
121+
@media (max-width: 960px) {
122+
.VPNavBarMenu, .VPNavBarExtra { display: none !important; }
123+
.VPNavBarHamburger { display: flex !important; }
124+
}
125+
@media (min-width: 768px) and (max-width: 960px) {
126+
.VPNavScreen { display: block !important; }
127+
}
128+
```
129+
130+
### Responsive patterns for components
131+
132+
| Problem | Solution |
133+
| ------------------------------------------- | ------------------------------------------------------------ |
134+
| Table columns too wide on mobile | `table-layout: fixed`, abbreviated headers via `.ct-name-short` / `.ct-name-long` toggle |
135+
| Long feature descriptions push rows wider | `display: none` on `.ct-feature-desc` at `≤640px` |
136+
| Terminal/code blocks cause page scroll | `overflow-x: auto` on the scroll container, `max-width: 100%` on the block |
137+
| Long strings in `<pre>` overflow | `pre { max-width: 100%; overflow-x: auto; }` in `custom.css` |
138+
139+
Never use `overflow-x: hidden` on the page root — it silently clips content. Apply it only to specific containers where clipping is intentional.
140+
141+
---
142+
143+
## Validation checklist
144+
145+
Before opening a PR for any docs change:
146+
147+
```bash
148+
bun run docs:build # must complete without errors or dead-link warnings
149+
bun run docs:build:a11y # build for a11y audit
150+
bun run docs:preview -- --port 4173 &
151+
bun run docs:a11y # 0 pa11y violations
152+
bun run docs:test:responsive # 20/20 Playwright tests green
153+
bun run format:check # oxfmt — no formatting diff
154+
```

0 commit comments

Comments
 (0)