feat(product-team): add code-to-prd skill — reverse-engineer any codebase into PRD

[alirezarezvani]

Summary

• Adds code-to-prd skill to product-team/ — reverse-engineers frontend, backend, or fullstack codebases into complete Product Requirements Documents
• Fullstack support: React, Vue, Angular, Svelte, Next.js, Nuxt, NestJS, Express, Django, DRF, FastAPI, Flask
• 2 Python scripts (codebase_analyzer.py, prd_scaffolder.py), 2 reference guides, 3 expected output samples
• /code-to-prd slash command (4-step workflow: analyze → scaffold → fill → finalize)
• Marketplace entry with 15 keywords, settings.json with command registration
• Skill-tester validated: 97.6/100 (EXCELLENT), quality 73.2/100 (B-), scripts 2/2 PASS
• Attribution to @lihanglogan for the original concept (PR #368)

Test plan

• python3 codebase_analyzer.py --help exits 0
• python3 prd_scaffolder.py --help exits 0
• prd_scaffolder.py --validate-only validates sample JSON
• prd_scaffolder.py --dry-run shows planned output without writing
• skill_validator.py scores 97.6/100 (EXCELLENT)
• quality_scorer.py scores 73.2/100 (B-, STANDARD tier)
• script_tester.py passes 2/2 scripts (18/18 checks)
• plugin.json schema-valid (8/8 allowed fields, version 2.1.2)
• YAML frontmatter valid with all required fields
• Test on a real Next.js project
• Test on a real Django project

🤖 Generated with Claude Code

[claude]

Code Review — feat(product-team): code-to-prd skill

Note: This PR has already been merged. Leaving this review for tracking and future improvement.

Overall this is a solid, well-structured addition. The 4-step workflow is clear, both scripts pass --help, and the scaffold output is genuinely useful. A few things worth addressing in a follow-up.

---

Bugs / Issues

1. agenthub displaced from marketplace.json
The diff replaces the agenthub entry with code-to-prd rather than appending a new entry. If agenthub is intentionally being removed that should be explicit, but it looks unintentional — agenthub is still present in engineering/agenthub/. This should be an append, not a replace.

2. Duplicate imports in prd_scaffolder.py

from pathlib import Path      # line ~2061
from typing import Any, Dict, List, Optional

from pathlib import Path      # duplicate ~2063
from typing import Any, Dict, List

pathlib.Path and the typing imports are declared twice. The second import also drops Optional, which is used elsewhere in the file (Optional[str] in scaffold()). While Python silently handles duplicate imports, the missing Optional could cause a NameError at runtime if the second import shadows the first in some edge cases. Clean this up.

3. Command description mismatch
commands/code-to-prd.md line 4 reads:

"Reverse-engineer a frontend codebase into a PRD"

But the skill supports frontend, backend, and fullstack. This description should match the SKILL.md description.

4. YAML frontmatter has duplicate keys
SKILL.md frontmatter contains both Name: code-to-prd and name: code-to-prd. YAML parsers typically use the last occurrence of a duplicate key, which could cause inconsistent behavior depending on the parser. Use one canonical key (name).

---

Quality

5. Quality score is 73.2/100 (B-)
The PR description notes this is below the EXCELLENT threshold. Per CLAUDE.md quality standards, skills should save users 40%+ time. The quality report should be addressed before publishing to ClawHub. Specific gaps worth filling:

• The ## Module Overview table in README.md scaffolding is pre-filled with a single <!-- TODO --> row — it could auto-group routes by common path prefix to give users a starting point.
• prd_scaffolder.py does not handle fullstack projects (both frontend_pages and backend_endpoints in the routes object) — it only reads routes.pages, so fullstack analysis output from codebase_analyzer.py won't be scaffolded properly.

6. Integration tests are unchecked

- [ ] Test on a real Next.js project
- [ ] Test on a real Django project

These two items remain unchecked in the test plan. For a skill claiming fullstack support, end-to-end tests on at least one real project should be a merge prerequisite.

---

Minor

• settings.json commands block maps "code-to-prd": "/code-to-prd" — the value is the command invocation string, which is inconsistent with other skills in the repo that use the command name as both key and value. Double-check the expected schema.
• generate_page_relationships() caps the navigation map at 20 routes with routes[:20] but prints no notice if routes are truncated — worth adding # ... ({n} more) only when truncation actually occurs (it does, but it's in an if block that's clear).

---

What's Working Well

• Scripts are stdlib-only with no pip dependencies — consistent with repo philosophy.
• --validate-only and --dry-run flags make the tooling safe to test.
• Mock detection logic in codebase_analyzer.py is a thoughtful addition.
• Attribution to @lihanglogan in README is a good practice.
• plugin.json correctly follows the 8-field schema constraint from CLAUDE.md.

---

Suggested follow-up PR:

1. Restore agenthub to marketplace.json (append code-to-prd instead of replacing).
2. Fix duplicate imports in prd_scaffolder.py.
3. Fix command description in commands/code-to-prd.md.
4. Add fullstack route handling in scaffolder (frontend_pages + backend_endpoints).
5. Run against at least one real Next.js or Django project and document the result.

🤖 Generated with Claude Code