make-it-shine

A project's public surface (GitHub page, marketing copy, social post) is its storefront. This skill makes it shine. but only after actually reading the code: No hallucinated features. No "Welcome to my project!" intros. No AI slop.

Hard rules

1. Read before write. Spawn parallel Explore subagents to map the repo. Never write a line that isn't grounded in actual code.
2. Length follows content, not vanity. If 4 lines explain it, write 4. Most repos need ~150-400 README lines, not 1500.
3. No AI slop. No badge salad, no "Welcome to <project>!", no emoji confetti, no "comprehensive solution leverages cutting-edge..." Drop em dashes. Drop AI vocab (delve, crucial, robust, leverage, foster, landscape, tapestry). Voice rules: references/voice-crisp.md + references/voice-warm.md.
4. Direct commit to default branch. Each meaningful change = its own commit so individual pieces are revertable.
5. Never co-author commits. Standard.
6. Confirm destructive actions. Overwriting existing CONTRIBUTING.md, LICENSE, or force-setting topics. ask first.
7. Never auto-post. Social mode enqueues. The user pulls the trigger via the drain command.

Phase 0. Mode select (ALWAYS first)

Before anything else, ask the user which mode(s) to run via AskUserQuestion (multi-select):

Defaults / common combos:

• Bare "polish this repo" → polish
• "Ship this + announce" → polish + social
• "Post about my paper" → research + social
• "Write copy for this" → marketing only
• "Make this shine" → ASK (could mean polish, polish+social, all-four)

If scripts/detect_research.sh returns yes, recommend research mode in the question. If ambiguous, ask explicitly.

Modes can stack. Phase order below shows which phases run for each mode.

Phase map (which phases run per mode)

Always track all running phases with TaskCreate.

Phase 1. Detect + audit (2 min)

1. scripts/detect_repo.sh → resolve owner/repo from git remote get-url origin. If user passed explicit owner/repo, use that.
2. scripts/audit_repo.sh → key=value report: description, topics, homepage, LICENSE, .gitignore, CONTRIBUTING, issue templates, README size, default branch, primary language, has-tests, has-CI, visibility, stars.
3. scripts/detect_research.sh → research=yes|ambiguous|no + signal list. If yes and research mode NOT in selection, surface as suggestion. If ambiguous, ask once.
4. Print audit summary. Don't write yet.

Phase 2. Deep exploration (5-10 min, parallel)

Spawn 5 parallel Explore subagents in a single message. Sharp, non-overlapping questions. Read references/exploration-plan.md for exact prompts.

Synthesize. Cross-check claims against actual files. No subagent claim through without a source-file reference.

Research mode swaps Agents 1 and 2 for paper-claim extraction + code-to-paper mapping. See references/research-mode.md#mode-specific-phase-2-subagents.

Phase 2.5. Fresh language calibration (30 sec, skip in research mode)

Pull a small sample of how devs are talking about this topic right now: Combats stale training-data slop.

1. Pick 2-4 keywords (project name + stack + domain). Avoid one-word generics ("AI", "agent"). pair them.
2. Run scripts/fetch_lang_samples.sh "<kw1>". Returns recent HN titles, Reddit posts, dev.to articles.
3. Read references/fresh-language-context.md for what signals to extract (overused phrases to AVOID, live terminology, cadence, pain points). DO NOT copy phrases verbatim. samples are a tuning fork.
4. Write one synthesis line: Fresh-lang scan: "agent harness" is the live term, "RAG" framing saturated, short fragments dominate.

If script errors or returns empty, skip silently.

Phase 3. Pick voice + length (1 min)

Read references/voice-crisp.md + references/voice-warm.md. Pick one:

• Crisp: libraries, SDKs, CLIs, devtools. Audience = engineers. Repo name is a noun.
• Warm: side projects, hackathons, anything with a story. Author talks in first person elsewhere.

Default crisp when unsure. Warm done badly is cringe.

Length tier from references/readme-skeletons.md:

• 4-line: joke repos / single-script tools.
• 1-page (~80-200 lines). most repos. Default.
• Multi-section (~200-500 lines). frameworks, multi-persona projects.
• Full guide (500+ lines). only if genuinely a platform.

State the choice in one line: Voice: crisp. Length: 1-page. README ~180 lines.

Research mode uses the research README skeleton + academic-crisp voice (numbers-over-adjectives, name baselines, declare limitations). See references/research-mode.md.

Phase 4. Write the README (polish + research only)

Use matching skeleton from references/readme-skeletons.md (or research skeleton from references/research-mode.md). Fill in only what's grounded by Phase 2.

Mandatory checks before save:

• First 3 lines hook the problem + outcome. Not "X is a Y for Z".
• All install/build/run commands match what audit + exploration found.
• Badges only if they carry information.
• Demo asset: if visual, check for existing screenshot/GIF; if none, add <!-- TODO: add demo.gif -->.
• Compare-table only if there are genuine, named alternatives. Be honest about what they do better.
• Last section: LICENSE link + one-line credit. No begging.

Phase 4M. Marketing copy (marketing mode only)

Read references/marketing-copy.md. Produce a single MARKETING.md (or output inline if user prefers) with:

• Hook line (≤15 words). what hurts without it, what it gets you. Not "X is a Y for Z".
• One-liner / repo description (≤100 chars). lead with the verb, name the outcome.
• Tagline / sub-hook (≤80 chars). punchier riff on the hook.
• 3 value props (1-line each). concrete outcomes, not adjectives.
• Vs-alternatives framing (only if named alternatives exist). what you do differently + what they do better.
• Social blurbs: one for X (≤280), one for Show HN title (≤80). These feed Phase 7 if social mode also picked.

Voice follows the Phase 3 pick. Fresh-language scan informs which phrases to avoi