akurai-tasks

public
Latest change cb00647e2dddee7d80e8f67a6858572f544a2ed6 - plan: track Framework convergence for AkurAI-Tasks by Ólafur Búi Ólafsson
---
name: pm
description: Manage this project's markdown state (plans, epics, tasks, docs, memories, codebase index) via the pm.py CLI. Use when creating or updating tasks/epics/docs, changing task status, logging project status, recording decisions or secret locations, finding where something lives (semantic search), or validating the state files. Triggers - "new task", "start/finish a task", "what's active", "log this", "where is X", "update the plan".
---

# pm — project state management

All project state lives in markdown under `.plan/ .tasks/ .docs/ .memories/ .codebase_index/`,
managed by `./pm.py` (Python stdlib, run from repo root). Never hand-edit generated
indexes; edit entry files, then sync.

## Commands

| Do | Run |
|----|-----|
| Create task / epic / doc | `./pm.py new task <slug> [--epic <epic>]` · `new epic <slug>` · `new doc <slug>` |
| Change status (bumps Updated, resyncs) | `./pm.py status <slug> <value>` |
| See tasks by status | `./pm.py list` |
| Regenerate all indexes | `./pm.py sync` |
| Check integrity | `./pm.py validate` |
| Dated status entry in MEMORIES.md | `./pm.py log "message"` |
| Semantic search, state files + code | `./pm.py search "query" [-n N]` |

Slugs are `lowercase-with-dashes`. Task statuses: `backlog | active | blocked | done`.
Epic statuses: `planned | active | done`.

## Workflow

- **Starting work:** `./pm.py new task <slug>` (or `status <slug> active` for an existing
  one). Fill in the What/Steps sections of the task file.
- **Finishing work:** update the task file's Notes/Steps, `./pm.py status <slug> done`,
  and `./pm.py log "shipped <thing>"`. Touch `.codebase_index/INDEX.md` only if the
  code layout changed.
- **Finding things:** prefer `./pm.py search "query"` over grep for conceptual questions
  ("where is auth handled", "what did we decide about X"). Results are `file::section`
  or `file.py:L<n>` ids. Needs local TEI servers on :8081/:8082 (override via
  `PM_EMBED_URL` / `PM_RERANK_URL`); falls back with a clear error if down.
- **Decisions and quirks:** append one-liners to the matching section of
  `.memories/MEMORIES.md` directly, then `./pm.py validate`.
- **Secrets:** record *location only* (vault entry, env var name) in the MEMORIES.md
  secrets table — never values; `validate` scans for leaked values and fails.
- **After any hand-edit** of state files: `./pm.py validate` (exit 1 = problems listed
  on stderr), and `./pm.py sync` if you added/removed entry files.

## References

- [file-formats.md](references/file-formats.md) — entry file field grammar, which files
  are generated vs. hand-edited, cache details.

Tests for the tooling itself: `python3 test_pm.py` (live search checks auto-skip if
TEI servers are down).