docs: make GitHub releases mandatory in publishing process

- Add prominent warnings that GitHub releases are REQUIRED
- Provide detailed gh release create command with template
- Clarify that GitHub releases are the official announcement mechanism
- Add verification step to check release page
- Emphasize this step cannot be skipped

This ensures AI agents and human publishers always create GitHub releases.

Author: tikazyq

AGENTS.md

@@ -171,8 +171,20 @@ When working on the LeanSpec codebase itself, always use the local build (`node
 
 ## Publishing Releases
 
+⚠️ **CRITICAL**: When publishing a release, you MUST create a GitHub release. This is not optional.
+
 See [docs/agents/PUBLISHING.md](docs/agents/PUBLISHING.md) for the complete release process.
 
+**Quick reminder of mandatory steps:**
+1. Update versions & CHANGELOG
+2. Run pre-release checks (`pnpm pre-release`)
+3. Commit, tag, and push
+4. Prepare packages (`pnpm prepare-publish`)
+5. Publish to npm (all packages)
+6. Restore packages (`pnpm restore-packages`)
+7. **CREATE GITHUB RELEASE** (`gh release create vX.Y.Z --title "..." --notes-file ...`) ← DO NOT SKIP THIS
+8. Verify everything is published correctly
+
 ## Spec Complexity Guidelines
 
 **Token Thresholds:**

docs/agents/PUBLISHING.md

@@ -46,28 +46,76 @@ The `.github/workflows/publish-dev.yml` workflow will automatically:
 
 ## Release Checklist
 
-1. **Version bump**: Update version in all package.json files (root, cli, core, ui, web) for consistency
+⚠️ **CRITICAL**: All steps must be completed in order. Do NOT skip steps.
+
+1. **Version bump**: Update version in all package.json files (root, cli, core, ui, mcp) for consistency
 2. **Update CHANGELOG.md**: Add release notes with date and version
 3. **Type check**: Run `pnpm typecheck` to catch type errors (REQUIRED before release)
 4. **Test**: Run `pnpm test:run` to ensure tests pass (web DB tests may fail - that's OK)
 5. **Build**: Run `pnpm build` to build all packages
 6. **Validate**: Run `node bin/lean-spec.js validate` and `cd docs-site && npm run build` to ensure everything works
-7. **Prepare for publish**: Run `pnpm prepare-publish` to replace `workspace:*` with actual versions
+7. **Commit & Tag**: 
+   ```bash
+   git add -A && git commit -m "feat: release version X.Y.Z with [brief description]"
+   git tag -a vX.Y.Z -m "Release vX.Y.Z: [title]"
+   git push origin vX.Y.Z
+   ```
+8. **Prepare for publish**: Run `pnpm prepare-publish` to replace `workspace:*` with actual versions
    - ⚠️ **CRITICAL**: This step prevents `workspace:*` from leaking into npm packages
    - Creates backups of original package.json files
    - Replaces all `workspace:*` dependencies with actual versions
-8. **Commit**: `git add -A && git commit -m "chore: bump version to X.Y.Z"`
-9. **Tag**: `git tag vX.Y.Z && git push origin main --tags`
-10. **GitHub Release**: `gh release create vX.Y.Z --title "vX.Y.Z - Title" --notes "Release notes here"`
-   - This triggers the GitHub Action workflow that publishes both `lean-spec` and `@leanspec/ui` to npm
-11. **Restore packages**: Run `pnpm restore-packages` to restore original package.json files with `workspace:*`
+9. **Publish to npm**: For each package (core, cli, mcp, ui):
+   ```bash
+   cd packages/core && npm publish --access public
+   cd ../cli && npm publish --access public
+   cd ../mcp && npm publish --access public
+   cd ../ui && npm publish --access public
+   ```
+   - If a package version already exists (403 error), that's OK - skip it
+   - Tag UI as latest if needed: `npm dist-tag add @leanspec/[email protected] latest`
+10. **Restore packages**: Run `pnpm restore-packages` to restore original package.json files with `workspace:*`
+11. **Create GitHub Release** (REQUIRED - DO NOT SKIP):
+   ```bash
+   # Create release notes file with formatted content
+   cat > /tmp/release-notes.md << 'EOF'
+   ## Release vX.Y.Z - YYYY-MM-DD
+   
+   ### 🎉 Major Changes
+   [List major features/changes]
+   
+   ### 🐛 Bug Fixes
+   [List bug fixes]
+   
+   ### ✨ Enhancements
+   [List enhancements]
+   
+   ### 📦 Published Packages
+   - `@leanspec/[email protected]`
+   - `[email protected]`
+   - `@leanspec/[email protected]`
+   - `@leanspec/[email protected]`
+   
+   ### 🔗 Links
+   - [npm: lean-spec](https://www.npmjs.com/package/lean-spec)
+   - [Documentation](https://lean-spec.dev)
+   - [Full Changelog](https://github.com/codervisor/lean-spec/blob/main/CHANGELOG.md)
+   EOF
+   
+   # Create the release
+   gh release create vX.Y.Z --title "Release vX.Y.Z: [Title]" --notes-file /tmp/release-notes.md
+   ```
+   - ⚠️ **This step is MANDATORY** - GitHub releases are the official release announcement
+   - Users discover new versions through GitHub releases
+   - Release notes provide context that CHANGELOG.md alone doesn't
 12. **Verify**: 
    - `npm view lean-spec version` to confirm CLI publication
    - `npm view @leanspec/ui version` to confirm UI publication
+   - `npm view @leanspec/mcp version` to confirm MCP publication
    - `npm view lean-spec dependencies` to ensure no `workspace:*` dependencies leaked
    - `npm view @leanspec/ui dependencies` to ensure no `workspace:*` dependencies leaked
    - Test installation: `npm install -g lean-spec@latest` in a clean environment
-   - Check GitHub release page: https://github.com/codervisor/lean-spec/releases
+   - **Check GitHub release page**: https://github.com/codervisor/lean-spec/releases
+   - Verify release appears with correct title and notes
 
 ## Critical - Workspace Dependencies