docs(readme): comparative audit — start-method accuracy + comparator benchmark + About/badge gaps + 12-item action list

[ComBba]

Summary

Comparative audit of README.md, About panel, badges, and discoverability metadata against 7 comparable Claude Code plugin / agent harness public repos. The README structure is competitive — hero PNG, badge density (11), tagline, and profile table are above the comparator median. The biggest weaknesses are factual drift (stale counts), missing recent-feature documentation (/pf:preview and H2 auto-launch), absence of a custom Open Graph image, and no motion (GIF/video) on a hackathon judged 25% on demoability.

This issue captures the full audit including the corroborating sources, so nothing is lost in PR-description archaeology.

---

Audit scope

1. Does the README accurately cover the start method and all rules?
2. How does the README compare to peer harness / Claude Code plugin repos?
3. Is the About panel and the badge set sufficient?
4. What are the prioritized improvements?

Today's date: 2026-04-26. Hackathon submission deadline: 2026-04-26 20:00 EST.

---

1. Start method + rules accuracy

Accurate (✅)

Area	Evidence
Install path: /plugin marketplace add → install pf → /reload-plugins → /pf:bootstrap → /pf:new	README L54–L80
Profile flags: --profile=standard|pro|max, --previews=N, --no-cache	L77–L91
Profile escalation precedence (Hard-require / Soft-suggest / Hint)	L100–L106
Cost regression + Rule 9 idea-drift detector	L109–L111
Two human gates (H1 design, H2 ship)	L7, L41–L46
Memory 4-layer rules (CLAUDE.md / PROGRESS.md / LESSONS.md / Anthropic Memory Tool)	L272–L278
Profile escalation history file path ~/.preview-forge/escalation-history.json	L103

Stale or missing (❌)

Area	Current	Should be	Severity
/pf:preview slash command + H2→preview-server auto-launch (PR #104)	Not documented anywhere	New section in "Slash Commands" + a note in the install/run flow	High
H1→SpecDD auto-advance (PR #103)	Not surfaced	Documented in run-flow narrative	Medium
Slash command count "14"	14 (badge L20, sections L177, L246, L253)	15 (PR #104 added /pf:preview)	High — appears in 4 places
Agent count "143"	143 (L8, L33, L213, L231, L245)	144 (scripts/verify-plugin.sh:48 checks -eq 144; v1.5 added scc-build-config)	High — appears in 5 places
verify-plugin.sh "56 checks"	L295	57 checks (PR #100/#101/#103/#104 each added asserts)	Medium
"What's inside" — Hooks 3	L247	7 (factory-policy, askuser-enforcement, auto-retro-trigger, idea-drift-detector, cost-regression, escalation-ledger, post-h1-signal)	High
"What's inside" — JSON schemas 3	L251	6 (preview-card, panel-vote, score-report, pf-profile, idea-spec + follow-ups)	High
"What's inside" — duplicate Slash commands row	L246 and L253	Single row	Bug
Layer-0 7 non-negotiable rules	Linked at L288, never inlined	Inline summary so first-time reader sees the contract without click-through	Medium

---

2. Comparator landscape (7 repos benchmarked)

Repo	Stars	Hero asset	Badges	Custom OG	Discussions	Topics
affaan-m/everything-claude-code	167k+	✅ hero.png	13	✅	?	8
wshobson/agents	34.3k	text callouts	4	✅	?	20
SuperClaude-Org/SuperClaude_Framework	22.5k	text-based	6	✅	✅	6
jeremylongshore/claude-code-plugins-plus-skills	2k	text-based	6	✅	?	16
SethGammon/Citadel	523	✅ Citadel-hero.svg	5 + interactive demo	✅	?	4
anothervibecoder-s/claudecode-harness	183	text only	concept list	❌	❌	0
dralgorhythm/claude-agentic-framework	71	none	none	❌	❌	7
Preview Forge (us)	0	✅ v1.6-gallery-hero.png	11	❌	❌	14

Where we already win

1. Badge density — 11 visible badges (CI / Marketplace Validate / Pages / Release / License / Built-with-Opus / Plugin / 143-Agents / 3-DD / 14-cmds / Stars-social). Above comparator median of 4–6.
2. Hero image above the fold — only 2/7 comparators have one (Citadel SVG, ECC PNG). Ours is a real product screenshot, stronger signal than abstract banners.
3. Tagline — TDD drove code with tests. SpecDD drove code with specs. We put PreviewDD in front. is a Citadel-class inversion punchline. Stronger than the generic "production-grade orchestration harness" pattern most competitors use.
4. License — Apache-2.0 is friendlier for enterprise downstreams than the MIT default.
5. Topics — 14 topics, above comparator median of 7.
6. Live CI/Marketplace/Pages badges — most small comparators don't bother. Green builds visible at a glance.

Where we lose

1. No custom Open Graph image (usesCustomOpenGraphImage: false). When the URL is shared on Slack / Twitter / Discord (every channel a hackathon judge is in), it falls back to the generic GitHub auto-OG. Citadel, ECC, SuperClaude all override this.
2. No demo GIF/video in the README. Hackathon judges 25 % on demo. A 10–15 s loop of /pf:new "..." → 26 mockups → pick → freeze would directly hit the rubric. Static gallery screenshot does not. ECC has animated demos; Citadel has an interactive demo link.
3. No "Why" / problem-pain section near top. Citadel: Stop re-explaining your codebase every session. claudecode-harness: Stop chatting with AI. Start engineering with it. We open with methodology jargon; the gallery-first pain framing only appears at L117.
4. No demo video link. README L298 has "Hackathon" section but does not link the actual 3-min Loom/YouTube — yet that is the primary submission artifact.
5. About description = 247 chars — GitHub truncates ~200. Tail (Built with Opus 4.7 hackathon.) gets cut off in repo listings.
6. Discussions OFF. Citadel and ECC both have it on. Free engagement signal.
7. Topics under-leveraged. Missing high-search terms: agent-orchestration, software-factory, preview-driven-development, subagents, claude-code-hooks, claude-code-skills, multi-agent-system, mcp. wshobson has 20.
8. homepageUrl points to a static HTML in the repo (preview-forge-proposal.html). ECC: ecc.tools; Citadel: interactive demo; SuperClaude: netlify. We could point to our live Pages site instead.
9. Layer-0 7 rules linked but never summarized inline.
10. No comparison strip — gallery-first is a real differentiator vs SuperClaude / wshobson, but the README never positions it.
11. No "Try it now" / live preview — Citadel has interactive demo, jeremylongshore has direct npm install. We require Claude Code Pro/Max to see anything.

---

3. About + badges field-by-field audit

About panel (gh repo view data)

Field	Current	Target	Severity
description	247 chars (truncates in listings)	≤200 chars	Medium
homepageUrl	…/blob/main/preview-forge-proposal.html (static HTML in repo)	https://two-weeks-team.github.io/PreviewForgeForClaudeCode/ (live Pages)	High
repositoryTopics	14 (anthropic, claude-code, claude-code-plugin, hackathon, multi-agent, nestia, nextjs, openapi, opus-4-7, spec-driven-development, test-driven-development, typescript, 3-dd, preview-driven-development)	+ agent-orchestration, software-factory, subagents, claude-code-hooks, claude-code-skills, mcp, multi-agent-system	Low–Medium
licenseInfo	Apache-2.0	✅ Keep	—
hasDiscussionsEnabled	false	true	Low (1 toggle)
usesCustomOpenGraphImage	false	true (upload via Settings → Social preview)	High
fundingLinks	[]	OK for hackathon	—

Badge audit (README header)

Badge	Status	Notes
CI	✅ Live, green	Keep
Marketplace Validate	✅ Live	Keep
Pages deploy	✅ Live	Keep
GitHub Release version	✅ Auto-updates	Keep
License: Apache 2.0	✅	Keep
Built with Opus 4.7	✅ Custom	Strong
Claude Code Plugin	✅ Custom	Strong
143 Agents	❌ Stale	Bump to 144
3-DD Methodology	✅	Keep
14 Slash Commands	❌ Stale	Bump to 15
Stars (social)	✅ Auto	Keep

Missing badges seen in comparator repos

• Awesome Claude Code listing (when accepted)
• Smithery registration (used by wshobson)
• Coverage / test count surfaced as a badge (we have 57 verify checks)

---

4. Prioritized action items (ranked by effort × hackathon-day impact)

• A1. Upload custom Open Graph image in Settings → Social preview (reuse docs/assets/v1.6-gallery-hero.png or a 1280×640 crop). Effort: 2 min. Impact: every share link looks polished. Severity: High.
• A2. Fix stale counts and the duplicate row in README:
  • 143 → 144 agents (L8, L33, L213, L231, L245 + Agents badge L25)
  • 14 → 15 slash commands (badge L20, L177, L246, L253 + add /pf:preview row)
  • "56 checks" → 57 (L295)
  • "What's inside" hooks 3 → 7, schemas 3 → 6
  • Remove duplicate Slash commands row at L253
    Effort: 10 min. Impact: removes credibility leaks. Severity: High.
• A3. Document /pf:preview + H2→preview-server auto-launch (PR feat(workflow): H2→preview server auto-launch + /pf:preview slash command (Phase 2) #104 work currently invisible in README). Add to Slash Commands table and to the Run-lifecycle narrative. Effort: 15 min. Impact: surfaces the latest demo-critical feature. Severity: High.
• A4. Add 10–15 s GIF or 30 s Loom link under the hero PNG showing /pf:new → 26 mockups → pick → freeze. Effort: 30 min capture + embed. Impact: directly serves the hackathon's 25 % "Demo" rubric. Severity: High.
• A5. Trim About description to ≤200 chars. Effort: 1 min. Severity: Medium.
• A6. Switch homepageUrl from …/blob/main/preview-forge-proposal.html to the live Pages site https://two-weeks-team.github.io/PreviewForgeForClaudeCode/. Effort: 1 min. Severity: Medium.
• A7. Add 3-line "The problem" section above About — Citadel-style pain framing before methodology jargon. Effort: 10 min. Severity: Medium.
• A8. Embed the 3-min demo video link in the Hackathon section once the Loom/YouTube URL is finalized. Effort: 1 min. Severity: High (required submission artifact).
• A9. Enable GitHub Discussions (Settings toggle). Effort: 30 sec. Severity: Low.
• A10. Add 5–7 missing topics (agent-orchestration, software-factory, subagents, claude-code-hooks, claude-code-skills, mcp, multi-agent-system). Effort: 2 min. Severity: Low–Medium.
• A11. Inline-summarize Layer-0 7 rules instead of linking. Effort: 15 min. Severity: Medium.
• A12. Add one-row "vs SuperClaude / vs wshobson" comparison strip anchored on the gallery-first differentiator. Effort: 20 min. Severity: Medium (and risky if wording is sloppy).

Minimum-viable polish (A1–A6, A8) ≈ 60 min. Full set ≈ 2 h.

---

Acceptance criteria

• All ❌ rows in §1 (start method) resolved or explicitly deferred with rationale
• §2 "Where we lose" items 1, 2, 4 closed (custom OG, demo motion, demo video link)
• §3 About-panel description, homepageUrl, usesCustomOpenGraphImage corrected
• All four stale-count callouts in §3 badge audit corrected
• Action items A1–A6 + A8 minimum complete; A7, A9–A12 either complete or moved to a follow-up issue
• No new factual drift introduced (verify by re-running bash scripts/verify-plugin.sh and confirming the README's "What's inside" table matches the script's reported counts)

---

Sources (corroborating evidence for the comparator landscape)

Comparable repos benchmarked

• wshobson/agents — 34.3k ★, "Intelligent automation and multi-agent orchestration for Claude Code"
• SuperClaude-Org/SuperClaude_Framework — 22.5k ★, "Configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies"
• SethGammon/Citadel — 523 ★, "Agent orchestration harness for Claude Code"
• anothervibecoder-s/claudecode-harness — 183 ★, "Production-grade orchestration harness for Claude Code"
• affaan-m/everything-claude-code — 167k+ ★, "Agent harness performance optimization system" (Anthropic hackathon winner)
• dralgorhythm/claude-agentic-framework — 71 ★, "More Effective Agent Harness for Claude"
• jeremylongshore/claude-code-plugins-plus-skills — 2k ★, "423 plugins, 2,849 skills, 177 agents"
• stellarlinkco/myclaude — Multi-agent orchestration workflow (Claude Code, Codex, Gemini, OpenCode)

Marketplace / discoverability references

• anthropics/claude-plugins-official — Anthropic-managed marketplace
• anthropics/claude-code — official Claude Code repo
• Build with Claude — community marketplace
• Chat2AnyLLM/awesome-claude-plugins — curated list
• ComposioHQ/awesome-claude-plugins — curated list
• quemsah/awesome-claude-plugins — adoption-metrics tracker
• rohitg00/awesome-claude-code-toolkit — 135 agents, 35 skills, 176+ plugins
• aitmpl.com — Claude Code Plugins & Marketplaces directory
• revfactory/harness — Agent Team & Skill Architect for Claude Code
• hesreallyhim/awesome-claude-code — alternatives index
• Multi-Agent Development (VS Code blog, 2026-02-05) — broader context on multi-agent IDE workflows

Internal repo evidence

• scripts/verify-plugin.sh:48 — agent_count check -eq 144
• scripts/verify-plugin.sh:80 — command count check -eq 14 (will need bump to 15 after A2)
• PR feat(workflow): H1->SpecDD auto-advance — sentinel hook + dispatch script + M3 imperatives (Phase 1) #103 — H1→SpecDD auto-advance (sentinel hook + dispatch script + M3 imperatives)
• PR feat(workflow): H2→preview server auto-launch + /pf:preview slash command (Phase 2) #104 — H2→preview server auto-launch + /pf:preview slash command (Phase 2)
• PR docs(readme): gallery-first hero shot above the fold (#67) #94 — gallery-first hero shot above the fold
• README.md — current text reviewed end-to-end at commit dcaeb8a on origin/main

Cross-references

• Master review index: 📋 v1.11.0 5×3 Review — 22-issue master index (#58~#79) #80
• Codex P2/P3 follow-ups umbrella: 📋 v1.11 review umbrella follow-ups — codex P2/P3 from PR #81~#94 #95
• Language policy: docs: enforce English-only language policy + retroactive cleanup of Korean issue bodies (#58–#80) #102
• Post-hackathon roadmap: Post-hackathon roadmap: deferred items from v1.7 audit (T-7, T-12 Windows, Q-4/Q-6/Q-7/Q-8) #57