{"id":48738711,"url":"https://github.com/harshal2802/pdd-skill","last_synced_at":"2026-04-12T06:04:39.365Z","repository":{"id":345580531,"uuid":"1186835358","full_name":"harshal2802/pdd-skill","owner":"harshal2802","description":"A Practical Framework for Building with AI","archived":false,"fork":false,"pushed_at":"2026-04-12T04:16:39.000Z","size":425,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T04:17:34.280Z","etag":null,"topics":["ai-assisted-development","ai-prompts","ai-workflow","backend","claude","claude-code","claude-skill","code-generation","data-science","developer-tools","devops","frontend","full-stack","llm","machine-learning","mobile-development","pdd","prompt-driven-development","prompt-engineering","software-development"],"latest_commit_sha":null,"homepage":"https://harshal2802.github.io/pdd-skill/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harshal2802.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T03:20:25.000Z","updated_at":"2026-04-12T04:16:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harshal2802/pdd-skill","commit_stats":null,"previous_names":["harshal2802/pdd-skill"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/harshal2802/pdd-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshal2802%2Fpdd-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshal2802%2Fpdd-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshal2802%2Fpdd-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshal2802%2Fpdd-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harshal2802","download_url":"https://codeload.github.com/harshal2802/pdd-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harshal2802%2Fpdd-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31705574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-12T05:11:36.334Z","status":"ssl_error","status_checked_at":"2026-04-12T05:11:27.332Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted-development","ai-prompts","ai-workflow","backend","claude","claude-code","claude-skill","code-generation","data-science","developer-tools","devops","frontend","full-stack","llm","machine-learning","mobile-development","pdd","prompt-driven-development","prompt-engineering","software-development"],"created_at":"2026-04-12T06:04:37.824Z","updated_at":"2026-04-12T06:04:39.360Z","avatar_url":"https://github.com/harshal2802.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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, and Codex. 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\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\u003e **Tip:** To pin a specific version, add `--branch v1.3.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 \u003cyour-project\u003e/.github/copilot-instructions.md\n\n# Copy the prompt files\ncp -r /tmp/pdd-skill/providers/copilot/prompts/ \u003cyour-project\u003e/.github/prompts/\n\n# Copy the reference files (project type flavors)\ncp -r /tmp/pdd-skill/core/references/ \u003cyour-project\u003e/.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 \u003cyour-project\u003e/.codex/plugins/pdd-skill\n\n# Or use the repo-local marketplace entry\ncp /tmp/pdd-skill/.agents/plugins/marketplace.json \u003cyour-project\u003e/.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## 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\u003c!-- GENERATED:claude-command-table:start --\u003e\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\u003c!-- GENERATED:claude-command-table:end --\u003e\n\nAll commands accept optional arguments, e.g., `/project:pdd-scaffold my-api` or `/project:pdd-review paste your code here`.\n\n## Workflow\n\n```mermaid\nflowchart LR\n    A[\"Scaffold (new)\"] --\u003e B[\"Context\"]\n    A2[\"Init (existing)\"] --\u003e B\n    B --\u003e S{Complex?}\n    S -- Yes --\u003e C[\"Research\"] --\u003e D[\"Plan\"] --\u003e E\n    S -- No --\u003e E[\"Prompts\"]\n    E --\u003e F[\"Run prompt\"]\n    F --\u003e G[\"Review\"]\n    G --\u003e H[\"Commit\"]\n    H -.-\u003e 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshal2802%2Fpdd-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharshal2802%2Fpdd-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharshal2802%2Fpdd-skill/lists"}