@phuc1403/musketeer 0.2.2 → 0.2.4

package/README.md

@@ -12,15 +12,19 @@ npm i -g @phuc1403/musketeer
 ## Use
 
 ```bash
-musketeer muster     # open the muster — pick your company (multi-select) → reconcile
+musketeer muster     # self-update → pick company (multi-select) → refresh all selected skills to latest
 musketeer promote    # update the musketeer CLI itself to the latest published version
 musketeer            # show usage
 musketeer --help     # show usage
 ```
 
-`musketeer muster` is **idempotent**: the picker pre-checks your current company (from `.musketeer.json`),
-and confirming applies the diff — install newly-checked, remove newly-unchecked, regenerate
-`settings.json`, and auto-install any missing prerequisites.
+`musketeer muster` **self-updates first**: it pulls the latest published version (re-execing when behind),
+so the refresh always applies the newest template. Set `MUSKETEER_NO_SELF_UPDATE=1` to skip (offline / pinned).
+
+It is also **idempotent** and **force-updating**: the picker pre-checks your current company (from
+`.musketeer.json`); on confirm it **re-writes every selected musketeer's files to the latest template**
+(overwriting any local edits), removes newly-unchecked ones, regenerates `settings.json`, and auto-installs
+any missing prerequisites.
 
 `musketeer promote` upgrades the **CLI tool** itself (not your project's company): it checks the npm
 registry, and if a newer version exists, runs `npm i -g @phuc1403/musketeer@latest`. _muster = which
@@ -30,7 +34,7 @@ musketeers are in this project; promote = upgrade the binary._
 
 | Musketeer | Default in muster | What it adds |
 |-----------|-------------------|--------------|
-| **core** | always on (locked, hidden) | research, handoff, skill-creator · statusline, usage-context, format-json hooks |
+| **core** | always on (locked, hidden) | research, handoff, skill-creator, git (+ git-manager agent) · statusline, usage-context, format-json hooks |
 | **architecture** | off | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
 | **hallmark** | off | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
 | **code-review** | off | code-review skill + code-reviewer agent |

package/bin/musketeer.js

@@ -6,16 +6,17 @@ const { parseArgs } = require('node:util');
 const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
 
 Usage:
-  musketeer muster     Open the muster — pick your company (multi-select), then reconcile
+  musketeer muster     Self-update to latest, then pick your company and refresh all selected skills
   musketeer promote    Update the musketeer CLI itself to the latest published version
   musketeer            Show this help
   musketeer --help     Show this help
 
 Notes:
   * "muster" changes which musketeers are in THIS project; "promote" upgrades the CLI itself.
+  * On confirm, muster REFRESHES every selected musketeer's files to the latest template (overwrites local edits).
+  * muster auto-updates the CLI to the latest published version first (set MUSKETEER_NO_SELF_UPDATE=1 to skip).
   * "core" is always installed and locked — it cannot be removed.
   * The muster is multi-select: check every musketeer you want, then confirm.
-  * Re-running is idempotent: the picker pre-checks your current company; confirm applies the diff.
   * settings.json is GENERATED per-selection; missing prereqs are auto-installed (announced).`;
 
 function parse(argv) {
@@ -48,6 +49,14 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'muster') {
+    // Pull the latest published version first, so the picker refreshes installed
+    // skills to the newest template (not a stale package's). Re-execs when behind.
+    const { ensureLatest } = require('../src/self-update');
+    const reexecCode = ensureLatest();
+    if (reexecCode !== null) {
+      process.exitCode = reexecCode;
+      return;
+    }
     // Lazy-require so help never pays the cost of loading the engine/manifest.
     const reconcile = require('../src/reconcile');
     await reconcile.run({ desiredIds: null, interactive: true });

package/manifest.json

@@ -3,16 +3,18 @@
   "musketeers": {
     "core": {
       "label": "core",
-      "description": "Always-on foundation: research, handoff, skill-creator + statusline, usage-context & format-json hooks.",
+      "description": "Always-on foundation: research, handoff, skill-creator, git (+ git-manager) + statusline, usage-context & format-json hooks.",
       "locked": true,
       "deps": [],
       "files": [
         "skills/research/**",
         "skills/handoff/**",
         "skills/skill-creator/**",
+        "skills/git/**",
         "skills/install.ps1",
         "skills/install.sh",
         "agents/researcher.md",
+        "agents/git-manager.md",
         "statusline.cjs",
         "hooks/usage-context-awareness.cjs",
         "hooks/lib/**",
@@ -43,7 +45,7 @@
           "order": 2
         }
       ],
-      "prereqs": ["node", "git", "python", "venv-anthropic", "claude-cli"]
+      "prereqs": ["node", "git", "gh", "python", "venv-anthropic", "claude-cli"]
     },
     "architecture": {
       "label": "architecture",
@@ -95,13 +97,14 @@
     },
     "dotnet": {
       "label": "dotnet",
-      "description": ".NET extras: tdd, knowledge-crunching + EF migration-guard hook.",
+      "description": ".NET extras: tdd, knowledge-crunching + EF migration-guard & CONTEXT auto-load hooks.",
       "locked": false,
       "deps": [],
       "files": [
         "skills/tdd/**",
         "skills/knowledge-crunching/**",
-        "hooks/block-migration-edits.cjs"
+        "hooks/block-migration-edits.cjs",
+        "hooks/inject-context.cjs"
       ],
       "settings": [
         {
@@ -110,6 +113,13 @@
           "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-migration-edits.cjs\"",
           "order": 1,
           "statusMessage": "Checking for EF migration edits"
+        },
+        {
+          "event": "SessionStart",
+          "matcher": "startup|resume|clear|compact",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-context.cjs\"",
+          "order": 1,
+          "statusMessage": "Loading domain CONTEXT"
         }
       ],
       "prereqs": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuc1403/musketeer",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
   "type": "commonjs",
   "bin": {

package/src/promote.js

@@ -23,6 +23,19 @@ function defaultRun(cmd) {
   };
 }
 
+/**
+ * Look up a package's published `latest` version from the registry.
+ * @param {(cmd:string)=>{code:number,stdout:string,stderr:string}} exec
+ * @param {string} name
+ * @returns {?string} the version, or null if unreachable / unparseable
+ */
+function fetchLatest(exec, name) {
+  const view = exec(`npm view ${name} version`);
+  const latest = (view.stdout || '').trim();
+  if (view.code !== 0 || !/^\d+\.\d+\.\d+/.test(latest)) return null;
+  return latest;
+}
+
 /** Compare dotted numeric versions: 1 if a>b, -1 if a<b, 0 if equal. */
 function compareVersions(a, b) {
   const pa = String(a).split('.').map(Number);
@@ -50,10 +63,9 @@ async function run(overrides = {}) {
   const current = overrides.current || pkg.version;
 
   log(`Checking rank… installed ${current} (${name})`);
-  const view = exec(`npm view ${name} version`);
-  const latest = (view.stdout || '').trim();
+  const latest = fetchLatest(exec, name);
 
-  if (view.code !== 0 || !/^\d+\.\d+\.\d+/.test(latest)) {
+  if (!latest) {
     log('Could not reach the npm registry to check for a newer version.');
     log(`Try manually: npm i -g ${name}@latest`);
     return { status: 'unknown', from: current, to: null };
@@ -78,4 +90,4 @@ async function run(overrides = {}) {
   return { status: 'promoted', from: current, to: latest };
 }
 
-module.exports = { run, compareVersions, defaultRun };
+module.exports = { run, fetchLatest, compareVersions, defaultRun };

package/src/reconcile.js

@@ -50,7 +50,7 @@ async function run(opts, overrides = {}) {
   const plan = copier.planFiles(prev.files, desired.files);
 
   d.log(`Company: ${desired.ids.join(', ')}`);
-  d.log(`Files: ${plan.copy.length} managed, ${plan.remove.length} to remove.`);
+  d.log(`Files: ${plan.copy.length} refreshed to latest, ${plan.remove.length} removed.`);
 
   copier.apply(plan, d.templateDir, projectDir);
   d.settingsMerger.generate(desired, projectDir);

package/src/self-update.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// Self-update gate for `musketeer muster`. Before the picker applies the bundled
+// template, make sure the CLI is at the latest PUBLISHED version — otherwise
+// "muster" would refresh installed skills to a stale package's template.
+//
+// When behind: promote (npm i -g @latest), then re-exec `musketeer muster` so the
+// picker runs under the freshly-installed template. A running Node process can't
+// reliably hot-swap its own package files mid-run, so re-exec is the safe path.
+//
+// Guards:
+//   MUSKETEER_REEXEC=1        set on the child so it never re-checks (no loop)
+//   MUSKETEER_NO_SELF_UPDATE=1 user opt-out (offline / pinned version)
+
+const { spawnSync } = require('child_process');
+const { fetchLatest, compareVersions, defaultRun } = require('./promote');
+const pkg = require('../package.json');
+
+/**
+ * Decide whether muster should self-update first. Pure — injectable exec/env.
+ * @param {{exec?:Function, current?:string, name?:string, env?:object}} [o]
+ * @returns {{action:'proceed'|'update', latest:?string}}
+ */
+function decide(o = {}) {
+  const exec = o.exec || defaultRun;
+  const current = o.current || pkg.version;
+  const name = o.name || pkg.name;
+  const env = o.env || process.env;
+
+  if (env.MUSKETEER_REEXEC === '1' || env.MUSKETEER_NO_SELF_UPDATE === '1') {
+    return { action: 'proceed', latest: null };
+  }
+  const latest = fetchLatest(exec, name);
+  if (!latest) return { action: 'proceed', latest: null }; // offline / unknown — proceed as-is
+  if (compareVersions(latest, current) <= 0) return { action: 'proceed', latest }; // already latest
+  return { action: 'update', latest };
+}
+
+/**
+ * Ensure the CLI is latest before muster applies the template.
+ * @param {object} [io] injectable { log, exec, spawn, env, name, current } for tests
+ * @returns {?number} an exit code if it re-exec'd a fresh muster (caller should
+ *   exit with it); null to mean "proceed in-process".
+ */
+function ensureLatest(io = {}) {
+  const log = io.log || ((m) => process.stdout.write(m + '\n'));
+  const exec = io.exec || defaultRun;
+  const spawn = io.spawn || spawnSync;
+  const env = io.env || process.env;
+  const name = io.name || pkg.name;
+  const current = io.current || pkg.version;
+
+  const d = decide({ exec, current, name, env });
+  if (d.action === 'proceed') return null;
+
+  log(`Updating musketeer ${current} → ${d.latest} before muster…`);
+  const ins = exec(`npm i -g ${name}@latest`);
+  if (ins.code !== 0) {
+    log('Self-update failed — continuing with the current version.');
+    if (ins.stderr) log(ins.stderr.trim());
+    return null;
+  }
+
+  // Re-exec the now-latest binary's muster, inheriting the TTY for the picker.
+  const r = spawn('musketeer', ['muster'], {
+    stdio: 'inherit',
+    shell: true,
+    env: { ...env, MUSKETEER_REEXEC: '1' },
+  });
+  return typeof r.status === 'number' ? r.status : 0;
+}
+
+module.exports = { decide, ensureLatest };

package/template/.claude/agents/git-manager.md

@@ -0,0 +1,19 @@
+---
+name: git-manager
+description: Stage, commit, and push code changes with conventional commits. Use when user says "commit", "push", or finishes a feature/fix.
+model: haiku
+tools: Glob, Grep, Read, Bash, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
+---
+You are a Git Operations Specialist. Execute workflow in EXACTLY 2-4 tool calls. No exploration phase.
+Activate `git` skill.
+**IMPORTANT**: Ensure token efficiency while maintaining high quality.
+
+## Team Mode (when spawned as teammate)
+
+When operating as a team member:
+1. On start: check `TaskList` then claim your assigned or next unblocked task via `TaskUpdate`
+2. Read full task description via `TaskGet` before starting work
+3. Only perform git operations explicitly requested in task — no unsolicited pushes or force operations
+4. When done: `TaskUpdate(status: "completed")` then `SendMessage` git operation summary to lead
+5. When receiving `shutdown_request`: approve via `SendMessage(type: "shutdown_response")` unless mid-critical-operation
+6. Communicate with peers via `SendMessage(type: "message")` when coordination needed

package/template/.claude/hooks/inject-context.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// SessionStart hook (dotnet company): auto-load the repo-root `CONTEXT.md` — the
+// bounded-context model produced by the knowledge-crunching skill — into every
+// session, so the domain's ubiquitous language and invariants "lead the code".
+//
+// If the root CONTEXT.md is missing, ALERT the user (systemMessage) so they
+// create one. Any other error fails open (emits nothing, exit 0) so it can never
+// block a session.
+const fs = require("fs");
+const path = require("path");
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const file = path.join(root, "CONTEXT.md");
+
+try {
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf-8");
+  } catch {
+    // Not found — surface a visible warning to the user, inject nothing.
+    process.stdout.write(
+      JSON.stringify({
+        systemMessage:
+          "musketeer: no CONTEXT.md at the repo root — the bounded-context model is missing. " +
+          "Run the knowledge-crunching skill (/knowledge-crunching) to create one.",
+      })
+    );
+    process.exit(0);
+  }
+
+  const additionalContext =
+    "Bounded-context model (root CONTEXT.md) — injected every session. It is the " +
+    "ubiquitous language and model rules of this bounded context, kept vendor- and " +
+    "decision-neutral. Treat it as canonical for domain naming, concepts, and invariants: " +
+    "name new code after it, and when a concept is renamed update CONTEXT.md and the code in " +
+    "the same turn. It bounds what the DOMAIN model sees, not what infrastructure may do " +
+    "(an ACL can legitimately key on more).\n\n" +
+    "===== CONTEXT.md =====\n" +
+    content.trimEnd();
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext,
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open
+}

package/template/.claude/skills/git/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ck:git
+description: "Git operations with conventional commits. Use for staging, committing, pushing, PRs, merges. Auto-splits commits by type/scope. Security scans for secrets."
+argument-hint: "cm|cp|pr|merge [args]"
+metadata:
+  author: claudekit
+  version: "1.0.0"
+---
+
+# Git Operations
+
+## Default (No Arguments)
+
+If invoked without arguments, use `AskUserQuestion` to present available git operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `cm` | Stage files & create commits |
+| `cp` | Stage files, create commits and push |
+| `pr` | Create Pull Request |
+| `merge` | Merge branches |
+
+Present as options via `AskUserQuestion` with header "Git Operation", question "What would you like to do?".
+
+Execute git workflows via `git-manager` subagent to isolate verbose output.
+
+**IMPORTANT:**
+- Sacrifice grammar for the sake of concision.
+- Ensure token efficiency while maintaining high quality.
+- Pass these rules to subagents.
+
+## Arguments
+- `cm`: Stage files & create commits
+- `cp`: Stage files, create commits and push
+- `pr`: Create Pull Request [to-branch] [from-branch]
+  - `to-branch`: Target branch (default: main)
+  - `from-branch`: Source branch (default: current branch)
+- `merge`: Merge [to-branch] [from-branch]
+  - `to-branch`: Target branch (default: main)
+  - `from-branch`: Source branch (default: current branch)
+
+## Quick Reference
+
+| Task | Reference |
+|------|-----------|
+| Commit | `references/workflow-commit.md` |
+| Push | `references/workflow-push.md` |
+| Pull Request | `references/workflow-pr.md` |
+| Merge | `references/workflow-merge.md` |
+| Standards | `references/commit-standards.md` |
+| Safety | `references/safety-protocols.md` |
+| Branches | `references/branch-management.md` |
+| GitHub CLI | `references/gh-cli-guide.md` |
+
+## Core Workflow
+
+### Step 1: Stage + Analyze
+```bash
+git add -A && git diff --cached --stat && git diff --cached --name-only
+```
+
+### Step 2: Security Check
+Scan for secrets before commit:
+```bash
+git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)"
+```
+**If secrets found:** STOP, warn user, suggest `.gitignore`.
+
+### Step 3: Split Decision
+
+**NOTE:**
+- Search for related issues on GitHub and add to body.
+- Only use `feat`, `fix`, or `perf` prefixes for files in `.claude` directory (do not use `docs`).
+
+**Split commits if:**
+- Different types mixed (feat + fix, code + docs)
+- Multiple scopes (auth + payments)
+- Config/deps + code mixed
+- FILES > 10 unrelated
+
+**Single commit if:**
+- Same type/scope, FILES ≤ 3, LINES ≤ 50
+
+### Step 4: Commit
+```bash
+git commit -m "type(scope): description"
+```
+
+## Output Format
+```
+✓ staged: N files (+X/-Y lines)
+✓ security: passed
+✓ commit: HASH type(scope): description
+✓ pushed: yes/no
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Secrets detected | Block commit, show files |
+| No changes | Exit cleanly |
+| Push rejected | Suggest `git pull --rebase` |
+| Merge conflicts | Suggest manual resolution |
+
+## References
+
+- `references/workflow-commit.md` - Commit workflow with split logic
+- `references/workflow-push.md` - Push workflow with error handling
+- `references/workflow-pr.md` - PR creation with remote diff analysis
+- `references/workflow-merge.md` - Branch merge workflow
+- `references/commit-standards.md` - Conventional commit format rules
+- `references/safety-protocols.md` - Secret detection, branch protection
+- `references/branch-management.md` - Naming, lifecycle, strategies
+- `references/gh-cli-guide.md` - GitHub CLI commands reference

package/template/.claude/skills/git/references/branch-management.md

@@ -0,0 +1,88 @@
+# Branch Management
+
+## Naming Convention
+
+**Format:** `<type>/<descriptive-name>`
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `feature/` | New features | `feature/oauth-login` |
+| `fix/` | Bug fixes | `fix/db-timeout` |
+| `refactor/` | Code restructure | `refactor/api-cleanup` |
+| `docs/` | Documentation | `docs/api-reference` |
+| `test/` | Test improvements | `test/integration-suite` |
+| `chore/` | Maintenance | `chore/deps-update` |
+| `hotfix/` | Production fixes | `hotfix/payment-crash` |
+
+## Branch Lifecycle
+
+### Create
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/new-feature
+```
+
+### During Development
+```bash
+# Regular commits
+git add <files> && git commit -m "feat(scope): description"
+
+# Stay current with main
+git fetch origin
+git rebase origin/main
+```
+
+### Before Merge
+```bash
+# Push final state
+git push origin feature/new-feature
+
+# Or after rebase (feature branches only)
+git push -f origin feature/new-feature
+```
+
+### After Merge
+```bash
+# Delete local
+git branch -d feature/new-feature
+
+# Delete remote
+git push origin --delete feature/new-feature
+```
+
+## Branch Strategies
+
+### Simple (small teams)
+```
+main (production)
+  └─ feature/* (development)
+```
+
+### Git Flow (releases)
+```
+main (production)
+develop (staging)
+  ├─ feature/*
+  ├─ bugfix/*
+  ├─ hotfix/*
+  └─ release/*
+```
+
+### Trunk-Based (CI/CD)
+```
+main (always deployable)
+  └─ short-lived feature branches
+```
+
+## Quick Commands
+
+| Task | Command |
+|------|---------|
+| List branches | `git branch -a` |
+| Current branch | `git rev-parse --abbrev-ref HEAD` |
+| Switch branch | `git checkout <branch>` |
+| Create + switch | `git checkout -b <branch>` |
+| Delete local | `git branch -d <branch>` |
+| Delete remote | `git push origin --delete <branch>` |
+| Rename | `git branch -m <old> <new>` |

package/template/.claude/skills/git/references/commit-standards.md

@@ -0,0 +1,46 @@
+# Commit Message Standards
+
+## Format
+```
+type(scope): description
+```
+
+## Types (priority order)
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting (no logic change)
+- `refactor`: Restructure without behavior change
+- `test`: Tests
+- `chore`: Maintenance, deps, config
+- `perf`: Performance
+- `build`: Build system
+- `ci`: CI/CD
+
+## Rules
+- **<72 characters**
+- **Present tense, imperative** ("add" not "added")
+- **No period at end**
+- **Scope optional but recommended**
+- **Focus on WHAT, not HOW**
+- Only use `feat`, `fix`, or `perf` prefixes for files in `.claude` directory (do not use `docs`).
+
+## NEVER Include AI Attribution
+- ❌ "Generated with Claude"
+- ❌ "Co-Authored-By: Claude"
+- ❌ Any AI reference
+
+## Good Examples
+- `feat(auth): add login validation`
+- `fix(api): resolve query timeout`
+- `docs(readme): update install guide`
+- `refactor(utils): simplify date logic`
+
+## Bad Examples
+- ❌ `Updated files` (not descriptive)
+- ❌ `feat(auth): added login using bcrypt with salt` (too long, describes HOW)
+- ❌ `Fix bug` (not specific)
+
+## Special Cases
+- `.claude/` skill updates: `perf(skill): improve token efficiency`
+- `.claude/` new skills: `feat(skill): add database-optimizer`

package/template/.claude/skills/git/references/gh-cli-guide.md

@@ -0,0 +1,109 @@
+# GitHub CLI Guide
+
+## Authentication
+```bash
+gh auth login        # Interactive login
+gh auth status       # Check auth state
+gh auth logout       # Logout
+```
+
+## Pull Requests
+
+### Create PR
+```bash
+# Basic
+gh pr create --base main --head feature-branch --title "feat: add login" --body "Summary"
+
+# With HEREDOC body
+gh pr create --base main --title "feat(auth): add OAuth" --body "$(cat <<'EOF'
+## Summary
+- Added OAuth2 provider support
+- Implemented token refresh
+
+## Test plan
+- [ ] Unit tests pass
+- [ ] Manual login test
+EOF
+)"
+
+# Draft mode
+gh pr create --draft --title "WIP: new feature"
+
+# Assign reviewers
+gh pr create --reviewer @user1,@user2
+
+# Add labels
+gh pr create --label "bug,priority:high"
+```
+
+### View/Review PR
+```bash
+gh pr list                    # List PRs
+gh pr view 123                # View PR details
+gh pr view 123 --web          # Open in browser
+gh pr checkout 123            # Checkout PR locally
+gh pr diff 123                # View PR diff
+gh pr status                  # Your PRs + reviews
+```
+
+### Merge PR
+```bash
+gh pr merge 123               # Default merge commit
+gh pr merge 123 --squash      # Squash commits
+gh pr merge 123 --rebase      # Rebase merge
+gh pr merge 123 --auto        # Auto-merge when checks pass
+gh pr merge 123 --delete-branch  # Delete branch after
+```
+
+### PR Comments
+```bash
+gh pr comment 123 --body "LGTM!"
+gh api repos/{owner}/{repo}/pulls/123/comments  # View all
+```
+
+## Issues
+
+```bash
+gh issue list                 # List issues
+gh issue view 42              # View issue
+gh issue create --title "Bug" --body "Description"
+gh issue develop 42 -c        # Create branch from issue
+```
+
+## Repository
+
+```bash
+gh repo view                  # Current repo info
+gh repo clone owner/repo      # Clone
+gh browse                     # Open repo in browser
+gh browse path/to/file:42     # Open file at line
+```
+
+## Workflow Runs
+
+```bash
+gh run list                   # List workflow runs
+gh run view <run-id>          # View run details
+gh run watch                  # Watch running workflow
+gh run rerun <run-id>         # Rerun failed workflow
+```
+
+## JSON Output (scripting)
+
+```bash
+gh pr list --json number,title,author
+gh pr view 123 --json commits,reviews
+gh issue list --json number,title --jq '.[].title'
+```
+
+## Common Patterns
+
+### Create PR with auto-merge
+```bash
+gh pr create --fill && gh pr merge --auto --squash
+```
+
+### Close stale PRs
+```bash
+gh pr list --state open --json number -q '.[].number' | xargs -I {} gh pr close {}
+```

package/template/.claude/skills/git/references/safety-protocols.md

@@ -0,0 +1,69 @@
+# Git Safety Protocols
+
+## Secret Detection Patterns
+
+### Scan Command
+```bash
+git diff --cached | grep -iE "(AKIA|api[_-]?key|token|password|secret|credential|private[_-]?key|mongodb://|postgres://|mysql://|redis://|-----BEGIN)"
+```
+
+### Patterns to Detect
+
+| Category | Pattern | Example |
+|----------|---------|---------|
+| API Keys | `api[_-]?key`, `apiKey` | `API_KEY=abc123` |
+| AWS | `AKIA[0-9A-Z]{16}` | `AKIAIOSFODNN7EXAMPLE` |
+| Tokens | `token`, `auth_token`, `jwt` | `AUTH_TOKEN=xyz` |
+| Passwords | `password`, `passwd`, `pwd` | `DB_PASSWORD=secret` |
+| Private Keys | `-----BEGIN PRIVATE KEY-----` | PEM files |
+| DB URLs | `mongodb://`, `postgres://`, `mysql://` | Connection strings |
+| OAuth | `client_secret`, `oauth_token` | `CLIENT_SECRET=abc` |
+
+### Files to Warn About
+- `.env`, `.env.*` (except `.env.example`)
+- `*.key`, `*.pem`, `*.p12`
+- `credentials.json`, `secrets.json`
+- `config/private.*`
+
+### Action on Detection
+1. **BLOCK commit immediately**
+2. Show matching lines: `git diff --cached | grep -B2 -A2 <pattern>`
+3. Suggest: "Add to .gitignore or use environment variables"
+4. Offer to unstage: `git reset HEAD <file>`
+
+## Branch Protection
+
+### Never Force Push To
+- `main`, `master`, `production`, `prod`, `release/*`
+
+### Pre-Merge Checks
+```bash
+# Check for conflicts before merge
+git merge --no-commit --no-ff origin/{branch} && git merge --abort
+```
+
+### Remote-First Operations
+Always use `origin/{branch}` for comparisons:
+- ✅ `git diff origin/main...origin/feature`
+- ❌ `git diff main...HEAD` (includes local uncommitted)
+
+## Error Recovery
+
+### Undo Last Commit (unpushed)
+```bash
+git reset --soft HEAD~1  # Keep changes staged
+git reset HEAD~1         # Keep changes unstaged
+```
+
+### Abort Merge
+```bash
+git merge --abort
+```
+
+### Discard Local Changes
+```bash
+git checkout -- <file>   # Single file
+git reset --hard HEAD    # All files (DANGER)
+```
+
+**Always confirm with user before destructive operations.**

package/template/.claude/skills/git/references/workflow-commit.md

@@ -0,0 +1,58 @@
+# Commit Workflow
+
+Execute via `git-manager` subagent.
+
+## Tool 1: Stage + Analyze
+```bash
+git add -A && \
+echo "=== STAGED ===" && git diff --cached --stat && \
+echo "=== SECURITY ===" && \
+git diff --cached | grep -c -iE "(api[_-]?key|token|password|secret|credential)" | awk '{print "SECRETS:"$1}' && \
+echo "=== GROUPS ===" && \
+git diff --cached --name-only | awk -F'/' '{
+  if ($0 ~ /\.(md|txt)$/) print "docs:"$0
+  else if ($0 ~ /test|spec/) print "test:"$0
+  else if ($0 ~ /\.claude/) print "config:"$0
+  else if ($0 ~ /package\.json|lock/) print "deps:"$0
+  else print "code:"$0
+}'
+```
+
+**If SECRETS > 0:** STOP, show matches, block commit.
+
+## Tool 2: Split Decision
+
+NOTE: 
+- Search for related issues on GitHub and add to body.
+- Only use `feat`, `fix`, or `perf` prefixes for files in `.claude` directory (do not use `docs`).
+
+**From groups, decide:**
+
+**A) Single commit:** Same type/scope, FILES ≤ 3, LINES ≤ 50
+
+**B) Multi commit:** Mixed types/scopes, group by:
+- Group 1: `config:` → `chore(config): ...`
+- Group 2: `deps:` → `chore(deps): ...`
+- Group 3: `test:` → `test: ...`
+- Group 4: `code:` → `feat|fix: ...`
+- Group 5: `docs:` → `docs: ...`
+
+## Tool 3: Commit
+
+**Single:**
+```bash
+git commit -m "type(scope): description"
+```
+
+**Multi (sequential):**
+```bash
+git reset && git add file1 file2 && git commit -m "type(scope): desc"
+```
+Repeat for each group.
+
+## Tool 4: Push (if requested)
+```bash
+git push && echo "✓ pushed: yes" || echo "✓ pushed: no"
+```
+
+**Only push if user explicitly requested** ("push", "commit and push").

package/template/.claude/skills/git/references/workflow-merge.md

@@ -0,0 +1,48 @@
+# Merge Workflow
+
+Execute via `git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## Step 1: Sync with Remote
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin
+git checkout {TO_BRANCH}
+git pull origin {TO_BRANCH}
+```
+
+## Step 2: Merge from REMOTE
+```bash
+git merge origin/{FROM_BRANCH} --no-ff -m "merge: {FROM_BRANCH} into {TO_BRANCH}"
+```
+
+**Why `origin/{FROM_BRANCH}`:** Ensures merging only committed+pushed changes, not local WIP.
+
+## Step 3: Resolve Conflicts
+If conflicts:
+1. Resolve manually
+2. `git add . && git commit`
+3. If clarifications needed, report to main agent
+
+## Step 4: Push
+```bash
+git push origin {TO_BRANCH}
+```
+
+## Pre-Merge Checklist
+- Fetch latest: `git fetch origin`
+- Ensure FROM_BRANCH pushed to remote
+- Check for conflicts: `git merge --no-commit --no-ff origin/{FROM_BRANCH}` then abort
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Merge conflicts | Resolve manually, then commit |
+| Branch not found | Verify branch name, ensure pushed |
+| Push rejected | `git pull --rebase`, retry |

package/template/.claude/skills/git/references/workflow-pr.md

@@ -0,0 +1,58 @@
+# Pull Request Workflow
+
+Execute via `git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## CRITICAL: Use REMOTE diff
+PRs based on remote branches. Local diff includes unpushed changes.
+
+## Tool 1: Sync + Analyze
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin && \
+git push -u origin HEAD 2>/dev/null || true && \
+BASE=${BASE_BRANCH:-main} && \
+HEAD=$(git rev-parse --abbrev-ref HEAD) && \
+echo "=== PR: $HEAD → $BASE ===" && \
+echo "=== COMMITS ===" && \
+git log origin/$BASE...origin/$HEAD --oneline && \
+echo "=== FILES ===" && \
+git diff origin/$BASE...origin/$HEAD --stat
+```
+
+**If "Branch not on remote":** Push first, retry.
+
+## Tool 2: Generate Content
+**Title:** Conventional commit format, <72 chars, NO version numbers
+**Body:** Summary bullets + Test plan checklist
+
+## Tool 3: Create PR
+```bash
+gh pr create --base $BASE --head $HEAD --title "..." --body "$(cat <<'EOF'
+## Summary
+- Bullet points
+
+## Test plan
+- [ ] Test item
+EOF
+)"
+```
+
+## DO NOT use (local comparison)
+- ❌ `git diff main...HEAD`
+- ❌ `git diff --cached`
+- ❌ `git status`
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Branch not on remote | `git push -u origin HEAD`, retry |
+| Empty diff | Warn: "No changes for PR" |
+| Push rejected | `git pull --rebase`, resolve, push |
+| No upstream | `git push -u origin HEAD` |

package/template/.claude/skills/git/references/workflow-push.md

@@ -0,0 +1,52 @@
+# Push Workflow
+
+Execute via `git-manager` subagent.
+
+## Pre-Push Checklist
+1. All changes committed
+2. Secrets scanned (see `safety-protocols.md`)
+3. Branch pushed to remote
+
+## Tool 1: Verify State
+```bash
+git status && \
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || echo "NO_UPSTREAM"
+```
+
+**If uncommitted changes:** Warn user, suggest commit first.
+**If NO_UPSTREAM:** Use `git push -u origin HEAD`.
+
+## Tool 2: Push
+```bash
+git push origin HEAD
+```
+
+**On success:** Report commit hashes pushed.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `rejected - non-fast-forward` | Remote has newer commits | `git pull --rebase`, resolve conflicts, push again |
+| `no upstream branch` | Branch not tracked | `git push -u origin HEAD` |
+| `Authentication failed` | Invalid credentials | Check `gh auth status` or SSH keys |
+| `Repository not found` | Wrong remote URL | Verify `git remote -v` |
+| `Permission denied` | No write access | Check repository permissions |
+
+## Force Push (DANGER)
+
+**NEVER force push to main/master/production branches.**
+
+If user explicitly requests force push on feature branch:
+```bash
+git push -f origin HEAD
+```
+
+**Warn user:** "Force push rewrites history. Collaborators may lose work."
+
+## Output Format
+```
+✓ pushed: N commits to origin/{branch}
+  - abc123 feat(auth): add login
+  - def456 fix(api): resolve timeout
+```