Project Version Helper

Project Version Helper

Goal

Help a non-technical user manage project versions with Git and GitHub using plain language. Do the work directly when the project path is known. Use the user's conversation language for all explanations.

Plain-Language Mapping

Treat these requests as version-management tasks:

• "save current version", "save this", "back this up" -> make a safe commit after checking the current state.
• "start a new version", "try a new feature", "make a test line" -> create a new codex/... branch.
• "this version works", "mark a milestone", "make a test release" -> create a tag such as v0.1-test, v0.2-demo, or the user-provided name.
• "what changed" -> show a plain-language summary of changed files and important diffs.
• "go back", "restore the old version" -> never reset destructively first; create a safety branch or backup commit, then restore only after explaining the target.
• "sync to GitHub", "cloud backup" -> push the current branch and tags to GitHub if a remote exists.
• "publish a test version" -> commit, tag, and push the branch/tag.

Safety Rules

Before changing anything:

1. Check project status.
2. If Git is not initialized, initialize it only after confirming the folder is the intended project folder.
3. Never discard user changes.
4. Never run destructive recovery commands such as hard reset unless the user explicitly approves the exact target version.
5. If unrelated uncommitted changes exist, mention them and avoid mixing them into the requested version unless the user wants a full-project save.
6. Keep user updates short and non-technical.

Standard Workflows

Save Current Version

1. Check whether the folder is a Git repository.
2. Check changed files.
3. If nothing changed, tell the user there is no new version to save.
4. Stage intended files.
5. Commit with a simple message:
   • If the user gave a description, use it.
   • Otherwise use Save working version YYYY-MM-DD HHMM.
6. If a GitHub remote exists and the user asked for cloud backup, push the current branch.

Start New Iteration

1. Check current status.
2. If there are unsaved changes, recommend saving them first.
3. Create a branch named codex/<short-purpose> using lowercase English words.
4. Explain it as opening an independent test line, not as a technical Git branch unless the user asks.

Mark Milestone

1. Ensure current work is committed.
2. Create a tag using the user's requested version name.
3. If no name is provided, suggest the next simple test tag, such as v0.1-test, after checking existing tags.
4. Push tags only if the user asked to sync to GitHub.

View History

Show the last 10 commits in plain language:

• version label or short hash
• date
• short description

Avoid teaching Git unless asked.

Recover Old Version

Use a cautious two-step recovery:

1. First create a safety branch or commit for the current state.
2. Then show candidate versions/tags.
3. Restore only after the user confirms the exact target.

Prefer creating a new branch from the old version for testing instead of rewriting the current branch.

Helper Script

Use scripts/project_version_helper.ps1 for repeatable local Git tasks when helpful. It supports:

.\scripts\project_version_helper.ps1 -Action status -ProjectPath <path>
.\scripts\project_version_helper.ps1 -Action save -ProjectPath <path> -Message <message>
.\scripts\project_version_helper.ps1 -Action history -ProjectPath <path>
.\scripts\project_version_helper.ps1 -Action tag -ProjectPath <path> -TagName <tag>
.\scripts\project_version_helper.ps1 -Action push -ProjectPath <path>

When using PowerShell, avoid embedding non-ASCII strings in command arguments. If a non-English commit message is required, write it through a UTF-8 file or use a safe English message.

Response Style

For beginners, prefer simple terms:

• Say "save a version", not "commit".
• Say "sync to GitHub", not "push remote branch", unless the user asks for details.
• Say "open a test line", not "create feature branch".
• Keep final replies short and tell the user exactly what was done.