npm package: @pdlc-os/pdlc
Description: Product Development Lifecycle — a Claude Code plugin for small startup-style teams
Latest version: 2.6.0

# PDLC — Product Development Lifecycle

A Claude Code plugin that guides small startup-style teams (2-5 engineers) through the full arc of feature development — from raw idea to shipped, production feature — using structured phases, a named specialist agent team, persistent memory, and safety guardrails.

PDLC combines the best of four Claude Code workflows:

- **[obra/superpowers](https://github.com/obra/superpowers)** — TDD discipline, systematic debugging, visual brainstorming companion
- **[gstack](https://github.com/garrytan/gstack)** — specialist agent roles, sprint workflow, real browser automation
- **[get-shit-done-cc](https://github.com/gsd-build/get-shit-done)** — context-rot prevention, spec-driven execution, file-based persistent memory
- **[bmad-method](https://github.com/bmadcode/bmad-method)** — adversarial review, edge case analysis, divergent ideation, multi-agent party mode
- plus additional features missing from these workflows including what-if analysis, roadmap pivots, etc.

---

## Why PDLC?

### Smart-handling of Tokens & Context

- PDLC is built to minimize context window consumption. It estimates context usage by tracking tool calls and token accumulation, warning at ~50% estimated usage and auto-checkpointing STATE.md at ~65% so no work is lost (thresholds are configurable in CONSTITUTION.md).
- Different models are used for different tasks — Haiku for setup/install operations, Opus for complex reasoning, Sonnet for focused specialist work. 
- Skills are loaded as markdown files on demand (not kept in context), and Agent Teams mode is the default so multi-agent work happens in separate context windows rather than consuming a single one. 
- Completed features are automatically archived and Beads is purged/compacted to reduce context noise from stale artifacts.

### Multi-developer ready

Multiple developers can work on the same PDLC-enabled repo. Every phase starts with a remote sync check — if local main is behind origin, a 6-agent team meeting assesses the remote changes for conflict risk before you proceed. The doctor command detects multi-user edits, rollbacks, and cross-session drift. Each developer runs their own local PDLC hooks via `npm install` — the shared state lives in `docs/pdlc/` in git.

### Scenario planning at any stage

Use `/pdlc whatif` at any point during inception or construction to explore hypothetical changes with a full 9-agent read-only analysis — no files are modified. If the analysis looks promising, convert it to a formal decision. Use `/pdlc decision` to pivot the design mid-flight — the team assesses blast radius across code, tests, architecture, roadmap, and documentation before anything changes.

### Full decision traceability

Every decision is recorded in the Decision Registry (DECISIONS.md) with who decided, when, why, and what was impacted. Every team meeting produces minutes (MOM files). Every shipped feature has an episode file with metrics, retro notes, and lessons learned. Tier 1 safety overrides are permanently logged. The entire project history is human-readable markdown in git.

### Visual brainstorming companion

During inception, PDLC can run a local browser-based UI (Material Design, light/dark toggle) for mockups, wireframes, architecture diagrams, and side-by-side comparisons. Users can click to select options in the browser or type feedback in the terminal — both inputs are merged. The server handles port conflicts, crashes gracefully, and falls back to text-only mode if it can't start.

### Plug-and-play extensibility

Add custom skills (`.pdlc/skills/<name>/SKILL.md`), custom agents (`.pdlc/agents/<name>.md`), and custom test layers (CONSTITUTION.md table) without forking. Templates are provided for both skills and agents. Custom agents are automatically included in team meetings when task labels match.

---

## Table of Contents

1. [Why PDLC?](#why-pdlc)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Documentation](#documentation)
5. [PDLC-OS Marketplace](#pdlc-os-marketplace)
6. [Prerequisites](#prerequisites)
7. [License](#license)

---

## Installation

PDLC can be installed **locally** (per-repo, recommended for teams) or **globally** (all projects on your machine). Both Beads (the task manager) and PDLC itself are installed with the same scope — you'll be prompted to approve Beads installation automatically.

### Local install (recommended)

Installs PDLC and Beads as devDependencies inside your repo. Hooks are written to `.claude/settings.local.json` so they only apply to this project.

```bash
cd your-repo
npm install --save-dev @pdlc-os/pdlc
```

The postinstall script auto-detects local context, registers hooks in `.claude/settings.local.json`, and prompts you to install Beads locally too.

Or install explicitly with the `--local` flag:

```bash
npx @pdlc-os/pdlc install --local
```

### Global install

Registers hooks in `~/.claude/settings.json` so PDLC is available across all projects. Beads is installed globally too.

```bash
npm install -g @pdlc-os/pdlc
```

Or without a global install:

```bash
npx @pdlc-os/pdlc install
```

Or directly from GitHub (always latest):

```bash
npm install -g pdlc-os/pdlc
```

### Install from source (offline / restricted networks)

If the npm registry is blocked (e.g., corporate firewalls), you can build a tarball from the Git repository and install from that.

```bash
# Clone the repo and build the tarball
git clone https://github.com/pdlc-os/pdlc.git
cd pdlc
npm pack
```

This produces a file like `pdlc-os-pdlc-2.3.1.tgz`. Install it locally or globally:

```bash
# Local (from your project directory)
cd /path/to/your-repo
npm install --save-dev /path/to/pdlc/pdlc-os-pdlc-2.3.1.tgz

# Global
npm install -g /path/to/pdlc/pdlc-os-pdlc-2.3.1.tgz
```

The postinstall script runs the same way as a registry install — hooks are registered and you'll be prompted to install Beads and Dolt.

> **Tip:** To share with teammates on the same restricted network, distribute the `.tgz` file via internal file share, Artifactory, or email. Each developer runs `npm install` against the tarball path.

### Verify installation

```bash
npx @pdlc-os/pdlc status
```

Shows install mode (local/global), plugin root path, hook registration, and Beads status.

### Uninstall

**Local** (from inside the repo):

```bash
npx @pdlc-os/pdlc uninstall --local
```

Removes PDLC hooks from `.claude/settings.local.json` and slash commands from `.claude/commands/`. You'll be prompted to uninstall Beads as well.

**Global:**

```bash
npx @pdlc-os/pdlc uninstall
```

Removes PDLC hooks from `~/.claude/settings.json` and slash commands from `~/.claude/commands/`. You'll be prompted to uninstall Beads globally too.

> **Note on Beads:** If your repo is already tracking tasks in Beads (`.beads/` directory), uninstalling Beads removes the CLI but your task data remains on disk. You won't be able to query or manage those tasks without the `bd` command. The uninstaller warns you about this before proceeding and defaults to keeping Beads installed.
> 
> **Note on Dolt:** If you uninstall Beads, you'll also be prompted to uninstall Dolt (the SQL database Beads uses). Dolt is a system-level binary — other tools may depend on it, so the uninstaller defaults to keeping it.

### Upgrade

```bash
# Local
npx @pdlc-os/pdlc upgrade --local

# Global
npx @pdlc-os/pdlc upgrade
```

The `upgrade` command:

1. Upgrades PDLC to the latest version (matching your install scope)
2. Re-registers hooks and slash commands with updated paths
3. Prompts to upgrade Beads as well (defaults to yes)
4. Prompts to upgrade Dolt as well (defaults to yes)
5. **Migrates project templates** — detects new sections added to CONSTITUTION.md, STATE.md, METRICS.md, etc. and appends them without touching your customizations. Creates missing files (e.g., METRICS.md if upgrading from a version that didn't have it). Ensures archive directories exist.

Template versioning: each template has a `<!-- pdlc-template-version: X.Y.Z -->` comment. The upgrade command compares your file's version against the current template, finds missing sections, and appends them. Your customized content is never overwritten.

Re-running `install` is also idempotent — it strips old hook paths and re-registers with the current version. Switching from global to local (or vice versa) automatically cleans up the previous install.

### Team onboarding (new team member pulls the repo)

When another developer clones or pulls a repo that already has PDLC initialized, they need to install PDLC locally to activate the hooks and slash commands. The project's `docs/pdlc/` memory files are already in git — they just need the tooling.

**Step 1 — Install PDLC and dependencies:**

```bash
npm install
```

If `@pdlc-os/pdlc` is in `devDependencies`, this installs it and runs the postinstall hook automatically — registering PDLC hooks in `.claude/settings.local.json` and copying slash commands to `.claude/commands/`. You'll be prompted to install Dolt and Beads if they're not already on your machine.

**Step 2 — Verify:**

```bash
npx @pdlc-os/pdlc status
```

You should see:

```
Install mode : local (this repo)
Dolt         : ✓ installed
Beads (bd)   : ✓ installed
Hooks registered: statusLine, PostToolUse, PreToolUse, SessionStart
```

**Step 3 — Start a Claude Code session:**

PDLC reads `docs/pdlc/memory/STATE.md` on session start and resumes from wherever the project left off. You'll see the current phase, active feature, and any pending work. The full memory bank (Constitution, Intent, Roadmap, Decisions, etc.) is already in the repo — no need to re-run `/pdlc init`.

> **Note:** Each developer's `.claude/settings.local.json` is local to their machine (not committed to git). The hooks point to the PDLC package in their `node_modules/`, so each developer needs their own `npm install`. The project's `docs/pdlc/` files are shared via git — this is the team's shared memory.

---

## Quick Start

Once installed, open any project in Claude Code:

```
/pdlc init
```

PDLC asks 7 questions about your project, scaffolds the memory bank, then **Oracle brainstorms a feature roadmap with you** — identifying, describing, and prioritizing 5-15 features in `ROADMAP.md`. Then start your first feature:

```
/pdlc brainstorm user-authentication
```

Work through Inception (discovery, PRD, design, plan), then:

```
/pdlc build
```

Build, review, and test the feature with TDD and multi-agent review. When ready:

```
/pdlc ship
```

Merge, deploy, reflect, and commit the episode record. After shipping, **Oracle reviews the roadmap and offers the next feature** — you can continue, pause, or switch to something else. The cycle repeats until the roadmap is complete.

At any point during inception or construction, record a decision or explore a scenario:

```
/pdlc decision We should use PostgreSQL instead of MongoDB
```

This triggers a **Decision Review Party** where all 9 agents assess cross-cutting impacts, produce minutes of meeting, and reconcile downstream effects (Beads tasks, PRDs, design docs, tests, roadmap sequencing) — all with your approval before any changes are applied.

```
/pdlc whatif What if we switched from REST to GraphQL?
```

This runs a **read-only What-If Analysis** — all 9 agents assess the hypothetical without changing any files. You can explore further, discard, or accept it as a formal decision.

If a feature turns out to be unviable, abandon it cleanly:

```
/pdlc abandon
```

This closes all Beads tasks, marks the feature as Dropped in the roadmap, creates an abandonment episode, and hands off to the next feature. All artifacts (PRD, design docs, branch) are preserved for reference.

Need to step away or switch context? Pause cleanly and resume later:

```
/pdlc pause
/pdlc resume
```

Pause saves your exact position (phase, sub-phase, active task). Resume rebases on main, reclaims your Beads task, and picks up where you left off.

If production is on fire:

```
/pdlc hotfix fix-login-crash
```

This **auto-pauses** your current feature, creates a hotfix branch, runs a compressed TDD build-ship cycle (no brainstorm/design), and after shipping the fix, **auto-resumes** your paused feature with an impact assessment and rebase.

If a shipped feature needs to be reverted:

```
/pdlc rollback user-authentication
```

This reverts the merge commit, runs a **Post-Mortem Party** with all 9 agents to diagnose the root cause, and presents 3 ranked fix approaches. You can fix and re-ship, abandon the feature, or pause.

If something feels off — after pulling a teammate's changes, after a rollback, or after a long break:

```
/pdlc doctor
```

This runs a **comprehensive health check** — 8 checks covering state file integrity, ROADMAP/STATE consistency, Beads task graph (including `bd doctor` for internal Beads health), document-vs-code drift, git rollback and multi-user detection, and Constitution compliance. Read-only by default, with optional fix mode.

---

## Documentation

Detailed documentation is organized in the [docs/wiki](docs/wiki/) folder:

### Overview & Flow

| #   | Document                                                 | What it covers                                                                                          |
| --- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 01  | [The PDLC Flow](docs/wiki/01-pdlc-flow.md)               | Summary and detailed Mermaid flow diagrams, approval gates                                              |
| 02  | [Feature Highlights](docs/wiki/02-feature-highlights.md) | Capabilities by phase: inception, construction, operation, decisions, what-if, cross-cutting            |
| 03  | [Phases in Detail](docs/wiki/03-phases-in-detail.md)     | Per-phase Mermaid diagrams, sub-phase tables, lead agents, pivot and scenario planning                  |
| 04  | [Doctor](docs/wiki/04-doctor.md)                         | Comprehensive health check: state consistency, doc/code drift, rollback detection, multi-user conflicts |
| 05  | [Pause & Resume](docs/wiki/05-pause-resume.md)           | Save and restore feature state, Beads task reclaim, rebase on resume                                    |
| 06  | [Hotfix](docs/wiki/06-hotfix.md)                         | Emergency compressed build-ship, auto-pause/resume, impact assessment                                   |
| 07  | [Rollback](docs/wiki/07-rollback.md)                     | Revert shipped features, post-mortem party, 3 ranked fix approaches                                     |
| 08  | [Abandon](docs/wiki/08-abandon.md)                       | Drop in-progress features, clean up tasks/artifacts, abandonment episode                                |

### Team & Meetings

| #   | Document                                                 | What it covers                                                                              |
| --- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 09  | [The Agent Team](docs/wiki/09-agent-team.md)             | 9 specialist agents: roles, models (Opus/Sonnet), focus areas, lead agent assignments       |
| 10  | [Party Mode](docs/wiki/10-party-mode.md)                 | 8 meeting types, meeting map across phases, spawn modes, announcements, durable checkpoints |
| 11  | [Deadlock Detection](docs/wiki/11-deadlock-detection.md) | 6 deadlock types with auto-resolution and human escalation paths                            |

### Architecture

| #   | Document                                                   | What it covers                                                                                      |
| --- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 12  | [Skills Architecture](docs/wiki/12-skills-architecture.md) | Skill file structure, phase skills, supporting skills, directory layout                             |
| 13  | [Memory Bank](docs/wiki/13-memory-bank.md)                 | All `docs/pdlc/` files: memory, PRDs, design docs, reviews, brainstorm logs, MOMs, metrics, archive |
| 14  | [Safety Guardrails](docs/wiki/14-safety-guardrails.md)     | Tier 1 (hard block), Tier 2 (pause), Tier 3 (logged warning) definitions                            |

### Features

| #   | Document                                             | What it covers                                                                             |
| --- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 15  | [Status Bar](docs/wiki/15-status-bar.md)             | Live phase/task/context status bar with configurable thresholds                            |
| 16  | [Visual Companion](docs/wiki/16-visual-companion.md) | Browser-based Material Design UI for mockups and diagrams during Inception                 |
| 17  | [Design Decisions](docs/wiki/17-design-decisions.md) | Rationale for architectural choices: TDD, file-based memory, pivot/scenario planning, etc. |
| 18  | [Extensibility](docs/wiki/18-extensibility.md)       | Custom skills, custom agents, custom test layers — extend PDLC without forking             |

---

## PDLC-OS Marketplace

| Resource           | URL                                                           |
| ------------------ | ------------------------------------------------------------- |
| GitHub org         | https://github.com/pdlc-os                                    |
| Core package       | https://www.npmjs.com/package/@pdlc-os/pdlc                   |
| Registry index     | https://github.com/pdlc-os/registry                           |
| Contribution guide | https://github.com/pdlc-os/registry/blob/main/CONTRIBUTING.md |

The `pdlc-os` GitHub organisation hosts community-contributed extensions:

| Type                    | Examples                                                                  |
| ----------------------- | ------------------------------------------------------------------------- |
| **Workflow templates**  | `@pdlc-os/workflow-saas-mvp`, `@pdlc-os/workflow-api-service`             |
| **Role packs**          | `@pdlc-os/agent-fintech-security`, `@pdlc-os/agent-accessibility-auditor` |
| **Stack adapters**      | `@pdlc-os/stack-nextjs-supabase`, `@pdlc-os/stack-rails-postgres`         |
| **Integration plugins** | `@pdlc-os/integration-linear`, `@pdlc-os/integration-notion`              |
| **Skill packs**         | `@pdlc-os/skill-hipaa`, `@pdlc-os/skill-seo-audit`                        |

---

## Prerequisites

| Dependency                                         | Install                                  | Notes                                                                                     |
| -------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| Node.js >= 18                                      | [nodejs.org](https://nodejs.org)         |                                                                                           |
| Claude Code                                        | [claude.ai/code](https://claude.ai/code) |                                                                                           |
| [Dolt](https://github.com/dolthub/dolt)            | Prompted during PDLC install             | SQL database required by Beads; installed via Homebrew (macOS) or official script (Linux) |
| [Beads (bd)](https://github.com/gastownhall/beads) | Prompted during PDLC install             | Task manager; same scope (local/global) as PDLC                                           |
| Git                                                | Built into macOS/Linux                   |                                                                                           |
| [GitHub CLI (gh)](https://cli.github.com)          | Prompted during `/pdlc init` if needed   | Required for PR creation during `/pdlc ship`; setup guided during init                    |

---

## License

MIT (c) pdlc-os contributors