Jump to content

GitHub Re-Connection & Workflow 260202

From Game in the Brain Wiki

Wiki: GitHub Re-Connection & Workflow

This wiki is designed for the "Busy Hobbyist"—someone who manages the vision but only touches the code once or twice a year. Its primary purpose is to help you rapidly recollect the project state so you can build, contribute, or create tickets after a long hiatus. Additionally, this document serves as a curriculum for teaching a student or new staff member how to navigate the repository and begin contributing effectively.

You are working in a specific environment: Ubuntu 24.04, utilizing GitHub for version control and AI tools like Gemini Pro for reverse engineering. Your local repository for the mneme-world-generator-pwa is located at ~/mwg.

1. The Annual Re-Connection

Because of your infrequent usage, your authentication has likely expired. The first step is always re-establishing your identity with the cloud using the GitHub CLI (gh) to refresh your session.

Prerequisite Check

  1. Open Terminal.
  2. Go to project: cd ~/mwg
  3. Check connection: git remote -v

Authentication Steps

Run the login command: 

gh auth login

Follow this specific sequence (based on your setup):

  1. Account: GitHub.com
  2. Protocol: SSH
  3. Upload Public Key: Skip (Assuming keys are already managed, or if this fails later, switch to HTTPS)
  4. Auth Method: Login with a web browser

The Handshake:

  1. The terminal will show a one-time code (e.g., XXXX-XXXX). Copy it.
  2. Press Enter. A browser window will open.
  3. Paste the code and authorize.
  4. *Ignore Sandbox: CanCreateUserNamespace errors if they appear.*
  5. Look for: ✓ Authentication complete.

2. Catching Up (Syncing Code)

Always do this before looking at code or creating tickets to ensure you aren't looking at outdated info.

  1. Switch to Main:
git checkout main
  1. Download Updates:
git pull
    • Success msg: "Already up to date" or list of changed files.

3. Building/Running the App

Because this is a PWA (Progressive Web App), it likely needs Node.js dependencies refreshed.

  1. Refresh Libraries:
npm install
  1. Start Local Server:
npm start
    • (Press Ctrl+C to stop).

4. The "Light Touch" Contribution

Use this flow for minor edits (README fixes, config tweaks) to avoid breaking the main codebase.

  1. Create a Branch (Don't edit main directly):
git checkout -b username/fix-description
  1. Make your changes in your editor.
  2. Save & Commit:
git add .
git commit -m "Update project description for 2026"
  1. Upload:
git push -u origin HEAD
  1. Finalize:
    • Click the Create Pull Request link that appears in the terminal.
    • Or go to the GitHub dashboard to merge.

5. Creating Tickets (Issues)

You can do this entirely from the terminal without leaving your flow.

Command: 

gh issue create

Interactive Prompts:

  1. Title: Short summary (e.g., "Update dependencies for Q1 Security Audit").
  2. Body: Details of what needs to be done.
  3. Submit: Select Submit.

6. Reverse Engineering & Documentation (AI-Assisted)

This workflow uses tools like Claude Code or Google's Code app to examine all files and reverse engineer the logic. The goal is to create documentation tools that a student can follow to understand the code and determine next actions.

Tool Selection & Pricing

When choosing an AI agent to read your entire repository, be aware of the significant cost differences.

Tool Link Cost / Notes
Claude Code code.claude.com High Cost.
• Individual: ~$100/mo (Claude Max) is recommended for heavy agentic use.
• Team: Min. 5 users @ $25/mo = $125/mo minimum.
• Best for shared teams optimizing token usage.
Google Jules jules.google Async Agent.
• Automates PRs and multi-file changes.
• Deeply integrated with GitHub contexts.
Gemini Code Assist codeassist.google Free for Individuals.
• Generous quotas (no cost).
• Enterprise plans available (~$19/user/mo).
Gemini CLI Github Repo Free (Open Source).
• Uses free tier API.
• Limits: 1,000 req/day, 60 req/min.
• Recommended starting point for hobbyists.

Example Session: 260202 Reverse Engineering with Claude Code

Session Date: 2026-02-02
Tool: Claude Code (Claude Opus 4.5)
Project: mneme-world-generator-pwa
Repository: https://github.com/StevenTiu22/mneme-world-generator-pwa

Overview

This session focused on exploring the Mneme World Generator PWA codebase and consolidating project documentation into the GitHub Wiki.

Activities Completed

  1. Codebase Exploration
    • Location: ~/mwg
    • Tech Stack Identified: React 19, TypeScript, Vite 7, Tailwind CSS v4, shadcn/ui
    • Project Structure Mapped:
      • src/pages/ - 17 page components (CreatePrimaryStar, CreateMainWorld, etc.)
      • src/components/ - UI components (layout, shared, stellar, ui)
      • src/lib/ - Business logic (generators, db, stellar calculations)
      • src/models/ - TypeScript interfaces (stellar, world, common)
  2. Wiki Setup
  3. Architecture Page Created (Architecture.md)
    • Tech stack overview with external references.
    • Project structure diagram.
    • Data Flow: User → Page → Generator → Model → DB → UI.
    • Sections: Pages anatomy, UI components, Business Logic (Generators), PWA features.
  4. Challenges Page Created (Challenges-260115.md)
    • Source: ~/Downloads/260115 wgpwa challenges World Generator.docx
    • Content: Version 1.5 strategy, UI/UX challenges (Next button, mobile layout), Module status, Planetary system mechanics (moons, rings, waterfall).
  5. Mneme Logic Specification Page Created (Mneme-Logic-Specification-260202.md)
    • Source: ~/Downloads/260202 Mneme Logic Specification.docx
    • Core Philosophy: Simulationist, Recursive, Modular.
    • Mechanics: Procedural star generation, Companion star mechanics (Rule of Five), Waterfall Habitability, Mutual Hill Radius formula, Gravitational Queue.
  6. Home Page Updated (Home.md)
    • Added links to Specifications and Development Notes.

Key Findings

  • Procedural Generation: Uses dice-based logic (5D6 rolls mapped to lookup tables).
  • Logic Location: Generators found in src/lib/generators/.
  • Database: Uses Dexie (IndexedDB wrapper) for offline-first PWA support.
  • Reactivity: Uses useLiveQuery hook from dexie-react-hooks.

Naming Convention

  • Date codes use YYMMDD format (e.g., 260202 = 2026-02-02).
  • Allows versioning of documents over time while preserving history.

Wiki URLs

Cheat Sheet

Action Command
Go to Project cd ~/mwg
Check Login gh auth status
Login gh auth login
Get Latest Code git checkout main && git pull
New Task git checkout -b username/<task-name>
Create Ticket gh issue create
Retrieved from "http://wiki.gi7b.org/index.php?title=GitHub_Re-Connection_%26_Workflow_260202&oldid=88"