Documentation and workflow design update#2
Open
martyn-fewtrell wants to merge 15 commits into
Open
Conversation
Introduced a full suite of Copilot agent and prompt files, markdown templates, and instruction files to standardize requirements, analysis, planning, execution, testing, refactoring, and documentation workflows. Enforced repository-wide and scoped rules for C#, .NET, configuration, authentication, testing, Playwright, documentation, and folder structure. Provided templates for all key documentation artifacts and a help file describing the end-to-end workflow. Enables iterative, standards-driven, and reviewable software delivery and documentation.
Introduce a wiki-first approach making `docs/wiki/` the project source of truth. Add `create-wiki.agent.md` and `review-instruction-coverage.agent.md` agents for wiki creation and instruction gap analysis. Update all major agents, prompts, instructions, and templates to require wiki review before planning or updates and wiki refresh after changes. Add comprehensive wiki documentation (asset model, workflow, usage). Revise README and help files to reflect the new workflow and guidance.
Updated workflow documentation to clarify that for new projects, wiki pages are created or refreshed during delivery rather than as a separate initial stage. For existing projects with implementation history but no wiki, the wiki baseline is still created first. Made instruction coverage review (`review-instruction-coverage.agent.md`) an explicit prerequisite before adding new scoped instructions. Revised workflow sequence and usage patterns to emphasize in-execution wiki updates and instruction coverage review, removing the requirement to always create the wiki first for new projects.
Refined `create-business-requirements.agent.md` to require saving the final markdown to `./docs/business-requirements.md` and clarified that only the saved file is the deliverable. Revised response style to always output the updated draft and treat the markdown file as the source of truth. Reordered steps in `workflow-overview.md` to create business requirements and systems analysis before instruction coverage and work package planning, ensuring foundational documents are established first.
Added `.github/instructions/good.instructions.md` with aspirational guidance for resilient, secure, cloud-first, operable, maintainable, and well-documented solutions. Outlines MUST, SHOULD, and MUST NOT rules for solution assets and delivery. Updated instructions-overview to reference the new file and its scope.
There was a problem hiding this comment.
Pull request overview
This PR introduces a comprehensive, documentation-led GitHub Copilot workflow for Microsoft project work. It establishes a wiki-first source of truth (docs/wiki/), a layered asset model (instructions, prompts, agents, templates, skills), and a staged delivery workflow covering business intent → systems analysis → work-package definition → delivery → test/refactoring review loops. The PR also updates the README and contributor guidance to reflect the new model.
Changes:
- Adds a full wiki under
docs/wiki/(index, workflow, prompts, agents, instructions, templates, skills overviews) - Adds repo-wide and scoped Copilot instruction files, three prompt files, fourteen custom agents, and twelve templates
- Updates the README to point at the new wiki and describe the suggested usage model
Reviewed changes
Copilot reviewed 50 out of 50 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds wiki-first workflow framing, Start Here section, and refreshed asset list |
| docs/wiki/*.md | New wiki landing page and overview pages for workflow, prompts, agents, instructions, templates, skills |
| .github/copilot-instructions.md | New repo-wide Copilot instructions |
| .github/instructions/*.instructions.md | New scoped instruction files (auth, configuration, csharp, docs, dotnet-stack, folders, good, playwright, prompts, refactoring, tests, work-packages) |
| .github/prompts/*.prompt.md | New prompt files for creating agents, prompts, and instructions |
| .github/agents/*.agent.md | New custom agents for foundation, work-package definition, execution, and review/mitigation workflows |
| .github/templates/*.md | New templates for business requirements, systems analysis, requirements, technical spec, delivery plan, agents/prompts/instructions, and test/refactoring review+mitigation reports |
Comments suppressed due to low confidence (1)
.github/templates/agent-template.md:4
- The
modelvalue'GPT-5.4'is inconsistent with the rest of the repository, which uses lowercase'gpt-5.4'(see all agent files under.github/agents/and the prompt files). Please use lowercase for consistency.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Renamed agent-template.md to agent.template.md and updated all references for consistency. Added the new agent.template.md file, updated model versions to GPT-5.4, corrected the templates-overview.md table, and made minor wording and formatting improvements for clarity in agent and prompt workflows.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Update instructions to require lowercase model identifiers (e.g., gpt-5.4) in agent and prompt files. Reorganize workflow documentation for clarity, ensuring instruction coverage review follows business and system understanding. Emphasize treating docs/wiki/ as the workflow source of truth and require contributors to review and update relevant wiki pages before and after planning or project changes.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
….GitHubCopilot.ToolKit into feature/add-base-files
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| @@ -0,0 +1,86 @@ | |||
| --- | |||
Comment on lines
+1
to
+3
| --- | ||
| description: 'Standardize the repository test approach (unit-first with xUnit, plus integration, end-to-end, and requirement-driven functional tests) so test projects are consistent, resilient, and CI-friendly.' | ||
| applyTo: 'test/**/*.cs, test/**/*.csproj' |
| @@ -0,0 +1,72 @@ | |||
| --- | |||
Comment on lines
+1
to
+3
| --- | ||
| description: 'Provide optional baseline guidance for repositories that use the Microsoft .NET application stack.' | ||
| applyTo: 'src/**/*.cs, src/**/*.csproj, src/**/*.sln, src/**/*.razor, src/**/*.json, infra/**/*' |
Comment on lines
+1
to
+3
| --- | ||
| description: 'Enforce safe, behavior-preserving refactoring practices so code becomes easier to maintain without introducing regressions.' | ||
| applyTo: 'src/**/*.cs, src/**/*.razor, src/**/*.razor.cs, test/**/*.cs' |
Comment on lines
+2
to
+6
| description: 'Describe the agent purpose in one actionable sentence.' | ||
| name: 'Agent Display Name' | ||
| model: 'gpt-5.4' | ||
| tools: ['search/codebase', 'read/readFile'] | ||
| # argument-hint: 'Describe the task, scope, and constraints.' |
|
|
||
| - Uses correct markdown front matter | ||
| - Scopes rules via `applyTo` | ||
| - Presents actionable guidance in the same style as existing files under `instructions/` |
Comment on lines
+19
to
+24
| 1. create the wiki baseline only when onboarding an existing project with implementation history but no wiki baseline | ||
| 2. review relevant wiki pages before every later planning or project-update task once those pages exist | ||
| 3. establish business intent | ||
| 4. establish system understanding | ||
| 5. review instruction coverage by using `review-instruction-coverage.agent.md` and close any approved coverage gaps with new scoped instructions | ||
| 6. define one work package |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Classification
Documentation and workflow design update.
PR Summary
This pull request introduces a comprehensive, documentation-led workflow for using GitHub Copilot, centered on a wiki-first approach and a layered asset model for planning, delivery, and review.
workflow-overview.mdandtemplates-overview.mdwiki pages detailing the recommended workflow and template usage.