tiararodney/mime-todo-spec
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update

Browse source
This commit is contained in:
Tiara Rodney 2026-03-15 03:39:06 +01:00
parent 3f0152bd2b
commit 0fbbe84bb3
No known key found for this signature in database
GPG key ID: 5CD8EC1D46106723
7 changed files with 940 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

57
dist/markdown/AGENTS.md vendored
View file

@ -28,11 +28,66 @@ If `dist/markdown/` is not available locally, the specification
- 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
- Description block and body grammar
- 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

432
dist/markdown/README.md vendored
View file

@ -20,10 +20,14 @@ Content-Type: <mime-type>
Valid part types are:
* `application/sprints` — defines sprint metadata
* `application/modules` — defines the repository module structure
* `application/bugzilla` — defines Bugzilla product/component mappings
* `application/issue` — defines a single issue
Parts may appear in any order in the raw file. The preprocessor will reorder
them so that the `application/sprints` part appears first.
them so that `application/sprints` appears first, followed by
`application/modules`, then `application/bugzilla`, then all
`application/issue` parts in original order.
## MIME Envelope (Added by Preprocessor)
@ -99,6 +103,155 @@ Required keys:
The `Range` defines a closed interval `[start, end]`.
## Part: `application/modules`
This part defines the repository’s logical module structure. Each module maps
a name to an optional repository-relative path.
At most one `application/modules` part MAY appear. Multiple
`application/modules` parts MUST be rejected.
The body MUST begin with:
```default
Modules:
```
followed by one or more module entries.
### Module Entry Forms
Compact form:
```default
- Name: Specification
Path: src
```
Expanded form:
```default
-
Name: Specification
Path: src
```
A module without a path (logical grouping):
```default
- Name: Documentation
```
### Module Entry Grammar
A module entry begins at a line matching:
```default
^\s*-\s*(Name:.*)?$
```
Key–value lines inside an entry match:
```default
^\s+[A-Za-z][A-Za-z0-9]*:\s*(.*)$
```
Required keys:
* `Name: <string>` — unique module identifier.
Optional keys:
* `Path: <repo-relative-path>` — path relative to repository root.
If omitted, the module is a logical grouping without a fixed location.
## Part: `application/bugzilla`
This part defines a unidirectional mapping from repository modules to
Bugzilla products and components. The `TODO` file is the source of truth;
Bugzilla is a downstream mirror.
At most one `application/bugzilla` part MAY appear. Multiple
`application/bugzilla` parts MUST be rejected.
An `application/bugzilla` part MUST NOT appear unless an
`application/modules` part is also present.
### Required Fields
```default
URL: <bugzilla-rest-api-url>
Mappings:
- Module: <module-name>
Product: <bugzilla-product>
Component: <bugzilla-component>
```
* **URL**: the base URL to the Bugzilla REST API.
* **Mappings**: one or more entries mapping a module name to a Bugzilla
product and component. Every `Module` value MUST reference a module
defined in the `application/modules` part.
Product and component names containing spaces or special characters are
permitted; tooling MUST URL-encode them when constructing API requests.
### Mapping Entry Grammar
A mapping entry begins at a line matching:
```default
^\s*-\s*(Module:.*)?$
```
Required keys:
* `Module: <string>` — references a module name.
* `Product: <string>` — Bugzilla product name.
* `Component: <string>` — Bugzilla component name.
### Sync Model
Synchronization is unidirectional: `TODO` → Bugzilla. The `TODO` file is
the canonical source of truth.
When a Bugzilla bug is created for a `TODO` issue, the bug’s `url` field
MUST be set to a resolvable URL pointing to the `TODO` file on the
integration branch. The URL format is host-dependent:
* Bitbucket: `<repo-url>/src/<branch>/TODO#<issue-id>`
* GitHub: `<repo-url>/blob/<branch>/TODO#<issue-id>`
* GitLab: `<repo-url>/-/blob/<branch>/TODO#<issue-id>`
The branch in the URL MUST be the integration branch (`develop`),
regardless of which branch the push is initiated from.
Transition commit messages are pushed as Bugzilla comments. Each comment is
tagged with `git-<short-hash>` (first 7 characters of the commit hash) to
prevent duplicate pushes. A comment tag is applied only after the comment
and any associated status update have both succeeded.
Work commits from issue branches are also pushed as Bugzilla comments,
forming a threaded work log. Work comments:
* MUST NOT be pushed unless the issue status is `in-progress`.
* MUST NOT follow a `done` transition comment.
Comment format (Markdown):
```default
**<commit-subject>**
<commit-body>
[`<short-hash>`](<commit-url>)
```
The commit URL format is host-dependent:
* Bitbucket: `<repo-url>/commits/<hash>`
* GitHub: `<repo-url>/commit/<hash>`
* GitLab: `<repo-url>/-/commit/<hash>`
## Part: `application/issue`
Each issue is represented as a structured block with strict field ordering.
@ -114,9 +267,10 @@ Title: <short title>
Status: <open|in-progress|done|hold|cancelled>
Priority: <low|medium|high>
Created: <YYYY-MM-DD>
Module: <module-name> # OPTIONAL
Relationships: <comma-separated list or empty>
DueStart: <YYYY-MM-DD> # OPTIONAL
DueEnd: <YYYY-MM-DD> # OPTIONAL
DueStart: <YYYY-MM-DD> # OPTIONAL
DueEnd: <YYYY-MM-DD> # OPTIONAL
Description: <first line>
<continuation lines>
```
@ -130,6 +284,9 @@ Description: <first line>
* **Status**: one of `open`, `in-progress`, `done`, `hold`, `cancelled`.
* **Priority**: one of `low`, `medium`, `high`.
* **Created**: ISO date.
* **Module**: optional. When present, MUST reference a module name defined in
the `application/modules` part. If no `application/modules` part exists,
the field is ignored.
* **Relationships**:
\* Empty:
```default
@ -140,7 +297,11 @@ Description: <first line>
```default
Relationships: dependsOn:43, relatesTo:10
```
* Valid kinds: `dependsOn`, `relatesTo`, `blocks`, `causedBy`.
* Valid kinds: `dependsOn`, `relatesTo`, `blocks`.
* All relationship target IDs MUST reference existing issue IDs in the
same `TODO` file. A target that does not exist MUST be rejected.
* A relationship targeting a `cancelled` issue SHOULD produce a warning
(stale reference).
* **DueStart / DueEnd**:
\* Optional.
\* If only one is present, the other is implicitly equal to it.
@ -148,9 +309,10 @@ Description: <first line>
### Description Block
* The first line appears on the same line as `Description:`.
* Continuation lines:
\* Must begin with whitespace.
\* Must align indentation consistently.
* `Description:` occupies 13 characters. Content begins at column 14.
* Continuation lines MUST be indented with 13 spaces, aligning with column 14.
* Lines MUST NOT exceed 80 columns. Long text MUST be word-wrapped at the
80-column boundary by the serializer.
* No blank lines allowed inside the description block.
### Body
@ -158,6 +320,20 @@ Description: <first line>
Any lines after the description block are considered free-form body text.
The body MUST NOT contain another `ID:` field or a MIME boundary.
### Issue Immutability
The `Description` field is immutable after the issue is created. To change
the scope of an issue, the issue MUST be cancelled and a new issue created.
Fields that MAY change after creation:
* `Status` (via transition commits)
Fields that MUST NOT change after creation:
* `ID`, `Type`, `Title`, `Priority`, `Created`, `Description`,
`Module`
## Git Workflow Rules
### Branch Naming
@ -186,6 +362,83 @@ bugfix/7
* A branch MUST be named exactly `<Type>/<ID>`.
* A branch MAY merge only when the issue status is `done`.
## Status Transition Rules
### Valid Transitions
Not all status changes are permitted. The following table defines the
complete set of valid transitions:
| From | Allowed transitions |
|---------------|-------------------------------------|
| `open` | `in-progress`, `hold`, `cancelled` |
| `in-progress` | `done`, `hold`, `open`, `cancelled` |
| `hold` | `open`, `in-progress`, `cancelled` |
| `done` | `open` |
| `cancelled` | `open` |
Any transition not listed MUST be rejected. A no-op transition (same status)
is permitted.
### Transition Commits
Each status transition MUST be recorded as a dedicated commit that modifies
only the `TODO` file. The commit message MUST follow this format:
```default
todo(<ID>): <status>
<body>
```
Where:
* `<ID>` is the issue’s integer ID.
* `<status>` is the new status value.
* `<body>` is a required description whose content depends on the
transition.
### Transition Details
**\`\`todo(<ID>): open\`\`** — Issue creation.
* Branch: MUST be on `develop`.
* Body: description of what needs to be done (becomes the issue’s
`Description` field).
**\`\`todo(<ID>): in-progress\`\`** — Start work.
* Branch: MUST be on `develop`.
* Body: high-level description of the planned approach.
* After this commit, the issue branch `<Type>/<ID>` may be created from
`develop`.
**\`\`todo(<ID>): done\`\`** — Complete work.
* Branch: MUST be on `<Type>/<ID>`.
* Body: high-level summary of what was delivered.
* After this commit, the issue branch may be merged into `develop` using
`--no-ff`.
**\`\`todo(<ID>): hold\`\`** — Pause work.
* Branch: MUST be on `<Type>/<ID>`.
* Body: reason for holding.
**\`\`todo(<ID>): cancelled\`\`** — Cancel issue.
* Branch: MUST be on `develop` or `<Type>/<ID>`.
* Body: reason for cancellation.
* If the issue is `open` (no branch exists), the commit is on `develop`.
* If the issue is `in-progress` or `hold` (branch exists), the commit
may be on the issue branch.
### Transition-Only Constraint
A transition commit MUST modify only the `TODO` file. No other files may
be included in the commit. This ensures that every transition is
independently auditable.
## Sprint Membership Logic
Given:
@ -222,7 +475,10 @@ The preprocessor MUST:
* Extract each part’s `Content-Type` and body.
* Reorder parts so that:
\* `application/sprints` appears first (if present)
\* `application/modules` appears second (if present)
\* `application/bugzilla` appears third (if present)
\* All `application/issue` parts follow in original order
\* Unknown part types are preserved in original order after issues
* Emit a MIME message with:
\* `MIME-Version: 1.0`
\* `Content-Type: multipart/mixed; boundary="ISSUE"`
@ -246,17 +502,26 @@ The parser MUST:
* Use a MIME parser to extract parts.
* Dispatch based on `Content-Type`:
\* `application/sprints` → sprint parser
\* `application/modules` → module parser
\* `application/bugzilla` → Bugzilla tracker parser
\* `application/issue` → issue parser
* Enforce:
\* Field order
\* Required fields
\* Description indentation rules
\* Description indentation and column rules
\* Sprint entry grammar
\* Module entry grammar
\* Module references: if `application/modules` is present, every issue `Module` field MUST reference a defined module name
\* Bugzilla mapping references: if `application/bugzilla` is present, every mapping `Module` value MUST reference a defined module name
\* Relationship targets: every target ID MUST reference an existing issue ID
\* Stale relationships: a relationship targeting a `cancelled` issue SHOULD produce a warning
* Produce a `TodoFile` object:
```default
{
sprints: Sprint[],
issues: Issue[]
issues: Issue[],
modules?: Module[],
bugzilla?: BugzillaTracker
}
```
@ -271,22 +536,159 @@ The parser MUST reject:
* Invalid sprint ranges
* Invalid date formats
* Multiple `application/sprints` parts
* Multiple `application/modules` parts
* Multiple `application/bugzilla` parts
* `application/bugzilla` without `application/modules`
* Issue `Module` referencing undefined module
* Bugzilla mapping `Module` referencing undefined module
* Relationship target referencing non-existent issue ID
* Invalid status transition
* Duplicate issue IDs
The parser SHOULD warn on:
* Relationship targeting a `cancelled` issue (stale reference)
Errors SHOULD include line numbers when possible.
## CLI Reference
The `@byteb4rb1e/mime-todo` CLI is the reference implementation of this
specification. It enforces all format, validation, transition, and commit
rules defined above. Both developers and automated agents MUST use the CLI
to interact with the `TODO` file rather than editing it manually.
Install:
```default
npm install -g @byteb4rb1e/mime-todo
```
### Issue Lifecycle
Creating an issue (MUST be on `develop`):
```default
todo create --type feature --title "Add login" --plan "Implement OAuth2 flow"
```
This produces a `todo(<ID>): open` commit modifying only the `TODO` file.
The `--plan` text becomes the issue’s `Description` field.
Starting work (MUST be on `develop`):
```default
todo start <id> --plan "High-level approach description"
```
This produces a `todo(<ID>): in-progress` commit. The issue branch
`<Type>/<ID>` may then be created by the user:
```default
git checkout -b feature/<id>
```
Completing work (MUST be on `<Type>/<ID>`):
```default
todo done <id> --summary "Summary of what was delivered"
```
This produces a `todo(<ID>): done` commit. The issue branch may then be
merged into `develop` using `--no-ff`.
Holding an issue (MUST be on `<Type>/<ID>`):
```default
todo hold <id> --reason "Blocked on dependency"
```
Cancelling an issue (MUST be on `develop` or `<Type>/<ID>`):
```default
todo cancel <id> --reason "Superseded by issue #5"
```
The CLI validates the current branch and the status transition before
committing. Invalid transitions or wrong branches are rejected with an
error.
### Read-Only Commands
These commands do not modify the `TODO` file and may be run from any
branch:
```default
todo list # list all issues
todo show <id> # show full issue details
todo sprints # list all sprints
todo issues-in-sprint <name> # list issues in a sprint
```
### Bugzilla Integration
Initializing products and components:
```default
todo init # check what exists
todo init --dry-run # preview changes
todo init --confirm --assignee user@example.com # create missing items
```
The `init` command reads the `application/bugzilla` part and ensures all
referenced products and components exist on the Bugzilla server.
Pushing commits to Bugzilla:
```default
todo push # push all unpushed commits
todo push HEAD~3 # push only the last 3 commits
todo push --dry-run # preview without pushing
todo push --strategy full # re-scan all bugs
```
On issue branches, `push` posts work commits as Bugzilla comments. Work
comments are only permitted when the issue is `in-progress` and no
`done` transition has been recorded.
On `develop`, `push` posts transition commits as Bugzilla comments and
updates the bug’s status accordingly.
Each comment includes a clickable link to the commit and is tagged with
`git-<short-hash>` for idempotency. Running `push` multiple times is
safe.
### Agent Usage
Agents MUST use the CLI for all `TODO` file interactions:
* Creating issues: `todo create`
* Transitioning issues: `todo start`, `todo done`, `todo hold`,
`todo cancel`
* Querying: `todo list`, `todo show`, `todo sprints`
* Syncing to Bugzilla: `todo push`
Agents MUST NOT:
* Edit the `TODO` file directly.
* Construct transition commits manually.
* Modify issue fields other than `Status` (and only via the CLI).
* Push to Bugzilla outside of the CLI’s `push` command.
## Extensibility
Defined part types:
* `application/sprints` — sprint metadata
* `application/modules` — repository module structure
* `application/bugzilla` — Bugzilla product/component mappings
* `application/issue` — single issue
Future part types MAY be added using:
```default
application/<subtype>
```
Examples:
* `application/metadata`
* `application/changelog`
* `application/epilog`
The preprocessor MUST preserve unknown part types but MUST NOT reorder them.
Unknown types are placed after all defined types.