Skip to content

Commit 999792a

Browse files
johnml1135johnml1135
committed
Spec kit and AI docs, tasks and instructions
Refine AI onboarding and workflows: * Update copilot-instructions.md with agentic workflow links and clearer pointers to src-catalog and per-folder guidance (COPILOT.md). * Tune native and installer instructions for mixed C++/CLI, WiX, and build nuances (interop, versioning, upgrade behavior, build gotchas). Spec kit improvements: * Refresh spec.md and plan.md to align with the feature-spec and bugfix agent workflows and FieldWorks conventions. Inner-loop productivity: * Extend tasks.json with quick checks for whitespace and commit message linting to mirror CI and shorten feedback loops. CI hardening for docs and future agent flows: * Add lint-docs.yml to verify COPILOT.md presence per Src/<Folder> and ensure folders are referenced in .github/src-catalog.md. * Add agent-analysis-stub.yml (disabled-by-default) to document how we will run prompts/test-failure analysis in CI later. Locally run CI checks in Powershell * Refactor scripts and add whitespace fixing algorithm
1 parent aa1658c commit 999792a

File tree

121 files changed

+7023
-103
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

121 files changed

+7023
-103
lines changed

‎.github/chatmodes/installer-engineer.chatmode.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
description: 'Installer engineer for WiX (packaging, upgrades, validation)'
3+
tools: ['search', 'editFiles', 'runTasks']
4+
---
5+
You are an installer (WiX) specialist for FieldWorks. You build and validate changes only when installer logic or packaging is affected.
6+
7+
## Domain scope
8+
- WiX .wxs/.wixproj, packaging inputs under DistFiles/, installer targets under Build/
9+
10+
## Must follow
11+
- Read `.github/instructions/installer.instructions.md`
12+
- Follow versioning/upgrade code policies; validate locally when touched
13+
14+
## Boundaries
15+
- CANNOT modify native or managed app code unless explicitly requested
16+
17+
## Handy links
18+
- Installer guidance: `.github/instructions/installer.instructions.md`
19+
- CI workflows (patch/base): `.github/workflows/`

‎.github/chatmodes/managed-engineer.chatmode.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
description: 'Managed engineer for C# and .NET (UI, services, tests)'
3+
tools: ['search', 'editFiles', 'runTasks', 'problems', 'testFailure']
4+
---
5+
You are a managed (C# and .NET) development specialist for FieldWorks. You work primarily in `Src/` managed projects and follow repository conventions.
6+
7+
## Domain scope
8+
- UI (WinForms/XAML) and services in managed code
9+
- Unit/integration tests for managed components
10+
- Resource and localization workflows (.resx, Crowdin)
11+
12+
## Must follow
13+
- Read `.github/instructions/managed.instructions.md`
14+
- Respect `.editorconfig` and CI checks in `.github/workflows/`
15+
16+
## Boundaries
17+
- CANNOT modify native C++/C++/CLI code unless explicitly requested
18+
- CANNOT modify installer (WiX) unless explicitly requested
19+
20+
## Handy links
21+
- Src catalog: `.github/src-catalog.md`
22+
- Managed guidance: `.github/instructions/managed.instructions.md`
23+
- Testing guidance: `.github/instructions/testing.instructions.md`

‎.github/chatmodes/native-engineer.chatmode.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
description: 'Native engineer for C++ and C++/CLI (interop, kernel, performance)'
3+
tools: ['search', 'editFiles', 'runTasks', 'problems', 'testFailure']
4+
---
5+
You are a native (C++ and C++/CLI) development specialist for FieldWorks. You focus on interop boundaries, performance, and correctness.
6+
7+
## Domain scope
8+
- C++/CLI bridge layers, core native libraries, interop types
9+
- Performance-sensitive code paths, resource management
10+
11+
## Must follow
12+
- Read `.github/instructions/native.instructions.md`
13+
- Coordinate managed/native changes across boundaries
14+
15+
## Boundaries
16+
- CANNOT modify WiX installer artifacts unless explicitly requested
17+
- Avoid modifying managed UI unless the task requires boundary changes
18+
19+
## Handy links
20+
- Src catalog: `.github/src-catalog.md`
21+
- Native guidance: `.github/instructions/native.instructions.md`
22+
- Build guidance: `.github/instructions/build.instructions.md`

‎.github/chatmodes/technical-writer.chatmode.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
description: 'Technical writer for docs (developer guidance, component docs)'
3+
tools: ['search', 'editFiles']
4+
---
5+
You write and maintain developer documentation and component guides with accuracy and minimal code changes.
6+
7+
## Domain scope
8+
- `.github/*.md`, `Src/<Folder>/COPILOT.md`, `.github/src-catalog.md`
9+
10+
## Must follow
11+
- Keep docs concise and aligned with repository behavior
12+
- Update COPILOT.md when implementation diverges from docs
13+
14+
## Boundaries
15+
- CANNOT change code behavior; limit edits to docs unless explicitly requested
16+
17+
## Handy links
18+
- Onboarding: `.github/copilot-instructions.md`
19+
- Src catalog: `.github/src-catalog.md`

‎.github/commit-guidelines.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Commit message guidelines (CI-enforced)
2+
3+
These align with the gitlint rules run in CI.
4+
5+
## Subject (first line)
6+
7+
- Max 72 characters.
8+
- Use imperative mood when reasonable (e.g., "Fix crash on startup").
9+
- No trailing punctuation (e.g., don't end with a period).
10+
- No tabs, no leading/trailing whitespace.
11+
12+
## Body (optional)
13+
14+
- Blank line after the subject.
15+
- Wrap lines at 80 characters.
16+
- Explain what and why over how; link issues like "Fixes #1234" when applicable.
17+
- No hard tabs, no trailing whitespace.
18+
19+
## Helpful commands (Windows PowerShell)
20+
21+
```powershell
22+
python -m pip install --upgrade gitlint
23+
git fetch origin
24+
gitlint --ignore body-is-missing --commits origin/<base>..
25+
```
26+
27+
Replace `<base>` with your target branch (e.g., `release/9.3`, `develop`).
28+
29+
## Common examples
30+
31+
- Good: "Refactor XCore event dispatch to avoid deadlock"
32+
- Good: "Fix: avoid trailing whitespace in generated XSLT layouts"
33+
- Avoid: "Fixes stuff." (too vague, trailing period)
34+
- Avoid: "WIP: temp" (unclear intent, typically avoided in shared history)

‎.github/context/codebase.context.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# High-signal context for FieldWorks agents
2+
3+
Use these entry points to load context efficiently without scanning the entire repo.
4+
5+
- Onboarding: `.github/copilot-instructions.md`
6+
- Src catalog (overview of major folders): `.github/src-catalog.md`
7+
- Component guides: `Src/<Folder>/COPILOT.md` (and subfolder COPILOT.md where present)
8+
- Build system: `Build/FieldWorks.targets`, `Build/FieldWorks.proj`, `agent-build-fw.sh`, `FW.sln`
9+
- Installer: `FLExInstaller/`
10+
- Test data: `TestLangProj/`
11+
- Localization: `crowdin.json`, `DistFiles/CommonLocalizations/`
12+
13+
Tips
14+
- Prefer top-level scripts or FW.sln over ad-hoc project builds
15+
- Respect CI checks (commit messages, whitespace) before pushing

‎.github/copilot-framework-tasks.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# AI agent framework tasks
2+
3+
This checklist tracks repository updates that improve AI workflows using agentic primitives, context engineering, and spec-first development.
4+
5+
## Option 1 — Docs-first primitives (low effort, high ROI)
6+
7+
- [x] Create domain instructions files:
8+
- [x] .github/instructions/managed.instructions.md
9+
- [x] .github/instructions/native.instructions.md
10+
- [x] .github/instructions/installer.instructions.md
11+
- [x] .github/instructions/testing.instructions.md
12+
- [x] .github/instructions/build.instructions.md
13+
- [x] Add role-scoped chat modes with tool boundaries:
14+
- [x] .github/chatmodes/managed-engineer.chatmode.md
15+
- [x] .github/chatmodes/native-engineer.chatmode.md
16+
- [x] .github/chatmodes/installer-engineer.chatmode.md
17+
- [x] .github/chatmodes/technical-writer.chatmode.md
18+
- [x] Add context and memory anchors:
19+
- [x] .github/context/codebase.context.md
20+
- [x] .github/memory.md
21+
- [x] Reference these entry points from onboarding:
22+
- [x] Link instructions, chat modes, and context in .github/copilot-instructions.md
23+
24+
## Option 2 — Agentic workflows + spec-first flow (moderate effort)
25+
26+
- [ ] Prompts in .github/prompts/:
27+
- [ ] feature-spec.prompt.md (spec → plan → implement with gates; uses spec-kit)
28+
- [ ] bugfix.prompt.md (triage → RCA → fix plan → patch + tests)
29+
- [ ] test-failure-debug.prompt.md (parse NUnit output → targeted fixes)
30+
- [ ] Specification templates:
31+
- [ ] .github/spec-templates/spec.md and plan.md (or link to spec-kit)
32+
- [ ] .github/recipes/*.md playbooks for common tasks
33+
- [ ] Fast inner-loop tasks:
34+
- [ ] Extend .vscode/tasks.json: quick builds (managed/native), smoke tests, whitespace/gitlint
35+
36+
## Option 3 — Outer-loop automation + MCP integration (higher effort)
37+
38+
- [ ] Copilot CLI/APM scaffolding:
39+
- [ ] apm.yml: map scripts to prompts and declare MCP dependencies
40+
- [ ] Document local usage: `apm install`, `apm run copilot-feature-spec --param specFile=...`
41+
- [ ] GH Action to run chosen prompt on PR, post summary/comments
42+
- [ ] MCP servers & boundaries:
43+
- [ ] Add GitHub MCP server and Filesystem MCP (pilot set); restrict by chat mode
44+
- [ ] Capture list and policies in `.github/context/mcp.servers.md`
45+
- [ ] CI governance:
46+
- [ ] lint-docs job to verify COPILOT.md presence/links and src-catalog consistency
47+
- [ ] prompt validation job to parse `.prompt.md` frontmatter/structure
48+
- [ ] Security & secrets:
49+
- [ ] Use least-privilege tokens (e.g., `secrets.COPILOT_CLI_PAT`)
50+
- [ ] Add a security review checklist for enabling new tools/servers
51+
- [ ] Rollout strategy:
52+
- [ ] Pilot a no-write prompt (`test-failure-debug.prompt.md`) on PRs
53+
- [ ] Iterate then enable selective write-capable workflows
54+
55+
See: `.github/option3-plan.md` for details.
56+
57+
## Notes
58+
- Keep instructions concise and domain-scoped (use `applyTo` when appropriate).
59+
- Use consistent headings across COPILOT.md: Responsibilities, Entry points, Dependencies, Tests, Pitfalls, Extension points.
60+
- Prefer fast inner-loop build/test paths for agents; reserve installer builds for when necessary.
61+
62+
63+
## small but high-impact extras
64+
- [ ] Add mermaid diagrams in .github/docs/architecture.md showing component relationships (Cellar/Common/XCore/xWorks), so agents can parse text-based diagrams.
65+
- [ ] Create tests.index.md that maps each major component to its test assemblies and common scenarios (fast lookup for agents).
66+
- [ ] Enrich each COPILOT.md with section headers that match your instructions architecture: Responsibilities, Entry points, Dependencies, Tests, Pitfalls, Extension points. Agents recognize consistent structures quickly.
67+
- [ ] Link your CI checks in the instructions: we already added commit/whitespace/build rules and a PR template—keep those links at the top of copilot-instructions.md.

0 commit comments

Comments
 (0)