Github Project Research

GitHub Project Research

Overview

Search before building when external references can reduce product or engineering risk. Treat popularity as evidence, not proof: product fit and license compatibility outrank stars.

Workflow

1. Restate the product goal, users, success criteria, required stack, deployment model, and license constraints. Ask one focused question if a missing answer would change the shortlist.
2. Create 2–3 repository queries covering product terms, domain synonyms, and stack terms. Add useful qualifiers such as in:name,description,readme, stars:>50, pushed:>=YYYY-MM-DD, language:TypeScript, and archived:false.
3. Prefer the GitHub repository-search connector. When gh is authenticated, use the bundled script for a compact shortlist:

python3 ~/.codex/skills/github-project-research/scripts/search_repositories.py \
  'project management issue tracker nextjs postgres in:name,description,readme stars:>50' \
  --limit 10 --format json

4. Merge and deduplicate query results. The script score is only an initial signal based on search relevance, stars, forks, recent pushes, archive state, and license metadata.
5. Inspect the strongest 3–5 repositories with GitHub metadata and targeted README, code, Issue, and PR searches. Verify product fit, architecture, last meaningful activity, release cadence, maintainer responsiveness, documentation, tests, security posture, and the actual LICENSE/NOTICE files.
6. Rank final candidates using this priority: product fit, maintainability, technical fit, license compatibility, documentation/tests, then community signals.
7. Recommend patterns to reuse, risks to avoid, and whether to adopt, fork, study, or build independently. Do not copy code until license compatibility is verified.

Output Contract

Return:

• the search scope and assumptions;
• a 3–5 row comparison with repository, fit, stars, recent activity, license, maintenance evidence, strengths, and risks;
• one recommended candidate or “build independently” conclusion;
• reusable product, architecture, UI, data-model, or testing ideas;
• rejected candidates and concise rejection reasons.

Skip Conditions

Skip mandatory GitHub research for small fixes, fully specified implementation work, confidential concepts that cannot be searched safely, or when the user explicitly opts out. State the skip reason briefly.

Common Mistakes

• Ranking by stars alone.
• Treating pushed_at as proof of active maintenance without checking releases or Issues.
• Assuming API license metadata is legally sufficient.
• Copying a repository architecture before comparing its scale and product constraints.
• Returning a long link dump instead of a decision-ready shortlist.