Add agents.md documentation for AI coding assistants
Metadata
Current evaluation
Adds agents.md with AI coding assistant docs for dev workflow. Stuck in changes_requested with 59 unresolved comments for ~9 months; project since adopted .github/instructions/ and Copilot Collections.
Suggested action: close stale
Reason: Review status is changes_requested with 59 unresolved comments and no activity for 269 days. The project has since adopted a different agent-documentation approach via .github/instructions/ (9 files) and Copilot Collections config (#1139, #1148, #1161), and prettier was updated to ignore agent Markdown instructions (#1157), indicating the original agents.md approach was superseded.
Impact:
15
Quick Win:
12.75
Staleness:
78
Complexity:
15
Confidence:
72
Issue body
- [x] Create agents.md file in root directory
- [x] Focus on development workflow as requested
- [x] Reference existing documentation (README.md, CONTRIBUTING.md, pyproject.toml)
- [x] Include setup instructions and make targets
- [x] Document testing patterns and structure
- [x] Include code quality standards (ruff, mypy, pyright)
- [x] Add commit message conventions with scopes
- [x] Include project structure overview
- [x] Document CI/CD workflows
- [x] Add tips for agents working with the codebase
- [x] Document breaking change patterns to avoid
- [x] Verify formatting with prettier ✓
- [x] Verify spelling with codespell ✓
- [x] Test all instructions for clarity and accuracy
- [x] Use official spread installation method
- [x] Streamline CI section and use correct spread backend
## Latest Update: Refinements
Made three targeted improvements based on review feedback:
**CI Section Simplified**
- Removed detailed list of workflow files (agents can explore .github/workflows/)
- Changed to concise statement: "When you push changes, all GitHub Actions workflows should pass"
- Focuses on the outcome rather than implementation details
**Spread Backend Corrected**
- Changed from LXD to multipass backend (LXD is disabled in spread.yaml)
- Updated installation: `sudo snap install multipass`
- Updated command: `spread multipass:` instead of `spread lxd:`
- Simplified instructions (no init step needed for multipass)
**Commit Scope Example Improved**
- Changed from `feat(TestService)` to `feat(models)`
- Better represents actual code structure (models/ directory vs TestService)
- More realistic example for the codebase
## Previous Updates
**Official Spread Installation**
- Changed to `go install github.com/canonical/spread/cmd/spread@latest` (official method)
**Instruction Testing and Clarity**
- Added Prerequisites section with Python 3.10+, Git, and uv
- Clarified `uv run pytest` requires prior `make setup`
- Enhanced spread test documentation
- More specific pyproject.toml sections
- Added guidance on commit scopes
**Commit Message Format**
- Added scope requirement with examples
**Dependencies**
- Changed to `uv add` commands
**Pydantic Models**
- Enhanced validation guidelines
**Breaking Changes**
- Added comprehensive breaking change patterns section
<!-- START COPILOT CODING AGENT SUFFIX -->
<details>
<summary>Original prompt</summary>
> I want to create an agents.md file for this repository so that agents can correctly work on this repo.
</details>
<!-- START COPILOT CODING AGENT TIPS -->
---
💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.8-27b |
Impact:
15
Quick Win:
12.75
Staleness:
78
Complexity:
15
Confidence:
72
|
close stale | Adds agents.md with AI coding assistant docs for dev workflow. Stuck in changes_requested with 59 unresolved comments for ~9 months; project since adopted .github/instructions/ and Copilot Collections. | |
| qwen/qwen3.8-27b |
Impact:
15
Quick Win:
12.0
Staleness:
85
Complexity:
20
Confidence:
82
|
close stale | Adds a 341-line agents.md file for AI coding assistant guidance. Stale ~9 months with 59 unresolved review comments; project adopted .github/instructions/ (Copilot Collections) instead, making this approach obsolete. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
88
Complexity:
10
Confidence:
72
|
close stale | Adds agents.md documentation for AI coding assistants, detailing workflows, testing, and CI/CD. Status is changes requested with 59 unresolved comments and over 7 months of inactivity. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
80
Complexity:
15
Confidence:
85
|
close stale | Adds an agents.md file to guide AI coding assistants through the repository's development workflow, testing, and CI/CD setup. Currently inactive for over 6 months with no maintainer feedback. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
75
Complexity:
15
Confidence:
70
|
needs review | Adds agents.md to guide AI coding assistants through project setup, workflows, testing, and conventions. Incorporates review feedback on CI and spread backend configuration. Inactive for over a month, awaiting review or merge. |
Update history
No update history recorded yet.
Related work
-
Related To:
craft-application#1139
(confidence 65%)
Copilot Collections config added after this PR went stale; represents the project's evolved approach to agent documentation, partially superseding the need for a root-level agents.md.
Related issues
No related issues found above the similarity threshold.