MIME TODO Specification — Agent Instructions

This directory contains the MIME TODO specification, which defines the canonical format for repository-root TODO issue tracker files.

Consuming the Specification

The agent-consumable specification is located at:

build/markdown/

Agents MUST read the specification from build/markdown/ for programmatic access. Do NOT parse the RST source under src/ directly.

If build/markdown/ is not available locally, the specification (including this AGENTS.md) can be retrieved from specs.code.tiararodney.com:

Specification: https://specs.code.tiararodney.com/mime-todo/markdown/README.md
Agent instructions: https://specs.code.tiararodney.com/mime-todo/markdown/AGENTS.md
Index: https://specs.code.tiararodney.com/mime-todo/markdown/

What This Spec Defines

MIME envelope structure and preprocessing rules
Issue part format (application/issue): field ordering, field semantics, valid values for Type, Status, Priority, and Relationships
Sprint part format (application/sprints): entry grammar, date ranges
Module part format (application/modules): module names and paths
Bugzilla tracker part format (application/bugzilla): product/component mappings, sync model, comment format
Description block and body grammar (80-column wrap, column 14 indent)
Issue immutability rules
Status transition state machine and commit conventions
Branch naming and lifecycle rules tied to issue Type and Status
Sprint membership logic
Preprocessor and parser requirements
Error handling requirements
CLI reference for spec-compliant issue management

Interacting with the TODO File

Agents MUST use the @byteb4rb1e/mime-todo CLI for all interactions with the TODO file. Do NOT edit the file directly or construct transition commits manually.

Issue Lifecycle

# Create an issue (must be on develop)
mime-todo create --type feature --title "Title" --plan "Description"

# Start work (must be on develop)
mime-todo start <id> --acceptance-criteria "What must be true for this to be done"
# Then create the branch: git checkout -b <type>/<id>

# Complete work (must be on <type>/<id>)
mime-todo done <id> --acceptance "What was delivered against the criteria"

# Hold or cancel
mime-todo hold <id> --reason "Why"
mime-todo cancel <id> --reason "Why"

Querying

mime-todo list                     # list all issues
mime-todo show <id>                # show issue details
mime-todo sprints                  # list sprints
mime-todo issues-in-sprint <name>  # issues in a sprint

Bugzilla Integration

mime-todo init                     # check products/components exist
mime-todo push                     # push commits to Bugzilla
mime-todo push --dry-run           # preview

What Agents MUST NOT Do

Edit the TODO file directly.
Construct todo(<ID>): <status> commits manually.
Modify issue fields other than Status (and only via the CLI).
Push to Bugzilla outside of mime-todo push.
Modify the specification files.

Rules for Agents

Do NOT modify the specification files.
Do NOT modify the RST source under src/.
Changes to this specification MUST be made upstream in the vendor repository.

Maintaining This Repository

If you are explicitly invoked to maintain this specification repository (building, publishing, or managing URLs), see CONTRIBUTING.md for instructions.

3.4 KiB Raw Blame History