diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..dfe983f --- /dev/null +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..32f004e --- /dev/null +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da9a7d3..37a10bd 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/README.md b/README.md index b26c58e..31624c5 100644 --- a/README.md +++ b/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) diff --git a/package.json b/package.json index 501bbe2..322fa7b 100644 --- a/package.json +++ b/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" + } }