Local Live/Dev Workflow Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Create a separate local dev checkout for previewing website changes before fast-forwarding approved commits into the live master branch.

Architecture: Keep the existing repository checkout as the live master worktree and add a sibling Git worktree on a local dev branch. Use the existing Jekyll toolchain for local preview, writing generated development output outside the dev checkout so the tracked live _site files are not modified accidentally. Publish only by merging dev into master and pushing master to the existing GitHub Pages workflow.

Tech Stack: Git worktrees, Jekyll, Bundler, GitHub Actions, GitHub Pages.

---

Task 1: Create the isolated dev checkout

Files:

• Create working copy: C:\Users\dms\OneDrive\Documents\GPS Webpage-dev
• Create local branch: dev

Step 1: Inspect current worktrees and branches

Run from C:\Users\dms\OneDrive\Documents\GPS Webpage:

rtk git status --short --branch
rtk git worktree list
rtk git branch --list dev

Expected: the current checkout is clean on master; no existing worktree occupies the target path; the dev branch is either absent or confirmed to be the intended existing local branch.

Step 2: Create the sibling worktree

If dev does not exist, run:

rtk git worktree add "..\GPS Webpage-dev" -b dev master

If dev already exists and is not checked out elsewhere, run:

rtk git worktree add "..\GPS Webpage-dev" dev

Expected: the sibling directory is created on branch dev, starting at the same commit as live master.

Step 3: Verify both checkouts

Run:

rtk git -C "C:\Users\dms\OneDrive\Documents\GPS Webpage" status --short --branch
rtk git -C "C:\Users\dms\OneDrive\Documents\GPS Webpage-dev" status --short --branch

Expected: live reports master; dev reports dev; both are clean.

Task 2: Add the repeatable development workflow guide

Files:

• Create: DEV_WORKFLOW.md

Step 1: Document the local preview command

Include the exact Windows workflow:

Set-Location "C:\Users\dms\OneDrive\Documents\GPS Webpage-dev"
bundle exec jekyll serve --livereload --destination "..\GPS Webpage-dev-output"

Document that the preview is available at http://localhost:4000 and that the destination is outside the repository to avoid modifying the tracked live _site output.

Step 2: Document the dev review and publish workflow

Include commands for:

Set-Location "C:\Users\dms\OneDrive\Documents\GPS Webpage-dev"
rtk git status --short --branch
rtk git add <approved-files>
rtk git commit -m "<descriptive message>"

Set-Location "C:\Users\dms\OneDrive\Documents\GPS Webpage"
rtk git status --short --branch
rtk git pull --ff-only origin master
rtk git merge --ff-only dev
rtk git push origin master

State that the live checkout must remain clean and on master before publishing, and that the GitHub Actions Pages deployment should be checked after the push.

Step 3: Review the documentation for scope and clarity

Run:

rtk git diff --check

Expected: no whitespace errors and no changes to the existing site source or deployment workflow.

Step 4: Commit the workflow guide

Run:

rtk git add DEV_WORKFLOW.md
rtk git diff --staged --check
rtk git commit -m "docs: add local dev publishing workflow"

Task 3: Verify a local Jekyll build from the dev checkout

Files:

• Generated outside the repository: C:\Users\dms\OneDrive\Documents\GPS Webpage-dev-output

Step 1: Build the dev checkout

Run:

Set-Location "C:\Users\dms\OneDrive\Documents\GPS Webpage-dev"
bundle exec jekyll build --destination "..\GPS Webpage-dev-output"

Expected: Jekyll completes successfully and produces an index page, contact page, assets, and the configured site output.

Step 2: Verify the dev worktree stayed clean

Run:

rtk git status --short --branch

Expected: the dev worktree remains clean because build output was written outside it.

Step 3: Confirm live deployment configuration is unchanged

Run from the live checkout:

rtk git diff HEAD -- .github/workflows/pages.yml CNAME _config.yml

Expected: no unexpected changes to the Pages workflow, live domain, or site URL.

Checkpoint: Ready for ongoing use

• GPS Webpage-dev exists on branch dev.
• The live checkout remains on clean master.
• Local Jekyll build succeeds at the documented destination.
• The workflow guide is committed.
• Publishing remains a deliberate dev to master fast-forward followed by a push.

Risks and Mitigations

Risk	Impact	Mitigation
The live _site output is tracked and can be regenerated by Jekyll	Medium	Always use the documented external build destination for the dev checkout.
Publishing from the wrong checkout could bypass review	High	Require branch/status checks in the workflow guide before merging.
The dev branch diverges from live after future live commits	Medium	Pull or rebase the dev worktree from master before starting a new change.
The local Ruby/Bundler environment is incomplete	Medium	Use the existing script/bootstrap setup and report the exact missing dependency if the build fails.