md-project-manager 0.1.1
CLI tool to organize project documentation in a consistent structure
Requires Python: >=3.9

# md-project-manager (`pm`)

A CLI for the workflow in `process.txt`.

## Install (local dev)

```bash
uv pip install -e .
```

## Quick Start

```bash
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`)

```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

```bash
ollama serve
ollama pull gpt-oss
```