docs: add README badges and publish workflow documentation

.npmignore

@@ -0,0 +1,39 @@
+# MGW npm package exclusions
+# Defense-in-depth: package.json "files" field is the primary allowlist.
+# This file provides an additional safety net to prevent accidental inclusion
+# of development, CI, and internal files.
+
+# Internal project management
+.mgw/
+.planning/
+.worktrees/
+.test/
+
+# CI/CD and GitHub
+.github/
+
+# Claude Code
+.claude/
+
+# Git
+.git
+.gitignore
+
+# Node
+node_modules/
+
+# Source (distributed as built dist/)
+lib/
+bin/
+
+# Markdown docs (README.md is always included by npm)
+CONTRIBUTING.md
+CODEOWNERS
+
+# Editor artifacts
+*.swp
+*.swo
+.DS_Store
+
+# Build tooling config
+package-lock.json

CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-24
+
+### Added
+
+- CLI entry point (`bin/mgw.cjs`) with 12 subcommands: `ask`, `help`, `init`, `issue`, `issues`, `link`, `milestone`, `next`, `project`, `review`, `run`, `sync`
+- Slash command suite for Claude Code (`.claude/commands/mgw/`) with matching prompt files for each subcommand
+- `/mgw:run` orchestrator pipeline — end-to-end issue execution with triage, worktree isolation, implementation, PR creation, and cleanup
+- `/mgw:project` AI-driven project scaffolding — generates milestones, phases, and issue graphs from a repository description
+- `/mgw:milestone` and `/mgw:next` milestone orchestration with dependency ordering and phase-aware sequencing
+- GitHub Projects v2 integration via `gh` CLI for issue, PR, milestone, and label management
+- Worktree isolation — each issue branch runs in its own `git worktree` under `.worktrees/`
+- Structured status comments on GitHub issues with pipeline stage tracking
+- State management system (`.mgw/active/` JSON files) for tracking issue lifecycle
+- `/mgw:ask` contextual question routing command
+- `/mgw:status` project dashboard command for at-a-glance milestone and issue progress
+- `/mgw:init` command for initializing MGW in a new repository with GitHub templates and labels
+- `/mgw:sync` post-merge cleanup for merged PRs (worktree removal, state archival)
+- `/mgw:review` PR review command and `/mgw:link` for linking related issues
+- Comment-aware pipeline — detects and reacts to new GitHub issue comments during execution
+- Shared workflow reference files (`workflows/github.md`, `workflows/state.md`) for consistent patterns across commands
+- JSON Schema-based pipeline templates with parameter validation
+- Template loader with parameter filling and validation (later refactored to validation-only)
+- `pkgroll` build pipeline producing CommonJS output in `dist/`
+- Shared `lib/` modules (`github.js`, `state.js`, `template-loader.js`) for code reuse across CLI commands
+- GitHub issue templates upgraded to YAML forms with structured fields
+- GitHub Actions auto-label workflow for PRs
+- CONTRIBUTING.md with development setup and PR process documentation
+- CODEOWNERS file and branch protection guidance
+- README.md with project overview, command reference, and installation instructions
+- `.npmignore` for clean package output
+- `npx` support for zero-install usage
+
+### Changed
+
+- Refactored `/mgw:project` from hardcoded JSON templates to AI-driven scaffolding
+- Refactored template loader to validation-only role after removing hardcoded template JSONs
+- Removed all `.planning/` writes from MGW commands (moved to external tooling)
+- Migrated all 10 original commands to reference shared workflow files
+
+### Fixed
+
+- Corrected `gh pr` JSON field from `merged` to `mergedAt` in sync command
+- Fixed `optsWithGlobals()` usage and `pkgroll` source path for successful builds
+- Fixed pipeline audit issues: 3 bugs, stale README content, and drifted `project.md`
+- Fixed orchestrator-owned status comments with prescriptive PR templates and milestone context

CONTRIBUTING.md

@@ -10,6 +10,7 @@ Thanks for considering a contribution. MGW is a small but opinionated project, a
 - [Testing Changes](#testing-changes)
 - [The Delegation Boundary (Read This First)](#the-delegation-boundary)
 - [PR Process](#pr-process)
+- [Publishing](#publishing)
 - [GSD as a Model](#gsd-as-a-model)
 
 ---
@@ -340,6 +341,45 @@ MGW tracks issue-to-PR state in `.mgw/`. After a PR is merged:
 
 ---
 
+## Publishing
+
+MGW is published to [npm](https://www.npmjs.com/package/mgw) as a public package. Publishing is currently a manual process performed by maintainers.
+
+### Prerequisites
+
+- You must have an npm account with publish access to the `mgw` package.
+- You must be logged in via the npm CLI.
+
+### Publish Workflow
+
+```bash
+# 1. Authenticate with npm (one-time setup)
+npm login
+
+# 2. Build the package
+npm run build
+
+# 3. Verify the package contents before publishing
+npm pack --dry-run
+
+# 4. Publish to npm
+npm publish
+```
+
+### Pre-publish Checklist
+
+1. **Version bump** — Update `version` in `package.json` following [semver](https://semver.org/). Patch for fixes, minor for features, major for breaking changes.
+2. **CHANGELOG updated** — Add an entry to `CHANGELOG.md` for the new version.
+3. **Build passes** — `npm run build` completes without errors.
+4. **CLI works** — `mgw --version` prints the expected version.
+5. **Dry run clean** — `npm pack --dry-run` shows only intended files (check `.npmignore` if unexpected files appear).
+
+### Future Work
+
+CI-based publishing (e.g., GitHub Actions triggered on version tags) is planned but not yet implemented. For now, all publishes are manual and coordinated by maintainers.
+
+---
+
 ## GSD as a Model
 
 MGW is built on top of [Get Shit Done](https://github.com/glittercowboy/get-shit-done) (GSD) and follows its contribution philosophy:

README.md

@@ -1,5 +1,10 @@
 # MGW — My GSD Workflow
 
+[![npm version](https://img.shields.io/npm/v/mgw)](https://www.npmjs.com/package/mgw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![node](https://img.shields.io/node/v/mgw)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/snipcodeit/mgw)](https://github.com/snipcodeit/mgw)
+
 > Issue in. PR out. No excuses.
 
 **GitHub-native issue-to-PR automation for [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), powered by [Get Shit Done](https://github.com/glittercowboy/get-shit-done).**
@@ -155,6 +160,26 @@ The `/mgw:sync` command reconciles local state with GitHub reality — archiving
 - [GitHub CLI](https://cli.github.com/) (`gh`) authenticated
 - A GitHub repository with issues enabled
 
+## Quick Start
+
+Try MGW without installing anything:
+
+```bash
+# See available commands
+npx mgw --help
+
+# List your open issues
+npx mgw issues
+
+# Sync local state with GitHub
+npx mgw sync
+
+# Cross-reference two issues
+npx mgw link 42 43
+```
+
+`npx mgw` gives you the full CLI subset that works without Claude Code. For the AI-powered pipeline commands (`run`, `issue`, `project`, `milestone`, etc.), do a full install below.
+
 ## Installation
 
 ### Full install (CLI + slash commands)
@@ -198,6 +223,17 @@ Then in Claude Code:
 /mgw:help
 ```
 
+### npx vs full install
+
+Not all commands work via `npx`. The CLI has two tiers:
+
+| Tier | Commands | Requirements |
+|------|----------|--------------|
+| **CLI-only** (works with npx) | `issues`, `sync`, `link`, `help`, `--help`, `--version` | Node.js >= 18, `gh` CLI |
+| **AI-powered** (requires full install) | `run`, `init`, `project`, `milestone`, `next`, `issue`, `update`, `pr` | Node.js >= 18, `gh` CLI, Claude Code CLI, GSD |
+
+AI-powered commands call `claude -p` under the hood and require the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) to be installed and authenticated. The slash command `.md` files must also be deployed to `~/.claude/commands/mgw/` for the full pipeline to work. Use `npx mgw` to explore the CLI and verify your GitHub setup before committing to a full install.
+
 ## Typical Workflow
 
 ### New project (from scratch)

package.json

@@ -29,7 +29,20 @@
     "type": "git",
     "url": "git+https://github.com/snipcodeit/mgw.git"
   },
-  "keywords": ["github", "cli", "automation", "pipeline", "gsd"],
+  "keywords": [
+    "claude-code",
+    "github",
+    "automation",
+    "project-management",
+    "gsd",
+    "cli",
+    "developer-tools",
+    "ai"
+  ],
   "author": "snipcodeit",
-  "license": "MIT"
+  "license": "MIT",
+  "homepage": "https://github.com/snipcodeit/mgw",
+  "bugs": {
+    "url": "https://github.com/snipcodeit/mgw/issues"
+  }
 }