1. Summary
Publishing means making code comprehensible and accessible to someone who wasn't there when it
was written. A pub.md file defines what a readme for this project must contain, the git
conventions to follow, and any release steps specific to this codebase. Claude handles the
mechanical parts - drafting prose, staging commits, formatting messages - while you retain
final approval before anything is committed or pushed.
2. pub.md Structure
# Publish Context
## Repo
GitHub URL or local path: [repo]
## Readme Requirements
Every readme must include:
- One-paragraph description of what the project does
- Prerequisites: language version, required tools, environment variables
- Build or install steps (exact commands)
- Basic usage with one concrete example
- Directory structure overview (only if non-obvious)
- Link to related documentation or site pages
## Git Conventions
Branch: main
Commit messages: lowercase action description
Examples: "added readme", "fixed broken link in nav", "updated dependency list"
Never force-push. Ask before any push.
Stage specific files by name - never git add -A.
## Release Checklist
- [ ] Readme written and reviewed
- [ ] All links in readme verified
- [ ] .gitignore up to date
- [ ] No debug output or test artifacts in the commit
3. Readme Generation
Ask Claude to draft first, then review before creating the file:
Read pub.md.
Read [main source file or entry point].
Draft a readme.md for this project following the requirements in pub.md.
Leave any section you cannot determine from the code as <!-- TODO -->.
Show me the draft - do not create the file yet.
After reviewing and editing the draft:
The draft looks good with these changes: [list edits].
Now create readme.md with those changes applied.
For an existing readme that needs updating:
Read pub.md.
Read readme.md.
Read [changed file].
The readme is out of date because [what changed].
Update only the sections affected by that change. Show me the updated
sections before writing the file.
4. Git Workflow
For a single repo commit:
Read pub.md.
Show me the git status and diff for [directory].
Propose a commit message following the conventions in pub.md.
List exactly which files you will stage.
Do not commit until I confirm.
After confirming:
That looks right. Stage those files and commit with that message.
For updating multiple repos in sequence:
Read pub.md.
I need to update these repos: [list].
For each repo in order:
1. Show git status and diff
2. Propose a commit message
3. List the files to stage
4. Wait for my approval before committing
5. Then move to the next repo
Start with [repo1].
The one-at-a-time structure matters. Claude reviewing all repos in one pass produces a list
of proposed commits too long to verify before any of them run. Sequential approval keeps
each commit visible and correctable.
5. Pre-Push Checklist
Before pushing, ask Claude to verify the release checklist from pub.md:
Read pub.md.
Walk through the release checklist for [repo]. For each item, state whether
it passes or needs attention. Cite the specific file or command that confirms each.
After the checklist passes and you are ready to push:
The checklist is clear. Push [branch] to origin.
Show me the push command before running it.
Claude should always show the git push command for your confirmation before running it.
If pub.md says "ask before any push," Claude will not push without an explicit instruction.
Do not remove that constraint from pub.md.