pm-manager

📋 PM Manager
Know what to fix next — with any AI coding agent.

An open source skill pack for local project governance — init a .pm/ workbench, keep a daily Top3, triage pasted logs, and run release-ready health scans. Inspired by Spec Kit’s command-template + multi-agent adapter model. Works alongside Spec Kit: Spec Kit drives what to build; PM Manager drives project health and what’s next.

Table of Contents

• What is PM Manager?
• Get Started
• CLI Reference
• Supported AI Coding Agents
• Available Slash Commands
• How it relates to Spec Kit
• Core Philosophy
• Daily Workflow
• Repository Layout
• Prerequisites
• Support
• License

What is PM Manager?

Most AI coding sessions jump straight into code. PM Manager flips the day-to-day loop: keep a local, auditable .pm/ board for health, todos, incidents, and release gates — then let the agent recommend at most three things to do today.

It is not a cloud PM suite and not a replacement for Jira/Linear. It is a developer-side governance workbench that lives in your repo’s local .pm/ directory (git-excluded), driven by slash commands / skills the same way Spec Kit drives /speckit.*.

Get Started

1. Install the Agent Skill (skills.sh)

npx skills@latest add wei63w/pm-manager

Or copy skills/pm-manager into your tool’s skills directory:

2. Install the CLI (optional, cross-platform)

Requires uv and Python 3.11+. The CLI scaffolds .pm/ and installs per-agent adapters.

# From GitHub (recommended)
uv tool install pm-manager-cli --from git+https://github.com/wei63w/pm-manager.git

# Or from a local checkout
uv tool install --editable .

Verify:

pm version
# or
pm-manager version

Upgrade later:

uv tool upgrade pm-manager-cli
# or reinstall from git
uv tool install pm-manager-cli --force --from git+https://github.com/wei63w/pm-manager.git

3. Bootstrap a project

In your application repository (not required to keep this pack checked out):

cd /path/to/your-app

# Create .pm/ + install Cursor & Claude adapters (default)
# Also runs non-interactive: npx skills add wei63w/pm-manager -y
# (skills.sh indexing; requires Node.js/npx — skipped with a warning if missing)
pm init

# Cursor only
pm init --agent cursor

# Claude Code only
pm init --agent claude

# Scaffold .pm/ only (no agent files, no skills.sh)
pm init --scaffold-only

# Skip skills.sh / npx step
pm init --no-skills-sh

Refresh adapters without re-scaffolding:

pm install --agent all
pm install --no-skills-sh   # adapters only
pm check

Windows / macOS / Linux all use the same commands. Legacy PowerShell helpers under scripts/powershell/ still work, but pm init is preferred.

4. Initialize governance in your agent

Open Cursor / Claude Code in the project and run:

/pm-init

• Detects new vs existing projects
• Discovers Spec Kit .specify/memory/constitution.md (and other charter candidates) when present
• For empty projects, accepts a one-line intent to generate an outline
• Complements the filesystem scaffold from pm init (agent fills charter/overview)

5. Check today's Top3

/pm-status

You’ll get a short health line and up to three actionable todos. Claim one with /pm-next, close it with /pm-done TODO-001.

6. Triage an incident

Paste a stack trace or log into the chat:

/pm-fix

Conversation paste is a first-class evidence source (no need to save a file first).

7. Pre-release full scan

/pm-all

Runs gated full governance with a noise-filtered summary (blocking + high by default). Use --verbose for the long list.

After the scan, open .pm/dashboard/index.html in a browser for the visual dashboard (KPI, charts, module risk). Or read overview.md in the IDE. Rebuild anytime with pm dashboard.

CLI Reference

pm-manager is an alias of pm.

Supported AI Coding Agents

Natural-language routing (when slash commands are unavailable) is documented in skills/pm-manager/memory/ROUTING.md.

Available Slash Commands

Daily commands (remember these)

Planning & export

Internal (usually via /pm-all)

Command prompts live in skills/pm-manager/templates/commands/ with Spec Kit–style frontmatter and handoffs.

How it relates to Spec Kit

They can run in the same repo. PM Manager will read Spec Kit artifacts when present; it does not replace Spec-Driven Development.

Core Philosophy

• Simple daily UX — few entry commands; Top3 over long finding dumps
• Local & auditable — evidence and todos stay in .pm/ with redaction
• On-demand scans — no background daemons; paste / --path / registered sources
• Safe defaults — report first; never auto-write app code/SQL/cloud without confirmation
• Charter-aware (optional) — without a charter you get technical debt scans; with one you get scoped “unreasonable” checks with confidence

Daily Workflow

/pm-init → /pm-status → /pm-done
         ↘ /pm-fix (incidents)
         ↘ /pm-all  → .pm/dashboard/  (release gate + overview)

Target .pm/dashboard/ (after /pm-all or pm dashboard)

.pm/dashboard/
  index.html    # visual dashboard — open in a browser
  overview.md   # IDE tables: KPI, bars, module risk ranking, hot/todos
  findings.md   # aggregated open findings
  todos.md      # aggregated open todos
  stats.json    # counts + health_score + module_risk
  README.md     # same as overview.md (entry alias)

Repository Layout

pm-manager/
  pyproject.toml                 # uv/pip package (pm / pm-manager entrypoints)
  src/pm_manager_cli/            # Cross-platform CLI (incl. pm dashboard)
  skills/pm-manager/             # Installable Agent Skill (skills.sh)
    SKILL.md                     # Router skill
    AGENTS.md                    # Agent-oriented notes
    templates/commands/          # Slash/skill command prompts
    templates/pm/                # Files copied into target .pm/
    memory/ROUTING.md            # NL → command map
  scripts/python/                # Thin wrappers (prefer `pm init`)
  scripts/powershell/            # Legacy Windows helpers
  adapters/cursor/               # Cursor skill variants
  adapters/claude-code/          # Claude Code command files
  skills.sh.json                 # skills.sh groupings

Prerequisites

• Windows / macOS / Linux
• uv (recommended) for uv tool install
• Python 3.11+
• Git (so exclude rules can be written)
• An AI coding agent that supports skills or project slash commands (Cursor or Claude Code recommended)
• Optional: Spec Kit if you already use constitution/specs

Support

Questions and bugs: open a GitHub issue.

License

This project is licensed under the MIT License.