diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 18d8a50..f525d57 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -129,7 +129,7 @@ { "name": "product-skills", "source": "./product-team", - "description": "13 product skills with 13 Python tools: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator.", + "description": "14 product skills with 16 Python tools: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, code-to-prd, research summarizer.", "version": "2.1.2", "author": { "name": "Alireza Rezvani" diff --git a/.claude/commands/plugin-audit.md b/.claude/commands/plugin-audit.md new file mode 100644 index 0000000..51f680e --- /dev/null +++ b/.claude/commands/plugin-audit.md @@ -0,0 +1,153 @@ +--- +description: Run the full 8-phase plugin audit pipeline on a skill directory. +--- + +Run the comprehensive plugin audit pipeline on the skill at `$ARGUMENTS`. If no argument provided, ask the user for the skill path. + +Execute all 8 phases sequentially. Auto-fix non-critical issues. Only prompt the user for critical decisions (external dependencies, security findings, breaking changes). + +## Phase 1: Discovery + +1. Verify `$ARGUMENTS` exists and contains `SKILL.md`. If not, error and stop. +2. Read `SKILL.md` frontmatter — extract `name`, `description`, `Category`, `Tier`. +3. Detect components: + - `scripts/*.py` → Python tools (count them) + - `references/*.md` → reference docs (count them) + - `assets/` → templates/samples + - `expected_outputs/` → test fixtures + - `agents/*.md` → embedded agents + - `skills/*/SKILL.md` → sub-skills (compound skill) + - `.claude-plugin/plugin.json` → standalone plugin + - `settings.json` → command registrations +4. Detect domain from path (`engineering/`, `product-team/`, `marketing-skill/`, etc.) +5. Search `commands/` for a `.md` file matching the skill name. +6. Display discovery summary. + +## Phase 2: Structure Validation + +Run: +```bash +python3 engineering/skill-tester/scripts/skill_validator.py $ARGUMENTS --json +``` + +Parse JSON. If score < 75: +- Auto-fix missing frontmatter fields, missing section headings, missing directories. +- Re-run. If still < 75, mark as FAIL but continue collecting results. + +## Phase 3: Quality Scoring + +Run: +```bash +python3 engineering/skill-tester/scripts/quality_scorer.py $ARGUMENTS --detailed --json +``` + +Parse JSON. If score < 60, report improvement roadmap items. + +## Phase 4: Script Testing + +If `$ARGUMENTS/scripts/` contains `.py` files, run: +```bash +python3 engineering/skill-tester/scripts/script_tester.py $ARGUMENTS --json --verbose +``` + +All scripts must PASS. If any script uses external imports, **ask the user** whether the dependency is acceptable. + +## Phase 5: Security Audit + +Run: +```bash +python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py $ARGUMENTS --strict --json +``` + +Zero CRITICAL or HIGH findings required. **Do NOT auto-fix security issues** — report them to the user with file, line, pattern, and recommended fix. + +## Phase 6: Marketplace & Plugin Compliance + +### 6a. plugin.json +If `$ARGUMENTS/.claude-plugin/plugin.json` exists: +- Must be valid JSON +- Only allowed fields: `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`, `skills` +- Version must be `2.1.2` +- Auto-fix version mismatches and remove extra fields. + +### 6b. settings.json +If `$ARGUMENTS/settings.json` exists: +- Must be valid JSON +- Version must match repo version +- Each command in `commands` field must have a matching `commands/*.md` file + +### 6c. Marketplace entry +Check `.claude-plugin/marketplace.json` for an entry with `source` matching `./$ARGUMENTS`. Verify version and name match. + +### 6d. Domain plugin.json +Check the parent domain's `.claude-plugin/plugin.json` — verify skill count in description matches actual count. Auto-fix stale counts. + +## Phase 7: Ecosystem Integration + +### 7a. Cross-platform sync +Verify skill appears in `.codex/skills-index.json` and `.gemini/skills-index.json`. If missing: +```bash +python3 scripts/sync-codex-skills.py --verbose +python3 scripts/sync-gemini-skills.py --verbose +``` + +### 7b. Command integration +If the skill has associated commands, verify: +- Command `.md` has valid frontmatter +- Command references the correct skill +- Command is in `mkdocs.yml` nav +Auto-fix missing nav entries. + +### 7c. Agent integration +Check for embedded agents in `$ARGUMENTS/agents/`. Search `agents/` for cs-* agents that reference this skill. Verify references resolve. + +### 7d. Cross-skill dependencies +Read SKILL.md for references to other skills (`../` paths, "Related Skills" sections). Verify each referenced skill exists. + +## Phase 8: Domain Code Review + +Based on the domain, apply the appropriate agent's review criteria: + +| Domain | Agent | Focus | +|--------|-------|-------| +| `engineering/` or `engineering-team/` | cs-senior-engineer | Architecture, code quality, CI/CD | +| `product-team/` | cs-product-manager | PRD quality, user stories, RICE | +| `marketing-skill/` | cs-content-creator | Content quality, SEO, brand voice | +| `ra-qm-team/` | cs-quality-regulatory | Compliance, audit trail, regulatory | +| `business-growth/` | cs-growth-strategist | Growth metrics, revenue impact | +| `finance/` | cs-financial-analyst | Model accuracy, metric definitions | +| Other | cs-senior-engineer | General code review | + +Read the agent's `.md` file for review criteria. Apply those criteria to the skill's SKILL.md, scripts, and references. Check: +- Workflows are actionable and complete +- Scripts solve the stated problem +- References contain accurate domain knowledge +- No broken internal links +- Attribution present where required + +## Final Report + +Present all results in a structured summary: + +``` +╔══════════════════════════════════════════════════════════════╗ +║ PLUGIN AUDIT REPORT: {skill_name} ║ +╠══════════════════════════════════════════════════════════════╣ +║ Phase 1 — Discovery ✅ {type}, {domain} ║ +║ Phase 2 — Structure ✅ {score}/100 ({level}) ║ +║ Phase 3 — Quality ✅ {score}/100 ({grade}) ║ +║ Phase 4 — Scripts ✅ {n}/{n} PASS ║ +║ Phase 5 — Security ✅ PASS (0 critical, 0 high) ║ +║ Phase 6 — Marketplace ✅ plugin.json valid ║ +║ Phase 7 — Ecosystem ✅ synced ║ +║ Phase 8 — Code Review ✅ passed ║ +║ ║ +║ VERDICT: ✅ PASS ║ +║ Auto-fixes: {n} | Warnings: {n} | Action items: {n} ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +**Verdict rules:** +- All phases pass → **PASS** +- Only warnings → **PASS WITH WARNINGS** +- Any blocker (structure <75, quality <60, script FAIL, security CRITICAL/HIGH, invalid plugin.json) → **FAIL** diff --git a/commands/plugin-audit.md b/commands/plugin-audit.md new file mode 100644 index 0000000..04c3573 --- /dev/null +++ b/commands/plugin-audit.md @@ -0,0 +1,312 @@ +--- +name: plugin-audit +description: | + Comprehensive audit pipeline for skills, plugins, agents, and commands. Validates structure, + quality, security, marketplace compliance, cross-platform compatibility, and ecosystem integration. + Runs all built-in validation tools, invokes domain-appropriate agents for code review, + and produces a pass/fail gate report. Usage: /plugin-audit +--- + +# /plugin-audit + +Full audit pipeline for any skill, plugin, agent, or command in this repository. Runs 8 validation phases, auto-fixes what it can, and only stops for user input on critical decisions (breaking changes, new dependencies). + +## Usage + +```bash +/plugin-audit product-team/code-to-prd +/plugin-audit engineering/agenthub +/plugin-audit engineering-team/playwright-pro +``` + +## What It Does + +Execute all 8 phases sequentially. Stop on critical failures. Auto-fix non-critical issues. Report results at the end. + +--- + +## Phase 1: Discovery + +Identify what the skill contains and classify it. + +1. Verify `{skill_path}` exists and contains `SKILL.md` +2. Read `SKILL.md` frontmatter — extract `name`, `description`, `Category`, `Tier` +3. Detect skill type: + - Has `scripts/` → has Python tools + - Has `references/` → has reference docs + - Has `assets/` → has templates/samples + - Has `expected_outputs/` → has test fixtures + - Has `agents/` → has embedded agents + - Has `skills/` → has sub-skills (compound skill) + - Has `.claude-plugin/plugin.json` → is a standalone plugin + - Has `settings.json` → has command registrations +4. Detect domain from path: `engineering/`, `product-team/`, `marketing-skill/`, etc. +5. Check for associated command: search `commands/` for a `.md` file matching the skill name + +Display discovery summary before proceeding: +``` +Auditing: code-to-prd + Domain: product-team + Type: STANDARD skill with standalone plugin + Scripts: 2 | References: 2 | Assets: 1 | Expected outputs: 3 + Command: /code-to-prd (found) + Plugin: .claude-plugin/plugin.json (found) +``` + +--- + +## Phase 2: Structure Validation + +Run the skill-tester validator. + +```bash +python3 engineering/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json +``` + +Parse the JSON output. Extract: +- Overall score and compliance level +- Failed checks (list each) +- Errors and warnings + +**Gate rule:** Score must be ≥ 75 (GOOD). If below 75: +- Read the errors list +- Auto-fix what's possible: + - Missing frontmatter fields → add them from SKILL.md content + - Missing sections → add stub headings + - Missing directories → create empty ones with a note +- Re-run after fixes. If still below 75, report as FAIL and continue to collect remaining results. + +--- + +## Phase 3: Quality Scoring + +Run the quality scorer. + +```bash +python3 engineering/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json +``` + +Parse the JSON output. Extract: +- Overall score and letter grade +- Per-dimension scores (Documentation, Code Quality, Completeness, Usability) +- Improvement roadmap items + +**Gate rule:** Score must be ≥ 60 (C). If below 60, report the improvement roadmap items as action items. + +--- + +## Phase 4: Script Testing + +If the skill has `scripts/` with `.py` files, run the script tester. + +```bash +python3 engineering/skill-tester/scripts/script_tester.py {skill_path} --json --verbose +``` + +Parse the JSON output. For each script, extract: +- Pass/Partial/Fail status +- Individual test results + +**Gate rule:** All scripts must PASS. Any FAIL is a blocker. PARTIAL triggers a warning. + +**Auto-fix:** If a script fails the `--help` test, check if it has `argparse` — if not, this is a real issue. If it fails the stdlib-only test, flag the import and **ask the user** whether the dependency is acceptable (this is a critical decision). + +--- + +## Phase 5: Security Audit + +Run the skill security auditor. + +```bash +python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json +``` + +Parse the JSON output. Extract: +- Verdict (PASS/WARN/FAIL) +- Critical findings (must be zero) +- High findings (must be zero in strict mode) +- Info findings (advisory only) + +**Gate rule:** Zero CRITICAL findings. Zero HIGH findings. Any CRITICAL or HIGH is a blocker — report the exact file, line, pattern, and recommended fix. + +**Do NOT auto-fix security issues.** Report them and let the user decide. + +--- + +## Phase 6: Marketplace & Plugin Compliance + +### 6a. plugin.json Validation + +If `{skill_path}/.claude-plugin/plugin.json` exists: + +1. Parse as JSON — must be valid +2. Verify only allowed fields: `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`, `skills` +3. Version must match repo version (`2.1.2`) +4. `skills` must be `"./"` +5. `name` must match the skill directory name + +**Auto-fix:** If version is wrong, update it. If extra fields exist, remove them. + +### 6b. settings.json Validation + +If `{skill_path}/settings.json` exists: + +1. Parse as JSON — must be valid +2. Version must match repo version +3. If `commands` field exists, verify each command has a matching file in `commands/` + +### 6c. Marketplace Entry + +Check if the skill has an entry in `.claude-plugin/marketplace.json`: + +1. Search the `plugins` array for an entry with `source` matching `./` + skill path +2. If found: verify `version`, `name`, and that `source` path exists +3. If not found: check if the skill's domain bundle (e.g., `product-skills`) would include it via its `source` path + +### 6d. Domain plugin.json + +Check the parent domain's `.claude-plugin/plugin.json`: +- Verify the skill count in the description matches reality +- Verify version matches repo version + +**Auto-fix:** Update stale counts. Fix version mismatches. + +--- + +## Phase 7: Ecosystem Integration + +### 7a. Cross-Platform Sync + +Verify the skill appears in platform indexes: + +```bash +grep -l "{skill_name}" .codex/skills-index.json .gemini/skills-index.json +``` + +If missing from either index: +```bash +python3 scripts/sync-codex-skills.py --verbose +python3 scripts/sync-gemini-skills.py --verbose +``` + +### 7b. Command Integration + +If the skill has associated commands (from settings.json `commands` field or matching name in `commands/`): +- Verify the command `.md` file has valid YAML frontmatter (`name`, `description`) +- Verify the command references the correct skill path +- Verify the command is in `mkdocs.yml` nav + +**Auto-fix:** Add missing mkdocs.yml nav entries. + +### 7c. Agent Integration + +If the skill has embedded agents (`{skill_path}/agents/*.md`): +- Verify each agent has valid YAML frontmatter +- Verify agent references resolve (relative paths to skills) + +Search `agents/` for any cs-* agent that references this skill: +```bash +grep -rl "{skill_name}\|{skill_path}" agents/ +``` + +If found, verify the agent's skill references are correct. + +### 7d. Cross-Skill Dependencies + +Read the SKILL.md for references to other skills (look for `../` paths, skill names in "Related Skills" sections): +- Verify each referenced skill exists +- Verify the referenced skill's SKILL.md exists + +--- + +## Phase 8: Domain-Appropriate Code Review + +Based on the skill's domain, invoke the appropriate agent's review perspective: + +| Domain | Agent | Review Focus | +|--------|-------|-------------| +| `engineering/` or `engineering-team/` | cs-senior-engineer | Architecture, code quality, CI/CD integration | +| `product-team/` | cs-product-manager | PRD quality, user story coverage, RICE alignment | +| `marketing-skill/` | cs-content-creator | Content quality, SEO optimization, brand voice | +| `ra-qm-team/` | cs-quality-regulatory | Compliance checklist, audit trail, regulatory alignment | +| `business-growth/` | cs-growth-strategist | Growth metrics, revenue impact, customer success | +| `finance/` | cs-financial-analyst | Financial model accuracy, metric definitions | +| Other | cs-senior-engineer | General code and architecture review | + +**How to invoke:** Read the agent's `.md` file to understand its review criteria. Apply those criteria to review the skill's SKILL.md, scripts, and references. This is NOT spawning a subagent — it's using the agent's documented perspective to structure your review. + +Review checklist (apply domain-appropriate lens): +- [ ] SKILL.md workflows are actionable and complete +- [ ] Scripts solve the stated problem correctly +- [ ] References contain accurate domain knowledge +- [ ] Templates/assets are production-ready +- [ ] No broken internal links +- [ ] Attribution present where required + +--- + +## Final Report + +Present results as a structured table: + +``` +╔══════════════════════════════════════════════════════════════╗ +║ PLUGIN AUDIT REPORT: {skill_name} ║ +╠══════════════════════════════════════════════════════════════╣ +║ ║ +║ Phase 1 — Discovery ✅ {type}, {domain} ║ +║ Phase 2 — Structure ✅ {score}/100 ({level}) ║ +║ Phase 3 — Quality ✅ {score}/100 ({grade}) ║ +║ Phase 4 — Scripts ✅ {n}/{n} PASS ║ +║ Phase 5 — Security ✅ PASS (0 critical, 0 high) ║ +║ Phase 6 — Marketplace ✅ plugin.json valid ║ +║ Phase 7 — Ecosystem ✅ Codex + Gemini synced ║ +║ Phase 8 — Code Review ✅ {domain} review passed ║ +║ ║ +║ VERDICT: ✅ PASS — Ready for merge/publish ║ +║ ║ +║ Auto-fixes applied: {n} ║ +║ Warnings: {n} ║ +║ Action items: {n} ║ +║ ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### Verdict Logic + +| Condition | Verdict | +|-----------|---------| +| All phases pass | **PASS** — Ready for merge/publish | +| Only warnings (no blockers) | **PASS WITH WARNINGS** — Review warnings before merge | +| Any phase has a blocker | **FAIL** — List blockers with fix instructions | + +### Blockers (any of these = FAIL) + +- Structure score < 75 +- Quality score < 60 (after noting roadmap) +- Any script FAIL +- Any CRITICAL or HIGH security finding +- plugin.json invalid or has disallowed fields +- Version mismatch with repo + +### Non-Blockers (warnings only) + +- Quality score between 60-75 +- Script PARTIAL results +- Missing from one platform index (auto-fixed) +- Missing mkdocs.yml nav entry (auto-fixed) +- Security INFO findings + +--- + +## Skill References + +| Tool | Path | +|------|------| +| Skill Validator | `engineering/skill-tester/scripts/skill_validator.py` | +| Quality Scorer | `engineering/skill-tester/scripts/quality_scorer.py` | +| Script Tester | `engineering/skill-tester/scripts/script_tester.py` | +| Security Auditor | `engineering/skill-security-auditor/scripts/skill_security_auditor.py` | +| Quality Standards | `standards/quality/quality-standards.md` | +| Security Standards | `standards/security/security-standards.md` | +| Git Standards | `standards/git/git-workflow-standards.md` | diff --git a/docs/commands/code-to-prd.md b/docs/commands/code-to-prd.md new file mode 100644 index 0000000..438bee7 --- /dev/null +++ b/docs/commands/code-to-prd.md @@ -0,0 +1,84 @@ +--- +title: "/code-to-prd — Slash Command for AI Coding Agents" +description: "Reverse-engineer a frontend codebase into a PRD. Usage: /code-to-prd [path]. Slash command for Claude Code, Codex CLI, Gemini CLI." +--- + +# /code-to-prd + +
+:material-console: Slash Command +:material-github: Source +
+ + +Reverse-engineer a frontend codebase into a complete Product Requirements Document. + +## Usage + +```bash +/code-to-prd # Analyze current project +/code-to-prd ./src # Analyze specific directory +/code-to-prd /path/to/project # Analyze external project +``` + +## What It Does + +1. **Scan** — Run `codebase_analyzer.py` to detect framework, routes, APIs, enums, and project structure +2. **Scaffold** — Run `prd_scaffolder.py` to create `prd/` directory with README.md, per-page stubs, and appendix files +3. **Analyze** — Walk through each page following the Phase 2 workflow: fields, interactions, API dependencies, page relationships +4. **Generate** — Produce the final PRD with all pages, enum dictionary, API inventory, and page relationship map + +## Steps + +### Step 1: Analyze + +Determine the project path (default: current directory). Run the frontend analyzer: + +```bash +python3 {skill_path}/scripts/codebase_analyzer.py {project_path} -o .code-to-prd-analysis.json +``` + +Display a summary of findings: framework, page count, API count, enum count. + +### Step 2: Scaffold + +Generate the PRD directory skeleton: + +```bash +python3 {skill_path}/scripts/prd_scaffolder.py .code-to-prd-analysis.json -o prd/ +``` + +### Step 3: Fill + +For each page in the inventory, follow the SKILL.md Phase 2 workflow: +- Read the page's component files +- Document fields, interactions, API dependencies, page relationships +- Fill in the corresponding `prd/pages/` stub + +Work in batches of 3-5 pages for large projects (>15 pages). Ask the user to confirm after each batch. + +### Step 4: Finalize + +Complete the appendix files: +- `prd/appendix/enum-dictionary.md` — all enums and status codes found +- `prd/appendix/api-inventory.md` — consolidated API reference +- `prd/appendix/page-relationships.md` — navigation and data coupling map + +Clean up the temporary analysis file: +```bash +rm .code-to-prd-analysis.json +``` + +## Output + +A `prd/` directory containing: +- `README.md` — system overview, module map, page inventory +- `pages/*.md` — one file per page with fields, interactions, APIs +- `appendix/*.md` — enum dictionary, API inventory, page relationships + +## Skill Reference + +- `product-team/code-to-prd/SKILL.md` +- `product-team/code-to-prd/scripts/codebase_analyzer.py` +- `product-team/code-to-prd/scripts/prd_scaffolder.py` +- `product-team/code-to-prd/references/prd-quality-checklist.md` diff --git a/docs/commands/index.md b/docs/commands/index.md index 728e85e..f8a18a9 100644 --- a/docs/commands/index.md +++ b/docs/commands/index.md @@ -1,13 +1,13 @@ --- title: "Slash Commands — AI Coding Agent Commands & Codex Shortcuts" -description: "17 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more." +description: "19 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more." ---
# :material-console: Slash Commands -

17 commands for quick access to common operations

+

19 commands for quick access to common operations

@@ -19,6 +19,12 @@ description: "17 slash commands for Claude Code, Codex CLI, and Gemini CLI — s Generate Keep a Changelog entries from git history and validate commit message format. +- :material-console:{ .lg .middle } **[`/code-to-prd`](code-to-prd.md)** + + --- + + Reverse-engineer a frontend codebase into a complete Product Requirements Document. + - :material-console:{ .lg .middle } **[`/competitive-matrix`](competitive-matrix.md)** --- @@ -55,6 +61,12 @@ description: "17 slash commands for Claude Code, Codex CLI, and Gemini CLI — s Detect project stack and generate CI/CD pipeline configurations for GitHub Actions or GitLab CI. +- :material-console:{ .lg .middle } **[`/plugin-audit`](plugin-audit.md)** + + --- + + Full audit pipeline for any skill, plugin, agent, or command in this repository. Runs 8 validation phases, auto-fixes... + - :material-console:{ .lg .middle } **[`/prd`](prd.md)** --- diff --git a/docs/commands/plugin-audit.md b/docs/commands/plugin-audit.md new file mode 100644 index 0000000..2cc1d77 --- /dev/null +++ b/docs/commands/plugin-audit.md @@ -0,0 +1,314 @@ +--- +title: "/plugin-audit — Slash Command for AI Coding Agents" +description: "|. Slash command for Claude Code, Codex CLI, Gemini CLI." +--- + +# /plugin-audit + +
+:material-console: Slash Command +:material-github: Source +
+ + +Full audit pipeline for any skill, plugin, agent, or command in this repository. Runs 8 validation phases, auto-fixes what it can, and only stops for user input on critical decisions (breaking changes, new dependencies). + +## Usage + +```bash +/plugin-audit product-team/code-to-prd +/plugin-audit engineering/agenthub +/plugin-audit engineering-team/playwright-pro +``` + +## What It Does + +Execute all 8 phases sequentially. Stop on critical failures. Auto-fix non-critical issues. Report results at the end. + +--- + +## Phase 1: Discovery + +Identify what the skill contains and classify it. + +1. Verify `{skill_path}` exists and contains `SKILL.md` +2. Read `SKILL.md` frontmatter — extract `name`, `description`, `Category`, `Tier` +3. Detect skill type: + - Has `scripts/` → has Python tools + - Has `references/` → has reference docs + - Has `assets/` → has templates/samples + - Has `expected_outputs/` → has test fixtures + - Has `agents/` → has embedded agents + - Has `skills/` → has sub-skills (compound skill) + - Has `.claude-plugin/plugin.json` → is a standalone plugin + - Has `settings.json` → has command registrations +4. Detect domain from path: `engineering/`, `product-team/`, `marketing-skill/`, etc. +5. Check for associated command: search `commands/` for a `.md` file matching the skill name + +Display discovery summary before proceeding: +``` +Auditing: code-to-prd + Domain: product-team + Type: STANDARD skill with standalone plugin + Scripts: 2 | References: 2 | Assets: 1 | Expected outputs: 3 + Command: /code-to-prd (found) + Plugin: .claude-plugin/plugin.json (found) +``` + +--- + +## Phase 2: Structure Validation + +Run the skill-tester validator. + +```bash +python3 engineering/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json +``` + +Parse the JSON output. Extract: +- Overall score and compliance level +- Failed checks (list each) +- Errors and warnings + +**Gate rule:** Score must be ≥ 75 (GOOD). If below 75: +- Read the errors list +- Auto-fix what's possible: + - Missing frontmatter fields → add them from SKILL.md content + - Missing sections → add stub headings + - Missing directories → create empty ones with a note +- Re-run after fixes. If still below 75, report as FAIL and continue to collect remaining results. + +--- + +## Phase 3: Quality Scoring + +Run the quality scorer. + +```bash +python3 engineering/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json +``` + +Parse the JSON output. Extract: +- Overall score and letter grade +- Per-dimension scores (Documentation, Code Quality, Completeness, Usability) +- Improvement roadmap items + +**Gate rule:** Score must be ≥ 60 (C). If below 60, report the improvement roadmap items as action items. + +--- + +## Phase 4: Script Testing + +If the skill has `scripts/` with `.py` files, run the script tester. + +```bash +python3 engineering/skill-tester/scripts/script_tester.py {skill_path} --json --verbose +``` + +Parse the JSON output. For each script, extract: +- Pass/Partial/Fail status +- Individual test results + +**Gate rule:** All scripts must PASS. Any FAIL is a blocker. PARTIAL triggers a warning. + +**Auto-fix:** If a script fails the `--help` test, check if it has `argparse` — if not, this is a real issue. If it fails the stdlib-only test, flag the import and **ask the user** whether the dependency is acceptable (this is a critical decision). + +--- + +## Phase 5: Security Audit + +Run the skill security auditor. + +```bash +python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json +``` + +Parse the JSON output. Extract: +- Verdict (PASS/WARN/FAIL) +- Critical findings (must be zero) +- High findings (must be zero in strict mode) +- Info findings (advisory only) + +**Gate rule:** Zero CRITICAL findings. Zero HIGH findings. Any CRITICAL or HIGH is a blocker — report the exact file, line, pattern, and recommended fix. + +**Do NOT auto-fix security issues.** Report them and let the user decide. + +--- + +## Phase 6: Marketplace & Plugin Compliance + +### 6a. plugin.json Validation + +If `{skill_path}/.claude-plugin/plugin.json` exists: + +1. Parse as JSON — must be valid +2. Verify only allowed fields: `name`, `description`, `version`, `author`, `homepage`, `repository`, `license`, `skills` +3. Version must match repo version (`2.1.2`) +4. `skills` must be `"./"` +5. `name` must match the skill directory name + +**Auto-fix:** If version is wrong, update it. If extra fields exist, remove them. + +### 6b. settings.json Validation + +If `{skill_path}/settings.json` exists: + +1. Parse as JSON — must be valid +2. Version must match repo version +3. If `commands` field exists, verify each command has a matching file in `commands/` + +### 6c. Marketplace Entry + +Check if the skill has an entry in `.claude-plugin/marketplace.json`: + +1. Search the `plugins` array for an entry with `source` matching `./` + skill path +2. If found: verify `version`, `name`, and that `source` path exists +3. If not found: check if the skill's domain bundle (e.g., `product-skills`) would include it via its `source` path + +### 6d. Domain plugin.json + +Check the parent domain's `.claude-plugin/plugin.json`: +- Verify the skill count in the description matches reality +- Verify version matches repo version + +**Auto-fix:** Update stale counts. Fix version mismatches. + +--- + +## Phase 7: Ecosystem Integration + +### 7a. Cross-Platform Sync + +Verify the skill appears in platform indexes: + +```bash +grep -l "{skill_name}" .codex/skills-index.json .gemini/skills-index.json +``` + +If missing from either index: +```bash +python3 scripts/sync-codex-skills.py --verbose +python3 scripts/sync-gemini-skills.py --verbose +``` + +### 7b. Command Integration + +If the skill has associated commands (from settings.json `commands` field or matching name in `commands/`): +- Verify the command `.md` file has valid YAML frontmatter (`name`, `description`) +- Verify the command references the correct skill path +- Verify the command is in `mkdocs.yml` nav + +**Auto-fix:** Add missing mkdocs.yml nav entries. + +### 7c. Agent Integration + +If the skill has embedded agents (`{skill_path}/agents/*.md`): +- Verify each agent has valid YAML frontmatter +- Verify agent references resolve (relative paths to skills) + +Search `agents/` for any cs-* agent that references this skill: +```bash +grep -rl "{skill_name}\|{skill_path}" agents/ +``` + +If found, verify the agent's skill references are correct. + +### 7d. Cross-Skill Dependencies + +Read the SKILL.md for references to other skills (look for `../` paths, skill names in "Related Skills" sections): +- Verify each referenced skill exists +- Verify the referenced skill's SKILL.md exists + +--- + +## Phase 8: Domain-Appropriate Code Review + +Based on the skill's domain, invoke the appropriate agent's review perspective: + +| Domain | Agent | Review Focus | +|--------|-------|-------------| +| `engineering/` or `engineering-team/` | cs-senior-engineer | Architecture, code quality, CI/CD integration | +| `product-team/` | cs-product-manager | PRD quality, user story coverage, RICE alignment | +| `marketing-skill/` | cs-content-creator | Content quality, SEO optimization, brand voice | +| `ra-qm-team/` | cs-quality-regulatory | Compliance checklist, audit trail, regulatory alignment | +| `business-growth/` | cs-growth-strategist | Growth metrics, revenue impact, customer success | +| `finance/` | cs-financial-analyst | Financial model accuracy, metric definitions | +| Other | cs-senior-engineer | General code and architecture review | + +**How to invoke:** Read the agent's `.md` file to understand its review criteria. Apply those criteria to review the skill's SKILL.md, scripts, and references. This is NOT spawning a subagent — it's using the agent's documented perspective to structure your review. + +Review checklist (apply domain-appropriate lens): +- [ ] SKILL.md workflows are actionable and complete +- [ ] Scripts solve the stated problem correctly +- [ ] References contain accurate domain knowledge +- [ ] Templates/assets are production-ready +- [ ] No broken internal links +- [ ] Attribution present where required + +--- + +## Final Report + +Present results as a structured table: + +``` +╔══════════════════════════════════════════════════════════════╗ +║ PLUGIN AUDIT REPORT: {skill_name} ║ +╠══════════════════════════════════════════════════════════════╣ +║ ║ +║ Phase 1 — Discovery ✅ {type}, {domain} ║ +║ Phase 2 — Structure ✅ {score}/100 ({level}) ║ +║ Phase 3 — Quality ✅ {score}/100 ({grade}) ║ +║ Phase 4 — Scripts ✅ {n}/{n} PASS ║ +║ Phase 5 — Security ✅ PASS (0 critical, 0 high) ║ +║ Phase 6 — Marketplace ✅ plugin.json valid ║ +║ Phase 7 — Ecosystem ✅ Codex + Gemini synced ║ +║ Phase 8 — Code Review ✅ {domain} review passed ║ +║ ║ +║ VERDICT: ✅ PASS — Ready for merge/publish ║ +║ ║ +║ Auto-fixes applied: {n} ║ +║ Warnings: {n} ║ +║ Action items: {n} ║ +║ ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### Verdict Logic + +| Condition | Verdict | +|-----------|---------| +| All phases pass | **PASS** — Ready for merge/publish | +| Only warnings (no blockers) | **PASS WITH WARNINGS** — Review warnings before merge | +| Any phase has a blocker | **FAIL** — List blockers with fix instructions | + +### Blockers (any of these = FAIL) + +- Structure score < 75 +- Quality score < 60 (after noting roadmap) +- Any script FAIL +- Any CRITICAL or HIGH security finding +- plugin.json invalid or has disallowed fields +- Version mismatch with repo + +### Non-Blockers (warnings only) + +- Quality score between 60-75 +- Script PARTIAL results +- Missing from one platform index (auto-fixed) +- Missing mkdocs.yml nav entry (auto-fixed) +- Security INFO findings + +--- + +## Skill References + +| Tool | Path | +|------|------| +| Skill Validator | `engineering/skill-tester/scripts/skill_validator.py` | +| Quality Scorer | `engineering/skill-tester/scripts/quality_scorer.py` | +| Script Tester | `engineering/skill-tester/scripts/script_tester.py` | +| Security Auditor | `engineering/skill-security-auditor/scripts/skill_security_auditor.py` | +| Quality Standards | `standards/quality/quality-standards.md` | +| Security Standards | `standards/security/security-standards.md` | +| Git Standards | `standards/git/git-workflow-standards.md` | diff --git a/docs/skills/product-team/code-to-prd.md b/docs/skills/product-team/code-to-prd.md new file mode 100644 index 0000000..9b4a843 --- /dev/null +++ b/docs/skills/product-team/code-to-prd.md @@ -0,0 +1,500 @@ +--- +title: "Code → PRD: Reverse-Engineer Any Codebase into Product Requirements — Agent Skill for Product Teams" +description: "|. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +--- + +# Code → PRD: Reverse-Engineer Any Codebase into Product Requirements + +
+:material-lightbulb-outline: Product +:material-identifier: `code-to-prd` +:material-github: Source +
+ +
+Install: claude /plugin install product-skills +
+ +## Name + +Code → PRD + +## Description + +Reverse-engineer any frontend, backend, or fullstack codebase into a complete Product Requirements Document (PRD). Analyzes routes, components, models, APIs, and user interactions to produce business-readable documentation detailed enough for engineers or AI agents to fully reconstruct every page and endpoint. + +# Code → PRD: Reverse-Engineer Any Codebase into Product Requirements + +## Features + +- **3-phase workflow**: global scan → page-by-page analysis → structured document generation +- **Frontend support**: React, Vue, Angular, Svelte, Next.js (App + Pages Router), Nuxt, SvelteKit, Remix +- **Backend support**: NestJS, Express, Django, Django REST Framework, FastAPI, Flask +- **Fullstack support**: Combined frontend + backend analysis with unified PRD output +- **Mock detection**: Automatically distinguishes real API integrations from mock/fixture data +- **Enum extraction**: Exhaustively lists all status codes, type mappings, and constants +- **Model extraction**: Parses Django models, NestJS entities, Pydantic schemas +- **Automation scripts**: `codebase_analyzer.py` for scanning, `prd_scaffolder.py` for directory generation +- **Quality checklist**: Validation checklist for completeness, accuracy, readability + +## Usage + +```bash +# Analyze a project and generate PRD skeleton +python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json +python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App" + +# Or use the slash command +/code-to-prd /path/to/project +``` + +## Examples + +### Frontend (React) +```bash +/code-to-prd ./src +# → Scans components, routes, API calls, state management +# → Generates prd/ with per-page docs, enum dictionary, API inventory +``` + +### Backend (Django) +```bash +/code-to-prd ./myproject +# → Detects Django via manage.py, scans urls.py, views.py, models.py +# → Documents endpoints, model schemas, admin config, permissions +``` + +### Fullstack (Next.js) +```bash +/code-to-prd . +# → Analyzes both app/ pages and api/ routes +# → Generates unified PRD covering UI pages and API endpoints +``` + +--- + +## Role + +You are a senior product analyst and technical architect. Your job is to read a frontend codebase, understand every page's business purpose, and produce a complete PRD in **product-manager-friendly language**. + +### Dual Audience + +1. **Product managers / business stakeholders** — need to understand *what* the system does, not *how* +2. **Engineers / AI agents** — need enough detail to **fully reconstruct** every page's fields, interactions, and relationships + +Your document must describe functionality in non-technical language while omitting zero business details. + +### Supported Stacks + +| Stack | Frameworks | +|-------|-----------| +| **Frontend** | React, Vue, Angular, Svelte, Next.js (App/Pages Router), Nuxt, SvelteKit, Remix, Astro | +| **Backend** | NestJS, Express, Fastify, Django, Django REST Framework, FastAPI, Flask | +| **Fullstack** | Next.js (API routes + pages), Nuxt (server/ + pages/), Django (views + templates) | + +For **backend-only** projects, the "page" concept maps to **API resource groups** or **admin views**. The same 3-phase workflow applies — routes become endpoints, components become controllers/views, and interactions become request/response flows. + +--- + +## Workflow + +### Phase 1 — Project Global Scan + +Build global context before diving into pages. + +#### 1. Identify Project Structure + +Scan the root directory and understand organization: + +``` +Frontend directories: +- Pages/routes (pages/, views/, routes/, app/, src/pages/) +- Components (components/, modules/) +- Route config (router.ts, routes.ts, App.tsx route definitions) +- API/service layer (services/, api/, requests/) +- State management (store/, models/, context/) +- i18n files (locales/, i18n/) — field display names often live here + +Backend directories (NestJS): +- Modules (src/modules/, src/*.module.ts) +- Controllers (*.controller.ts) — route handlers +- Services (*.service.ts) — business logic +- DTOs (dto/, *.dto.ts) — request/response shapes +- Entities (entities/, *.entity.ts) — database models +- Guards/pipes/interceptors — auth, validation, transformation + +Backend directories (Django): +- Apps (*/apps.py, */views.py, */models.py, */urls.py) +- URL config (urls.py, */urls.py) +- Views (views.py, viewsets.py) — route handlers +- Models (models.py) — database schema +- Serializers (serializers.py) — request/response shapes +- Forms (forms.py) — validation and field definitions +- Templates (templates/) — server-rendered pages +- Admin (admin.py) — admin panel configuration +``` + +**Identify framework** from `package.json` (Node.js frameworks) or project files (`manage.py` for Django, `requirements.txt`/`pyproject.toml` for Python). Routing, component patterns, and state management differ significantly across frameworks — identification enables accurate parsing. + +#### 2. Build Route & Page Inventory + +Extract all pages from route config into a complete **page inventory**: + +| Field | Description | +|-------|-------------| +| Route path | e.g. `/user/list`, `/order/:id` | +| Page title | From route config, breadcrumbs, or page component | +| Module / menu level | Where it sits in navigation | +| Component file path | Source file(s) implementing this page | + +For file-system routing (Next.js, Nuxt), infer from directory structure. + +**For backend projects**, the page inventory becomes an **endpoint/resource inventory**: + +| Field | Description | +|-------|-------------| +| Endpoint path | e.g. `/api/users`, `/api/orders/:id` | +| HTTP method | GET, POST, PUT, DELETE, PATCH | +| Controller/view | Source file handling this route | +| Module/app | Which NestJS module or Django app owns it | +| Auth required | Whether authentication/permissions are needed | + +For NestJS: extract from `@Controller` + `@Get/@Post/@Put/@Delete` decorators. +For Django: extract from `urls.py` → `urlpatterns` and `viewsets.py` → router registrations. + +#### 3. Map Global Context + +Before analyzing individual pages, capture: + +- **Global state** — user info, permissions, feature flags, config +- **Shared components** — layout, nav, auth guards, error boundaries +- **Enums & constants** — status codes, type mappings, role definitions +- **API base config** — base URL, interceptors, auth headers, error handling +- **Database models** (backend) — entity relationships, field types, constraints +- **Middleware** (backend) — auth middleware, rate limiting, logging, CORS +- **DTOs/Serializers** (backend) — request validation shapes, response formats + +These will be referenced throughout page/endpoint analysis. + +--- + +### Phase 2 — Page-by-Page Deep Analysis + +Analyze every page in the inventory. **Each page produces its own Markdown file.** + +#### Analysis Dimensions + +For each page, answer: + +##### A. Page Overview +- What does this page do? (one sentence) +- Where does it fit in the system? +- What scenario brings a user here? + +##### B. Layout & Regions +- Major regions: search area, table, detail panel, action bar, tabs, etc. +- Spatial arrangement: top/bottom, left/right, nested + +##### C. Field Inventory (core — be exhaustive) + +**For form pages**, list every field: + +| Field Name | Type | Required | Default | Validation | Business Description | +|-----------|------|----------|---------|------------|---------------------| +| Username | Text input | Yes | — | Max 20 chars | System login account | + +**For table/list pages**, list: +- Search/filter fields (type, required, enum options) +- Table columns (name, format, sortable, filterable) +- Row action buttons (what each one does) + +**Field name extraction priority:** +1. Hardcoded display text in code +2. i18n translation values +3. Component `placeholder` / `label` / `title` props +4. Variable names (last resort — provide reasonable display name) + +##### D. Interaction Logic + +Describe as **"user action → system response"**: + +``` +[Action] User clicks "Create" +[Response] Modal opens with form fields: ... +[Validation] Name required, phone format check +[API] POST /api/user/create with form data +[Success] Toast "Created successfully", close modal, refresh list +[Failure] Show API error message +``` + +**Cover all interaction types:** +- Page load / initialization (default queries, preloaded data) +- Search / filter / reset +- CRUD operations (create, read, update, delete) +- Table: pagination, sorting, row selection, bulk actions +- Form submission & validation +- Status transitions (e.g. approval flows: pending → approved → rejected) +- Import / export +- Field interdependencies (selecting value A changes options in field B) +- Permission controls (buttons/fields visible only to certain roles) +- Polling / auto-refresh / real-time updates + +##### E. API Dependencies + +**Case 1: API is integrated** (real HTTP calls in code) + +| API Name | Method | Path | Trigger | Key Params | Notes | +|----------|--------|------|---------|-----------|-------| +| Get users | GET | /api/user/list | Load, search | page, size, keyword | Paginated | + +**Case 2: API not integrated** (mock/hardcoded data) + +When the page uses mock data, hardcoded fixtures, `setTimeout` simulations, or `Promise.resolve()` stubs — the API isn't real yet. **Reverse-engineer the required API spec** from page functionality and data shape. + +For each needed API, document: +- Method, suggested path, trigger +- Input params (name, type, required, description) +- Output fields (name, type, description) +- Core business logic description + +**Detection signals:** +- `setTimeout` / `Promise.resolve()` returning data → mock +- Data defined in component or `*.mock.*` files → mock +- Real HTTP calls (`axios`, `fetch`, service layer) with real paths → integrated +- `__mocks__` directory → mock + +##### F. Page Relationships + +- **Inbound**: Which pages link here? What parameters do they pass? +- **Outbound**: Where can users navigate from here? What parameters? +- **Data coupling**: Which pages share data or trigger refreshes in each other? + +--- + +### Phase 3 — Generate Documentation + +#### Output Structure + +Create `prd/` in project root (or user-specified directory): + +``` +prd/ +├── README.md # System overview +├── pages/ +│ ├── 01-user-mgmt-list.md # One file per page +│ ├── 02-user-mgmt-detail.md +│ ├── 03-order-mgmt-list.md +│ └── ... +└── appendix/ + ├── enum-dictionary.md # All enums, status codes, type mappings + ├── page-relationships.md # Navigation map between pages + └── api-inventory.md # Complete API reference +``` + +#### README.md Template + +```markdown +# [System Name] — Product Requirements Document + +## System Overview +[2-3 paragraphs: what the system does, business context, primary users] + +## Module Overview + +| Module | Pages | Core Functionality | +|--------|-------|--------------------| +| User Management | User list, User detail, Role mgmt | CRUD users, assign roles and permissions | + +## Page Inventory + +| # | Page Name | Route | Module | Doc Link | +|---|-----------|-------|--------|----------| +| 1 | User List | /user/list | User Mgmt | [→](./pages/01-user-mgmt-list.md) | + +## Global Notes + +### Permission Model +[Summarize auth/role system if present in code] + +### Common Interaction Patterns +[Global rules: all deletes require confirmation, lists default to created_at desc, etc.] +``` + +#### Per-Page Document Template + +```markdown +# [Page Name] + +> **Route:** `/xxx/xxx` +> **Module:** [Module name] +> **Generated:** [Date] + +## Overview +[2-3 sentences: core function and use case] + +## Layout +[Region breakdown — text description or ASCII diagram] + +## Fields + +### [Region: e.g. "Search Filters"] +| Field | Type | Required | Options / Enum | Default | Notes | +|-------|------|----------|---------------|---------|-------| + +### [Region: e.g. "Data Table"] +| Column | Format | Sortable | Filterable | Notes | +|--------|--------|----------|-----------|-------| + +### [Region: e.g. "Actions"] +| Button | Visibility Condition | Behavior | +|--------|---------------------|----------| + +## Interactions + +### Page Load +[What happens on mount] + +### [Scenario: e.g. "Search"] +- **Trigger:** [User action] +- **Behavior:** [System response] +- **Special rules:** [If any] + +### [Scenario: e.g. "Create"] +- **Trigger:** ... +- **Modal/drawer content:** [Fields and logic inside] +- **Validation:** ... +- **On success:** ... + +## API Dependencies + +| API | Method | Path | Trigger | Notes | +|-----|--------|------|---------|-------| +| ... | ... | ... | ... | ... | + +## Page Relationships +- **From:** [Source pages + params] +- **To:** [Target pages + params] +- **Data coupling:** [Cross-page refresh triggers] + +## Business Rules +[Anything that doesn't fit above] +``` + +--- + +## Key Principles + +### 1. Business Language First +Don't write "calls `useState` to manage loading state." Write "search button shows a spinner to prevent duplicate submissions." + +Don't write "useEffect fetches on mount." Write "page automatically loads the first page of results on open." + +Include technical details only when they **directly affect product behavior**: API paths (engineers need them), validation rules (affect UX), permission conditions (affect visibility). + +### 2. Don't Miss Hidden Logic +Code contains logic PMs may not realize exists: +- Field interdependencies (type A shows field X; type B shows field Y) +- Conditional button visibility +- Data formatting (currency with 2 decimals, date formats, status label mappings) +- Default sort order and page size +- Debounce/throttle effects on user input +- Polling / auto-refresh intervals + +### 3. Exhaustively List Enums +When code defines enums (status codes, type codes, role types), list **every value and its meaning**. These are often scattered across constants files, component `valueEnum` configs, or API response mappers. + +### 4. Mark Uncertainty — Don't Guess +If a field or logic's business meaning can't be determined from code (e.g. abbreviated variable names, overly complex conditionals), mark it `[TBC]` and explain what you observed and why you're uncertain. Never fabricate business meaning. + +### 5. Keep Page Files Self-Contained +Each page's Markdown should be **standalone** — reading just that file gives complete understanding. Use relative links when referencing other pages or appendix entries. + +--- + +## Page Type Strategies + +### Frontend Pages + +| Page Type | Focus Areas | +|-----------|------------| +| **List / Table** | Search conditions, columns, row actions, pagination, bulk ops | +| **Form / Create-Edit** | Every field, validation, interdependencies, post-submit behavior | +| **Detail / View** | Displayed info, tab/section organization, available actions | +| **Modal / Drawer** | Describe as part of triggering page — not a separate file. But fully document content | +| **Dashboard** | Data cards, charts, metrics meaning, filter dimensions, refresh frequency | + +### Backend Endpoints (NestJS / Django / Express) + +| Endpoint Type | Focus Areas | +|---------------|------------| +| **CRUD resource** | All fields (from DTO/serializer), validation rules, permissions, pagination, filtering, sorting | +| **Auth endpoints** | Login/register flow, token format, refresh logic, password reset, OAuth providers | +| **File upload** | Accepted types, size limits, storage destination, processing pipeline | +| **Webhook / event** | Trigger conditions, payload shape, retry policy, idempotency | +| **Background job** | Trigger, schedule, input/output, failure handling, monitoring | +| **Admin views** (Django) | Registered models, list_display, search_fields, filters, inline models, custom actions | + +--- + +## Execution Pacing + +**Large projects (>15 pages):** Work in batches of 3-5 pages per module. Complete system overview + page inventory first. Output each batch for user review before proceeding. + +**Small projects (≤15 pages):** Complete all analysis in one pass. + +--- + +## Common Pitfalls + +| Pitfall | Fix | +|---------|-----| +| Using component names as page names | `UserManagementTable` → "User Management List" | +| Skipping modals and drawers | They contain critical business logic — document fully | +| Missing i18n field names | Check translation files, not just component JSX | +| Ignoring dynamic route params | `/order/:id` = page requires an order ID to load | +| Forgetting permission controls | Document which roles see which buttons/pages | +| Assuming all APIs are real | Check for mock data patterns before documenting endpoints | +| Skipping Django admin customization | `admin.py` often contains critical business rules (list filters, custom actions, inlines) | +| Missing NestJS guards/pipes | `@UseGuards`, `@UsePipes` contain auth and validation logic that affects behavior | +| Ignoring database constraints | Model field constraints (unique, max_length, choices) are validation rules for the PRD | +| Overlooking middleware | Auth middleware, rate limiters, and CORS config define system-wide behavior | + +--- + +## Tooling + +### Scripts + +| Script | Purpose | Usage | +|--------|---------|-------| +| `scripts/codebase_analyzer.py` | Scan codebase → extract routes, APIs, models, enums, structure | `python3 codebase_analyzer.py /path/to/project` | +| `scripts/prd_scaffolder.py` | Generate PRD directory skeleton from analysis JSON | `python3 prd_scaffolder.py analysis.json` | + +**Recommended workflow:** +```bash +# 1. Analyze the project (JSON output — works for frontend, backend, or fullstack) +python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json + +# 2. Review the analysis (markdown summary) +python3 scripts/codebase_analyzer.py /path/to/project -f markdown + +# 3. Scaffold the PRD directory with stubs +python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App" + +# 4. Fill in TODO sections page-by-page using the SKILL.md workflow +``` + +Both scripts are **stdlib-only** — no pip install needed. + +### References + +| File | Contents | +|------|----------| +| `references/prd-quality-checklist.md` | Validation checklist for completeness, accuracy, readability | +| `references/framework-patterns.md` | Framework-specific patterns for routes, state, APIs, forms, permissions | + +--- + +## Attribution + +This skill was inspired by [code-to-prd](https://github.com/lihanglogan/code-to-prd) by [@lihanglogan](https://github.com/lihanglogan), who proposed the original concept and methodology in [PR #368](https://github.com/alirezarezvani/claude-skills/pull/368). The core three-phase workflow (global scan → page-by-page analysis → structured document generation) originated from that work. This version was rebuilt from scratch in English with added tooling (analysis scripts, scaffolder, framework reference, quality checklist). diff --git a/docs/skills/product-team/index.md b/docs/skills/product-team/index.md index 749a3d4..74eded5 100644 --- a/docs/skills/product-team/index.md +++ b/docs/skills/product-team/index.md @@ -1,13 +1,13 @@ --- title: "Product Skills — Agent Skills & Codex Plugins" -description: "14 product skills — product management agent skill and Claude Code plugin for PRDs, discovery, analytics, and roadmaps. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." +description: "15 product skills — product management agent skill and Claude Code plugin for PRDs, discovery, analytics, and roadmaps. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." ---
# :material-lightbulb-outline: Product -

14 skills in this domain

+

15 skills in this domain

@@ -23,6 +23,12 @@ description: "14 product skills — product management agent skill and Claude Co Backlog management and sprint execution toolkit for product owners, including user story generation, acceptance crite... +- **[Code → PRD: Reverse-Engineer Any Codebase into Product Requirements](code-to-prd.md)** + + --- + + - 3-phase workflow: global scan → page-by-page analysis → structured document generation + - **[Competitive Teardown](competitive-teardown.md)** --- diff --git a/mkdocs.yml b/mkdocs.yml index 4a73078..e0ec0f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -212,6 +212,7 @@ nav: - "Experiment Designer": skills/product-team/experiment-designer.md - "Landing Page Generator": skills/product-team/landing-page-generator.md - "Product Analytics": skills/product-team/product-analytics.md + - "Code to PRD": skills/product-team/code-to-prd.md - "Product Discovery": skills/product-team/product-discovery.md - "Product Manager Toolkit": skills/product-team/product-manager-toolkit.md - "Product Strategist": skills/product-team/product-strategist.md @@ -364,11 +365,13 @@ nav: - Commands: - Overview: commands/index.md - "/changelog": commands/changelog.md + - "/code-to-prd": commands/code-to-prd.md - "/competitive-matrix": commands/competitive-matrix.md - "/financial-health": commands/financial-health.md - "/okr": commands/okr.md - "/persona": commands/persona.md - "/pipeline": commands/pipeline.md + - "/plugin-audit": commands/plugin-audit.md - "/prd": commands/prd.md - "/project-health": commands/project-health.md - "/retro": commands/retro.md diff --git a/product-team/.claude-plugin/plugin.json b/product-team/.claude-plugin/plugin.json index ead9362..990fbcd 100644 --- a/product-team/.claude-plugin/plugin.json +++ b/product-team/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "product-skills", - "description": "12 production-ready product skills: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, and roadmap communicator. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "14 production-ready product skills: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, code-to-prd, research summarizer. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.1.2", "author": { "name": "Alireza Rezvani", diff --git a/product-team/CLAUDE.md b/product-team/CLAUDE.md index 472505a..ee08524 100644 --- a/product-team/CLAUDE.md +++ b/product-team/CLAUDE.md @@ -1,6 +1,6 @@ # Product Team Skills - Claude Code Guidance -This guide covers the 12 production-ready product management skills and their Python automation tools. +This guide covers the 14 production-ready product management skills and their Python automation tools. ## Product Skills Overview @@ -17,12 +17,14 @@ This guide covers the 12 production-ready product management skills and their Py 10. **experiment-designer/** - Experiment design and sample size planning (1 tool) 11. **product-discovery/** - Discovery frameworks and assumption mapping (1 tool) 12. **roadmap-communicator/** - Roadmap communication and changelog generation (1 tool) +13. **code-to-prd/** - Reverse-engineer any codebase into PRD (2 tools: codebase_analyzer, prd_scaffolder) +14. **research-summarizer/** - Research synthesis and summarization (1 tool) -**Total Tools:** 13 Python automation tools +**Total Tools:** 16 Python automation tools **Agents:** 5 (cs-product-manager, cs-agile-product-owner, cs-product-strategist, cs-ux-researcher, cs-product-analyst) -**Slash Commands:** 7 (/rice, /okr, /persona, /user-story, /competitive-matrix, /prd, /sprint-plan) +**Slash Commands:** 8 (/rice, /okr, /persona, /user-story, /competitive-matrix, /prd, /sprint-plan, /code-to-prd) ## Python Automation Tools @@ -308,7 +310,7 @@ python roadmap-communicator/scripts/changelog_generator.py --from v1.0.0 --to HE --- -**Last Updated:** March 11, 2026 -**Skills Deployed:** 12/12 product skills production-ready -**Total Tools:** 13 Python automation tools -**Agents:** 5 | **Commands:** 7 +**Last Updated:** March 17, 2026 +**Skills Deployed:** 14/14 product skills production-ready +**Total Tools:** 16 Python automation tools +**Agents:** 5 | **Commands:** 8