Core workflows

Plan, do, commit

1. Canonical board in <common>-taskmark (or taskmark/ in single mode)
2. /tkmd-verify when the board was created on an older Taskmark — repairs scaffold, deletes leftover generated files, and strips legacy item markdown. Never commits
3. /tkmd-plan to search existing work and add only the smallest useful hierarchy from prose (new files only)
4. After Cursor Plan mode, /tkmd-save to turn that plan into epic/story/task/bug items and keep diagrams on them — never commits, never implements
5. /tkmd-save-do when you want that Cursor plan saved and the newly created items implemented immediately. Prefer save-only then /tkmd-do later when you want to review the board first
6. /tkmd-plan-do when you want the prose plan and immediate implementation of only the newly created items. Prefer plan-only then /tkmd-do later when you want to review the board first
7. Implement existing targets with /tkmd-do in product repos — never commits; does not set in_progress; finished leaves are done
8. If planned work will never be implemented, use /tkmd-shelf — eligible leaves become shelved without changing parent markdown or committing
9. /tkmd-changelog when you want Unreleased notes in board CHANGELOG.md; /tkmd-version when you are ready to promote them and set that SemVer on every linked product. Neither commits, and neither writes a README changelog
10. /tkmd-reportme when you want a personal report of work you finished since the last report (gitignored .reports/; never commits)
11. /tkmd-commit when you want git commits (simple one-liners; no push by default)

Shelve discarded work

/tkmd-shelf closes work without claiming it was implemented. A leaf receives status: shelved and a completed_at timestamp, while acceptance criteria, resolvers, and cancelled: false remain unchanged. Story and epic targets cascade to their eligible task/bug descendants only.

Shelved work is visually distinct from done, is terminal for parent rollups, and is removed by Hide completed. The command never commits or pushes.

Overall tree

The local board’s default view is Overall: one nested list, not three stacked tables. Expand an epic to see its stories and epic-direct tasks/bugs; expand a story to see its tasks and bugs. At each level, incomplete items sort before complete ones, then newest first. Hide completed treats done, shelved, and cancelled as complete — including bug leaves — and keeps an ancestor visible while it still has incomplete descendants.

Work items stays a flat list (legacy All / Stories / Tasks query values open that same flat view). Search, hide-completed, timeframe, pagination, and deep links apply to Overall: ?epic= expands that epic, ?story= expands the story under it, and ?item= opens detail.

Parent status, points, Actual, implementers, lifecycle dates, and aggregated Prompt & feedback / Commits / Work log are read-time views over descendant leaves. Commands write only new item files or the executed leaf — never parent rollups.

Leaf-only writes

Two people can create and finish different tasks without merging parent files. /tkmd-plan, /tkmd-save, /tkmd-save-do, /tkmd-plan-do, and /tkmd-do change only new or target item markdown — not parent epic.md / story.md lists, rollups, or generated board files.

At read time the UI derives parent child lists, status, points, implementers, lifecycle dates, Prompt & feedback, Commits, and Work log from descendant leaves.

Work logs and Actual

Leaves keep a Work log. Actual is the sum of closed Started → Ended intervals on task/bug leaves. Epics and stories sum their descendant leaves. There is no time estimate or owner property.

• Open or invalid intervals are not counted until they have a valid Ended timestamp
• Never hand-set Actual in frontmatter

Shared-batch

When one sitting delivers many leaves, measure one batch span and allocate milliseconds by points. Same Started on each leaf; Ended = Started + allocated slice. Do not copy the full batch onto every task.

Prompt & feedback log

Written on leaves whenever an agent does product work. Append a prompt row when the user asks for work; append feedback when they accept, reject, or give later notes. Author comes from git identity when available. Prefer an open matching task/bug; if the change is follow-up on finished work, append to that done leaf; create a new leaf only when nothing fits. Never write these rows on epic.md or story.md. Parent views aggregate descendant rows.

Commits log

Append-only table on the leaf: SHA | Repo | Date (UTC) | Author | Message. In multi-repo workspaces the Repo column is the short folder name from local REPOS.md. /tkmd-commit is how commits land; /tkmd-plan, /tkmd-save, /tkmd-save-do, /tkmd-plan-do, /tkmd-do, /tkmd-verify, /tkmd-changelog, /tkmd-version, and /tkmd-reportme do not commit.

Related: Commands, Structure.