Vibe Framework — landing page

A single-file landing page describing the Vibe Framework: a way of building software solo with AI coding agents, where a folder of markdown notes acts as the agent's long-term memory and every sprint improves the setup itself.

Live: https://djominov.github.io/vibe-framework/

What's here

index.html              the whole site: markup, styles, both prompts, one small script
prompts/
  setup.md              one-time onboarding walkthrough  <- source of truth
  working.md            the standing way of working      <- source of truth
scripts/
  sync-prompts.py       copies prompts/*.md into index.html, HTML-escaped
CHANGELOG.md            what shipped, per sprint
RETROSPECTIVES.md       what we learned, per sprint
TASKS.md                read-only mirror of the Notion board

No build step and no dependencies. The page opens directly in a browser and deploys as-is.

Editing the prompts

prompts/*.md are the source of truth. After editing either one:

python3 scripts/sync-prompts.py

That writes the escaped copy into index.html. To check without writing, useful before a commit:

python3 scripts/sync-prompts.py --check    # exits 1 if the page is stale

Do not paste prompt text into index.html by hand. Both prompts contain placeholders such as <type>, <scope> and <notes>, and a browser parses those as tags. Left unescaped they disappear from whatever the copy button puts on the clipboard, so the reader gets `(): [TASK-]` instead of `<type>(<scope>): <description> [TASK-<id>]`. The sync script escapes them; hand-editing does not. This shipped as a real bug and went unnoticed for a week, because the copied text was the right length and only the placeholders were missing.

Editing everything else

All in index.html. Design tokens sit at the top of the <style> block; sections follow in document order and are marked with comments.

Fonts load from Google Fonts with a system fallback, so the page still renders offline.

Deploying

Commit and push to main. GitHub Pages serves from main at root.

A build occasionally sticks in building while the site keeps serving the previous version. Confirm the push itself is fine before blaming the code, then force a rebuild:

# is the change actually on GitHub?
gh api repos/djominov/vibe-framework/contents/index.html --jq '.content' | base64 -d | grep -c "a new string"

# force a fresh build
gh api -X POST repos/djominov/vibe-framework/pages/builds

Verify against what the server returns, not the local file:

curl -s https://djominov.github.io/vibe-framework/ | grep -c "a new string"