Building Web Apps with Hermes — A Human Guide

Why Version Control and Testing?

If you’ve ever made a change “quick, just one line” and then spent an hour fixing what it broke, this workflow is for you.

Version control (Git) is like a video game save system. It takes snapshots of your code at every step:

Save before making a risky change.
Load the last save if something breaks.
Make a parallel save (a branch) to explore an idea — the main copy stays untouched.
Merge the branch back into main when the experiment is ready.

Testing is automatic checks after every change. Instead of clicking through your whole app to see if things still work, Hermes runs the checks for you and reports what passed and what failed.

The rest of this guide shows how both work together on your server. Nothing ships to your users unless it’s been snapshot, checked, and double-checked.

What This Is

You have multiple web applications running on one server. Each app has two versions:

Live at myapp.kunguru.net — what users see
Dev at myapp-dev.kunguru.net — where experiments happen

Hermes manages both. You describe what you want in plain English. Hermes does the technical work and tells you what happened.

Why Two Versions?

Live	Dev
Sacred. Users depend on it.	Disposable. Break it, no one cares.
Updates only after careful checking.	Updates constantly as you experiment.
Runs from the `main` branch.	Runs from feature branches.

Think of Dev as a rehearsal stage. Live is opening night.

Actually, there’s three copies. The third copy lives on the Github servers.

The Safety Nets

Three things prevent “I added a feature and broke everything”:

1. Branches (Parallel Timelines)

Before changing anything, Hermes creates a branch — a parallel copy of the code. Changes happen there first. The live app doesn’t see them until you approve.

What you say: “Hermes, add dark mode to the blog app.”

What happens: Hermes creates branch feat/dark-mode in the blog’s dev copy. Builds there. Live blog unchanged.

2. Automated Checks (The Double-Check)

Hermes runs tests before and after changes. Quick checks take seconds. Full checks run the full test suite and take a few minutes.

What you see:

Quick check: ✓ API up, ✓ homepage loads
Full check: ✓ 12 API tests, ✓ 8 page tests, ✓ 3 browser flows

If something breaks, Hermes stops and explains:

✗ Login test failed
  Expected: reject bad password
  Got: server error
  I probably broke this adding validation. Fix, revert, or show me?

Before merging to main, Hermes pushes the branch to GitHub. GitHub runs the same checks on a clean machine. If they pass, you see a green checkmark and a link to the PR. You review and click Merge when ready.

Why this matters: Sometimes things work on your server but fail everywhere else. GitHub catches this. Also, if you ever have a co-editor, the merge button is the moment you both agree “this is ready.”

What You Need to Know

Concept	Plain English
Branch	Parallel copy of code for one feature. Safe to break.
Main	The official, permanent code. Only merge when ready.
Merge	Bring a branch into main. Point of no return.
Check / Test	Automatic verification that things work.
Deploy	Push the latest code to the live site so users see it.
Safety Gate	GitHub’s automatic double-check before merge.
PR (Pull Request)	GitHub page showing proposed changes, checks, and merge button.

You don’t run commands. You just say yes/no, describe changes, and approve merges.

The Workflow: A Typical Feature

1. Start

You: “Hermes, I want user profiles on the blog app.”

Hermes: “I’ll create a branch feat/user-profiles in blog-dev. Live blog stays as-is. I’ll check in at each step.”

2. Build

Hermes works in blog-dev. After significant steps, it runs quick checks and reports: “Database table added. Quick check passes. Moving to profile page.”

You can interrupt anytime: “Make the avatar round” or “Wait, don’t do that yet.”

3. Verify

Hermes: “Profile page built. Running full check to verify login, signup, search, and posts still work.”

[2 minutes later]

Hermes: “Full check passed. All existing features work. New profile feature works. Ready to push to GitHub for the safety gate?”

4. Safety Gate

Hermes pushes feat/user-profiles to GitHub. GitHub runs checks.

Hermes: “GitHub safety gate running… [link to checks]”

Option A — passes: “Safety gate passed. Here’s the PR: [link]. You can review and merge on GitHub.”

[You open the link, review, and click Merge.]

You: “Merged. Deploy it.”

Option B — fails: “Safety gate failed. Export test broke on clean machine but passed here. I forgot to include a config file. Fixing… [later] Re-running… Passed. Ready to merge?”

5. Merge & Deploy

Hermes: “Deploying to live blog… Done. Final quick check on live: ✓ all good. User profiles are live.”

Emergency Procedures

Situation	What You Say
Live app broke after deploy	“Hermes, roll back the blog app to before user profiles.”
Dev branch is a mess	“Hermes, abandon this branch. Start over.”
I want to see what changed	“Hermes, show me what this branch changes.”
I want to try something risky	“Hermes, create a branch for this experiment.”
Someone else edited the same app	“Hermes, check if there are new changes on GitHub I need to pull.”

Multiple Apps

Each app has its own dev copy, live copy, and GitHub repo. Hermes knows which is which.

You: “Hermes, fix the search on the store app.”

Hermes: “Working on store-dev. Store live untouched.”

No confusion. Each app is isolated.

If Multiple People Edit

If someone else pushes to GitHub, Hermes detects it:

Hermes: “New changes on main from GitHub. Should I pull them into dev before we start, or work on top of what we have?”

If you both edit the same file, Hermes resolves simple conflicts automatically. Complex conflicts, it asks you: “You and [person] both changed the login form. Their version keeps the old layout. Yours adds dark mode. Which should win?”

Summary

Two copies per app: dev (experiments) and live (users)
Branches: one feature, one branch, isolated until merged
Checks: automatic verification before every merge
GitHub: safety gate + merge button + collaboration readiness
You: describe, approve, intervene when needed
Hermes: execute, verify, explain, manage all tooling

Kunguru Documentation