chore: regenerate markdown

build/markdown/AGENTS.md

@@ -0,0 +1,103 @@
+# 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:
+
+```default
+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
+
+```sh
+# 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
+
+```sh
+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
+
+```sh
+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.