Orange-pm

A Claude Code plugin for product-management planning automation.

No vendor lock-in: external integrations (wiki, chat, design, repo, tasks) are auto-detected from whatever MCP servers/connectors you have attached. With no connectors at all, the entire workflow still runs on local files.

---

Installation

1. Install the plugin

In any Claude Code session:

/plugin marketplace add weg-9000/Orange-pm
/plugin install orange-pm@orange-pm

That's it — you do not need to clone this repository. The plugin ships everything, including the workspace scaffolding.

2. Create your workspace (Planning-Agent-Hub)

The plugin operates on a dedicated working directory called the Planning-Agent-Hub. Create an empty directory anywhere and open Claude Code in it:

mkdir my-planning-hub
cd my-planning-hub
claude

Then run:

/init-hub

This scaffolds the entire Hub structure in the current directory:

my-planning-hub/
├── CONTEXT/              # PM profile, planning rules, doc-tone, stakeholders
│   ├── layer-config.md   #   PREFIX & document-layer settings
│   ├── connectors.md     #   optional capability → MCP tool mapping
│   └── gates/            #   phase-gate criteria (5 files)
├── PROJECTS/             # all deliverables, one subdirectory per product
├── templates/            # graph schema, work-order format
└── .claude/CLAUDE.md     # session entry rules

⚠️ Always run Claude Code from the Hub directory. All skills and hooks resolve paths relative to the current working directory. Running from anywhere else will fail the environment check.

3. Connect external tools — optional

The plugin bundles no MCP servers and hardcodes no vendors. At runtime, skills detect whichever MCP servers/connectors you have attached and use them by capability:

capability	Used for	Example services
wiki	publish & read documents	Confluence, Notion
chat	read messages, send notices	Slack, Mattermost
design	browse design files	Figma
repo	MRs/PRs & issues	GitLab, GitHub
tasks	schedules & assignments	Jira, Asana

Attach connectors the normal Claude Code way (claude mcp add <name> ... or Settings → Connectors). Authentication lives in each MCP server's own config — the plugin never asks for tokens or environment variables.

If several tools serve the same capability, declare your preference in the Hub's CONTEXT/connectors.md. Full protocol (detection order, graceful degradation): CONNECTORS.md.

No connectors? No problem. Every phase from Discovery through Integrate runs entirely on local files; publish/notify steps simply offer --local-only or are skipped with a marker.

---

Quick Start

# Open Claude Code in your Hub directory
# → the SessionStart hook prints current phase & open items automatically

/discover dbaas          # Phase -1: start a new project
/research dbaas          # competitor analysis
/stakeholder dbaas       # collect stakeholder requirements
/product-audit dbaas     # audit your own product
/draft-req dbaas         # synthesize the requirements doc
/lc dbaas                # verify phase gates
/ingest dbaas            # Phase 0: project structure & doc sync
/graph-gen dbaas         # build the dependency graph
/fanout dbaas            # Phase 1: generate Work Orders
/flow dbaas S-001        # Phase 2: screen interaction sequences
/review draft.md         # validate a draft
/critique {URL or file}  # critical review of policy/screen specs
/integrate dbaas         # Phase 3: cross-validation
/confirm dbaas           # Phase 4: freeze v1.0
/cr dbaas                # publish to wiki (wiki connector · --local-only)
/su dbaas                # notify stakeholders (chat connector)

---

Phase Flow

Phase -1  Discovery       /discover /research /stakeholder /product-audit /draft-req
    ↓ [discovery-exit-gate]
Phase  0  Ingest & Graph  /ingest /graph-gen
    ↓ [policy-entry-gate]
Phase  1  Fanout          /fanout
    ↓
Phase  2  Draft           /explore /flow /review /critique   (1 Work Order = 1 session)
    ↓
Phase  3  Integrate       /integrate   (max 3 rounds)
    ↓ [integration-exit-gate]
Phase  4  Confirm         /confirm → /cr → /su

Run /lc {product} before advancing — it validates every gate condition.

---

Session Management

• Session start — the SessionStart hook prints the current phase, open P0 items, the last Work Order, and the next recommended skills.
• Session end — /sc {product} writes session-log.md and RESUME.md.
• Session resume — on the next launch, the SessionStart hook restores context from RESUME.md.

---

Advanced: Vector search — optional

/search finds related nodes/chunks to gather context before /explore, surface candidate conflicts for /integrate, or locate a policy quickly. By default it runs a local BM25 approximation over graph.json — no infrastructure required.

For semantic (kNN) ranking, you can attach a self-hosted Neo4j 5.x vector store:

# 1. Start the vector store (once, on a VM/host)
cd deploy/neo4j
cp .env.example .env          # set NEO4J_PASSWORD etc. (.env is gitignored)
docker compose up -d

# 2. Install client-side extras (ingestion/search host)
pip install -r deploy/neo4j/requirements-vector.txt

# 3. Load + embed, then search with vector ranking
python scripts/graph_to_neo4j.py     # base-load graph.json into Neo4j
python scripts/embed_pipeline.py      # build chunk embeddings + vector index

Embeddings default to a local sentence-transformers model (no API key); set ORANGE_EMBED_MODEL=voyage-3 + VOYAGE_API_KEY to use Voyage cloud instead.

Graceful degradation: if Neo4j is unreachable or the embedding index is missing, /search falls back to BM25-only and marks results [vector search skipped] — nothing breaks. /lc reports embedding staleness so you know when to re-run embed_pipeline.py.

---

Updating & Versioning

• The SessionStart hook checks for new commits (24 h TTL) and prints a one-line notice when an update is available.
• Update with /orange-pm:update or /plugin marketplace update orange-pm.
• Releases follow SemVer; per-version notes live on GitHub Releases. Maintainers bump versions with python scripts/bump_version.py patch|minor|major.

---

Requirements

• Claude Code v1.0+
• Python 3.10+ on PATH (hooks & validation scripts) — pip install -r requirements.txt
• An empty directory for the Hub (scaffolded by /init-hub)
• (optional) MCP servers/connectors for external integrations — see CONNECTORS.md
• (optional) Neo4j + vector extras for semantic /search — see Advanced: Vector search