Project Workflow Manual

pman is an opinionated framework for a project workflow that maximizes context reuse, note management, and collaboration between humans, AI agents, and Unix tooling. It draws from the Unix philosophy: small, deterministic commands with predictable outputs and a strict hierarchical file structure.

The reason it exists is simple: most workflows fail in the boring parts. Naming, structure, and bookkeeping drift over time. pman makes those parts deterministic so projects stay searchable, notes stay aligned, and people (or agents) stay in sync.

Whether you use the CLI or not, the workflow still stands. It can be executed manually, by an AI agent, or even with notebooks and sticky notes. The value is the workflow, not the tooling.

• Projects are always created the same way.
• Notes stay aligned with the codebase.
• Archives are predictable and searchable.
• Tooling can rely on a stable filesystem shape.
• Humans and LLM agents share the same context across the full project lifecycle.

GitHub README • CLI Reference • Download AGENTS.md

How the Workflow Works

The workflow has five core steps:

1. Workspace layout: ~/src holds projects by reverse-domain. Notes live in ~/src/Notes using PARA.
2. Project creation: Create a project note in Notes/Projects/ with a chronological PROJ-<n> id and slug (e.g., proj-22-my-feature).
3. Project tracking: The registry (Notes/Projects/_registry.md) is the authoritative index of active projects.
4. Archiving: Move completed project notes into Notes/Archives/Projects/ and update the registry status to archived.
5. Determinism: Slugs are unique across both active and archived projects, so history remains unambiguous.

Set Up Your Workspace

Create a strict hierarchy under ~/src. This becomes the single, shared context for both humans and AI agents.

~/src/
├── com/
│   ├── example/        # Personal projects (your domain)
│   └── orgname/        # Organization projects
├── localhost/          # Local-only projects
└── Notes/
    ├── Projects/       # Active project notes
    │   └── _registry.md
    ├── Areas/          # Long-running areas of responsibility
    ├── Resources/      # Reference material
    └── Archives/
        └── Projects/   # Completed project notes

1. Create ~/src and place your projects in a reverse-domain tree.
2. Create ~/src/Notes and set up the PARA folders (Projects, Areas, Resources, Archives).
3. Create Notes/Projects/_registry.md to track active and archived projects.
4. Download and place the AGENTS file at ~/src/AGENTS.md as the workflow contract.
5. If using Claude, symlink CLAUDE.md to AGENTS.md: ln -s AGENTS.md CLAUDE.md

Connect Notes Everywhere

Notes are the shared context. Keep them close to every repo by symlinking or cloning.

1. Symlink ~/src/Notes into each project (recommended), or clone it directly.
2. Ensure each repo has a corresponding Area note in Notes/Areas/.
3. Reference Area notes from project notes for long-running work.
4. Use the registry in Notes/Projects/_registry.md to track active work.

Install the CLI (Optional)

The CLI automates deterministic steps like creating and archiving project notes. The workflow can be executed manually without it.

Install with Cargo:

cargo install --git https://github.com/divanvisagie/pman

Create a new project:

pman new "My Feature" --status active

Archive a completed project:

pman archive proj-22

Maintain the AGENTS File

The AGENTS.md file documents baseline project conventions so the workflow can be reproduced without relying on this specific codebase. Keep it up to date.

When you notice repeated undesired behavior from an AI agent, ask it to update the file directly (e.g., "please add to the agents file not to do X again"). This keeps humans and AI agents aligned on the same operational context.