docs: Add OSS project files (CHANGELOG, linter config, release docs)

- CHANGELOG.md: Initial release notes for v0.1.0 - .golangci.yml: Linter configuration adapted from beads - RELEASING.md: Release process documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-02 01:33:19 -08:00
parent 9cb33ee289
commit 5f8d13203b
3 changed files with 355 additions and 0 deletions
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -0,0 +1,63 @@
+version: "2"
+
+run:
+  timeout: 5m
+  tests: false
+
+linters:
+  default: 'none'
+  enable:
+    - errcheck
+    - gosec
+    - misspell
+    - unconvert
+    - unparam
+
+  settings:
+    errcheck:
+      exclude-functions:
+        - (*database/sql.DB).Close
+        - (*database/sql.Rows).Close
+        - (*database/sql.Tx).Rollback
+        - (*database/sql.Stmt).Close
+        - (*database/sql.Conn).Close
+        - (*os.File).Close
+        - (os).RemoveAll
+        - (os).Remove
+        - (os).Setenv
+        - (os).Unsetenv
+        - (os).Chdir
+        - (os).MkdirAll
+        - (fmt).Sscanf
+    misspell:
+      locale: US
+
+  exclusions:
+    rules:
+      # G304: File inclusion via variable in tests is safe (test data)
+      - path: '_test\.go'
+        linters:
+          - gosec
+        text: "G304"
+      # G306: File permissions 0644 in tests are acceptable (test fixtures)
+      - path: '_test\.go'
+        linters:
+          - gosec
+        text: "G306"
+      # G302/G306: Directory/file permissions 0700/0750 are acceptable
+      - linters:
+          - gosec
+        text: "G302.*0700|G301.*0750"
+      # G204: Safe subprocess launches with validated arguments (tmux, git, etc.)
+      - path: 'internal/tmux/|internal/git/|internal/cmd/'
+        linters:
+          - gosec
+        text: 'G204'
+      # errcheck: Ignore unchecked errors in test files for common cleanup patterns
+      - path: '_test\.go'
+        linters:
+          - errcheck
+        text: "Error return value of .*(Close|Rollback|RemoveAll|Setenv|Unsetenv|Chdir|MkdirAll|Remove|Write).* is not checked"
+
+issues:
+  uniq-by-line: true
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to the Gas Town project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-02
+
+### Added
+
+Initial public release of Gas Town - a multi-agent workspace manager for Claude Code.
+
+#### Core Architecture
+- **Town structure** - Hierarchical workspace with rigs, crews, and polecats
+- **Rig management** - `gt rig add/list/remove` for project containers
+- **Crew workspaces** - `gt crew add` for persistent developer workspaces
+- **Polecat workers** - Transient agent workers managed by Witness
+
+#### Agent Roles
+- **Mayor** - Global coordinator for cross-rig work
+- **Deacon** - Town-level lifecycle patrol and heartbeat
+- **Witness** - Per-rig polecat lifecycle manager
+- **Refinery** - Merge queue processor with code review
+- **Crew** - Persistent developer workspaces
+- **Polecat** - Transient worker agents
+
+#### Work Management
+- **Convoy system** - `gt convoy create/list/status` for tracking related work
+- **Sling workflow** - `gt sling <bead> <rig>` to assign work to agents
+- **Hook mechanism** - Work attached to agent hooks for pickup
+- **Molecule workflows** - Formula-based multi-step task execution
+
+#### Communication
+- **Mail system** - `gt mail inbox/send/read` for agent messaging
+- **Escalation protocol** - `gt escalate` with severity levels
+- **Handoff mechanism** - `gt handoff` for context-preserving session cycling
+
+#### Integration
+- **Beads integration** - Issue tracking via beads (`bd` commands)
+- **Tmux sessions** - Agent sessions in tmux with theming
+- **GitHub CLI** - PR creation and merge queue via `gh`
+
+#### Developer Experience
+- **Status dashboard** - `gt status` for town overview
+- **Session cycling** - `C-b n/p` to navigate between agents
+- **Activity feed** - `gt feed` for real-time event stream
+- **Nudge system** - `gt nudge` for reliable message delivery to sessions
+
+### Infrastructure
+- **Daemon mode** - Background lifecycle management
+- **npm package** - Cross-platform binary distribution
+- **GitHub Actions** - CI/CD workflows for releases
+- **GoReleaser** - Multi-platform binary builds
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -0,0 +1,238 @@
+# Release Process for Gas Town
+
+This document describes the release process for Gas Town, including GitHub releases and npm packages.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Release Checklist](#release-checklist)
+- [1. Prepare Release](#1-prepare-release)
+- [2. GitHub Release](#2-github-release)
+- [3. npm Package Release](#3-npm-package-release)
+- [4. Verify Release](#4-verify-release)
+- [Hotfix Releases](#hotfix-releases)
+
+## Overview
+
+A Gas Town release involves multiple distribution channels:
+
+1. **GitHub Release** - Binary downloads for all platforms
+2. **npm** - Node.js package for cross-platform installation (`@gastown/gt`)
+
+## Prerequisites
+
+### Required Tools
+
+- `git` with push access to steveyegge/gastown
+- `goreleaser` for building binaries
+- `npm` with authentication (for npm releases)
+- `gh` CLI (GitHub CLI, recommended)
+
+### Required Access
+
+- GitHub: Write access to repository and ability to create releases
+- npm: Publish access to `@gastown` organization
+
+### Verify Setup
+
+```bash
+# Check git
+git remote -v  # Should show steveyegge/gastown
+
+# Check goreleaser
+goreleaser --version
+
+# Check GitHub CLI
+gh auth status
+
+# Check npm
+npm whoami  # Should show your npm username
+```
+
+## Release Checklist
+
+Before starting a release:
+
+- [ ] All tests passing (`go test ./...`)
+- [ ] npm package tests passing (`cd npm-package && npm test`)
+- [ ] CHANGELOG.md updated with release notes
+- [ ] No uncommitted changes
+- [ ] On `main` branch and up to date with origin
+
+## 1. Prepare Release
+
+### Update CHANGELOG.md
+
+Add release notes to CHANGELOG.md following the Keep a Changelog format:
+
+```markdown
+## [0.2.0] - 2026-01-15
+
+### Added
+- New feature X
+
+### Changed
+- Improved Y
+
+### Fixed
+- Bug in Z
+```
+
+Commit the CHANGELOG changes:
+
+```bash
+git add CHANGELOG.md
+git commit -m "docs: Add CHANGELOG entry for v0.2.0"
+git push origin main
+```
+
+### Update Version
+
+Update version in relevant files:
+
+1. `internal/cmd/version.go` - CLI version constant
+2. `npm-package/package.json` - npm package version
+
+```bash
+# Update versions
+vim internal/cmd/version.go
+vim npm-package/package.json
+
+# Commit
+git add -A
+git commit -m "chore: Bump version to 0.2.0"
+git push origin main
+```
+
+### Create Release Tag
+
+```bash
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+```
+
+This triggers GitHub Actions to build release artifacts automatically.
+
+## 2. GitHub Release
+
+### Using GoReleaser (Recommended)
+
+GoReleaser automates binary building and GitHub release creation:
+
+```bash
+# Clean any previous builds
+rm -rf dist/
+
+# Create release (uses GITHUB_TOKEN from gh CLI)
+GITHUB_TOKEN=$(gh auth token) goreleaser release --clean
+```
+
+This will:
+- Build binaries for all platforms (macOS, Linux, Windows - amd64/arm64)
+- Create checksums
+- Generate release notes from CHANGELOG.md
+- Upload everything to GitHub releases
+
+### Verify GitHub Release
+
+1. Visit https://github.com/steveyegge/gastown/releases
+2. Verify the new version is marked as "Latest"
+3. Check all platform binaries are present
+
+## 3. npm Package Release
+
+The npm package wraps the native binary for Node.js environments.
+
+### Test Installation Locally
+
+```bash
+cd npm-package
+
+# Run tests
+npm test
+
+# Pack and test install
+npm pack
+npm install -g ./gastown-gt-0.2.0.tgz
+gt version  # Should show 0.2.0
+
+# Cleanup
+npm uninstall -g @gastown/gt
+rm gastown-gt-0.2.0.tgz
+```
+
+### Publish to npm
+
+```bash
+# IMPORTANT: Ensure GitHub release with binaries is live first!
+cd npm-package
+npm publish --access public
+```
+
+### Verify npm Release
+
+```bash
+npm install -g @gastown/gt
+gt version  # Should show 0.2.0
+```
+
+## 4. Verify Release
+
+After all channels are updated:
+
+### GitHub
+
+```bash
+# Download and test binary
+curl -LO https://github.com/steveyegge/gastown/releases/download/v0.2.0/gastown_0.2.0_darwin_arm64.tar.gz
+tar -xzf gastown_0.2.0_darwin_arm64.tar.gz
+./gt version
+```
+
+### npm
+
+```bash
+npm install -g @gastown/gt
+gt version
+```
+
+## Hotfix Releases
+
+For urgent bug fixes:
+
+```bash
+# Create hotfix branch from tag
+git checkout -b hotfix/v0.2.1 v0.2.0
+
+# Make fixes and bump version
+# ... edit files ...
+
+# Commit, tag, and release
+git add -A
+git commit -m "fix: Critical bug fix"
+git tag -a v0.2.1 -m "Hotfix release v0.2.1"
+git push origin hotfix/v0.2.1
+git push origin v0.2.1
+
+# Follow normal release process
+GITHUB_TOKEN=$(gh auth token) goreleaser release --clean
+
+# Merge back to main
+git checkout main
+git merge hotfix/v0.2.1
+git push origin main
+```
+
+## Version Numbering
+
+Gas Town follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (x.0.0): Breaking changes
+- **MINOR** (0.x.0): New features, backwards compatible
+- **PATCH** (0.0.x): Bug fixes, backwards compatible
+
+## Questions?
+
+- Open an issue: https://github.com/steveyegge/gastown/issues
+- Check existing releases: https://github.com/steveyegge/gastown/releases