Skip to content

chore: add Copilot review instructions and docs AGENTS.md #1321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anchildress1 wants to merge 1 commit into
base: main
Choose a base branch
from
+20 −0
Open

chore: add Copilot review instructions and docs AGENTS.md #1321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Copilot instructions for automated code reviews 🌱

- Reference [AGENTS.md](../AGENTS.md) as the authoritative source for project conventions when reviewing any files changed in this repo.
- For files in `docs/`, additionally consult the [./docs AGENTS.md](../docs/AGENTS.md) for additional requirements designed to promote consistency in independent documentation contributions.
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The path reference ./docs AGENTS.md is syntactically incorrect within the markdown link. The link text suggests it should point to ../docs/AGENTS.md (which is correct in the URL portion), but the display text "./docs AGENTS.md" is misleading. Consider changing this to either "docs/AGENTS.md" or "documentation-specific AGENTS.md" for clarity.

Suggested change
- For files in `docs/`, additionally consult the [./docs AGENTS.md](../docs/AGENTS.md) for additional requirements designed to promote consistency in independent documentation contributions.
- For files in `docs/`, additionally consult the [docs/AGENTS.md](../docs/AGENTS.md) for additional requirements designed to promote consistency in independent documentation contributions.

Copilot uses AI. Check for mistakes.
16 changes: 16 additions & 0 deletions docs/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# AGENTS.md for Spec Kit documentation

## Guidelines for consistent user documentation

- The correct syntax for this project is "Spec Kit" (two words, capital S and K). Never use any other variation outside of code snippets.
- Use active voice and present tense where possible.
- Write for an audience familiar with AI and programming concepts, but new to Spec Kit.
- Ensure an informal narrative, teaching voice: give a one-line "why" plus a one-line "how" and a minimal, copy‑pastable example/command when helpful.
- User documentation files are expected to use kebab-case for the `.md` extension, except for special files like `README.md`.
- Examples should be copy-pastable in fenced code blocks and accurate; if unsure, prefer not to change examples.

## GitHub Pages Deployment Constraints

- Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`.
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The URL format appears incorrect. GitHub Pages URLs typically follow the pattern https://[org-or-user].github.io/[repo-name]/. The current URL shows github.github.io which would only be correct if the organization is literally named "github". Please verify and update this to reflect the actual GitHub Pages URL for this repository.

Suggested change
- Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`.
- Documentation is hosted at `https://[org-or-user].github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The path to the GitHub Pages deployment workflow is incorrect. The file is located at .github/workflows/docs.yml, not .github/docs.yml. Please update the reference to the correct path.

Suggested change
- Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`.
- Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/workflows/docs.yml`.

Copilot uses AI. Check for mistakes.
- The static site is generated with DocFX. Use library ID `/dotnet/docfx` if referencing `context7` MCP.
- All documentation changes must be aligned with these standard flows, else deployments will fail.