pdlc

pdlc-skills

English · 中文

Author: kanfu-panda Repo: github.com/kanfu-panda/pdlc-skills License: MIT

pdlc-skills turns AI software engineering into an auditable, on-disk state machine. It's a Claude Code plugin shipping a staged PDLC (Product Development Life Cycle) workflow — PRD → design → TDD → implement → review → ship → retro — where every stage enforces hard contracts (artifacts persisted to docs/, per-feature state machine, tests-before-code, mandatory self-check, single-shot auto-repair), so AI work produces real, reviewable files instead of chat-only output.

Three things fall out of that state machine:

• Auditable — every artifact lands on disk; you git diff exactly what the AI did.
• Autonomous — checks come from real command exit codes (never model self-report), so an autonomous loop can drive tdd → implement → review to convergence unattended, with fail-stop, stuck-stop, and budget guards.
• Portable — the state machine lives in your repo, so it's tool-agnostic. Claude Code has the richest integration (38 slash commands + statusline + in-plugin loop engine); Codex (Claude-Code-compatible distributions) and others drive the same methodology via adapters. See Multi-platform.

---

Why PDLC

Without this plugin, an AI assistant working on a feature typically:

• Says it built the feature, but the PRD lives only in the chat transcript.
• Writes code without writing tests first.
• Skips the design step, which means architectural drift accumulates silently.
• Has no memory between sessions of which stage a feature is in.

PDLC turns those soft conventions into hard contracts:

Hard contract	What it gives you
Every artifact lands on disk under docs/	You can git diff what the AI did
Every stage updates a per-feature state machine	/pdlc-status always knows where you are
Tests must exist (and fail) before implementation	Real TDD red-light gate, not a suggestion
Each stage runs a self-check before handing off	Catch drift at stage boundary, not in review
Auto-repair runs at most once	No infinite "fix → check → fix" loops
Each stage declares its next_step	Multi-stage flows are command-driven, not memorized

---

Quick demo

A typical end-to-end flow looks like this:

$ # In Claude Code:
$ /pdlc-feature add phone-number verification to user login

→ Allocating feature ID F20260502-090000 (user-auth-phone)
→ Stage 1: writing PRD
   ✓ docs/01_requirements/prd/F20260502-090000-user-auth-phone-prd.md
   ✓ self-check 8/8 passed
→ Stage 2: technical design
   ✓ docs/02_design/api/F20260502-090000-user-auth-phone-api.md
   ✓ docs/02_design/database/F20260502-090000-user-auth-phone-db.md
→ Stage 3: TDD red light
   ✓ 14 tests written, all failing as expected
→ Stage 4: implementation
   ✓ 14/14 tests now passing
→ Stage 5: code review + auto-repair
   ✓ 3 lint issues auto-fixed
   ✓ docs/07_reviews/code/F20260502-090000-user-auth-phone-review.md
→ Stage 6: handoff
   📦 docs/.pdlc-state/F20260502-090000.json updated
   👉 Next: /pdlc-ship

Every artifact above is a real file you can git diff. Run /pdlc-status any time to see where each feature stands. (Output above is illustrative — actual Claude Code output is markdown, not ASCII.)

---

Install

One-liner — no manual clone needed.

# Global (~/.claude/plugins/pdlc/)
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --global

# Project-scoped (<project>/.claude/plugins/pdlc/)
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --project /path/to/my-project

That's it. The installer is a thin wrapper around claude plugin marketplace add + claude plugin install: it registers the marketplace source and installs the plugin into your .claude/plugins/pdlc/ directory.

Upgrade

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --upgrade --global

Uninstall

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --uninstall --global

Check your version

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --version

Equivalent native commands

If you'd rather call Claude Code's plugin CLI directly:

claude plugin marketplace add kanfu-panda/pdlc-skills
claude plugin install pdlc@pdlc-skills

For contributors / template customization

git clone https://github.com/kanfu-panda/pdlc-skills.git
cd pdlc-skills
# edit references/templates/*.md or skills/pdlc-*/SKILL.md
bash install.sh --global   # installs from your local clone

---

Verify the install

claude plugin list | grep pdlc
# expected: pdlc@pdlc-skills  Version: 1.6.4 (or newer)  Status: ✔ enabled

In Claude Code (after restarting the session), type / and start typing pdlc- — you should see all 38 sub-commands (/pdlc-feature, /pdlc-prd, /pdlc-tdd, ...) in autocomplete.

---

Multi-platform (other AI coding tools)

Claude Code has the richest integration — 38 slash commands + statusline + in-plugin autonomous loop. But the PDLC methodology, state machine, and templates are platform-neutral: the same docs/.pdlc-state/ carries over no matter which tool drives it, so you can switch tools (or share a repo across a team on different tools) without losing PDLC state.

• Any tool (Codex, Cursor, Windsurf, Copilot, Cline, …): use the platform-neutral methodology doc docs/pdlc-methodology.md as your project rules (AGENTS.md / .cursor/rules / .github/copilot-instructions.md / …), then drive PDLC in natural language ("run the PDLC review stage" → the agent follows the doc).
• Codex (native skills — for Claude-Code-compatible Codex distributions):

  git clone https://github.com/kanfu-panda/pdlc-skills.git
  cd pdlc-skills && bash install.sh --target codex
  

  Builds the adapter and installs 34 pdlc skills into ~/.codex/skills/ (the 2 Claude Code-only skills — statusline config + the autonomous loop engine — are skipped). Codex skills are description-triggered, not slash commands — after restarting Codex, drive PDLC in natural language (e.g. 用 pdlc 写个 PRD：<一句话需求>). Requires a local clone + python3. Remove with bash install.sh --target codex --uninstall.
  • Autonomous convergence on Codex: adapters/codex-loop-run.sh <feature-id> --project <dir> drives tdd → implement → review to review_done (external Runbook; release stays human). Cleared the state-integrity admission gate on a real run — see ADR 0004.
  • ⚠️ Scope — not verified on vanilla OpenAI Codex. The adapter was validated only on a Codex distribution that reads ~/.codex/skills/; we have no vanilla environment to test on. If Codex ignores the skills after a restart, it doesn't read that directory — fall back to the platform-neutral route above (methodology doc in AGENTS.md), which needs no adapter. Reports from vanilla users are welcome via issues.

Cursor / Windsurf / Copilot native adapters are planned per real demand. Design & roadmap: ADR 0003.

---

Autonomous convergence (loop engineering)

Because every stage writes objective checks — real unit / lint / coverage exit codes from docs/00_standards/test-commands.yml, never model self-report — to a machine-readable state machine, an outer loop can drive the mechanical stages to done without a human in the seat:

• /pdlc-loop-run <feature-id> — the convergence engine: auto-advances tdd → implement → review to review_done, with an iteration cap, fail-stop (a stage reports ok:false → stop), and stuck-stop (state didn't advance → stop). Release always stays human — it never auto-ships.
• /pdlc-loop-next <feature-id> — read-only helper that prints the next convergence command, for your own shell loops.
• On Codex — adapters/codex-loop-run.sh drives the same loop externally (cleared a real-machine state-integrity gate — see ADR 0004).

Design: ADR 0001.

---

Quality gate

The same objective-checks discipline, promoted from a per-feature stage to a standing gate:

• /pdlc-test-setup — lays the foundation: detects your stack, runs every candidate command once and watches the exit code, then writes docs/00_standards/test-commands.yml. Commands that don't actually run are left blank with a note on how to fill them, never guessed — a plausible-but-broken command would silently corrupt every downstream stage's checks.
• /pdlc-quality — runs the real checks, compares them against docs/00_standards/quality-targets.yml, and writes a dated report to docs/07_reviews/quality/ — Markdown (the source of truth, git diff-able and read by /pdlc-ship as a release gate) plus a self-contained HTML view of the same data, ready to open, print and sign. A human signs off; the tool only reports facts.

Two things keep "all core flows are covered" from becoming an opinion:

1. An explicit core_flow → E2E test map (docs/00_standards/e2e-flow-map.yml) turns coverage into a matrix you can check mechanically. A mapping that points at a test which didn't run is rot — reported red, not skipped.
2. PRD reconciliation — every run diffs the P0/P1 flows in your PRDs against the declared core_flows, and drift is a red light. A stale flow list is the dangerous failure mode: the matrix goes green while reality has holes, dressing up "we don't know" as "we're covered".

Anything that can't be measured is reported as unmeasured, never as passing. Design: ADR 0005.

---

Stage catalog (three layers)

Layer 1 · Entry points (3)

One-sentence prompts drive the whole chain.

Slash command	Purpose
/pdlc-feature	End-to-end new feature (PRD → Design → TDD → Implement → Review → Ship)
/pdlc-fix	End-to-end bug fix (locate → reproduce → fix → test → document)
/pdlc-status	Show the project's PDLC state at a glance

Layer 2 · Stages (11)

Use when you want fine-grained control over one stage.

Slash command	Purpose
/pdlc-prd	Author a PRD
/pdlc-design	Technical design
/pdlc-tdd	Write failing tests first
/pdlc-implement	Implement code against the design
/pdlc-review	Code + doc review
/pdlc-e2e	End-to-end tests
/pdlc-refactor	Refactor code
/pdlc-ship	Release workflow (tests → VERSION → CHANGELOG → tag → CI)
/pdlc-deploy	Deployment doc
/pdlc-retro	Iteration retrospective with trend comparison
/pdlc-task	In-stage task tracking

Layer 3 · Tools (24)

Specialized stages you can invoke explicitly.