Project Workflow Manual

AI coding is fast, but most teams still lose time: context disappears, rationale gets buried in chat, and the same decisions get rehashed.

pman fixes that by turning context into files. Every meaningful change starts as a project note, gets planned in writing, and is archived when done. Your agent executes code; your notes preserve intent.

GitHub README • CLI Reference • Download AGENTS.md

Why This Matters

Code survives. Chat context usually does not. By turning plans into artifacts rather than transient conversation, future work gets easier because you can always trace why changes happened. The project note becomes the single source of truth for intent, while the code and git history record what changed.

What pman Does Today

The CLI covers the full project lifecycle. pman init, pman update, and pman verify handle workspace bootstrap. pman new, pman list, and pman archive manage the project lifecycle from creation through completion. For note manipulation, read, write, and edit provide precise I/O primitives with line-range selection and stale-context guards, while cat, head, tail, wc, and less offer familiar Unix ergonomics scoped to the Notes root. pman skill generate rounds things out with skill template generation.

Configuration is handled through PMAN_NOTES_DIR, PMAN_PROJECT_PREFIX, canonical AGENTS.md, and canonical skills under .pman/skills/. When claude or codex CLIs are installed, pman creates bridge symlinks so each agent consumes the same canonical files through its own convention.

Quick Start

Pick a workspace directory, run pman init ., and start using your coding agent to execute changes through project notes. That is the whole setup.

cargo install --git https://github.com/divanvisagie/pman
pman init .
pman verify --path .
pman new "My Feature" --status active

For hybrid MCP setups, install and run pman-mcp as a Python MCP shim over the Rust CLI:

pipx install "git+https://github.com/divanvisagie/pman"
pman-mcp --transport stdio --notes-dir ~/Notes
pman-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --notes-dir ~/Notes

The Rust pman binary must be available on PATH (or configured with --pman-bin).

Workflow In Five Steps

Every change starts with pman new, which creates a project note. From there you refine scope and approach inside that note, then implement once the plan is solid. When the work is done, capture outcomes and follow-ups in the same note, and close it with pman archive.

flowchart LR
    A[New Project Note] --> B[Plan in Note]
    B --> C[Implement]
    C --> D[Record Outcomes]
    D --> E{Done?}
    E -->|No| B
    E -->|Yes| F[Archive]

Workspace Model

Notes/
  Projects/
    _registry.md
  Areas/
  Resources/
  Archives/
    Projects/

The registry at Notes/Projects/_registry.md is the authoritative index for active and archived projects.

Configuration Model

pman keeps agent guidance in AGENTS.md and skills in .pman/skills/. If supported CLIs are installed, pman creates bridge symlinks so those tools consume the same canonical files.

AGENTS.md
.pman/skills/project/SKILL.md
CLAUDE.md -> AGENTS.md
.claude/skills/project -> .pman/skills/project
.codex/skills/project -> .pman/skills/project

Upgrading

pman update --path .

This refreshes embedded workflow resources while leaving your workspace README.md untouched.