103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
# 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)
|
|
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.
|