# 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:

```
dist/markdown/
```

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

If `dist/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

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

# Start work (must be on develop)
todo start <id> --plan "Planned approach"
# Then create the branch: git checkout -b <type>/<id>

# Complete work (must be on <type>/<id>)
todo done <id> --summary "What was delivered"

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

### Querying

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

### Bugzilla Integration

```sh
todo init                     # check products/components exist
todo push                     # push commits to Bugzilla
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 `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.