ai-prd-workflow
Decide what to build before your agent builds it: PRD, features, rules and sequenced RFCs for AI coding agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 16 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nurettincoban/ai-prd-workflow with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nurettincoban/ai-prd-workflow'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nurettincoban--ai-prd-workflow)HTML
<a href="/listings/nurettincoban--ai-prd-workflow"><img src="/api/listings/nurettincoban--ai-prd-workflow/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
In Claude Code, install the plugin, restart Claude Code, and start the interview:
/plugin marketplace add nurettincoban/ai-prd-workflow /plugin install prd-workflow@ai-prd-workflow /prd-workflow:create-prd # then /prd-workflow:verify-prd
<details> <summary><b>Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Devin, or any chat assistant</b></summary>
Install the skills into your project:
cd your-project curl -fsSL https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/main/install.sh | bash -s -- .
In Codex, type `$create-prd` instead of `/create-prd`. In a chat assistant (ChatGPT, Claude.ai, …), copy a prompt from the [command table](#how-it-works) and paste it in.
</details>
> [!IMPORTANT] > Restart your AI tool after installing. A running session does not see new skills, so the first command fails with `Unknown skill` — which looks like a broken install but is only a stale session.
Then run the commands in order (with the plugin, each one carries its name: `/prd-workflow:verify-prd`):
/create-prd # interview → PRD.md (existing code? use /document-existing instead) /verify-prd # gaps and contradictions → improved PRD.md + PRD-REVIEW.md /extract-features # → FEATURES.md /generate-rules # → RULES.md /generate-rfcs # → RFCs/ + RFCS.md, in dependency order /test-strategy # → TEST-STRATEGY.md, before any test is written /implement-rfc 001 # plan → your approval → code → proof that it works /review-rfc 001 # review in a fresh context → reviews/REVIEW-RFC-001.md
Run `/workflow-status` whenever you are unsure what comes next, and `/manage-changes` when requirements change. Start with the first two: the interview takes about ten minutes, and `/verify-prd` will tell you within a few more whether this is for you.
**Or try it on the example.** The `before/` folder looks complete, and it is not. Copy it, so the original stays for comparison:
git clone https://github.com/nurettincoban/ai-prd-workflow.git cp -r ai-prd-workflow/examples/url-shortener/before linksnip ai-prd-workflow/install.sh linksnip
Open `linksnip` in your AI tool, run `/workflow-status` or `/verify-prd`, and compare the result with [the problems we found by hand](examples/url-shortener/README.md) and with what [our run](examples/url-shortener/after/) produced.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 22 lines
- {
- "name": "ai-prd-workflow",
- "owner": {
- "name": "Nurettin Coban"
- },
- "description": "Decide what to build before your agent builds it: PRD, features, rules and sequenced RFCs for AI coding agents",
- "plugins": [
- {
- "name": "prd-workflow",
- "source": "./",
- "description": "Eleven commands that take an idea or an existing codebase to a verified PRD, features, rules and sequenced RFCs, then implement and review them one at a time, with a script that checks the files still agree.",
- "category": "workflows",
- "tags": [
- "prd",
- "rfc",
- "spec-driven",
- "planning",
- "agent-skills"
- ]
- }
- ]
- }
README.md · README · 236 lines · 1 finding marked
- <div align="center">
- <a href="https://nurettincoban.github.io/ai-prd-workflow/"><img src=".github/social-preview.png" width="820" alt="AI PRD Workflow: decide what to build before your agent builds it"></a>
- # 📋 AI PRD Workflow
- ### Decide what to build before your agent builds it.
- **Idea or existing code → verified PRD → features → rules → sequenced RFCs → reviewed, tested code**
- [](https://github.com/nurettincoban/ai-prd-workflow/actions/workflows/ci.yml)
- [](LICENSE)
- [](https://github.com/nurettincoban/ai-prd-workflow/stargazers)
- [](#quick-start)
- [](#install-options)
- **[🌐 Website](https://nurettincoban.github.io/ai-prd-workflow/)** · **[See a real run](#what-one-run-produced)** · **[Quick start](#quick-start)** · **[How it works](#how-it-works)** · **[Why](#why-this-workflow)** · **[Evidence](#evidence)** · **[Install options](#install-options)**
- English · [简体中文](README.zh-CN.md) · [Türkçe](README.tr.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Español](README.es.md)
- <sub>RFC-driven since <a href="https://github.com/nurettincoban/ai-prd-workflow/commit/0993e28"><b>March 2025</b></a> — before Claude Code or Cursor had a plan mode, and before Kiro or Spec Kit existed.</sub>
- </div>
- ---
- AI coding agents write code well. They are worse at deciding what to build, remembering yesterday's decisions, and noticing when two documents disagree. This workflow handles that part. It takes an idea — or a codebase that already exists — to a reviewed product spec (PRD), prioritized features, project rules, and small implementation specs (RFCs) in dependency order. Then it implements and reviews them one at a time.
- Every step writes a markdown file that the next step reads, so decisions outlive the chat session. A script checks that the files still agree with each other. No CLI to learn, no framework to adopt, no lock-in: the commands are plain prompts, installed as skills for Claude Code, Codex, Copilot, Cursor, Gemini CLI, OpenCode and Devin.
- ## What one run produced
- We gave it the spec of a small URL shortener that looks finished, and ran the commands. Three things it caught before any code existed:
- | The spec said | What the workflow did |
- |---|---|
- | "Redirect short URL to original URL via HTTP 301" | `/verify-prd`: browsers cache a 301, so repeat clicks are never counted and deleted links keep redirecting. The fixed spec redirects with 302, and [RFC-003](examples/url-shortener/after/RFCs/RFC-003-Redirect-and-Click-Recording.md) tests "never 301". |
- | No user accounts, and anyone can "delete a short URL" | `/verify-prd`: anyone can delete anyone's link. Nobody was there to decide, so it wrote a proposed fix as an open question marked **(assumption)**, not as a decision. |
- | RFC-002 claims features F5, F6 and F11 | `/workflow-status`: its acceptance criteria only test the API, so the analytics page and chart those features require had nothing to make anyone build them. Every ID was cited, so a script could not see it. |
- **10 of 10** problems we had listed by hand, found by `/verify-prd` without seeing the list. **12 of 13** cross-document problems, found by `/workflow-status`. **12 RFCs** and **203 planned tests** generated, each RFC read cold by a second model first. About an hour of agent time on Claude Opus 5.5, no human input. **[Browse the whole run →](examples/url-shortener/)**
- ## Quick start
- In Claude Code, install the plugin, restart Claude Code, and start the interview:
- ```
- /plugin marketplace add nurettincoban/ai-prd-workflow
- /plugin install prd-workflow@ai-prd-workflow
- /prd-workflow:create-prd # then /prd-workflow:verify-prd
- ```
- <details>
- <summary><b>Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Devin, or any chat assistant</b></summary>
- Install the skills into your project:
- ```bash
- cd your-project
- curl -fsSL https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/main/install.sh | bash -s -- .
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 60 on GitHub
- ```
- In Codex, type `$create-prd` instead of `/create-prd`. In a chat assistant (ChatGPT, Claude.ai, …), copy a prompt from the [command table](#how-it-works) and paste it in.
- </details>
- > [!IMPORTANT]
- > Restart your AI tool after installing. A running session does not see new skills, so the first command fails with `Unknown skill` — which looks like a broken install but is only a stale session.
- Then run the commands in order (with the plugin, each one carries its name: `/prd-workflow:verify-prd`):
- ```
- /create-prd # interview → PRD.md (existing code? use /document-existing instead)
- /verify-prd # gaps and contradictions → improved PRD.md + PRD-REVIEW.md
- /extract-features # → FEATURES.md
- /generate-rules # → RULES.md
- /generate-rfcs # → RFCs/ + RFCS.md, in dependency order
- /test-strategy # → TEST-STRATEGY.md, before any test is written
- /implement-rfc 001 # plan → your approval → code → proof that it works
- /review-rfc 001 # review in a fresh context → reviews/REVIEW-RFC-001.md
- ```
- Run `/workflow-status` whenever you are unsure what comes next, and `/manage-changes` when requirements change. Start with the first two: the interview takes about ten minutes, and `/verify-prd` will tell you within a few more whether this is for you.
- **Or try it on the example.** The `before/` folder looks complete, and it is not. Copy it, so the original stays for comparison:
- ```bash
- git clone https://github.com/nurettincoban/ai-prd-workflow.git
- cp -r ai-prd-workflow/examples/url-shortener/before linksnip
- ai-prd-workflow/install.sh linksnip
- ```
- Open `linksnip` in your AI tool, run `/workflow-status` or `/verify-prd`, and compare the result with [the problems we found by hand](examples/url-shortener/README.md) and with what [our run](examples/url-shortener/after/) produced.
- ## How it works
- ```mermaid
- flowchart TB
- subgraph define ["1 · Define what to build"]
- direction LR
- idea([💡 New idea]) --> create["/create-prd"] --> verify["/verify-prd"]
- code([🗂️ Existing code]) --> document["/document-existing"] --> verify
- end
- subgraph plan ["2 · Plan how to build it"]
- direction LR
- features["/extract-features"] --> rules["/generate-rules"] --> rfcs["/generate-rfcs"] --> tests["/test-strategy"]
- end
- subgraph build ["3 · Build it, one RFC at a time"]
- direction LR
- implement["/implement-rfc"] --> review["/review-rfc"]
- review -.->|next RFC| implement
- end
- subgraph anytime ["Anytime"]
- direction LR
- changes["/manage-changes"] ~~~ status["/workflow-status"]
- end
- define --> plan --> build
- build ~~~ anytime
- ```
- | Command | What it does | Writes | Prompt |
- |---|---|---|---|
- | `/create-prd` | Interviews you about the idea, a few questions at a time | `PRD.md` | [view](interactive-prd-creation-prompt.md) |
- | `/document-existing` | Reads an existing codebase, then asks what the code cannot tell it | `PRD.md`, `FEATURES.md`, `RULES.md` | [view](document-existing-prompt.md) |
- | `/verify-prd` | Finds gaps, contradictions, and claims that cannot be built as written | `PRD.md`, `PRD-REVIEW.md` | [view](prd-comprehensive-verification-prompt.md) |
- | `/extract-features` | Turns requirements into features with permanent IDs and MoSCoW priorities | `FEATURES.md` | [view](prd-to-features-prompt.md) |
- | `/generate-rules` | Sets the standards the agent must follow, with dependency versions checked against the registry | `RULES.md` | [view](prd-to-rules-prompt.md) |
- | `/generate-rfcs` | Splits the work into small RFCs in dependency order, then checks each one for gaps with a fresh reader | `RFCs/`, `RFCS.md` | [view](prd-to-rfcs-prompt.md) |
- | `/test-strategy` | Plans the tests for each RFC before they are written | `TEST-STRATEGY.md` | [view](testing-strategy-prompt.md) |
- | `/implement-rfc <id>` | Plans, waits for your approval, writes the code, then runs the build and tests to prove each criterion | code, RFC status | [view](implementation-prompt-template.md) |
- | `/review-rfc <id>` | Reviews the code against the RFC, the rules, and the test plan, in a fresh context | `reviews/` | [view](code-review-prompt.md) |
- | `/manage-changes` | Checks a change against past decisions and rules, then updates every affected file together | `changes/` | [view](prd-change-management-prompt.md) |
- | `/workflow-status` | Reports what is done, what has drifted, and what to do next | — | [view](workflow-status-prompt.md) |
- A few rules hold it together:
- - **Plan, approve, then code.** `/implement-rfc` stops after the plan and waits for you.
- - **Review with fresh eyes.** `/review-rfc` will not review code written in the same conversation. In Claude Code it runs in a separate context automatically.
- - **IDs never change.** Requirements, features, rules, and RFCs cite each other by ID. [`scripts/trace-check.py`](scripts/trace-check.py) fails when a citation breaks or a Must-have feature has no RFC, and the commands run it for you.
- - **When files disagree,** `PRD.md` wins over `FEATURES.md`, which wins over `RULES.md`, then the RFCs. The commands say which file they followed, and flag the other for correction.
- ## Why this workflow
- Your coding agent probably has a plan mode. A plan mode plans one task. This workflow plans the product:
- | Built-in plan mode | This workflow |
- |---|---|
- | Plans one task: "how do I build this?" | Plans the product: what are we building, for whom, and what is out of scope? |
- | The plan disappears with the session | PRD, features, rules, and RFCs stay — across sessions, models, tools, and teammates |
- | Takes your request at face value | Interviews you first, so decisions are written down before any code exists |
- | Reviews code by "looks right" | Reviews against written acceptance criteria, and checks the files against each other |
- The two work together: `/generate-rfcs` decides what the next piece of work is, and `/implement-rfc` hands your agent's planner a small, well-defined task.
- **Use it for** multi-week builds, and anything real you build with AI, where scope creep and forgotten decisions hurt more than code quality. **Skip it for** a one-line fix.
- If you know spec-driven development (GitHub Spec Kit, Amazon Kiro), this is the same idea, with RFCs as the unit of work, no CLI or framework to adopt, and a script that checks the documents against each other.
- ## Evidence
- Everything in this section that you can check, you can check here:
- - **[The url-shortener example](examples/url-shortener/)** — the v2.0 spec, the problems we found in it by hand, and a full run of the current commands on it. Fresh-context runs that never saw our list found 10 of 10 PRD problems (`/verify-prd`) and 12 of 13 cross-document problems (`/workflow-status`), plus several we had missed. Cold reads by a second model, run by hand in this example, found over 150 places where the generated RFCs would have made an implementer guess; the [reports](examples/url-shortener/cold-reads/) are there too. These are single runs of one model.
- - **[The todo-cli example](examples/todo-cli/)** — a ten-line idea for a terminal to-do list, taken all the way to 386 lines of reviewed code and 66 passing tests, every step on Claude Sonnet 5.5 with nobody answering questions. It shows what each command caught, including tests that would have passed with the feature broken, and the one decision the run left open for you.
- - **[The eval suite](evals/)** — runs the same checks with and without the workflow, on your own account, so you can measure the difference yourself. It grades the ten PRD problems and seven of the thirteen cross-document ones, the ones a regular expression can recognize reliably.
- <p align="center">
- <img src=".github/demo-workflow-status.svg" width="860" alt="/workflow-status auditing the v2.0 example: the traceability check fails because F7 has no RFC and RFCS.md is missing, then reading the documents against each other finds 20 inconsistencies, such as no RFC building the UI and HTTP 301 caching breaking click counts">
- </p>
- <p align="center"><sub>A real <code>/workflow-status</code> run on the v2.0 example, condensed. <a href="examples/url-shortener/workflow-status-on-before.md">Full report</a></sub></p>
- Each step looks at the project from a different angle, and each catches problems the others cannot. We saw this while building a TypeScript library end to end with the workflow. That library is not public, so treat this table as a field report, not proof:
- | Step | What it caught | Why only this step caught it |
- |---|---|---|
- | `/verify-prd` | A function contradicting the PRD's own convention; an unspecified color space; a hidden rendering dependency | It compared the spec with the reference implementation |
- | RFC edge cases | That the pinned TypeScript version would break the build; a clone-aliasing bug | It reasoned about code that did not exist yet |
- | `/review-rfc` | A geometry leak on an error path; unvalidated `NaN` inputs | All 17 acceptance criteria had already passed |
- | `/test-strategy` | Normals never checked for being finite, so degenerate geometry rendered black while every test passed | It asks which tests should exist, not which do |
- | `/workflow-status` | Two required files never created, while their RFC was reported complete | It checked claims against the files on disk |
- | CI from an RFC | A wrong peer-dependency range: the tests failed on three published versions | It ran the tests against each version |
- | Fresh-reader check | An RFC that contradicted itself; a criterion that could only pass by luck | The author had read past both, repeatedly |
- The most striking result: before any code existed, an RFC's edge-case section predicted that a build plugin would not support TypeScript 7 yet, and named the fallback version. That is exactly what happened. Type-checking passed throughout, so only running the build revealed it.
- IDs held, too. When the PRD changed mid-project, a fresh agent re-ran `/extract-features` and added the new features at the end instead of renumbering — without being told to, because the RFCs cite features by number.
- ## Install options
- `install.sh` puts the skills where each tool looks for them:
- | Tool | Folder | Run a command |
- |---|---|---|
- | Claude Code | `.claude/skills/`, or the plugin | `/create-prd` |
- | GitHub Copilot (VS Code, CLI) | `.agents/skills/` | `/create-prd` |
- | Cursor | `.agents/skills/` | `/create-prd`, from the `/` menu |
- | Gemini CLI | `.agents/skills/` | `/create-prd` |
- | OpenCode | `.agents/skills/` | `/create-prd` |
- | Devin | `.agents/skills/` | `/create-prd` |
- | Codex | `.agents/skills/` | `$create-prd`, or pick it from `/skills` |
- From a clone of this repository:
- ```bash
- ./install.sh /path/to/your/project # both folders (the default)
- ./install.sh /path/to/your/project --claude # Claude Code only
- ./install.sh /path/to/your/project --agents # the other tools only
- ```
- - `install.sh` never overwrites a skill you have edited. `--force` replaces it after saving a backup.
- - `--ref v3.0.0` installs a specific release. Use the same tag in the curl URL.
- - Upgrading from v2? Add `--remove-legacy` to move the old command files into a backup folder.
- - Prefer copy-paste? `./copy-prompt.sh --list` shows the prompts, and `./copy-prompt.sh <file>` copies one to your clipboard.
- ## Tips
- - **Answer the questions.** The interview commands work best with your real decisions, not the agent's guesses.
- - **Read each file before you move on.** Fixing a PRD takes minutes; fixing code built on a wrong PRD takes days.
- - **Keep the rules in context.** Reference `RULES.md` from your agent config (`CLAUDE.md`, `AGENTS.md`, or `.cursor/rules/`). `/generate-rules` suggests how.
- - **Parallelize if you can.** An RFC can start as soon as its declared predecessors are done. Working alone, just follow the numbers.
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md). The prompt files at the root are the source; everything else is generated or checked from them.
- ## Acknowledgments
- Thank you to [Anthropic](https://www.anthropic.com) for supporting this project and welcoming it into its open source program.
- ## License
- MIT — see [LICENSE](LICENSE).
- ---
- <p align="center">If this workflow saved you from building the wrong thing, a ⭐ helps others find it.</p>
install.sh · Bundled script · 288 lines · 1 finding marked
- #!/usr/bin/env bash
- #
- # Install the ai-prd-workflow commands into a project as Agent Skills.
- #
- # --claude Claude Code -> .claude/skills/<name>/SKILL.md
- # --agents Codex, GitHub Copilot, Cursor, Gemini CLI, -> .agents/skills/<name>/SKILL.md
- # OpenCode, Devin
- # --all both (the default)
- #
- # Usage:
- # ./install.sh [target-project-dir] [--claude] [--agents] [--force] [--ref <tag>] [--remove-legacy]
- # ./install.sh --build maintainers: regenerate skills/ in this repo from the prompt sources
- #
- # Without cloning the repo (pin a release by replacing main with a tag and adding --ref <tag>):
- # curl -fsSL https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/main/install.sh | bash -s -- /path/to/project
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 15 on GitHub
- #
- # Files you have edited are never overwritten silently: every generated SKILL.md carries a
- # checksum, a file whose checksum no longer matches is kept, and --force replaces it after
- # saving a backup.
- set -euo pipefail
- VERSION="3.1.0"
- REPO_URL="https://github.com/nurettincoban/ai-prd-workflow"
- # Overridable so the curl path can be tested without the network (file:// works).
- RAW_BASE="${AI_PRD_WORKFLOW_RAW:-https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow}"
- SCRIPT_SOURCE="${BASH_SOURCE[0]:-}"
- if [ -n "$SCRIPT_SOURCE" ] && [ -f "$SCRIPT_SOURCE" ]; then
- SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
- else
- SCRIPT_DIR=""
- fi
- # name|source prompt|description|argument hint|options
- COMMANDS='
- create-prd|interactive-prd-creation-prompt.md|Interview the user about a product idea and write PRD.md. Use at the start of a new project, before features, rules or RFCs exist.||
- document-existing|document-existing-prompt.md|Document an existing codebase as PRD.md, FEATURES.md and RULES.md, so new work is planned against the code as it is. Use instead of create-prd when the code already exists.||
- verify-prd|prd-comprehensive-verification-prompt.md|Review PRD.md for gaps, contradictions and unverifiable claims, write an improved PRD.md and record the findings in PRD-REVIEW.md.||
- extract-features|prd-to-features-prompt.md|Turn PRD.md into FEATURES.md: permanent feature IDs, MoSCoW priorities, acceptance criteria and the PRD requirement each feature comes from.||
- generate-rules|prd-to-rules-prompt.md|Write RULES.md, the project standards the AI must follow, with registry-verified dependency versions and permanent rule IDs.||
- generate-rfcs|prd-to-rfcs-prompt.md|Break the PRD into sequenced implementation RFCs under RFCs/ with an RFCS.md index, then cold-read each RFC for gaps.||
- test-strategy|testing-strategy-prompt.md|Write TEST-STRATEGY.md, a test plan per RFC, before the tests are written.||
- implement-rfc|implementation-prompt-template.md|Implement one RFC: check its predecessors, present a plan for approval, write the code, then demonstrate every acceptance criterion.|<rfc-id>|
- review-rfc|code-review-prompt.md|Review an implemented RFC in a fresh context against its acceptance criteria, RULES.md and the test plan, and save the review to reviews/.|<rfc-id>|fork
- manage-changes|prd-change-management-prompt.md|Assess a requirement change mid-project against the rules and past decisions, then update every affected artifact together.||
- workflow-status|workflow-status-prompt.md|Report which workflow artifacts exist, which RFCs are implemented and reviewed, what has drifted, and the next step.||
- '
- # shellcheck disable=SC2016 # $ARGUMENTS is a literal placeholder for the AI tool to substitute
- ARG_PREAMBLE='Target RFC ID: "$ARGUMENTS" -- if that still reads as a literal placeholder, use the RFC ID from my message instead. Substitute it for [ID] everywhere below. If no ID was given, ask which RFC to work on before doing anything else.'
- die() { echo "Error: $*" >&2; exit 1; }
- sha256() {
- if command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
- else shasum -a 256 | cut -d' ' -f1
- fi
- }
- # Checksum of a generated SKILL.md: every byte except the checksum line itself, CRs ignored.
- checksum_of() { tr -d '\r' < "$1" | grep -v '^ checksum: ' | sha256; }
- recorded_checksum() { tr -d '\r' < "$1" | sed -n 's/^ checksum: "sha256:\([0-9a-f]*\)"$/\1/p'; }
- yaml_quote() { printf '"%s"' "$(printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g')"; }
- usage() {
- cat <<EOF
- Install the ai-prd-workflow commands into a project as Agent Skills (v$VERSION).
- Usage: ./install.sh [target-project-dir] [options]
- --claude Claude Code: .claude/skills/
- --agents Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Devin: .agents/skills/
- --all Both (default)
- --force Replace skills you have edited (a backup is saved first)
- --ref <tag> Install a specific release, e.g. --ref v$VERSION (skills ship from v3.0.0)
- --remove-legacy Move command files left by v2.x installs into a backup folder
- --build Maintainers: regenerate skills/ in this repository from the prompt sources
- Claude Code users can install the plugin instead:
- /plugin marketplace add nurettincoban/ai-prd-workflow
- /plugin install prd-workflow@ai-prd-workflow
- EOF
- }
- TARGET="."
- TARGET_SET=""
- TOOLS=""
- FORCE=0
- REF=""
- REMOVE_LEGACY=0
- BUILD=0
- while [ $# -gt 0 ]; do
- case "$1" in
- --claude) TOOLS="$TOOLS claude" ;;
- --agents) TOOLS="$TOOLS agents" ;;
- --all) TOOLS="claude agents" ;;
- --cursor|--gemini|--opencode|--windsurf)
- echo "Note: $1 now installs Agent Skills into .agents/skills/, which that tool reads." >&2
- TOOLS="$TOOLS agents" ;;
- --force) FORCE=1 ;;
- --ref)
- [ $# -ge 2 ] || die "--ref needs a tag, e.g. --ref v$VERSION"
- REF="$2"; shift ;;
- --remove-legacy) REMOVE_LEGACY=1 ;;
- --build) BUILD=1 ;;
- --help|-h) usage; exit 0 ;;
- --*) die "unknown option '$1' (see --help)" ;;
- *)
- [ -z "$TARGET_SET" ] || die "only one target directory allowed (got '$TARGET' and '$1')"
- TARGET="$1"; TARGET_SET=1 ;;
- esac
- shift
- done
- [ -n "$TOOLS" ] || TOOLS="claude agents"
- # ------------------------------------------------------------------ build
- # Generates skills/<name>/SKILL.md from the prompt sources. Only maintainers run this;
- # installs copy the generated files, so every channel ships byte-identical skills.
- render_skill() {
- local name="$1" src="$2" desc="$3" arghint="$4" options="$5"
- echo "---"
- echo "name: $name"
- echo "description: $(yaml_quote "$desc")"
- if [ -n "$arghint" ]; then echo "argument-hint: $(yaml_quote "$arghint")"; fi
- if [ "$options" = "fork" ]; then
- echo "context: fork"
- echo "agent: general-purpose"
- fi
- echo "metadata:"
- echo " source: \"$REPO_URL\""
- echo " version: \"$VERSION\""
- echo "---"
- echo ""
- if [ -n "$arghint" ]; then
- echo "$ARG_PREAMBLE"
- echo ""
- fi
- tr -d '\r' < "$SCRIPT_DIR/$src"
- }
- build_skills() {
- [ -n "$SCRIPT_DIR" ] || die "--build only works from a clone of the repository"
- local out="$SCRIPT_DIR/skills" tmp sum name src desc arghint options
- rm -rf "$out"
- mkdir -p "$out"
- while IFS='|' read -r name src desc arghint options; do
- [ -n "$name" ] || continue
- mkdir -p "$out/$name"
- tmp="$out/$name/SKILL.md.tmp"
- render_skill "$name" "$src" "$desc" "$arghint" "$options" > "$tmp"
- sum="$(sha256 < "$tmp")"
- # The checksum goes right after the version line; checksum_of() skips that one line.
- awk -v line=" checksum: \"sha256:$sum\"" '{ print } /^ version: "/ && !done { print line; done = 1 }' "$tmp" > "$out/$name/SKILL.md"
- rm "$tmp"
- if grep -q 'trace-check.py' "$out/$name/SKILL.md"; then
- mkdir -p "$out/$name/scripts"
- tr -d '\r' < "$SCRIPT_DIR/scripts/trace-check.py" > "$out/$name/scripts/trace-check.py"
- fi
- echo " skills/$name/"
- done <<< "$COMMANDS"
- }
- if [ "$BUILD" = 1 ]; then
- echo "Building skills/ (v$VERSION):"
- build_skills
- exit 0
- fi
- # ---------------------------------------------------------------- install
- if [ -e "$TARGET" ] && [ ! -d "$TARGET" ]; then die "'$TARGET' is not a directory."; fi
- [ -d "$TARGET" ] || die "target directory '$TARGET' does not exist."
- # fetch <path in the repo>: the file from this copy, from a git ref of this clone, or downloaded
- fetch() {
- local path="$1"
- if [ -n "$SCRIPT_DIR" ] && [ -z "$REF" ]; then
- cat "$SCRIPT_DIR/$path" 2>/dev/null
- elif [ -n "$SCRIPT_DIR" ] && git -C "$SCRIPT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
- git -C "$SCRIPT_DIR" show "$REF:$path" 2>/dev/null
- else
- curl -fsSL "$RAW_BASE/${REF:-main}/$path"
- fi
- }
- # A release missing from this clone otherwise surfaces as "could not fetch" on the first skill.
- if [ -n "$REF" ] && [ -n "$SCRIPT_DIR" ] && git -C "$SCRIPT_DIR" rev-parse --git-dir >/dev/null 2>&1 \
- && ! git -C "$SCRIPT_DIR" rev-parse --verify -q "$REF^{commit}" >/dev/null; then
- die "no tag or commit '$REF' in this clone. Run 'git fetch --tags' and try again, or check the name at $REPO_URL/tags"
- fi
- # Stage every skill once, so each tool folder gets identical files.
- STAGE="$(mktemp -d)"
- trap 'rm -rf "$STAGE"' EXIT
- while IFS='|' read -r name _; do
- [ -n "$name" ] || continue
- mkdir -p "$STAGE/$name"
- fetch "skills/$name/SKILL.md" > "$STAGE/$name/SKILL.md" \
- || die "could not fetch skills/$name/SKILL.md${REF:+ at $REF} (skills ship from v3.0.0)"
- if grep -q 'trace-check.py' "$STAGE/$name/SKILL.md"; then
- mkdir -p "$STAGE/$name/scripts"
- fetch "skills/$name/scripts/trace-check.py" > "$STAGE/$name/scripts/trace-check.py" \
- || die "could not fetch skills/$name/scripts/trace-check.py"
- fi
- done <<< "$COMMANDS"
- ADDED=0; UPDATED=0; CURRENT=0; KEPT=0
- install_skill() {
- local name="$1" dest="$2" out="$2/SKILL.md" recorded actual
- if [ -f "$out" ]; then
- if [ "$(tr -d '\r' < "$out")" = "$(tr -d '\r' < "$STAGE/$name/SKILL.md")" ]; then
- CURRENT=$((CURRENT + 1))
- return 0
- fi
- recorded="$(recorded_checksum "$out")"
- actual="$(checksum_of "$out")"
- if [ -z "$recorded" ] || [ "$recorded" != "$actual" ]; then
- if [ "$FORCE" != 1 ]; then
- echo " kept $out (edited locally -- rerun with --force to replace it)"
- KEPT=$((KEPT + 1))
- return 0
- fi
- cp "$out" "$out.backup-$(date +%Y%m%d%H%M%S)"
- echo " replaced $out (backup saved beside it)"
- else
- echo " updated $out"
- fi
- UPDATED=$((UPDATED + 1))
- else
- echo " added $out"
- ADDED=$((ADDED + 1))
- fi
- mkdir -p "$dest"
- cp "$STAGE/$name/SKILL.md" "$out"
- if [ -d "$STAGE/$name/scripts" ]; then
- mkdir -p "$dest/scripts"
- cp "$STAGE/$name/scripts/"* "$dest/scripts/"
- fi
- }
- # v2.x installed plain command files under these names; skills with the same names replace them.
- LEGACY_MARKER='You are (an experienced Product Manager|an expert|a senior software developer|guiding a project through)'
- handle_legacy() {
- local dir="$TARGET/$1" found="" name file
- [ -d "$dir" ] || return 0
- for name in create-prd verify-prd extract-features generate-rules generate-rfcs implement-rfc review-rfc test-strategy manage-changes workflow-status; do
- file="$dir/$name.md"
- if [ -f "$file" ] && grep -Eq "$LEGACY_MARKER" "$file"; then
- if [ "$REMOVE_LEGACY" = 1 ]; then
- mkdir -p "$dir/.ai-prd-workflow-v2-backup"
- mv "$file" "$dir/.ai-prd-workflow-v2-backup/"
- fi
- found="$found $name"
- fi
- done
- [ -n "$found" ] || return 0
- if [ "$REMOVE_LEGACY" = 1 ]; then
- echo "Moved v2 command files from $1/ to $1/.ai-prd-workflow-v2-backup/:$found"
- else
- echo "Note: $1/ still has v2 command files with the same names:$found"
- echo " Rerun with --remove-legacy to move them into a backup folder."
- fi
- }
- for tool in claude agents; do
- case " $TOOLS " in *" $tool "*) ;; *) continue ;; esac
- case "$tool" in
- claude) dir=".claude/skills"; label="Claude Code" ;;
- agents) dir=".agents/skills"; label="Codex, Copilot, Cursor, Gemini CLI, OpenCode, Devin" ;;
- esac
- echo "$label -> $dir/"
- while IFS='|' read -r name _; do
- [ -n "$name" ] || continue
- install_skill "$name" "$TARGET/$dir/$name"
- done <<< "$COMMANDS"
- if [ "$CURRENT" -gt 0 ]; then echo " $CURRENT already up to date"; fi
- CURRENT=0
- done
- handle_legacy ".claude/commands"
- handle_legacy ".cursor/commands"
- echo ""
- echo "Done (ai-prd-workflow v$VERSION): $ADDED added, $UPDATED updated, $KEPT kept."
- echo "Restart your AI tool so it picks up new skills, then type / to see them."
- echo "Start with /create-prd for a new project, /document-existing for an existing codebase,"
- echo "or /workflow-status to see where a project stands."
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.