pdm-bridge

Claude Code plugin (Skill + slash commands + MCP server) that gives a Project Manager a single pane of glass across hardware (PDM) and software (Git) lifecycles.

The skill text lives at skills/pdm-bridge/SKILL.md and describes when Claude should reach for this tool. This README describes how to install and run it.

Why this exists

Real hardware/software products are built by two co-evolving teams:

• mechanical / electrical engineers, working in SolidWorks PDM / Windchill / Teamcenter / Onshape, governed by ECOs and PRINCE2-style stage gates;
• firmware / software engineers, working in GitHub or GitLab, governed by Scrum sprints and (at scale) SAFe Product Increments.

Project managers reconcile the two by hand. pdm-bridge unifies them through one schema (schemas/project_state.schema.json) and exposes the unification as MCP tools, slash commands, and a Skill so Claude can drive the dashboard, risk reconciliation, and cross-module triggers.

Install

Three paths in order of how shareable each is:

A. As a Claude Code plugin (recommended)

# After publishing this directory as a Git repo:
/plugin marketplace add <owner>/<repo>
/plugin install pdm-bridge@<owner>-<repo>

# Local dev (no install needed):
claude --plugin-dir /path/to/pdm-bridge

The plugin manifest at .claude-plugin/plugin.json registers the MCP server, four slash commands (/pdm-init, /pdm-status, /pdm-sync, /pdm-evaluate), and the SKILL in one shot.

B. As a skill only (lightweight, no slash commands)

ln -s "$(pwd)/skills/pdm-bridge" ~/.claude/skills/pdm-bridge

The MCP server is still required for the tools to do anything:

cd pdm-bridge
pip install -e .
claude mcp add pdm-bridge -- pdm-bridge

C. Just the MCP server

For non-Claude-Code MCP hosts:

pip install pdm-bridge      # once published
pdm-bridge                  # stdio (default)
pdm-bridge --sse 0.0.0.0:7842
pdm-bridge --enable-writes  # allow PM tool pushes etc.
python -m pdm_bridge        # equivalent to the console script

Quick demo (no live PDM/Git needed)

python -c "
from pdm_bridge.core.state import new_project
from pdm_bridge.profiles.scale import profile_for
from pdm_bridge.hardware.pdm import sync_pdm
from pdm_bridge.software.git import sync_git
from pdm_bridge.sync.orchestrator import install_default_rules, evaluate_rules, RuleEngine
from pdm_bridge.dashboard import render_dashboard

ps = new_project(name='Demo Device', description=None,
                 scale_profile='small_team', lifecycle_mode='iterative',
                 profile=profile_for('small_team'))
sync_pdm(ps, adapter='generic', connection={'path': 'examples/small_team_iterative.pdm.json'})
sync_git(ps, adapter='generic', connection={'path': 'examples/small_team_iterative.git.json'})
install_default_rules(ps)
evaluate_rules(ps, RuleEngine(allow_writes=False))
print(render_dashboard(ps))
"

Layout

pdm-bridge/
├── .claude-plugin/plugin.json    # plugin manifest (MCP server inline)
├── skills/pdm-bridge/SKILL.md    # the Skill
├── commands/                     # slash commands (auto-discovered)
│   ├── pdm-init.md
│   ├── pdm-status.md
│   ├── pdm-sync.md
│   └── pdm-evaluate.md
├── schemas/project_state.schema.json
├── src/pdm_bridge/
│   ├── server.py                 # MCP entry point (13 tools)
│   ├── core/                     # PMI/APM + IPMA ICB4
│   ├── hardware/                 # PDM, PRINCE2, BOM
│   ├── software/                 # Git, Agile, SAFe
│   ├── sync/                     # rule engine
│   ├── pm/                       # ClickUp/Monday/Asana/Jira
│   ├── adapters/                 # pdm_http (configurable), pdm_generic, git_*
│   ├── profiles/scale.py         # solo|small_team|department|enterprise
│   ├── storage.py
│   └── dashboard.py
├── examples/
│   ├── small_team_iterative.{pdm,git}.json
│   ├── enterprise_safe.json
│   └── connections/              # PDM connection templates
│       ├── solidworks_pdm.example.json
│       ├── windchill.example.json
│       ├── teamcenter.example.json
│       ├── onshape.example.json
│       └── generic_rest.example.json
├── scripts/pm_smoke.py           # live read-only PM-tool ping
└── tests/                        # pytest, 19 tests

Iterative loop -- design intent

Real projects do not move linearly:

development beginning during the planning phase ... in a repeated loop of plan -> develop -> update plan -> update design -> update plan

Two design choices keep this honest:

1. plan_revision.maturity is part of the schema. Values vague | draft | baselined | frozen let tools accept partial data when the plan is intentionally exploratory, and tighten enforcement as the plan hardens. Profile small_team never enforces scope_baselined_before_release; enterprise does.
2. Every PDM/Git event lands in sync.events[]. The rule engine can promote any of those into plan_revision.change_log, which is the "plan updated because design changed" loop. There is no model where a released deliverable is locked -- it can move back to in_dev and projectstate_diff will surface that to the PM.

PDM connection model

The skill ships one configurable HTTP adapter (pdm_http) plus a file-based adapter for tests. The user describes the actual PDM at call time. Connection templates for SolidWorks PDM, Windchill, Teamcenter, Onshape, and a generic REST surface live in examples/connections/. Custom non-HTTP transports register at runtime via pdm_bridge.hardware.pdm.register_adapter(name, fetcher).

Standards

Concern	Source
Core governance	PMBOK 7 (PMI, 2021); APM BoK (APM, 2023)
Resource competency	IPMA ICB4 (Moradi et al., 2020)
Hardware stage-gates	PRINCE2 (Vanickova, 2017)
Sprint cadence + DoD	Extended Scrum (Wagenaar et al., 2016)
Multi-team scaling	SAFe (Turetken et al., 2017)
ITTO patterns	PMBOK 5 ITTO reference (PMI), used to shape I/O

See skills/pdm-bridge/SKILL.md for the reference list with DOIs.

Status

• Full schema + Pydantic model.
• MCP server with 13 tools (project_bootstrap, pdm_sync, git_sync, core_recompute, sync_evaluate, pm_pull, pm_push, dashboard_render, …).
• 4 slash commands.
• 4 PM adapters (ClickUp, Monday, Asana, Jira) with mocked tests + optional live smoke (scripts/pm_smoke.py).
• 19 tests passing on Python 3.10/3.11/3.12 (CI: .github/workflows/ci.yml).
• Read-only by default. Mutating tools require --enable-writes.