gh-repo-father

gh-repo-father 🧑‍👶

From raw idea → methodology-informed plan → GitHub repo ready for Claude Code.

This is a thin orchestrator. At each phase, read the relevant reference file before acting — do not rely on memory.

Quick-start Checklist

Phase 0 — Check prereqs (gh, git)
Phase 1 — Brainstorm & plan (read references/brainstorm.md)
Phase 2 — Pick methodology (read references/methodology-guide.md)
Phase 3 — Scaffold (read references/project-templates.md)
Phase 4 — Populate files (read references/file-guide.md)
Phase 5 — Git + GitHub push
Phase 6 — Handoff to Claude Code

Phase 0 — Prereqs

which gh && gh auth status 2>&1 | head -2
which git && git --version

If gh is missing or unauthenticated, warn the user but continue with planning.

Phase 1 — Brainstorm

→ Read references/brainstorm.md now before asking a single question.

Flow inside brainstorm.md:

Clarifying questions (one at a time)
Web search the idea
Novelty evaluation — present prior art + verdict before any approach proposals
Propose 2–3 approaches
Write comprehensive plan → wait for approval

Do NOT scaffold until plan is explicitly approved by user.

Phase 2 — Methodology

→ Read references/methodology-guide.md now.

After understanding what the project is, pick the right design methodology:

Signal in the idea	Suggested methodology
"users", "customers", UX focus	JTBD + User Stories
"service", "API", "integration"	SDD (Service Design Doc)
"domain", "entities", complex logic	DDD (Domain-Driven Design)
"tests first", reliability focus	TDD
General / unclear	SDD lite

Present the methodology choice to the user and confirm before writing plan docs.

Phase 3 — Scaffold

→ Read references/project-templates.md now.

Steps:

REPO_NAME="<slugified-name>"   # lowercase, hyphens, no special chars
mkdir -p "$(pwd)/../$REPO_NAME"
cd "$(pwd)/../$REPO_NAME"
git init

Pick the template closest to the project type. Blend if hybrid.

Phase 4 — Populate Files

→ Read references/file-guide.md now.

Always create: README.md, README-zh-tw.md, CLAUDE.md, plan/, .gitignore, LICENSE. The CLAUDE.md is the most important file — Claude Code reads it first.

Phase 5 — Commit & Push

git add -A
git commit -m "feat: initial scaffold — $(date +%Y-%m-%d)

Auto-generated by gh-repo-father.
Methodology: <chosen methodology>
Plan: plan/00-overview.md"

gh repo create "$REPO_NAME" \
  --private \
  --source=. \
  --remote=origin \
  --push \
  --description "<one-liner>"

If gh unavailable: commit locally, print manual push command.

Phase 6 — Handoff

✅ Done!

📁 Local:   ../<repo-name>/
🐙 GitHub:  https://github.com/<username>/<repo-name>

🚀 To start in Claude Code:
   1. claude.ai/code → "Open GitHub repo"
   2. Select: <username>/<repo-name>
   3. CLAUDE.md tells Claude Code exactly what to do next.

📋 Plan: plan/00-overview.md
✅ Todo:  plan/01-todo.md

Reference Index

File	Read when
`references/brainstorm.md`	Phase 1 — asking questions, proposing approaches
`references/methodology-guide.md`	Phase 2 — picking TDD / SDD / DDD / JTBD
`references/project-templates.md`	Phase 3 — choosing file tree template
`references/file-guide.md`	Phase 4 — writing CLAUDE.md, READMEs, plan/ docs