Add agents.md documentation for AI coding assistants
Metadata
Current evaluation
Adds a 341-line root agents.md for AI coding assistants; changes requested with 59 unresolved comments, no CI results, inactive ~300 days.
Suggested action: close superseded
Reason: Merged PR canonical/craft-application#1209 adds a 99-line AGENTS.md and its summary explicitly states it 'Supersedes stale draft #954.' This PR is a stale draft with 59 unresolved review comments and no CI results.
Evaluated by: mr-cal-bot
Impact:
20
Quick Win:
2
Complexity:
25
Confidence:
95
Actionability:
10
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 |
|---|---|---|---|---|
| ~deepseek/deepseek-pro-latest |
Impact:
20
Quick Win:
2
Complexity:
25
Confidence:
95
Actionability:
10
|
close superseded | Adds a 341-line root agents.md for AI coding assistants; changes requested with 59 unresolved comments, no CI results, inactive ~300 days. | |
| stealth/space-bunny-alpha |
Impact:
25
Quick Win:
3
Complexity:
40
Confidence:
91
Actionability:
18
|
keep open | Adds a 341-line root AGENTS.md for AI assistants, but changes are requested with 59 unresolved comments, no CI results, and no activity for about 300 days. | |
| stealth/space-bunny-alpha |
Impact:
18
Quick Win:
3
Complexity:
16
Confidence:
83
Actionability:
22
|
keep open | Adds a 341-line root agents.md covering agent development workflows, quality tools, tests, commits, CI, and spreading. Changes are requested, with no recent activity or reported CI checks. | |
| qwen/qwen3.6-35b-a3b |
Impact:
15
Quick Win:
1
Complexity:
10
Confidence:
85
Actionability:
5
|
close stale | Adds agents.md documentation for AI coding assistants; open with changes_requested and 59 unresolved review comments, inactive for 288 days | |
| qwen/qwen3.8-27b |
Impact:
15
Quick Win:
13
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
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. |
Update history
No update history recorded yet.
Related work
-
Superseded By:
canonical/craft-application#1209
(confidence 95%)
Merged PR adding AGENTS.md, explicitly described as superseding stale draft #954.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1209 docs: add AGENTS.md for AI coding assistants | craft-application | merged | Merged PR adding a 99-line AGENTS.md for AI coding assistants, derived from Starbase's AGENTS.lib.md template and customized for craft-application. Supersedes stale draft #954. | |
| #276 docs: add AGENTS.md | craft-platforms | closed | Merged in #276 via commit 3a60b54, adding a 94-line craft-platforms-specific AGENTS.md (project overview, craft app/library references, dev workflow) for AI coding agents, split out of the Starbase merge #270. |