{
  "markdown": "# Prompt Driven Development (PDD) Skill\n\nA multi-provider Prompt Driven Development toolkit for structuring AI-assisted development with versioned prompts, persistent context, and structured review.\n\nPDD treats prompts as first-class artifacts, not throwaway inputs. This repo currently packages the same core PDD system for Claude Code, GitHub Copilot, Codex, and Google Antigravity. The core workflows are **scaffold**, **init**, **context**, **research**, **plan**, **prompts**, **update**, **review**, **eval**, plus the `status` and `help` utility workflows.\n\nFor simple features, you only need **Context → Prompts → Review**. Research, Plan, and Eval add value for complex or critical features but are not required.\n\n## Installation\n\nPDD is packaged for three surfaces from the same shared core:\n\n| Provider | Adapter | Notes |\n|---|---|---|\n| Claude Code | `providers/claude/` | Claude skill, slash commands, hooks, and plugin metadata |\n| GitHub Copilot | `providers/copilot/` | Copilot prompts plus always-on instructions |\n| Codex | `providers/codex/` | Codex plugin and `pdd` skill adapter |\n| Google Antigravity | `providers/antigravity/` | Antigravity skill, workflows, and `GEMINI.md` workspace rules |\n\n### Claude Code\n\n**Plugin install (recommended):**\n\nRun these commands inside Claude Code (not your terminal):\n\n```\n/plugin marketplace add harshal2802/pdd-skill\n/plugin install pdd-skill\n```\n\nThe plugin system auto-discovers the skill and commands. No manual config needed.\n\n**Manual install:**\n\n```bash\ngit clone https://github.com/harshal2802/pdd-skill.git .claude/skills/pdd-skill\n```\n\nThen add the skill to `.claude/settings.json` (create the file if it doesn't exist):\n\n```json\n{\n  \"skills\": [\".claude/skills/pdd-skill/providers/claude/skills/pdd/SKILL.md\"]\n}\n```\n\n> **Tip:** To pin a specific version, add `--branch v1.5.0` to the clone command. To install globally instead of per-project, clone to `~/pdd-skill` and reference it in `~/.claude/settings.json`.\n\n### GitHub Copilot\n\nClone the repo, then copy these files into your project:\n\n```bash\ngit clone https://github.com/harshal2802/pdd-skill.git /tmp/pdd-skill\n\n# Copy the always-on instructions\ncp /tmp/pdd-skill/providers/copilot/copilot-instructions.md <your-project>/.github/copilot-instructions.md\n\n# Copy the prompt files\ncp -r /tmp/pdd-skill/providers/copilot/prompts/ <your-project>/.github/prompts/\n\n# Copy the reference files (project type flavors)\ncp -r /tmp/pdd-skill/core/references/ <your-project>/.github/references/\n```\n\nIn VS Code Copilot Chat, type `/` to see the available PDD prompt files (e.g. `/pdd-scaffold`, `/pdd-context`). Requires VS Code 1.93+ with Copilot Chat prompt file support.\n\nSee [`providers/copilot/README.md`](providers/copilot/README.md) for the full workflow list and usage details.\n\n### Codex\n\nClone the repo into your project as a local plugin:\n\n```bash\ngit clone https://github.com/harshal2802/pdd-skill.git /tmp/pdd-skill\n\n# Copy the plugin into your project\ncp -r /tmp/pdd-skill/plugins/pdd-skill <your-project>/.codex/plugins/pdd-skill\n\n# Or use the repo-local marketplace entry\ncp /tmp/pdd-skill/.agents/plugins/marketplace.json <your-project>/.agents/plugins/marketplace.json\n```\n\nThe `pdd` skill exposes all workflows (e.g. `pdd:scaffold`, `pdd:context`, `pdd:review`).\n\nSee [`providers/codex/README.md`](providers/codex/README.md) for layout details and the full command table.\n\n### Google Antigravity\n\nClone the repo, then copy these files into your project:\n\n```bash\ngit clone https://github.com/harshal2802/pdd-skill.git /tmp/pdd-skill\n\n# Copy the workspace rules\ncp /tmp/pdd-skill/providers/antigravity/GEMINI.md <your-project>/GEMINI.md\n\n# Copy the skill entrypoint\nmkdir -p <your-project>/.agents/skills/pdd\ncp /tmp/pdd-skill/providers/antigravity/skills/pdd/SKILL.md <your-project>/.agents/skills/pdd/SKILL.md\n\n# Copy the workflow files\nmkdir -p <your-project>/.agent/workflows\ncp /tmp/pdd-skill/providers/antigravity/workflows/*.md <your-project>/.agent/workflows/\n\n# Copy the reference files (project type flavors)\nmkdir -p <your-project>/.agent/references\ncp -r /tmp/pdd-skill/core/references/* <your-project>/.agent/references/\n```\n\nIn Antigravity, the workflow files auto-expose as slash commands (e.g. `/pdd-scaffold`, `/pdd-context`). `GEMINI.md` is used instead of the cross-tool-standard `AGENTS.md` so installing alongside Codex or Cursor does not produce a rules-file collision.\n\nSee [`providers/antigravity/README.md`](providers/antigravity/README.md) for layout details and the full command table.\n\n## Repo Structure\n\nThe repo is now organized into a shared core plus thin provider adapters:\n\n```text\npdd-skill/\n├── core/\n│   ├── workflows/          # Provider-agnostic workflow definitions\n│   ├── references/         # Shared project-type references\n│   ├── examples/           # Shared example PDD projects\n│   └── metadata/           # Workflow + provider metadata\n├── providers/\n│   ├── claude/             # Claude Code skill, commands, hooks, plugin metadata\n│   ├── copilot/            # Copilot prompt files + always-on instructions\n│   └── codex/              # Codex plugin + skill adapter\n├── plugins/\n│   └── pdd-skill           # Codex plugin compatibility path\n└── .agents/plugins/        # Codex repo-local marketplace metadata\n```\n\nThe `.claude-plugin` symlink at the root is required by the Claude plugin system. The `plugins/pdd-skill` path is required by the Codex marketplace. All other top-level compatibility symlinks have been removed — use `core/` and `providers/` paths directly. See [`docs/architecture.md`](docs/architecture.md) for details.\n\n## Maintenance\n\nShared PDD behavior now lives under `core/metadata/` and `core/workflows/`, while provider wrappers under `providers/` contain generated sections where duplication was previously highest.\n\nWhen changing shared behavior:\n\n```bash\npython3 scripts/render_workflow_tables.py\nbash tests/consistency.sh\nbash tests/test-hooks.sh\n```\n\nSee [`docs/maintenance.md`](docs/maintenance.md) for the full maintenance workflow and [`docs/final-architecture-review.md`](docs/final-architecture-review.md) for the final source-of-truth boundaries.\n\n## Project Structure\n\nA PDD project looks like this:\n\n```\nmy-project/\n├── pdd/\n│   ├── prompts/\n│   │   ├── features/        # Prompt files grouped by area (e.g., features/auth/, features/tasks/)\n│   │   │   ├── auth/        #   One subfolder per feature domain, app module, or tool\n│   │   │   └── tasks/\n│   │   ├── templates/       # Reusable prompt patterns\n│   │   └── experiments/     # Exploratory, time-boxed prompts\n│   ├── context/\n│   │   ├── project.md       # What you're building, why, and with what stack\n│   │   ├── conventions.md   # Code style, naming, patterns the AI should follow\n│   │   └── decisions.md     # Architecture decisions and the reasoning behind them\n│   └── evals/               # Tests for prompt quality and output correctness\n│       ├── baselines/       # Known-good outputs for diff comparison\n│       └── scripts/         # Automated validation scripts\n├── src/                     # Reviewed, committed AI-generated artifacts (or user-chosen name)\n└── ...\n```\n\n## Slash Commands\n\nPDD includes slash commands for Claude Code. If you installed via plugin, they're available automatically. For manual installs, copy them into your project:\n\n```bash\n# Only needed for manual installs\ncp -r .claude/skills/pdd-skill/providers/claude/commands/* .claude/commands/\n```\n\nInvoke them in Claude Code:\n\n<!-- GENERATED:claude-command-table:start -->\n| Command | What it does |\n|---|---|\n| `/project:pdd-scaffold` | Set up a new PDD project with folders, context stubs, and starter guidance. |\n| `/project:pdd-init` | Add PDD structure to an existing repository and infer a starting context. |\n| `/project:pdd-context` | Write or update the persistent project context files that future prompts depend on. |\n| `/project:pdd-research` | Explore the problem space, evaluate options, and decide what to build. |\n| `/project:pdd-plan` | Break a feature into phases and decide the prompt chain strategy before coding. |\n| `/project:pdd-prompts` | Generate focused feature prompts and place them in the right PDD folder. |\n| `/project:pdd-update` | Diagnose and improve a prompt that is producing weak or incorrect output. |\n| `/project:pdd-review` | Verify and review AI-generated output before it is committed. |\n| `/project:pdd-eval` | Track prompt quality over time with repeatable evaluation criteria. |\n| `/project:pdd-status` | Check what PDD artifacts exist, what is stale, and what to do next. |\n| `/project:pdd-help` | Show the available workflows, when to use them, and the typical sequence. |\n<!-- GENERATED:claude-command-table:end -->\n\nAll commands accept optional arguments, e.g., `/project:pdd-scaffold my-api` or `/project:pdd-review paste your code here`.\n\nIn Antigravity (workflow files auto-expose as `/`-prefixed slash commands):\n\n<!-- GENERATED:antigravity-command-table:start -->\n| Command | What it does |\n|---|---|\n| `/pdd-scaffold` | Set up a new PDD project with folders, context stubs, and starter guidance. |\n| `/pdd-init` | Add PDD structure to an existing repository and infer a starting context. |\n| `/pdd-context` | Write or update the persistent project context files that future prompts depend on. |\n| `/pdd-research` | Explore the problem space, evaluate options, and decide what to build. |\n| `/pdd-plan` | Break a feature into phases and decide the prompt chain strategy before coding. |\n| `/pdd-prompts` | Generate focused feature prompts and place them in the right PDD folder. |\n| `/pdd-update` | Diagnose and improve a prompt that is producing weak or incorrect output. |\n| `/pdd-review` | Verify and review AI-generated output before it is committed. |\n| `/pdd-eval` | Track prompt quality over time with repeatable evaluation criteria. |\n| `/pdd-status` | Check what PDD artifacts exist, what is stale, and what to do next. |\n| `/pdd-help` | Show the available workflows, when to use them, and the typical sequence. |\n<!-- GENERATED:antigravity-command-table:end -->\n\n## Workflow\n\n```mermaid\nflowchart LR\n    A[\"Scaffold (new)\"] --> B[\"Context\"]\n    A2[\"Init (existing)\"] --> B\n    B --> S{Complex?}\n    S -- Yes --> C[\"Research\"] --> D[\"Plan\"] --> E\n    S -- No --> E[\"Prompts\"]\n    E --> F[\"Run prompt\"]\n    F --> G[\"Review\"]\n    G --> H[\"Commit\"]\n    H -.-> I[\"Eval\"]\n\n    style A2 fill:#3498db,stroke:#2980b9,color:#fff\n    style S fill:#f1c40f,stroke:#d4ac0d,color:#333\n    style C fill:#1abc9c,stroke:#17a589,color:#fff\n    style D fill:#1abc9c,stroke:#17a589,color:#fff\n    style I fill:#f4a460,stroke:#c4824a,color:#fff\n```\n\n**Quick path**: Context → Prompts → Review → commit. Use **Init** instead of Scaffold for existing projects. Add Research and Plan for complex features. Eval is optional for tracking prompt reliability.\n\nUnlike Copilot where you invoke each step manually, Claude Code **auto-triggers** the right workflow based on what you say. After each step, it suggests the natural next one:\n\n```\nYou:    \"Help me add authentication to my API\"\nClaude: detects → Research workflow (explores the problem, checks for existing auth libraries)\n        → suggests Plan (feature spans schema + middleware + routes)\n        → walks through Prompts for each phase\n        → runs Review (verify + review) on generated code\n        → suggests Eval after commit\n```\n\nYou can also jump directly to any workflow with slash commands, or let the skill route you automatically.\n\n## What's Included\n\n| Path | Purpose |\n|---|---|\n| `core/workflows/` | Provider-agnostic workflow definitions shared across Claude, Copilot, and Codex |\n| `core/references/` | Shared project-type references used to tailor context questions and review checklists |\n| `core/examples/` | Complete example PDD projects |\n| `core/metadata/workflows.json` | Structured workflow ids, labels, categories, and provider mappings |\n| `providers/claude/skills/pdd/SKILL.md` | Claude Code entrypoint skill |\n| `providers/claude/commands/` | Claude Code slash commands |\n| `providers/claude/hooks/` | Optional Claude session-start hook |\n| `providers/claude/plugin/plugin.json` | Claude plugin manifest |\n| `providers/copilot/` | Copilot prompt files and always-on instructions |\n| `providers/codex/plugin/.codex-plugin/plugin.json` | Codex plugin manifest |\n| `.agents/plugins/marketplace.json` | Repo-local Codex marketplace entry for `plugins/pdd-skill` |\n\nThe skill auto-detects your project type and loads the right reference file to enrich context questions, conventions, and review checklists.\n\n## Example\n\nSee [`core/examples/task-management-api/`](core/examples/task-management-api/) for a complete PDD setup with filled-in context files, standalone and chained feature prompts, and an eval checklist.\n\n## Migrating from the old layout\n\nIf you have an existing PDD project using the old layout (with `prompts/`, `context/`, `evals/` at the project root), see [`docs/migration.md`](docs/migration.md) for step-by-step migration instructions.\n\n## Learn More\n\n- **[Philosophy](docs/philosophy.md)** — Why PDD exists, the four layers, project type flavors, and how to get started\n- **[Efficiency Tips](docs/efficiency-tips.md)** — Practical habits for reducing token usage and cost\n- **[Migration Guide](docs/migration.md)** — Moving from the old layout to the `pdd/` structure\n- **[Architecture](docs/architecture.md)** — How the repo is organized for multiple providers\n- **[Maintenance](docs/maintenance.md)** — How generated sections and shared metadata are maintained\n\n## License\n\nMIT\n",
  "bytes": 13596,
  "sha": "5d9b3054fd81092a380e383f994725154c17e63045bd59a8c518c29170b6a66f",
  "repo_slug": "harshal2802/pdd-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_harshal2802_pdd_skill_pdd_skill_bc9885c1/readme"
}