1. Audit Check what exists and what's broken:
```bash
# Configuration
[ -f ".releaserc.js" ] || [ -f ".releaserc.json" ] && echo "β semantic-release" || echo "β semantic-release"
[ -f "commitlint.config.js" ] || [ -f "commitlint.config.cjs" ] && echo "β commitlint" || echo "β commitlint"
grep -q "commit-msg" lefthook.yml 2>/dev/null && echo "β commit-msg hook" || echo "β commit-msg hook"
# GitHub Actions
[ -f ".github/workflows/release.yml" ] && echo "β release workflow" || echo "β release workflow"
grep -q "semantic-release" .github/workflows/release.yml 2>/dev/null && echo "β runs semantic-release" || echo "β doesn't run semantic-release"
grep -q "GEMINI_API_KEY" .github/workflows/release.yml 2>/dev/null && echo "β LLM synthesis configured" || echo "β LLM synthesis missing"
# Public page
ls app/changelog/page.tsx src/app/changelog/page.tsx 2>/dev/null && echo "β changelog page" || echo "β changelog page"
# Health
gh release list --limit 3 2>/dev/null || echo "β no releases"
```
Commit history check:
```bash
git log --oneline -10 | while read line; do
echo "$line" | grep -qE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: " || echo "NON-CONVENTIONAL: $line"
done
```
2. Plan From audit findings, build remediation plan. Every project needs:
Must have:
semantic-release configured with changelog, git, github plugins commitlint enforcing conventional commits Lefthook commit-msg hook running commitlint GitHub Actions workflow running semantic-release on push to main Should have:
LLM synthesis transforming technical changelog to user-friendly notes Public /changelog page fetching from GitHub Releases API RSS feed at /changelog.xml or /changelog/rss 3. Execute Fix everything. Don't stop at a report.
Installing semantic-release:
```bash
pnpm add -D semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github
```
Create .releaserc.js:
```javascript
module.exports = {
branches: ['main'],
plugins: [
'@semantic-release/commit-analyzer',
'@semantic-release/release-notes-generator',
['@semantic-release/changelog', { changelogFile: 'CHANGELOG.md' }],
['@semantic-release/git', { assets: ['CHANGELOG.md', 'package.json'] }],
'@semantic-release/github',
],
};
```
Installing commitlint:
```bash
pnpm add -D @commitlint/cli @commitlint/config-conventional
```
Create commitlint.config.js:
```javascript
module.exports = { extends: ['@commitlint/config-conventional'] };
```
Add to lefthook.yml:
```yaml
commit-msg:
commands:
commitlint:
run: pnpm commitlint --edit {1}
```
Creating release workflow:
Create .github/workflows/release.yml per changelog-setup reference.
Adding LLM synthesis:
> REQUIRED: Before implementing, read llm-infrastructure/references/model-research-required.md
>
> Do NOT use model names from this document or your training data.
> Run the OpenRouter fetch script and web search to determine current best model for this task.
Steps:
Research current models (MANDATORY): ```bash
# Query OpenRouter for current fast/cheap models
python3 ~/.claude/skills/llm-infrastructure/scripts/fetch-openrouter-models.py \
--task fast --filter "google|anthropic|openai" --top 10
# Web search: "best LLM for text summarization 2026"
# Web search: "Gemini API current models 2026"
```
Create scripts/synthesize-release-notes.mjs that: - Fetches latest release from GitHub API
- Uses OpenRouter API (not direct provider APIs) for flexibility
- Model name comes from environment variable, NOT hardcoded
- Gets user-friendly summary back
- Updates release body via GitHub API
Configure secrets in GitHub: - OPENROUTER_API_KEY (preferred) or provider-specific key
- Model name as environment variable (e.g., LLM_MODEL_SYNTHESIS)
Creating public changelog page:
Per changelog-page, create:
app/changelog/page.tsx - Fetches from GitHub Releases APIGroups releases by minor version No auth required (public page) RSS feed support Making changelog discoverable (CRITICAL):
A changelog page that users can't find is useless. Ensure:
Footer link : Add "changelog" link to global footer (visible on landing page)Settings link : Add "View changelog" link in app settings/about sectionVersion display : Show current app version in settings (use NEXT_PUBLIC_APP_VERSION env var)RSS link : Mention RSS feed on the changelog page itselfExample footer links:
```tsx
```
Example settings "About" section:
```tsx
Version
{process.env.NEXT_PUBLIC_APP_VERSION || '0.1.0'}
```
Delegate implementation to Codex where appropriate.
4. Verify Prove it works. Not "config exists"βactually works.
Commitlint test:
```bash
echo "bad message" | pnpm commitlint
# Should fail
echo "feat: valid message" | pnpm commitlint
# Should pass
```
Commit hook test:
```bash
# Try to commit with bad message (should be rejected)
git commit --allow-empty -m "bad message"
# Should fail due to commitlint hook
```
Release workflow test:
If you can trigger a release:
Merge a PR with feat: or fix: commit Watch GitHub Actions run Verify: - Version bumped in package.json
- CHANGELOG.md updated
- GitHub Release created
- Release notes populated (LLM synthesis ran)
Public page test:
Navigate to /changelog Verify releases displayed Verify grouped by minor version Check RSS feed works If any verification fails, go back and fix it.
|