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:

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.1 (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):
  copy

  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.

Layer 2 · Stages (11)

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

Layer 3 · Tools (24)

Specialized stages you can invoke explicitly.

• 🎨 Design (4): /pdlc-ui-design · /pdlc-ui-design-pro · /pdlc-db-design · /pdlc-arch
• 🔍 Quality (5): /pdlc-quality (the standing gate — run real checks, verify every core flow has a passing E2E via an explicit flow→test map, reconcile the flow list against PRDs, then a human signs off) · /pdlc-test-setup (lay the objective-check foundation — detect the stack, verify each command really runs, then write test-commands.yml; unverified commands are left blank rather than guessed) · /pdlc-lint · /pdlc-perf · /pdlc-security
• 🔧 Engineering (7): /pdlc-code-gen · /pdlc-add-service · /pdlc-add-app · /pdlc-api-mock · /pdlc-db-migrate · /pdlc-i18n · /pdlc-changelog
• 🔗 Governance (2): /pdlc-standard · /pdlc-relate
• 🏗️ Project lifecycle (3): /pdlc-bootstrap · /pdlc-adopt · /pdlc-onboard
• 🔁 Loop tooling (2): /pdlc-loop-next (prints the next mechanical-convergence command) · /pdlc-loop-run (convergence engine: auto-advances tdd → implement → review to review_done; release stays human) — design
• ⚙️ Settings (1): /pdlc-settings (interactive config; currently the optional PDLC statusline — enable/disable/display items) — design

3-step quick start

1. Install (one-line, no clone):
   copy

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

2. Ship a feature: in Claude Code, run /pdlc-feature add a captcha to login
3. Fix a bug: /pdlc-fix the pagination crash on empty lists

Check progress anytime: /pdlc-status.

Target-project contract

When a stage runs, it reads and writes these paths in your project:

docs/ARCHITECTURE.md                                        # surface · whole-system overview (pdlc-arch, in-place)
docs/GLOSSARY.md                                            # surface · project vocabulary
docs/00_standards/                                          # surface · team conventions (pdlc-standard; read by prd / implement / tdd / code-gen / onboard)
docs/00_standards/test-commands.yml                        # surface · single source of check commands (unit/coverage/lint/e2e) for tdd / implement / review + loop drivers

The check commands in test-commands.yml are the objective source of truth for last_phase_result.checks (real exit codes, never model self-audit) — the foundation that lets /pdlc-loop-* drive PDLC autonomously. See docs/decisions/0001-loop-engineering-integration.md.

docs/01_requirements/prd/                                   # PRDs
docs/02_design/{api,database,architecture,ui-ux}/           # technical design
docs/03_development/                                        # developer manuals (onboard writes here)
docs/04_testing/{unit-tests,e2e-tests,defects,security,perf}/   # tests & defects
docs/05_deployment/                                         # deployment docs
docs/06_tasks/                                              # in-stage task tracking
docs/07_reviews/{doc,code,design,retro,quality}/            # review records + quality reports
docs/.pdlc-state/<feature-id>.json                          # state machine + relations (one per feature, e.g. F20260419-090000.json)
docs/.pdlc-state/_relations.json                            # auto · reverse index of feature relations (pdlc-relate)
docs/.pdlc-state/_graph.md                                  # auto · mermaid relation graph

Document templates

references/templates/ ships 11 standard document templates that Claude fills in per feature:

• prd-template.md — Product Requirements Document
• api-design-template.md — API design
• arch-design-template.md — Architecture design (per-feature, ledger)
• architecture-overview-template.md — Whole-system architecture overview (surface)
• db-design-template.md — Database schema design
• db-migrate-template.md — DB migration script
• test-plan-template.md — Test plan
• deploy-doc-template.md — Deployment manual
• changelog-template.md — Changelog entry
• glossary-template.md — Project glossary (surface)
• adopt-report-template.md — Legacy-project adoption report

The Iron Law

Every Layer 1 / Layer 2 stage that produces artifacts enforces six invariants. Read-only stages (such as /pdlc-status) are exempt.

1. Persist to disk — every artifact is a real file, not just chat output
2. Update the state machine — every completed stage writes docs/.pdlc-state/<feature-id>.json
3. Tests first — code cannot be implemented until a failing test exists (TDD red light)
4. Self-check — every stage runs a self-audit before handing off
5. One-shot repair — auto-fix loops run at most once; stubborn failures get flagged for humans
6. State must advance — a successful stage must change current_stage; a stage that didn't advance fails loudly instead of returning silently (so autonomous loops can't spin on stale state) — the exception is a deliberate human-block, which stays put but records blocked_reason

Questions / discussion

For usage questions, design discussions, or "is this a bug or am I holding it wrong" — please use GitHub Discussions rather than opening an Issue.

For confirmed bugs and feature requests, open an Issue with the bundled templates.

For private security concerns, see SECURITY.md.

Development

Run the tests locally:

bash tests/frontmatter-check.sh   # validate every sub-skill's frontmatter
bash tests/install-smoke.sh       # end-to-end install + layout checks

See CONTRIBUTING.md for PR workflow and coding conventions.

User manual: docs/usage-guide.md · Release notes: CHANGELOG.md.

💖 Support this project

PDLC is built and maintained in spare time. The zero-cost way to support it: leave a ⭐ star — stars are how other Claude Code users discover this project. If it saves you hours (or sanity) and you want to go further:

Donation channels:

• 🇨🇳 Afdian (爱发电) — for users in China; Alipay / WeChat Pay; native support for monthly tiers and one-time tips.
• 🌍 PayPal — for international users; any amount, one-time.

Tiers (Afdian — choose monthly or one-time at the same amount):

If you donate via PayPal, please drop your GitHub handle in a SPONSORS issue so we can add you to the list. The list is updated monthly — see SPONSORS.md.

License

MIT — use it, fork it, ship it.