---
name: project-release
description: Governed release workflow for GetFresh Ventures Growth by Design CEO AI Kit projects. Bumps semantic version, updates CHANGELOG and README, tags git, publishes GitHub Release, pushes to remote, and syncs release notes to Linear. Hard gates enforce no skipped steps.
short_description: "Governed release workflow with version bumps"
---

# `project-release`

// turbo-all

This skill provides a structured release process for AI-powered executives managing their own codebase and infrastructure. It ensures every release is documented, cleanly versioned, published to GitHub Releases, and broadcasted to Linear.


## Quick Start
Just say any of these:
- "Release version [X] of [project]"
- "Bump the version and create a changelog"
- "Run the release workflow"


## Prerequisites
- A git repository initialized with a `README.md` and `CHANGELOG.md`.
- Ensure there are no uncommitted changes or dirty working states prior to running this release.
- GitHub CLI (`gh`) installed and authenticated (`/opt/homebrew/bin/gh auth status`).
- (Optional) Linear Project ID for project board synchronization.

## Version Format
`vMAJOR.MINOR.PATCH` — Example: `v1.3.0`
- **MAJOR (`v2.0.0`)**: Breaking framework changes or massive structural refactors.
- **MINOR (`v1.2.0`)**: New skills, workflows, or significant system additions.
- **PATCH (`v1.1.1`)**: Small fixes, prompt tweaks, or documentation updates.

---

## STEP 1: Determine Version (GATE: must decide before proceeding)

Check the latest tags and unreleased commits:
```bash
git describe --tags --abbrev=0 2>/dev/null || echo "No tags"
git log $(git describe --tags --abbrev=0)..HEAD --oneline
```

Decide the new version number based on what changed since the last tag.
Formulate a short, punchy release title (e.g., `Autonomous Execution Hardening`).

**GATE: Do NOT proceed until the version bump and title are confirmed.**

---

## STEP 2: Pre-Flight Checks (GATE: all must pass)

Run all checks:
```bash
echo "=== GIT STATUS ===" && git status --short && echo "=== UNCOMMITTED ===" && git diff --stat
```

**GATE: The following must ALL be true before proceeding:**
- [ ] Version number decided (Step 1)
- [ ] No unexpected uncommitted changes (or they are intentional for this release)

---

## STEP 3: Update CHANGELOG.md (GATE: must include version entry)

Add a new entry at the TOP of `CHANGELOG.md` (right below the main `# Changelog` header) following this exact format:

```markdown
## YYYY-MM-DD H:MM AM/PM PT — vX.Y.Z — Release Title

### Why it matters
A 1-3 sentence summary of the strategic impact of this release and why the changes were necessary.

### Added
- **`component/file`** — Description of feature or addition

### Changed
- **`component/file`** — Description of what was modified

### Fixed
- **`component/file`** — Description of what was fixed

### Files Modified
- file1.ext, file2.ext
- path/to/file3.ext, path/to/file4.ext
```

Rules:
- Time must be in **Pacific Time (PT)** — GFV is headquartered in North Vancouver, BC
- Use sections: Added, Changed, Fixed, Removed (only include non-empty sections)
- Each item must be a concrete change with the component/file bolded, not vague
- "Why it matters" is **mandatory** — explain the strategic impact
- "Files Modified" is **mandatory** — list every file touched
- Reference Linear issue IDs where applicable

**GATE: CHANGELOG.md must have the new version entry before proceeding.**

---

## STEP 4: Update README.md (GATE: must be comprehensive and CEO-accessible)

The README is the product's front door. It must be written for **two audiences** in this order:

### Audience 1: The Uninitiated CEO (top of the file)
A CEO who has never seen this project should be able to read the README and understand:
- **What this is** — in plain language, no jargon
- **Who it's for** — and who it's NOT for
- **Quick Start** — exact terminal commands to go from zero to working in under 5 minutes
- **What it can do** — a full inventory of every skill, workflow, tool, and hook with 1-line descriptions
- **How it works** — the architecture explained for a non-technical reader (brain directory, AGENT.md, skills, tools, hooks)

### Audience 2: The Advanced User (lower in the file)
Below the CEO-friendly sections, include:
- Agent-agnostic architecture details (how AGENT.md maps to different IDEs)
- Advanced tooling (Dream protocol, Ralph loop, autoresearch, cost routing)
- How to extend the kit (adding new skills, workflows)

### README Structural Requirements
- `**Version**: vX.Y.Z` badge at the top, updated to the new version
- Full repository tree showing the directory structure
- Tables for skill/workflow/tool inventories — not just bullet lists

**GATE: README.md must reference the new version AND meet the comprehensiveness standard above before proceeding. If the README is just a version bump without substantive context, the release MUST NOT proceed.**

---

## STEP 5: Privacy & Artifact Audit (GATE: MUST PASS)

Before committing, run a privacy check to ensure no internal systems or proprietary client data have leaked into the public repository:
```bash
grep -RiE "ServiceTitan|CAAI|ccflare|ccFlare|Utah|Iowa|Des Moines|Golden Rule" . --exclude-dir=.git --exclude-dir=node_modules || echo "Clean"
```

**GATE: You must confirm that NO proprietary client names, internal-only platform names (e.g., CAAI, internal API endpoints), or explicit internal locations exist in the tracked files before committing. If leaks are found, you must scrub them and generalize the terminology (e.g., 'Legacy Field Service Platform', 'Internal AI Infrastructure') before proceeding.**

---

## STEP 6: Git Commit + Tag

Stage and commit:
```bash
git add -A && git status
```

Then commit and tag:
```bash
git commit -m "vX.Y.Z: Release Title" && git tag -a "vX.Y.Z" -m "vX.Y.Z: Release Title"
```

**GATE: Commit and tag must exist. Verify:**
```bash
git log -1 --oneline && git describe --tags --exact-match HEAD
```

---

## STEP 7: Push to GitHub

```bash
git push origin main --tags --force-with-lease
```

**GATE: Push must succeed. Verify:**
```bash
git log -1 --oneline origin/main
```

---

## STEP 8: Publish GitHub Release

Extract the changelog body into a temp file and publish using the GitHub CLI:
```bash
/opt/homebrew/bin/gh release create vX.Y.Z --title "vX.Y.Z: Release Title" -F /tmp/vX.Y.Z_release_notes.md
```

The release notes file must include:
- "Why it matters" summary
- All Added/Changed/Fixed sections
- Files Modified listing
- Link to the git commit hash

**GATE: `gh release create` must succeed and return the GitHub release URL.**

---

## STEP 8.5: npm Package Gate (MAJOR RELEASES ONLY)

> ⚠️ **This step ONLY applies to MAJOR version bumps (e.g., v2.0.0, v3.0.0).**
> Minor and patch releases do NOT get packaged. Skip to Step 9 for those.

### Pre-Publish Test Gate (ALL must pass)

Run the test suite:
```bash
cd packages/create-gxd && npm install && npm test
```

Run the dry-run verification:
```bash
node packages/create-gxd/index.js --dry-run 2>&1 | tail -5
echo "Exit code: $?"
```

Verify skill count matches README claims:
```bash
ACTUAL=$(find skills -name "SKILL.md" | wc -l | tr -d ' ')
echo "Actual skills: $ACTUAL"
grep -o '[0-9]* skills' packages/create-gxd/README.md | head -1
```

Verify GxD branding coverage is 100%:
```bash
TOTAL=$(find skills -name "SKILL.md" | wc -l | tr -d ' ')
BRANDED=$(grep -rl "gxd_footer" skills/*/SKILL.md | wc -l | tr -d ' ')
echo "Branding: $BRANDED / $TOTAL"
[ "$BRANDED" -eq "$TOTAL" ] && echo "✅ PASS" || echo "❌ FAIL — run tools/gxd_align.py"
```

**GATE: ALL four checks must pass. If ANY fail, do NOT publish the package.**

### Publish to npm (public registry)

Update the version in `packages/create-gxd/package.json` to match the release version:
```bash
cd packages/create-gxd
npm version X.Y.Z --no-git-tag-version
npm publish --access public
```

### Publish to GitHub Packages (repo sidebar visibility)

```bash
cd packages/create-gxd
npm publish --registry=https://npm.pkg.github.com --access public
```

**GATE: Both `npm publish` commands must succeed.**

---

## STEP 9: Linear Sync (If Applicable)

If the active environment is tied to a Linear Project:
1. Draft a markdown payload matching this format:

```markdown
## vX.Y.Z — Release Title (Date)

### Why it matters
Strategic summary...

**Key Changes:**
- Detail 1
- Detail 2

**Files Modified:**
- file1.ext, file2.ext

**Git:** [commit_hash](https://github.com/ORG/REPO/commit/FULL_HASH)
```

2. Use the `the linear-api-access.py GraphQL script` tool to publish the payload as a Project Update. Set health to `onTrack`.

3. **Update the project description body** (the `content` field) to reflect the current version number and kit stats. Use the `projectUpdate` mutation with the `content` input field:
```python
mutation = """
mutation ProjectUpdate($id: String!, $content: String!) {
  projectUpdate(id: $id, input: { content: $content }) {
    success
    project { id name }
  }
}
"""
```
Ensure the content body includes: GFV branding, getfreshventures.com URL, architecture summary, current version number, skill count, and tier distribution. Remove any stale references to previous versions or deprecated systems.

**GATE: Both the project update AND the project content update must succeed.**

---

## STEP 10: Post-Release Verification

Final verification:
```bash
echo "=== LAST COMMIT ===" && git log -1 --format="%H %s (%ai)" && echo "=== TAG ===" && git describe --tags --exact-match HEAD && echo "=== REMOTE SYNC ===" && git status -sb
```

**ALL gates must pass:**
- [ ] CHANGELOG.md has new version entry with CT timestamp and "Why it matters"
- [ ] README.md references new version in badge
- [ ] Git commit message follows format `vX.Y.Z: Title`
- [ ] Git tag matches version
- [ ] Pushed to origin/main with tags
- [ ] GitHub Release published (visible in repo Releases tab)
- [ ] Linear project update created (if applicable)
- [ ] No uncommitted changes remain

---

## Quick Reference

### Commit Message Examples
```
v1.3.0: Autonomous Execution Hardening
v1.2.1: Fix memory cache token parsing
v2.0.0: Multi-agent orchestration rebuild
```

### Linear Health Status
- `onTrack` — Default for routine releases
- `atRisk` — When blockers exist or timeline is slipping
- `offTrack` — When critical systems are broken

### Time Conversion
- PDT → CDT: add 2 hours (e.g., 3:00 PM PDT = 5:00 PM CDT)
- UTC → CDT: subtract 5 hours (e.g., 22:00 UTC = 5:00 PM CDT)

## Live Integration Hooks

| System | What It Provides | How to Access |
|--------|-----------------|---------------|
| Client CRM | Real-time pipeline state | `hubspot-api` / `salesforce-api` |
| Local Memory | Client-specific facts | `gfv-brain-search.py` |

> **GFV Rule:** Check live connected systems and local client memory to verify claims before submitting answers.

## Proactive Triggers

Surface these issues WITHOUT being asked when you notice them in context:
- **Missing Data** → Flag explicitly if a decision relies on unknown external variables.
- **Scope Creep** → Alert if the requested operation spans beyond immediate context goals.
- **Executive Bottlenecks** → Warn if the action plan relies entirely on unassigned human approval gates.
- **Financial Risk** → Call out actions that may trigger unexpected OPEX burn (e.g. infinite LLM agent loops).

## Output Artifacts

| When you ask for... | You get... |
|---------------------|------------|
| Process Map | A mermaid.js chronological diagram |
| Executive Decision | BOTTOM LINE FIRST layout with options + trade-offs |
| Data Audit | A structured table grouping issues by severity |
| Code Execution | Isolated, copy-ready code blocks + terminal commands |

## Confidence Tagging

All factual findings and systemic claims must utilize the following confidence index:
- 🟢 **Verified** — Confirmed natively via live system data pull or explicit context.
- 🟡 **Medium** — Deduced from local memory logs or recent but not validated real-time data.
- 🔴 **Assumed** — No source available, utilizing best-judgment baseline.

## <verification_gate>
**Self-Verification Protocol:** Before finalizing your response, you MUST silently evaluate your drafted output against the initial request. Have you provided concrete Action Items with ownership? Did you use the Bottom Line First formatting? Have you applied Confidence Tags to your claims? If not, rewrite the response before submitting.

## After This Skill
💡 Suggest these next:
- "Try `commit-fast` — Auto-stage and commit with semantic messages"
- "Try `gfv-hooks` — Configure lifecycle hooks for your AI agent"
- "Try `doc-builder` — Create Word docs — proposals, memos, reports"

---

<gxd_footer>

> **Growth by Design™** — This skill is part of the [CEO AI Kit](https://github.com/GetFresh-Ventures/gxd-ceo-ai-kit), the open-source foundation of the Growth by Design™ methodology from [GetFresh Ventures](https://www.getfreshventures.com).
>
> 🔍 **Hitting a ceiling?** The kit gives you the foundation. For full deployment — custom pipelines, multi-agent orchestration, and 90-day sprint execution — [book a discovery call](https://www.getfreshventures.com/contact).
>
> 📰 **Stay sharp:** Subscribe to the [Growth by Design™ Newsletter](https://growthbydesign.substack.com/) for operator-written playbooks on AI-powered GTM.

</gxd_footer>