diff --git a/docs/project-conventions.md b/docs/project-conventions.md index d7056337..e55c2de3 100644 --- a/docs/project-conventions.md +++ b/docs/project-conventions.md @@ -8,7 +8,13 @@ Rules extracted from commit history that are specific to this project and not al - Describe intent/behavior, not implementation details - Reverts use `Revert "Original message"` convention - NEVER ADD a "Co-Authored-By" reference in the message body -- If you're working on a GitHub issue, make sure to include the issue ID in the commit message body. Specifies if the commit closes the issue. +- **When the work maps to a Backlog.md task, prefix the commit subject with the task identifier**, e.g. `ML-3: fix scrobble rule ordering`. The prefix counts toward the 60-character limit. + +## Workflow + +- **Backlog.md is the source of truth for task management.** The project has the Backlog.md MCP server configured; use it (via the MCP tools) for creating, viewing, and updating tasks. Do not invent a parallel tracking system. +- **All work that maps to a Backlog.md task must reference the task identifier in the commit subject** (see Commit Messages above). One commit can reference one task; if a single change spans multiple tasks, that is a signal to split the commit. +- **GitHub issues are legacy and read-only for the agent.** Never create, comment on, close, or reopen GitHub issues — only the user does that. When asked about "the issue tracker" or "open issues", reach for Backlog.md, not `gh issue`. ## Architecture