---
name: markdownto-backlog-workspace
description: Organize or edit a Markdown To backlog directory with one priority spine, linked notes, and delegated work.
---
# Markdown To backlog-workspace
## Contract and workflow
Read `mdto spec backlog-workspace` (or the adjacent `SPEC.md` in a checkout) and the
[shared conventions](https://markdownto.ai/specs/conventions.md) before authoring or
repairing content. Outside a checkout, use the [published spec](https://markdownto.ai/specs/backlog-workspace.md).
This skill accompanies `[email protected]`. The spec and its fixtures govern conformance;
editorial advice below is non-normative and should adapt to the user's brief.
If the source declares another version, obtain its matching contract before changing it.
The unit is a directory, not a new file envelope. Exactly one direct member declares
`markdownto: [email protected]`; that file is the priority spine. Never write a
`[email protected]` envelope. Read the backlog spec as well as the workspace spec.
A nested spine establishes a sub-backlog; ordinary notes do not become task authorities.
Use the workspace's `graduate`, `archive`, and `sweep` transactions for their multi-file
changes. Inspect their current CLI help for directory flags and validate the directory,
not merely its spine.
## Content quality
Keep priority in the spine and accumulated reasoning in the note a task has earned.
A useful note states the outcome, current evidence, unresolved decisions, and next action;
it should not duplicate a second priority queue. Delegate a coherent workstream rather
than fragmenting every task into a directory. Archive closed work with its context and
links intact so future readers can distinguish a settled decision from a live proposal.
## Check and deliver
Validate each spine with `mdto validate <spine-file>` before and after edits.
The current universal validate/render commands accept files, not directories. Workspace
verbs resolve cross-file relations before acting; inspect the requested transaction with
`--dry-run --dir <directory>`. Do not run a mutation merely to obtain validation. Read diagnostics against the spec's rationale; preserve meaning when
repairing syntax. Prefer spec-owned verbs for edits they support, checking their current
`--help`; otherwise make a focused source edit, preserving unrelated content and IDs.
Render the spine with `mdto render <spine-file>` and inspect the workspace view when available. Validation checks
structure, not editorial quality: review the content against the user's purpose as well.
Without the CLI, use the contract and examples and report that validation was not run.
Deliver the Markdown source and any requested artifacts, stating what was actually checked.
Give this guide to your agent, or read it as an author. It covers workflow and editorial judgment; the specification defines conformance.
Contract and workflow
Read mdto spec backlog-workspace (or the adjacent SPEC.md in a checkout) and the shared conventions before authoring or repairing content. Outside a checkout, use the published spec. This skill accompanies [email protected]. The spec and its fixtures govern conformance; editorial advice below is non-normative and should adapt to the user's brief. If the source declares another version, obtain its matching contract before changing it.
The unit is a directory, not a new file envelope. Exactly one direct member declares markdownto: [email protected]; that file is the priority spine. Never write a [email protected] envelope. Read the backlog spec as well as the workspace spec. A nested spine establishes a sub-backlog; ordinary notes do not become task authorities. Use the workspace's graduate, archive, and sweep transactions for their multi-file changes. Inspect their current CLI help for directory flags and validate the directory, not merely its spine.
Content quality
Keep priority in the spine and accumulated reasoning in the note a task has earned. A useful note states the outcome, current evidence, unresolved decisions, and next action; it should not duplicate a second priority queue. Delegate a coherent workstream rather than fragmenting every task into a directory. Archive closed work with its context and links intact so future readers can distinguish a settled decision from a live proposal.
Check and deliver
Validate each spine with mdto validate <spine-file> before and after edits. The current universal validate/render commands accept files, not directories. Workspace verbs resolve cross-file relations before acting; inspect the requested transaction with --dry-run --dir <directory>. Do not run a mutation merely to obtain validation. Read diagnostics against the spec's rationale; preserve meaning when repairing syntax. Prefer spec-owned verbs for edits they support, checking their current --help; otherwise make a focused source edit, preserving unrelated content and IDs. Render the spine with mdto render <spine-file> and inspect the workspace view when available. Validation checks structure, not editorial quality: review the content against the user's purpose as well. Without the CLI, use the contract and examples and report that validation was not run. Deliver the Markdown source and any requested artifacts, stating what was actually checked.