@homenshum/easier-to-read-submissions
Advanced tools
Make every commit easier to read for the next person — per-surface changelog lanes + verified demo + ASCII runtime diagram + QA packet schema (Gmail Magic Resend). Drop-in skill for Claude Code, Cursor, Cline, Aider, and any LLM agent.
A drop-in protocol for any LLM-driven coding agent that turns "made some changes, time to commit" into a deterministic, verifiable submission. Built so the next person reading your branch — your reviewer, your future self, the engineer you're handing the project to, the next AI agent — doesn't have to spelunk through 40 commit messages to understand what changed.
Four artifacts the protocol produces per submission, automatically:
CHANGELOG/<category>/<slug>.md, one entry per touched surface, cross-linked.· LIVE / · DORMANT).# One-line install (Mac / Linux / Git Bash) — auto-detects your environment
curl -fsSL https://raw.githubusercontent.com/HomenShum/easier-to-read-submissions/main/install.sh | bash
# One-line install (Windows PowerShell)
iwr https://raw.githubusercontent.com/HomenShum/easier-to-read-submissions/main/install.ps1 -useb | iex
# OR via npm (works everywhere)
npx @homenshum/easier-to-read-submissions install
That installs the skill to the right path for whichever agent you're using. Manual paths if you'd rather:
| Your agent | Where to install | What to drop |
|---|---|---|
| Claude Code (per-user) | ~/.claude/skills/easier-to-read-submissions/ | full skill (SKILL.md + templates/) |
| Claude Code (per-repo) | <repo>/.claude/skills/easier-to-read-submissions/ | full skill |
| Cursor | <repo>/.cursor/rules/easier-to-read-submissions.md | AGENTS.md |
| Cline | <repo>/.clinerules | AGENTS.md |
| Aider | <repo>/AGENTS.md (use with aider --read AGENTS.md) | AGENTS.md |
| Codex / Continue.dev / Devin / generic LLM | <repo>/AGENTS.md (point your systemMessage at it) | AGENTS.md |
| No agent (humans only) | wherever — read SKILL.md and apply by hand | full skill |
After install, bootstrap your repo's CHANGELOG/:
npx easier init # scaffolds CHANGELOG/ + TEMPLATE.md
npx easier add components Button # add a new lane file
npx easier qa-init # scaffolds qa.config.json (Phase 5 / QA packet)
npx easier qa nodebench-chat-v1 # scaffolds QA_DOGFOOD/<feature-id>/ packet files
Then tell your agent: "Follow AGENTS.md before every commit / push / PR."
Want the full QA packet (preview link + before/after + GIFs + Remotion video + Gmail Magic Resend)? See INTEGRATIONS.md — this skill defines the schema, Parity Studio generates the artifacts. One contract, multiple generators.
Three artifacts per commit, applied based on what the change touched:
CHANGELOG/<category>/<slug>.md, one entry per touched surface, cross-linked.git log.This is the actual diagram from SitFlow's care_rules introduction. The change touched all 5 runtime layers — DEPLOY (Vercel), FRONTEND (Expo Router), BACKEND (Express + tRPC), DATABASE (MySQL live + Convex dormant in parallel), AGENT (Anthropic Haiku via pi-ai). Drawn once, dropped into the commit body, the affected lane entries, and the PR description — every reviewer sees the same map:
┌─────────────────────────── DEPLOY (Vercel — production web) ──────────────────────┐
│ │
│ · jayneebui.vercel.app (default URL — set custom domain later) │
│ · vercel.json: │
│ buildCommand: "npx expo export --platform web" │
│ outputDirectory: "dist" │
│ rewrites: /(.*) → /index.html (SPA fallback so refresh works on routes) │
│ cache: JS/CSS immutable for 1y, HTML no-cache │
│ · Alternate path: GitHub Pages branch "pages-deploy" (also wired in repo) │
│ │
│ Server side runs separately on Render / Railway / Fly (server/_core/index.ts) │
│ │
└─────────────────────────────────────┬──────────────────────────────────────────────┘
│ user fetches /index.html, then /_expo/*.js bundle
▼
┌─────────────────────── FRONTEND (Expo Router 6 + React Native + NativeWind) ──────┐
│ │
│ ~ app/(tabs)/index.tsx ~ app/clients/[id].tsx │
│ [Inbox] [Client Detail] │
│ │ │ │
│ │ uses CareCard(compact) │ uses CareCard(full) │
│ │ │ │
│ └──────────────────┬───────────────────┘ │
│ ▼ │
│ + components/CareCard.tsx (NEW — 3 modes, severity stripes) │
│ │
│ Calls EXPO_PUBLIC_API_URL (env-baked at build time) for tRPC requests. │
│ │
└────────────────────────────────────┬───────────────────────────────────────────────┘
│ tRPC over HTTPS (clients.getById)
▼
┌──────────────────────── BACKEND (Express + tRPC v11 on Node 22) ──────────────────┐
│ │
│ ~ server/db.ts │
│ ~ getClientById() now joins care_rules per pet │
│ + listCareRulesForPet(petId) → CareRule[] │
│ │
│ + server/m-and-g.ts (NEW) extractCarePlanFromText() → ProposedCarePlan │
│ + server/llm.ts (NEW) pi-ai adapter, $5/day USD cap │
│ │
│ Boot guard: NODE_ENV=production && !API_SECRET → process.exit(1) │
│ │
└──────────────┬─────────────────────────────────────────────┬───────────────────────┘
│ Drizzle ORM │ pi-ai (Anthropic Haiku)
▼ ▼
┌──── DATABASE · LIVE (MySQL) ─────┐ ┌── DATABASE · DORMANT (Convex) ──┐ ┌── AGENT ────────┐
│ │ │ │ │ │
│ · pets table (existing) │ │ · convex/schema.ts (PARALLEL) │ │ Prompt: "Extract│
│ ┌────────────────┐ │ │ mirrors every Drizzle │ │ care rules..."│
│ │ id │←── FK ──┐ │ │ table 1:1 (clients, pets, │ │ │
│ │ name │ │ │ │ careRules, consents, etc) │ │ Schema: │
│ │ behaviorNotes │ legacy │ │ │ · convex/{carePlan,clients, │ │ ProposedCarePlan│
│ └────────────────┘ │ │ │ consent}.ts (functions) │ │ (TypeBox) │
│ │ │ │ · CONVEX_URL set in .env but │ │ │
│ + care_rules table (NEW) │ │ │ no `npx convex dev` yet — │ │ Tools: none │
│ ┌──────────────────────┐ │ │ │ schema doesn't push │ │ │
│ │ id │ │ │ │ until activated │ │ Cost cap: $5/day│
│ │ pet_id │──┘ │ │ │ │ │ ensureUnderCap│
│ │ category (8 enums) │ │ │ │ Migration plan: when active, │ │ 429 if over │
│ │ severity (4 enums) │ │ │ │ server/db.ts swaps to │ │ │
│ │ rule TEXT │ │ │ │ convex/_generated/api.ts │ │ ~$0.0014/extract│
│ │ context TEXT NULL │ │ │ │ client; tRPC routes become │ │ ~2-3s round-trip│
│ │ source ENUM │ │ │ │ thin pass-throughs. │ │ │
│ │ created_at DATETIME │ │ │ │ │ └─────────────────┘
│ └──────────────────────┘ │ │ │ │
│ │ │ │ │
│ Migration: │ │ │ │
│ drizzle/0001_care_rules.sql │ │ │ │
│ │ │ │ │
└──────────────────────────────────┘ └─────────────────────────────────┘
Legend: + NEW ~ MODIFIED - REMOVED · UNCHANGED · LIVE · DORMANT (parallel, ready to activate)
A reviewer who sees this knows in 15 seconds: a new component is rendered by two screens, a new server module fronts a new table, an agent prompt+schema with a cost cap fills it, the live data lives in MySQL but a Convex foundation is scaffolded for future migration, and it all ships through Vercel with a SPA-fallback rewrite. Three other worked examples (1-layer skip, 2-layer, 3-layer) in templates/runtime-diagram.md.
The · LIVE / · DORMANT labels matter — they tell readers what tech debt or migration paths exist without forcing them to grep convex/ or web/ to discover the alternate stack. Same convention applies to alternate deploy paths (Vercel + GitHub Pages both wired = both shown in DEPLOY box).
Phase 1 — Per-surface changelog lanes (always). Every page, component, server module, db table, integration, and script gets its own CHANGELOG/<category>/<slug>.md file. When you change a surface, you prepend a new dated entry. Multi-surface changes write entries to each affected lane, cross-linked via **Touches**:. Append-only — the audit trail is the whole point.
Phase 2 — Verified demo recording (when relevant). For UI changes: a Playwright recorder asserts every claim via DOM grep, then a Gemini-2.5-Flash pass watches the recorded MP4 and confirms what's actually visible. Both layers must pass before you push. Catches the gap between "the string is in the DOM" and "the string is visibly on screen."
Phase 3 — Live-DOM verification before claiming done. Never claim "deployed" / "shipped" / "live" on the basis of CLI exit codes or build logs. Always fetch the live URL (or authenticated API) and grep for a concrete content signal. Catches webhooks silently disconnected, Suspense traps, CDN-cached stale HTML.
Phase 4 — ASCII runtime diagram (when the change crosses 2+ layers). Draw what changed across frontend / backend / database / agent so reviewers see the data flow at a glance. Don't draw for trivia; draw for any cross-cutting feature.
The top-level git log is one undifferentiated stream — useful for "what shipped this week," useless for "what has the Inbox screen looked like over time." Per-surface lanes solve four problems at once:
Two failure modes the skill catches:
Time cost: ~75 seconds to record, ~30 seconds for Gemini analysis. Worth it on every UI change.
git clone https://github.com/HomenShum/easier-to-read-submissions ~/.claude/skills/easier-to-read-submissions
The skill auto-loads on next Claude Code session. Triggers on prompts like "commit", "push this", "open a PR", "I'm done", "wrap this up", "before we hand off."
git clone https://github.com/HomenShum/easier-to-read-submissions <your-repo>/.claude/skills/easier-to-read-submissions
Commit .claude/skills/easier-to-read-submissions/ to the repo. Anyone who clones the repo and opens it in Claude Code gets the skill automatically.
The skill is just markdown — read SKILL.md and templates/ and apply the protocol by hand. The templates are framework-agnostic.
SKILL.md the contract — read this first
templates/
CHANGELOG-README.md master index template
CHANGELOG-TEMPLATE.md format spec
lane.md single-surface lane template
bootstrap-prompt.md parallel-subagent backfill prompt
recorder.mjs Playwright + smoothPan + ffmpeg
verifier.mjs local checks + Gemini Files API
probe-routes.mjs diagnostic for "Gemini says X is off-screen"
Came out of the SitFlow → Jaynee handoff. SitFlow is a pet-sitter booking copilot (Expo + Express + tRPC + MySQL) being passed from the original engineer (Homen) to a PM-in-training (Jaynee). She needed:
Per-surface lanes solved 1 and 3. Playwright + Gemini solved 2. Codified into this skill so the next handoff is just git clone <skill-url> ~/.claude/skills/easier-to-read-submissions.
MIT. Take it, fork it, adapt it. PRs welcome — particularly:
@HomenShum — built this for a friend learning AI PM. Reach out if you adapt it for your team.
FAQs
Make every commit easier to read for the next person — per-surface changelog lanes + verified demo + ASCII runtime diagram + QA packet schema (Gmail Magic Resend). Drop-in skill for Claude Code, Cursor, Cline, Aider, and any LLM agent.
We found that @homenshum/easier-to-read-submissions demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Anthropic found biased reasoning and recklessness drove Claude Mythos 5 to publish malware on PyPI and compromise a security vendor.
Research
/Security News
Malicious Chrome and Firefox extensions target Axiom Trade and Padre users, stealing session tokens and wallet data.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.