chore: add Copilot review instructions and docs AGENTS.md #1321
Conversation
- Add AGENTS.md with guidelines for consistent user documentation - Add copilot-instructions.md for automated code review standards - Include DocFX requirements and deployment constraints Commimt-generated-by: GitHub Copilot <[email protected]> Signed-off-by: Ashley Childress <[email protected]>
|
Moved from #937 |
There was a problem hiding this comment.
Pull request overview
This pull request establishes AI agent guidelines and automated code review standards for the Spec Kit project by introducing two new documentation files. These files define conventions for consistent documentation style, naming patterns, and code review practices.
Key Changes:
- Added centralized documentation guidelines for maintaining consistency across user-facing content
- Established automated code review instructions that reference authoritative convention sources
- Documented DocFX deployment constraints and GitHub Pages hosting requirements
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
.github/copilot-instructions.md |
Establishes code review standards by pointing to AGENTS.md files as authoritative sources for project and documentation conventions |
docs/AGENTS.md |
Defines user documentation guidelines including the "Spec Kit" naming convention, tone requirements, kebab-case file naming, and DocFX deployment details |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## GitHub Pages Deployment Constraints | ||
|
|
||
| - Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`. |
There was a problem hiding this comment.
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.
| - 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 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. |
There was a problem hiding this comment.
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.
| - 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. |
|
|
||
| ## GitHub Pages Deployment Constraints | ||
|
|
||
| - Documentation is hosted at `https://github.github.io/spec-kit/` via GitHub Pages deployment defined by `.github/docs.yml`. |
There was a problem hiding this comment.
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.
| - 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`. |
|
As an aside, this The instructions defined currently make for a fantastic developer guide doc—so fantastic that we can easily use that to build out an automated PR creation trigger where users can submit new agent support requests with an issue template and coding agent can handle literally everything else automatically—but it's not doing the IDE integration version any favors whatsoever. I have plans to work on it as soon as I can, but—just so we're on the same page—any code contributions I would make will be waiting on these instruction fixes as a prerequisite to starting work, because I cannot function with a misdirected agent acting like an unhinged toddler on Halloween! |
1 participant
Commimt-generated-by: GitHub Copilot [email protected]
This pull request introduces new AI documentation guidelines and instructions to ensure consistency and clarity in both code reviews and user documentation for the project. The changes focus on establishing authoritative sources for conventions and providing detailed standards for documentation contributions.
Documentation standards and conventions:
Added a new
.github/copilot-instructions.mdfile instructing code reviewers (including Copilot) to referenceAGENTS.mdas the authoritative source for project conventions, and to consult a separatedocs/AGENTS.mdfor documentation-specific requirements when reviewing files in thedocs/directory.Introduced a new
docs/AGENTS.mdfile outlining guidelines for consistent user documentation, including naming conventions ("Spec Kit"), tone, syntax, example formatting, and kebab-case file naming for documentation files.Documentation deployment process:
docs/AGENTS.mdthat documentation is deployed via GitHub Pages using DocFX, with deployment constraints and requirements for alignment with standard flows to avoid deployment failures.