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 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.0 (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.
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/. A human signs off; the tool only reports facts.
Two things keep "all core flows are covered" from becoming an opinion:
- 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.
- 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.
- 🎨 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
- Install (one-line, no clone):
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global
- Ship a feature: in Claude Code, run
/pdlc-feature add a captcha to login
- 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 Documentapi-design-template.md — API designarch-design-template.md — Architecture design (per-feature, ledger)architecture-overview-template.md — Whole-system architecture overview (surface)db-design-template.md — Database schema designdb-migrate-template.md — DB migration scripttest-plan-template.md — Test plandeploy-doc-template.md — Deployment manualchangelog-template.md — Changelog entryglossary-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.
- Persist to disk — every artifact is a real file, not just chat output
- Update the state machine — every completed stage writes
docs/.pdlc-state/<feature-id>.json
- Tests first — code cannot be implemented until a failing test exists (TDD red light)
- Self-check — every stage runs a self-audit before handing off
- One-shot repair — auto-fix loops run at most once; stubborn failures get flagged for humans
- 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):
| Tier | Afdian | PayPal equivalent | What you get |
|---|
| ☕ Tip | ¥10 one-time | $1+ one-time | Thank-you. Not listed. |
| 🌱 Backer | ¥30/month | $5+ one-time | Your name on SPONSORS.md |
| 🌳 Sponsor | ¥66/month | $20+ one-time | Name + avatar + link on SPONSORS.md |
| 🏢 Enterprise | ¥888/month | $100+/month | Logo + link at the top of README.md |
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.
