WorkPackageManager

WorkPackageManager is a standalone Node.js CLI that creates and maintains markdown progress files for work packages.

Each progress file tracks:

• milestone checklist (M1, M2, ...)
• per-milestone tasks (M1.1, M1.2, ...)
• timestamped execution log entries

Requirements

• Node.js 18+
• Writable workspace directory

Repository Layout

• WPM/WorkPackageManager.mjs: CLI implementation
• WPM/core/: shared read/write/filter modules used by CLI and TUI
• WPM/tui/: Ink-based terminal UI
• WPM/tests/: unit tests
• WPM/work-package-manager-help.txt: generated help text
• planning/: progress markdown files
• README.md: this documentation

Quick Start

Run commands from the repository root:

node WPM/WorkPackageManager.mjs help

Create a new progress file in planning/:

node WPM/WorkPackageManager.mjs init "Module 22 PII Rework" --status WIP --dir "../planning" --description "Refactor settings and split app entrypoints"

Add milestone and task:

node WPM/WorkPackageManager.mjs milestone add --file "../planning/260212-1637 - Module 22 PII Rework.md" --id M2 --title "Settings migration"
node WPM/WorkPackageManager.mjs task add --file "../planning/260212-1637 - Module 22 PII Rework.md" --milestone M2 --title "Migrate settings UI"

Log work and close when finished:

node WPM/WorkPackageManager.mjs log --file "../planning/260212-1637 - Module 22 PII Rework.md" --message "Migration finished [M2.1 completed]" --category p
node WPM/WorkPackageManager.mjs close --file "../planning/260212-1637 - Module 22 PII Rework.md" --message "All milestones complete" --category m

Start the interactive TUI:

node WPM/WorkPackageManager.mjs tui --dir "../planning"

Run unit tests:

npm test

Public npm Publishing (@tilmannauch)

This project is configured for public publishing to npm under @tilmannauch.

Publish flow:

npm login
npm whoami
npm pack --dry-run
npm publish --access public

Install globally in your workflow:

npm i -g @tilmannauch/wpm
wpm help

Commands

• help: print usage and rewrite WPM/work-package-manager-help.txt
• init <work-package-name>: create a new progress file
• log: append a timestamped log line
• close: append log line and set metadata status to DONE
• open / reopen: append log line and set metadata status to WIP
• milestone add: add a milestone checklist item and matching plan heading
• milestone list: list milestones, optionally filtered by task presence
• task add: add a task under an existing milestone
• tui: launch terminal UI with monitor/edit workflows

Common Options

• --file <path>: target progress file (absolute or relative to script folder)
• --message <text>: required for log, close, open
• --category <value>: optional category for log events
• --help: print usage

Categories

Built-in category names:

• test, error, progress, planning, git, milestone, decision

Supported shorthand aliases:

• t, e, p, pl, g, m, d

Custom values are allowed after sanitization.

Progress File Format

init creates a file named:

YYMMDD-HHMM - <Work Package Name>.md

Each file contains:

• ## Metadata (creator, date, description, status)
• ## Milestones (checklist of M# items)
• ## Plan (task checklists grouped by ### M# - Title)
• ## Log (timestamped entries)

Example task line format:

- [ ] M2.3 Implement API mapping

Auto-Completion via Log Tags

If a log message contains a bracketed tag with:

1. a completion verb (close, complete, done, finish, and variants), and
2. a task reference (M#.##)

the referenced task is automatically checked.

Examples:

• [closes M2.3]
• [M2.3 completed]
• [finished M2.3]
• [M2.3 done]

If all tasks under a milestone are checked, the milestone checkbox is also checked automatically.

Typical Workflow

1. init a new file for the work package.
2. Add milestones with milestone add.
3. Add tasks with task add.
4. Track execution with log entries.
5. Mark completion with close.
6. If work resumes, use open/reopen.

TUI Usage

The TUI starts in monitor mode (read-only) and supports mode switching for edit actions.

Keyboard shortcuts:

• Ctrl+P: select planning folder
• 1-9: select fixed tab slot
• Ctrl+O: assign/select planning file for the active tab slot
• Ctrl+F: select multiple log categories (checkbox style)
• Ctrl+S: search log text (combined with category filter)
• PgUp/PgDn: scroll the log panel
• Ctrl+R: manual reload
• Ctrl+W: toggle auto-refresh
• Ctrl+B: toggle file status (WIP/DONE)
• Ctrl+I: create/initialize new planning file
• Ctrl+E: toggle monitor/edit mode
• Ctrl+Y: edit selected milestone or task title (edit mode)
• Ctrl+N: create milestone or task (edit mode)
• Ctrl+L: add log entry (edit mode)
• Ctrl+T: toggle selected task completion (edit mode)
• Ctrl+Z: undo last edit action (edit mode)
• Ctrl+K: toggle shortcut bar visibility
• Ctrl+G: open key help overlay
• Esc: close active overlay

Notes:

• The TUI requires an interactive terminal (TTY).
• Edit actions persist immediately to the active progress file.
• Layout responds to terminal size changes.
• Milestones/tasks panel scrolls with selection (Up/Down), and log panel scrolls with PgUp/PgDn.
• Task and log lines wrap to additional rows instead of truncating.
• Monitor/status bar stays pinned to the bottom with a keymap bar directly beneath it.

Troubleshooting

• Missing required --file value: add --file <path> for commands that edit or read an existing progress file.
• Progress file not found: check the path and remember relative paths resolve from WPM/ (the script folder), not your current shell folder.
• Target file is marked DONE and cannot be modified: run open first, then apply log, milestone add, or task add.
• Target file is already DONE: close only works when metadata status is currently WIP.
• Target file is already WIP: open/reopen only works when metadata status is currently DONE.
• Milestone already exists or Task already exists: use a different ID/number, or omit task add --id to auto-assign the next task number.
• Completion tag references missing milestone/task: ensure log completion tags (for example [M2.3 completed]) point to existing tasks.
• Use only one filter: milestone list allows exactly one of --with-tasks, --without-tasks, or --milestone M#.

Notes

• Files with metadata Status: DONE are protected from mutation commands such as milestone add, task add, and log.
• milestone list supports exactly one filter at a time: --with-tasks, --without-tasks, or --milestone M#.