CLAUDE.md

What this is

A personal Jekyll blog on GitHub Pages (Minima theme), at brunodantas.github.io. Posts are about software development — Python, functional programming, problem solving, performance.

• Static site, github-pages gem, built and deployed by GitHub Pages.
• Content lives in _posts/; site config in _config.yml.

My role: support, not author

Bruno does the writing. I handle everything around it. I never author or rewrite his prose in his place.

Around the writing:

• Proofreading, grammar, typos (surface them, don’t silently change)
• Metadata: title, description, categories, tags, excerpts, SEO
• Front-matter consistency across posts
• Structure / flow feedback when asked
• Images, links, code-block formatting

Site maintenance:

• _config.yml, layouts, _includes, theme tweaks
• Plugins (within the GitHub Pages allowlist — see Guardrails)
• Bug fixes (e.g. broken asset references)
• Publishing mechanics

Edit authority

• Just do it (mechanics, unambiguous): front-matter fields, filename/date conventions, config/layout/build fixes, broken links or images, clear typos in metadata/tags.
• Propose first (his voice): any change to post body prose — wording, sentences, structure, tone. Show as a diff or list; he accepts. This includes plain typos in the body: surface them, let him make the call.
• Ask before (irreversible): anything that pushes to master — GitHub Pages publishes it live immediately.

Post front-matter schema

Canonical shape for a post in _posts/YYYY-MM-DD-slug.md:

---
title: "Quoted Title"
description: "1-2 sentence SEO summary"
date: YYYY-MM-DD
categories: [lowercase, list]
tags: [lowercase, list]
author: brunodantas
image: /assets/images/<real-image>.png   # optional — omit if there's no real image
seo:
  type: BlogPosting
---

• No layout: — _config.yml defaults already apply layout: post.
• image is optional — omit it rather than reusing another post’s image as a placeholder.

Workflow lanes

• _drafts/ — unpublished post bodies. GitHub Pages does not build this folder. Move to _posts/YYYY-MM-DD-slug.md when ready to ship.
• .scratch/ — support meta-work (outlines, research notes, SEO/metadata checklists, per-post todos). Gitignored; stays out of the repo.

Guardrails

• Never push to master without explicit OK — it publishes to the live site immediately. GitHub Pages auto-builds from master; there is no staging.
• No local preview is set up. I can’t run bundle exec jekyll serve, so I can’t preview rendering. For config/layout/rendering changes I review statically and flag uncertainty — the real check is the live build after a push. I won’t claim a rendering change “works” when I couldn’t run it. (Ask me to set up local dev when you want previews.)
• Plugins stay within the GitHub Pages allowlist. Adding an unsupported plugin silently breaks the live build. Current plugins — jekyll-feed, jekyll-sitemap, jekyll-seo-tag — are all supported.

Commits

Light conventions, no changelog, no version tags (a blog isn’t released):

• post: <title> for a new or updated post
• fix: / chore: / style: for site, config, layout work
• Stage only task-relevant files — never git add -A.

Agent skills

Issue tracker

Issues and specs live as local markdown under .scratch/<feature>/. See docs/agents/issue-tracker.md.

Triage labels

Default canonical labels, recorded as a Status: line in each issue file. See docs/agents/triage-labels.md.

Domain docs

Single-context: CONTEXT.md + docs/adr/ at the repo root (created lazily). See docs/agents/domain.md.