pman - Project Workflow Manual

Project Workflow Manual

pman is an opinionated workflow for agentic programming with Claude Code.

LLMs are great at generating code and iterating through implementation problems, but they struggle with context. Context is the hardest part of software development. pman flips the dynamic: you become the context manager, while Claude focuses on code, frameworks, and documentation. Each plays to their strength.

The key insight is that most file changes happen through the agent chat as an intermediary. Instead of editing files or running commands directly, you work through Claude. Because Claude is configured with the workflow rules via CLAUDE.md and skills, it enforces conventions automatically: creating project notes before coding, updating the registry, following commit formats. You describe intent; Claude handles execution within the established structure.

This doesn't mean you can't edit files directly. Sketch out pseudocode in vim, tweak a config by hand, or use whatever tool fits the moment. The workflow is interactive: when you make changes outside the chat, tell Claude to look at what you did. Claude, your editor, and any other tool are tools in the toolbox—not the entire toolbox.

Unlike throwaway planning, pman treats plans as persistent artifacts, like source files, but managed in a separate, centralized Notes directory. By documenting every change, you build a reference set for future work. Changed service A and now service B needs updating? Pull in context from A's project note. The Notes vault becomes your cross-system memory.

Agent compatibility: This workflow is developed and tested exclusively with Claude Code. It may work with other AI coding agents, but I only test with Claude and have found it to be the most effective for this style of work. The workflow, prompts, and tooling are optimized for Claude's capabilities.

GitHub README • CLI Reference • Download CLAUDE.md

Quick Start

Create a workspace directory (e.g., ~/src, ~/code, whatever you prefer)
Start Claude Code in that directory
Tell Claude: "set up https://divanv.com/pman/INSTALL.md"

Claude will read the install instructions and configure your workspace automatically. The setup works in any directory—it becomes your workspace root.

Glossary

Term	Meaning
Project	Time-bound effort to achieve an outcome (feature, bugfix, refactor)
System	What the project changes—may span one or more repositories
Repository	A git repo containing code

A project changes a system. A system is made of one or more repositories. Projects live in Notes/Projects/, repositories live in the workspace.

The Core Idea

Plan before you code. Every change starts in a project note, not in the codebase. You and Claude collaborate on the plan in writing. Only after the plan is complete do you start coding.


flowchart LR
    subgraph Workflow
        A[Create Project Note] --> B[Plan with Claude]
        B -->|Update| N[(Project Note)]
        N --> C[Execute Code]
        C --> D[Record Outcomes]
        D -->|Update| N
    end

    D --> E{Done?}
    E -->|No| B
    E -->|Yes| F[Archive]

The workflow has five steps:

Create a project note: pman new creates a project note in Notes/Projects/ with a chronological PROJ-<n> id and slug.
Plan collaboratively: Work with Claude to develop the plan in the project note. Goals, constraints, approach: all written down. The plan lives in the note, not in chat history.
Execute: Once the plan is complete, start writing code. The plan is the spec; follow it.
Record outcomes: Update the project note with what worked, what changed, and any follow-up tasks.
Archive: pman archive moves the project note to Notes/Archives/Projects/ and updates the registry.

Example Session

Here's how a typical session looks:


sequenceDiagram
    actor User
    participant Claude
    participant PN as Project Note
    participant Code as System

    User->>Claude: I want to add feature X
    Claude->>PN: Create project note
    User->>Claude: Let's plan this
    Claude->>PN: Write goals and approach
    User->>Claude: What about edge cases?
    Claude->>PN: Update plan
    User->>Claude: Looks good, build it
    Claude->>Code: Implement changes
    Claude->>PN: Record outcomes
    User->>Claude: Done, archive it
    Claude->>PN: Move to Archives

Notice how Claude writes to the project note throughout. It does this based on the instructions in CLAUDE.md, but you may also want to explicitly tell it to write something down during your chat. The note becomes the single source of truth for why a change was made, while git records what changed.

Workspace Structure

pman expects a Notes directory following PARA (Projects, Areas, Resources, Archives):

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

The workspace structure for your repositories is up to you—document it in your workspace README.md.

Key concepts:

Registry: Notes/Projects/_registry.md is the authoritative index of all projects, active and archived.
Deterministic slugs: Each project gets a unique slug like proj-22-my-feature. Slugs make projects easy to reference in conversation and across notes.

Manual Setup

If you prefer to set up manually instead of using Claude:

Create a workspace directory for your projects.
Create a Notes directory with PARA folders (Projects, Areas, Resources, Archives).
Create Notes/Projects/_registry.md to track projects.
Download CLAUDE.md and place it at your workspace root.
Copy skills to ./.claude/skills/.
Create a README.md documenting your workspace layout and custom tools.

See INSTALL.md for detailed instructions and file contents.

Install the CLI

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

Configuration

pman ships two types of configuration files:

CLAUDE.md

Generic workflow instructions for Claude. Contains workflow rules, commands, and boundaries. Written as directives for Claude, not documentation for humans.

cp resources/CLAUDE.md ./

README.md (user-maintained)

Your workspace-specific configuration. Document your:

Directory layout and organization
Custom tools and commands
Project creation workflow
System-specific conventions

Claude reads both files, combining generic workflow with your specific setup.

Claude Code Skills

Skills teach Claude about specific workflows. This repo includes two skills in resources/skills/:

para-notes: PARA note management, project notes, pman usage
project-structure: Workspace navigation, project boundaries

Install to your workspace's .claude/skills/ directory:

mkdir -p ./.claude/skills
cp -r resources/skills/* ./.claude/skills/
# or symlink for automatic updates:
ln -s /path/to/pman/resources/skills/* ./.claude/skills/

Upgrading

Because CLAUDE.md and skills are generic, upgrading is simple:

cp resources/CLAUDE.md ./
cp -r resources/skills/* ./.claude/skills/

Your README.md stays untouched—no merge conflicts.

Keeping Things in Sync

The CLAUDE.md file is the contract between you and Claude. It defines commands, tools, structure, and workflow rules. Keep it up to date.

When Claude does something you don't like, ask it to update CLAUDE.md directly: "Please add to CLAUDE.md not to do X again." This way, the lesson persists across sessions.

Similarly, keep your project notes current. They're the shared context that makes collaboration with Claude effective.