md-project-manager (pm)

A CLI for the workflow in process.txt.

Install (local dev)

uv pip install -e .

Quick Start

pm init .
pm note "Primary users are nurses and admin"
pm toknow
pm todo
pm phase planning
pm demo "Demoed rota module and captured feedback"
pm flow

Commands

• pm init [path]: Create workflow files/folders and defaults.
• pm help: Show commands.
• pm flow: Show process definition.
• pm note "...": Append to notes.log.
• pm toknow [hint] [--date DD/MM/YY] [--model MODEL] [--endpoint URL] [--timeout SEC]: Regenerate toknows.md via Ollama.
• pm toknow next: Show the next [open] question from toknows.md.
• pm todo [hint] [--date DD/MM/YY] [--model MODEL] [--endpoint URL] [--timeout SEC]: Regenerate todos.md via Ollama.
• pm demo "...": Append demo note to blogposts/YYYY-MM-DD.md.
• pm notes [--date DD/MM/YY] [--plain]: View notes.log as a compressed vertical timeline.
• pm phase [recon|planning|building] [--hint ...] [--timeout SEC]: Show/set phase. Transition recon -> planning generates assumptions.md.

Date Filter Behavior

For pm toknow and pm todo:

• --date DD/MM/YY includes only notes.log entries up to that date.
• If --date is omitted, all notes are included.
• Before sending notes to the model, timestamp and username are stripped to reduce token usage.

For pm toknow next:

• Reads toknows.md and prints the first [open] question to resolve next.

Notes View

• pm notes opens a scrollable terminal view (j/k, arrow keys, PgUp/PgDn, g, G, q).
• Gaps are compressed (short gaps: none, medium: small spacing, long: labeled gap marker).
• Use pm notes --plain for non-interactive output.

Created Layout

pm init creates:

• .config.yaml
• .pm_state.json
• process.txt
• notes.log
• toknows.md
• todos.md
• blogposts/
• archives/

archives/ is added to .gitignore on init.

File Update Policy

pm toknow, pm todo, and assumptions generation replace full markdown files. Before replacement, previous versions are copied to archives/ as timestamped backups.

Entry Formats

• notes.log: DD/MM/YY:HH MM: author: message
• toknows.md: model-generated markdown
• todos.md: model-generated markdown
• assumptions.md: model-generated markdown
• blogposts/YYYY-MM-DD.md: - DD/MM/YY:HH MM: author: demo note

Author is sourced from git config user.name (fallback: OS login name).

Config (.config.yaml)

ollama_endpoint: http://localhost:11434/api/generate
ollama_model: gpt-oss
ollama_token: REPLACE_ME
ollama_insecure_tls: false
ollama_timeout_sec: 180
process_file: process.txt
prompts:
  toknow: "..."
  todo: "..."
  assumptions: "..."

Prompts are configurable in .config.yaml. ollama_token must be set in .config.yaml for AI commands to run. If endpoint ends with /chat, the CLI uses chat payload format automatically. If your endpoint uses a self-signed cert, set ollama_insecure_tls to true.

Ollama Prerequisite

ollama serve
ollama pull gpt-oss