@snipcodeit/mgw 0.1.0

package/commands/help.md

@@ -0,0 +1,119 @@
+---
+name: mgw:help
+description: Show available MGW commands and usage guide
+argument-hint: ""
+allowed-tools: []
+---
+
+<objective>
+Display the MGW (My GSD Workflow) command reference. No side effects.
+</objective>
+
+<process>
+
+Display the following help text exactly:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW — My GSD Workflow
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+GitHub ↔ GSD bridge. Automates the issue → triage → execute → PR lifecycle.
+Work runs in isolated git worktrees — your main workspace stays on the default branch.
+Local state in .mgw/ (gitignored, per-developer).
+
+COMMANDS
+
+  Setup
+  ─────
+  /mgw:init                    Bootstrap repo for MGW (state, templates, labels)
+
+  Project
+  ───────
+  /mgw:project                 Initialize project — milestones, issues, ROADMAP from template
+
+  Browse & Triage
+  ───────────────
+  /mgw:issues [filters]        List open issues (defaults: @me, open)
+  /mgw:issue <number>          Triage issue against codebase, recommend GSD route
+
+  Pipeline
+  ────────
+  /mgw:run <number>            Autonomous: triage → GSD execute → PR (worktree-isolated)
+  /mgw:milestone               Execute milestone issues in dependency order (auto-sync, checkpoint)
+  /mgw:next                    Show next unblocked issue — what to work on now
+
+  Query
+  ─────
+  /mgw:status [milestone] [--json]  Project dashboard — milestone progress + issue stages
+  /mgw:roadmap [--set-dates] [--post-discussion]  Roadmap table — milestone completion, due dates, Discussion post
+
+  GitHub Operations
+  ─────────────────
+  /mgw:update <number> [msg]   Post status comment (auto-detects type, or custom)
+  /mgw:pr [number] [--base b]  Create PR from GSD artifacts + issue context
+  /mgw:link <ref> <ref>        Cross-reference issues/PRs/branches
+
+  Query
+  ─────
+  /mgw:ask <question>          Route a question — in-scope, adjacent, separate, duplicate, out-of-scope
+
+  Maintenance
+  ───────────
+  /mgw:sync                    Reconcile .mgw/ state with GitHub
+  /mgw:help                    This help text
+
+TYPICAL FLOW
+
+  0. /mgw:init                      One-time repo setup (state, templates, labels)
+  1. /mgw:project                   Day 1: create milestones + issue backlog from template
+  2. /mgw:next                      See what's unblocked — pick your next issue
+  3. /mgw:run 42                    Full pipeline: plan → execute → verify → PR
+                                    (runs in worktree, you stay on main)
+  4. /mgw:milestone                 Auto-run all unblocked issues in dependency order
+  5. /mgw:sync                      After merge: archive state, clean up branches
+
+  Or work issue-by-issue:
+  /mgw:issues                      Browse your assigned issues
+  /mgw:issue 42                    Triage — scope, validity, security, GSD route
+  /mgw:run 42                      Auto-triages if not done yet
+
+MANUAL OPERATIONS
+
+  /mgw:update 42 "switching approach due to #38"
+  /mgw:link 42 #43
+  /mgw:link 42 branch:fix/auth-42
+  /mgw:pr                          Standalone PR from current branch
+  /mgw:pr 42 --base develop        PR linked to issue, custom base
+
+FILTER EXAMPLES
+
+  /mgw:issues                      Your open issues (default)
+  /mgw:issues --label bug           Filter by label
+  /mgw:issues --assignee all        All open issues
+  /mgw:issues --milestone v2.0      Filter by milestone
+
+GSD ROUTE MAPPING
+
+  Issue scope → GSD entry point (recommended by /mgw:issue):
+  Small (1-2 files)        → gsd:quick
+  Medium (3-8 files)       → gsd:quick --full
+  Large (9+ files/new sys) → gsd:new-milestone
+
+STATE
+
+  .mgw/active/              In-progress issues
+  .mgw/completed/           Archived after merge
+  .mgw/cross-refs.json      Issue ↔ PR ↔ branch links
+  .mgw/config.json          User preferences
+  .mgw/project.json         Project structure (milestones, phases, template)
+
+SHARED WORKFLOWS
+
+  workflows/state.md        State management, staleness detection, validate_and_load
+  workflows/github.md       All gh CLI patterns (issues, PRs, labels, comments)
+  workflows/gsd.md          Task() spawn templates, CLAUDE.md injection, GSD utilities
+  workflows/validation.md   Delegation boundary rule — MGW orchestrates, never codes
+```
+
+</process>

package/commands/init.md

@@ -0,0 +1,250 @@
+---
+name: mgw:init
+description: Bootstrap current repo for MGW integration — creates .mgw/ state, GitHub templates, gitignore entries
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+---
+
+<objective>
+One-time setup for a repo to work with MGW. Creates the .mgw/ state directory,
+GitHub issue/PR templates, and ensures gitignore entries. Safe to re-run — skips
+anything that already exists.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+@~/.claude/commands/mgw/workflows/github.md
+@~/.claude/commands/mgw/workflows/validation.md
+</execution_context>
+
+<process>
+
+<step name="verify_repo">
+**Verify we're in a git repo with a GitHub remote:**
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+gh repo view --json nameWithOwner -q .nameWithOwner
+```
+
+If not a git repo → error: "Not a git repository. Run from a repo root."
+If no GitHub remote → error: "No GitHub remote found. MGW requires a GitHub repo."
+
+Store REPO_NAME from gh output.
+</step>
+
+<step name="init_mgw_state">
+**Initialize .mgw/ directory (from state.md):**
+
+Follow initialization procedure from @~/.claude/commands/mgw/workflows/state.md:
+```bash
+mkdir -p "${REPO_ROOT}/.mgw/active" "${REPO_ROOT}/.mgw/completed"
+```
+
+Ensure .mgw/ is gitignored:
+```bash
+if ! grep -q "^\.mgw/$" "${REPO_ROOT}/.gitignore" 2>/dev/null; then
+  echo ".mgw/" >> "${REPO_ROOT}/.gitignore"
+fi
+```
+
+Initialize cross-refs:
+```bash
+if [ ! -f "${REPO_ROOT}/.mgw/cross-refs.json" ]; then
+  echo '{"links":[]}' > "${REPO_ROOT}/.mgw/cross-refs.json"
+fi
+```
+
+Ensure .worktrees/ is gitignored:
+```bash
+if ! grep -q "^\.worktrees/$" "${REPO_ROOT}/.gitignore" 2>/dev/null; then
+  echo ".worktrees/" >> "${REPO_ROOT}/.gitignore"
+fi
+```
+</step>
+
+<step name="create_issue_templates">
+**Create GitHub issue templates (skip if they exist):**
+
+Check for existing templates:
+```bash
+ls "${REPO_ROOT}/.github/ISSUE_TEMPLATE/" 2>/dev/null
+```
+
+If no templates exist, create:
+
+`${REPO_ROOT}/.github/ISSUE_TEMPLATE/bug.yml`:
+```yaml
+name: Bug Report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: textarea
+    id: bluf
+    attributes:
+      label: BLUF
+      description: Bottom Line Up Front — one sentence summary of the problem
+    validations:
+      required: true
+
+  - type: textarea
+    id: whats-wrong
+    attributes:
+      label: What's Wrong
+      description: What's broken, with file paths and line numbers where relevant
+    validations:
+      required: true
+
+  - type: textarea
+    id: whats-involved
+    attributes:
+      label: What's Involved
+      description: Files and systems that need changes
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-fix
+    attributes:
+      label: Steps to Fix
+      description: Suggested fix approach (optional but helpful for triage)
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+    validations:
+      required: false
+```
+
+`${REPO_ROOT}/.github/ISSUE_TEMPLATE/enhancement.yml`:
+```yaml
+name: Enhancement
+description: New feature or improvement to existing functionality
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: bluf
+    attributes:
+      label: BLUF
+      description: Bottom Line Up Front — one sentence summary of what you want
+    validations:
+      required: true
+
+  - type: textarea
+    id: whats-needed
+    attributes:
+      label: What's Needed
+      description: What should change or be added, with specifics
+    validations:
+      required: true
+
+  - type: textarea
+    id: whats-involved
+    attributes:
+      label: What's Involved
+      description: Files, systems, and scope estimate
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+    validations:
+      required: false
+```
+
+If templates already exist → report "Issue templates already exist, skipping."
+</step>
+
+<step name="create_pr_template">
+**Create PR template (skip if exists):**
+
+Check: `${REPO_ROOT}/.github/PULL_REQUEST_TEMPLATE.md`
+
+If not found, create:
+```markdown
+## Summary
+<!-- 2-4 bullets: what changed and why -->
+
+-
+
+Closes #<!-- issue number -->
+
+## Changes
+<!-- Group by system/module -->
+
+-
+
+## Test Plan
+<!-- How to verify these changes work -->
+
+- [ ]
+```
+
+If exists → report "PR template already exists, skipping."
+</step>
+
+<step name="ensure_labels">
+**Ensure standard labels exist on GitHub:**
+
+```bash
+gh label create "bug" --description "Something isn't working" --color "d73a4a" --force
+gh label create "enhancement" --description "New feature or improvement" --color "a2eeef" --force
+
+# MGW pipeline labels
+gh label create "mgw:triaged" --description "Issue triaged and ready for pipeline" --color "0e8a16" --force
+gh label create "mgw:needs-info" --description "Blocked — needs more detail or clarification" --color "e4e669" --force
+gh label create "mgw:needs-security-review" --description "Blocked — requires security review" --color "d93f0b" --force
+gh label create "mgw:discussing" --description "Under discussion — not yet approved" --color "c5def5" --force
+gh label create "mgw:approved" --description "Discussion complete — approved for execution" --color "0e8a16" --force
+gh label create "mgw:in-progress" --description "Pipeline actively executing" --color "1d76db" --force
+gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder comment" --color "b60205" --force
+```
+
+`--force` updates existing labels without error.
+</step>
+
+<step name="report">
+**Report setup status:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► INIT — ${REPO_NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  .mgw/                  ${created|exists}
+  .mgw/cross-refs.json   ${created|exists}
+  .gitignore entries     ${added|exists}
+  Issue templates        ${created|exists}
+  PR template            ${created|exists}
+  GitHub labels          synced
+  MGW pipeline labels    synced (7 labels)
+
+Ready to use:
+  /mgw:issues            Browse issues
+  /mgw:run <number>      Full pipeline
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Verified git repo with GitHub remote
+- [ ] .mgw/ directory structure created
+- [ ] .mgw/ and .worktrees/ in .gitignore
+- [ ] cross-refs.json initialized
+- [ ] Issue templates created (bug + enhancement)
+- [ ] PR template created
+- [ ] GitHub labels ensured (bug, enhancement)
+- [ ] MGW pipeline labels ensured (7 mgw:* labels)
+- [ ] Setup report shown
+</success_criteria>