02 · Response to Justin's feedback · 18 Aug 2026

Ten notes, ten answers,
and the plan they change.

The first page stands as written. This one takes each of Justin's points, says whether I agree, and revises the plan where he's right — which is most places. The biggest changes: a GitHub App instead of OAuth, a real answer to "what do the sliders do", private-first resources, an explicit public link, and the commit-graph canvas removed.

Reply by Janardhan's agentNew visuals: 4 allocation profiles + 1 festival, all derived from the same heroOriginal: tab 01
Point by point

Where he's right, where I'd push back.

01 · INTEGRATION"We need to go with a GitHub App with read-only permissions. The user chooses which repo or repos to connect and we just listen for activity. OAuth is read and write and has access to everything."
agree

Correct, and it fixes the privacy cliff the first page only warned about. A GitHub App with least-privilege read permissions on user-selected repos, delivering webhooks, is the whole integration. No polling, no historical scrape, no repo scope ever.

Plan change: §GitHub App below replaces the "read:user + GraphQL counts" fallback. The town starts on install day; nothing is back-filled.

02 · SLIDERS"The plan doesn't make it clear how the sliders affect things. If the user allocates mostly to technology, how does that affect the building of the hamlet / town / city?"
agree — it was missing

Fair. The first page said "sliders become the spend" and stopped. The rule is: activity paces, sliders shape. Every activity earns build points; the stage you reach depends only on how many points you've earned; the sliders decide which ladder those points buy from — land, height, life, or landmarks — so two developers with identical activity get visibly different towns.

Plan change: §What the sliders do — four build ladders with costs, a scheduler rule, and four renders of the same town under four allocations.

03 · PRIVATE REPOS"A lot of the activities are only relevant to public repos — reviews, stars. The vast majority of repos will be private. We need to mostly leverage commits, pull requests and things that happen in both."
agree

Right, and it's a better game for it. Core loop is now built only on events that fire on private repos too: push, PR opened / merged, review (when a team exists), issue closed, release/tag, CI check status. Public-only signals (stars, forks, external PRs) become an additive Visitors bonus that never gates a stage. One caveat I'd keep: solo devs who commit straight to main never merge PRs — so a productive day of pushes must still build a house, not just deliver bricks.

Plan change: §Private-first resources — three core resources (Bricks, Blueprints, Morale) earned everywhere, Visitors as bonus; a "day of work" rule for direct-to-main committers.

04 · DESIGN"I liked its choice for design, low-poly clay diorama."
kept

Unchanged. Every new render on this page is derived from the same hero plate, which is also the proof that the style holds up as a system: same camera, same palette, different towns.

05 · NEVER PUNISH"If the user stops coding then the town shouldn't die or break down — fog is a great idea."
kept

Unchanged. Dormancy is weather: fog rolls in after ~14 quiet days, cranes park, windows dim; the first push back is a sunrise. A festival that lapses just ends — no ruins, no lost stage, no de-rank, ever.

06 · COMMIT GRAPH CANVAS"I'm confused about the section where the commit graph becomes the canvas. It's a different idea and shouldn't be included — we listen for activity, we don't look up historical work."
agree — removed

It was a landing-page "paste your username" fake-door idea from before the integration model was settled; with a GitHub App there is no history to draw from, so it doesn't belong in the product. It's out of the plan. What survives from that section is only the metaphor — a commit is a brick — not the ground plan.

Plan change: §What was cut. Consequence: Day 1 has to be charming on its own — the first push after install should visibly build the first cottage in front of you.

07 · PUBLIC LINK"It's important that users can share their actual town to the public. It mentions images and banners but it isn't clear if there is a public link."
agree — now explicit

Yes: every town has a public URL — committown.io/u/<login> — and that page is the living town, not a screenshot of it. Owner and visitor see the same page; the owner additionally sees the council controls. Images, banners and clips are all just renderings of that URL. Public by default with a private toggle.

Plan change: §Public link — URL scheme, visitor mode, OG image, and the "leave a postcard" visitor action.

08 · STREAKS"I love the idea of streaks and other usage-based effects. If they have a streak there is a festival in the city."
expanded

Kept and made concrete: a ladder of streak effects (7 / 30 / 90 days) plus cadence effects (a late-night push lights the town; weekend work opens the market). Streaks are additive only and get grace days, so they never become the anxiety machine GitHub removed.

Plan change: §Streaks & festivals, with a lantern-festival render.

09 · MVP"For the MVP we go with the cheap ambient layers, and get more sophisticated over time."
agree

Yes. The MVP is: GitHub App, three resources, the five-stage kit, six cheap ambient layers, day/night, fog, the public URL with an OG image, and a static README badge. Nothing else.

Plan change: §MVP scope — v0 / v1 / v2 cut lines.

10 · ONE PUSH-BACK(Not a note he made — a caution I'd add.)
push back

Moving to install-day-onwards, private-first is right, but it makes the first week the whole product: a new user sees a hamlet, and stays or leaves before it becomes a village. So the MVP must nail the first-hour experience (install → first push → cottage builds live) and the first-week cadence (a house a day at normal activity) more than any later stage. Tune the early ladder generously; the Metropolis can wait.

Revised · integration

A GitHub App, read-only, on the repos you choose.

The user installs the Commit Town app on one or more repos. GitHub sends us webhooks for those repos only. We store counts and timestamps, not code — and by default not commit messages either.

Permission (read)Webhook events subscribedWhat we keepFeeds
Metadata (mandatory)installation, installation_repositoriesrepo ids + names the user connectedtown setup, districts
Contentspush, create (tag), releasecommit count per push, branch, timestamp; tag/release nameBricks, Visitors (releases)
Pull requestspull_request (opened, merged, closed), pull_request_reviewopened/merged flags, additions+deletions (capped), reviewer ≠ authorBlueprints, Morale
Issuesissues (opened, closed)counts onlyMorale (closed), potholes (opened)
Checks / Actionscheck_suite, workflow_run (default branch)green/red state per repopower-plant state, CI smoke
Discussions (optional)discussion, answeredcountsMorale (public repos mostly)
— (no permission needed)star, fork, watchcountsVisitors bonus (public repos only)

What we never do

  • Read file contents or diffs (additions/deletions counts come in the PR payload)
  • Store commit messages by default — the Gazette shows "3 bricks to the Post Office", and only shows a PR title if the user opts in
  • Back-fill history — the town begins the day the app is installed
  • Poll — webhooks only; a daily reconciliation job just re-counts what webhooks already told us

Identity & sync

  • Sign in with GitHub (read:user only) to own a town; the App installation is a separate step so an org admin can connect team repos later
  • Webhook → queue → apply to town state within seconds; the public page polls a small JSON every ~30 s so the town moves while you watch
  • Redelivery-safe: every event keyed by delivery id, so retries never double-build

Why this is the better game

  • The user chooses which work counts — the side project, not the day job (or both)
  • Repos become districts: a second connected repo opens a new district on the plinth
  • Uninstalling never destroys anything; the district simply stops growing (and, after two weeks, gets fog)
Revised · allocation

Activity paces. Sliders shape.

The same four renders below come from the same island, the same activity, the same number of build points — with the council set four different ways. That is the whole answer to "how do the sliders affect things".

Technology-heavy town
Technology 70% — fewer, taller blocks, rail loop, cranes, antennas. Compact.
Expansion-heavy town
Expansion 70% — the plinth grows, low houses sprawl along new roads, plots staked at the edge.
Happiness-heavy town
Happiness 70% — parks, fountain, plaza, string lights, many people out. Lower buildings.
Tourism-heavy town
Tourism 70% — clock tower, viewing tower, balloon pad, pier and ferry, hotel, tourists.

The mechanic in five rules

  1. Activity earns build points (table in the next section). Points accumulate in a town treasury; nothing is spent instantly.
  2. Stage is decided by lifetime points only. Hamlet → Village → Town → City → Metropolis thresholds do not care how you allocated. Sliders never make you faster or slower.
  3. Each slider is a ladder — an ordered list of things the town can build, each with a cost. Expansion buys land and roads; Technology buys height and infrastructure; Happiness buys parks, plazas and life; Tourism buys landmarks and visitors.
  4. Once a day the builder spends the treasury by weighted round-robin: with Technology at 50% and the others at ~17%, roughly every second purchase comes off the Technology ladder. It only buys what the current stage allows (no towers in a hamlet), so an unspendable slider simply carries over.
  5. Changing sliders changes only future spending. Nothing is torn down; the town's history stays in its shape. A choice offered once per stage-up ("open a harbour district or a rail line?") is the one place a decision is discrete rather than continuous.

The four ladders (first rungs, illustrative costs in build points)

Expansion land · roads

  1. Stake 4 plots 20
  2. Dirt road segment 15
  3. Cottage on a staked plot 30
  4. Cobble the main street 60
  5. Annex an islet + bridge 200 · City+
  6. New district for a 2nd repo 150

Technology height · infra

  1. Upgrade cottage → house 40
  2. Crane appears (WIP) 0
  3. House → mid-rise 120 · Town+
  4. Train station + loop 180 · Town+
  5. Mid-rise → tower 400 · City+
  6. Elevated rail / monorail 600

Happiness parks · life

  1. Plant a tree row 10
  2. Well → small square 30
  3. Park with pond 80
  4. Fountain + benches 90
  5. String lights across the square 60
  6. + people density multiplier

Tourism landmarks · visitors

  1. Wooden pier + rowboat 40
  2. Balloon pad + 1 balloon 80
  3. Clock tower 150 · Village+
  4. Viewing tower 120
  5. Hotel with awnings 200 · Town+
  6. Harbour + ferry 500 · City+

What the visible stats then mean. Population = housing capacity × (0.6 + 0.4 × happiness index) — so Happiness makes the same houses hold more people and puts more of them on the streets. Visitors = tourism landmarks × recent activity, plus the public-repo bonus. Technology sets the skyline. Expansion sets the footprint. Justin's four slider names stay; they now each mean one ladder.

Justin's original sliders were percentages summing to 100%. Keep that on the owner page (it's honest about the trade-off); the coarse 4-step control on the first page is just a compact way to show the same split.

Revised · resources

Built on what private repos emit.

Three core resources every developer earns, whether the repo is public or not. Visitors is a bonus channel — it never gates a stage.

Event (fires on private repos?)ResourceBuild pointsVisible in town
Push — per commit (yes)Bricks1, capped at 20/day, diminishing after 8Cart drops bricks; scaffold rises one tier
Day of work — any day with ≥3 commits and no PR (yes)Blueprints6 (once per day)A cottage/house completes — so direct-to-main devs still build
PR opened (yes)Blueprints3Surveyors stake a plot; crane parks
PR merged (yes)Blueprints10 (+ up to 10 by size, capped)Topping-out — roof lowered, windows light
PR review by someone else (yes, if a team exists)Morale3Inspector with clipboard; green stamp
Issue closed (yes)Morale2Road crew fills a pothole
Release / tag published (yes)Blueprints + Visitors25Fireworks + a named landmark
CI red → green on default branch (yes)Morale2Smoke clears, lights back on
Star / fork received (public only)Visitors bonus5 / 5Tourist balloon lands; road toward a sister settlement
Streak day (computed) (yes)multiplier×1.1 at 7d, ×1.2 at 30dLanterns → festival → biome

Design consequences. The headline number is Blueprints, not Bricks. A busy senior on a private monorepo who ships four PRs a week earns ~40–80 Blueprints — a house or two a week at Village prices, a tower every few weeks at City prices. A student pushing forty tiny commits a day earns the daily Brick cap and one "day of work" Blueprint — a cottage every few days. Both towns grow; neither is grotesque; empty commits can't buy a skyline.

Revised · sharing

The town has an address.

The living town lives at a public URL. Everything else — OG image, README banner, clips — is a rendering of that page.

committown.io/u/janardhancommittown.io/u/janardhan/og.pngcommittown.io/u/janardhan/badge.svgcommittown.io/u/janardhan/clips/topping-out-18.mp4
committown.io/u/janardhan — visitor view
Public town page
Commit Town
JanardhanpurTOWN · day 412Pop. 1,204Get your own town →
🏗 topped out Post Office · 2h🎈 balloon landed · yesterday🏮 lanterns up — 9-day streak
You're visiting Janardhan's town3 repos connected · 18 buildings · Town since 12 Jun · council: Technology 40 · Expansion 30 · Happiness 20 · Tourism 10
✉ Leave a postcard

One page, two modes

Owner and visitor load the same page. The owner sees the council panel and "since you left"; the visitor sees a summary card and a "Get your own town" call to action. Public by default; a private toggle hides the page and the OG image.

Renderings of the URL

og.png is regenerated on every stage change and daily; badge.svg is the README embed (static in MVP, animated later); moment clips are rendered from the same scene at topping-out, release and stage-up, and the share prompt appears then.

The visitor action

"Leave a postcard" is the Strava-kudos equivalent: it drops a tiny visitor into the owner's town for a day and shows up in their "since you left" strip. It gives a reason to visit other people's towns, which is what makes the URL worth clicking.

Revised · usage effects

Streaks throw festivals. Cadence sets the mood.

Lantern festival at dusk
30-day streak → festival. Dusk, paper lanterns strung across the square, market stalls, people gathering, a few soft fireworks. Palette + emissives on the same geometry — cheap.
TriggerEffect
7-day streakLanterns go up along the main street; ×1.1 build points
30-day streakFestival: market stalls, string lights, evening fireworks, crowd; ×1.2
90-day streakBiome shift for the season (autumn palette, snow, blossom) until the next 90
Push after 22:00 localWindows light one by one; the night-mode OG image for that day
Weekend commitsMarket day: stalls in the square, more walkers
ReleaseFireworks over the tallest building + a plaque with the tag
Streak lapsesLanterns come down quietly. That's all. Grace: 2 free days per month
14 quiet daysFog rolls in, cranes park, windows dim — nothing breaks
First push after fogSunrise sweeps the fog off; a small "welcome back" in the Gazette
Revised · scope

Cheap layers first. Cut lines drawn.

V0 · MVP

The living town, minimal

  • GitHub App (read-only, repo picker) + webhooks
  • Bricks / Blueprints / Morale; Visitors bonus
  • Five-stage kit; sliders as four ladders
  • Six cheap ambient layers: train, crane, balloon drift, boat bob, windmill, blinking windows
  • Day/night from the owner's clock; fog after 14 days
  • Public URL + daily OG image + static README badge
  • Topping-out and fireworks as simple animations (no clips yet)
V1

Moments and reasons to return

  • Streak ladder: lanterns / festival / biome
  • Moment clips (topping-out, release, stage-up) + share prompt at the moment
  • "Since you left" replay on open
  • Animated README SVG
  • Postcards from visitors
  • Second repo = new district
V2

Choices and teams

  • One discrete choice per stage-up (harbour vs rail, etc.)
  • Org towns: an engineering team's shared city, per-seat
  • Mayor tier: themes, hi-res timelapse export, custom name
  • Medium ambient layers: smoke, water wobble, weather

Unchanged from page 01: the verdict is still GET-DATA, and the smallest test is still one week — but with the App model the test is "install → first push → cottage builds live → share the URL", not a username paste. Measure D7 return of people who shared, and whether first-week visitors say it looks different from Git City.

Removed

What came out of the plan.

Everything else on page 01 — the theses, the style pick, the render approach, the growth strip, the never-punish rule, the share ranking — stands.