orbital-command 0.1.0

package/templates/skills/git-dev/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: git-dev
+description: Merges feature branch into dev with direct merge (no PR). Use when feature work is committed and ready to integrate into the dev branch.
+user-invocable: true
+---
+
+# /git-dev — Merge Feature Branch into Dev
+
+Direct merge from feature branch into dev. The review gate already provides the quality gate, so no PR is needed for this step.
+
+## Prerequisites
+
+- On a feature branch (not main/staging/dev)
+- All changes committed (clean working tree)
+- Feature branch has scope work committed via `/git-commit`
+
+## Workflow
+
+### Step 0: Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh`
+2. For each scope in `scopes/completed/`:
+   - Append session UUID to `sessions.prDev` in frontmatter
+
+### Step 1: Verify Ready State
+
+```bash
+# Check you're on a feature branch
+BRANCH=$(git branch --show-current)
+
+# Block if on main/staging/dev
+if [[ "$BRANCH" == "main" || "$BRANCH" == "staging" || "$BRANCH" == "dev" ]]; then
+  echo "Must be on a feature branch, not $BRANCH"
+  exit 1
+fi
+
+# Check for uncommitted changes
+git status --porcelain
+```
+
+### Step 2: Scope Transition (local only)
+
+Find scopes in `scopes/completed/`:
+1. For each scope file in `scopes/completed/*.md`:
+   - `mv scopes/completed/{file} scopes/dev/`
+   - Update frontmatter: `status: dev`
+   - Update DASHBOARD: `🔀 **Status**: Merged to Dev`
+
+If BATCH_SCOPE_IDS is set, only transition those specific scopes.
+
+### Step 3: Merge into Dev
+
+```bash
+# Save current branch name
+FEATURE_BRANCH=$(git branch --show-current)
+
+# Fetch latest dev
+git fetch origin dev
+
+# Checkout dev and merge
+git checkout dev
+git merge "$FEATURE_BRANCH"
+git push origin dev
+
+# Return to feature branch
+git checkout "$FEATURE_BRANCH"
+```
+
+If merge conflicts occur, resolve them before continuing.
+
+### Step 4: Signal Completion
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_dev"}' --scope "{NNN}"
+```
+
+## Output
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  Merged feature branch into dev                              ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Branch: feat/my-feature → dev                               ║
+║  Scopes transitioned: 093, 094 → dev                         ║
+║                                                              ║
+║  Next: /git-staging to create a PR from dev to staging       ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+## Batch Support
+
+When dispatched by the batch orchestrator with `BATCH_SCOPE_IDS`:
+- Only transition the specified scope IDs
+- The batch orchestrator tracks completion via `onScopeStatusChanged`
+
+## Related
+
+- `/git-commit` — Commit work to feature branch (previous step)
+- `/git-staging` — Create PR from dev to staging (next step)

package/templates/skills/git-hotfix/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: git-hotfix
+description: Applies emergency fixes by branching from main with expedited workflow. Use only for critical production issues, genuine emergencies, or urgent security fixes.
+user-invocable: true
+---
+
+# /git-hotfix
+
+Emergency workflow for critical production fixes.
+
+---
+
+## When to Use Hotfix
+
+**Only for production emergencies:**
+
+- [ ] Users affected right now
+- [ ] Money/funds at risk
+- [ ] Security vulnerability active
+- [ ] Core functionality broken
+
+**NOT for:**
+- Performance improvements
+- Minor bugs
+- Features that were missed
+- "Nice to have" fixes
+
+---
+
+## Hotfix Rules
+
+1. **Branch from main** (not staging)
+2. **Minimal fix only** - no refactoring, no "while I'm here"
+3. **Direct PR to main** - bypasses staging for speed
+4. **Backport to staging** - sync after production is fixed
+
+---
+
+## Execution
+
+### Step 0: Detect Branching Mode
+
+```bash
+BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manifest.sh 2>/dev/null | cut -d'"' -f2)
+[ -z "$BRANCHING_MODE" ] && BRANCHING_MODE="trunk"
+```
+
+### Step 1: Create Hotfix Branch
+
+```bash
+# Start from main (production code)
+git checkout main
+git pull origin main
+
+# Create hotfix branch
+git checkout -b hotfix/brief-description
+
+# Example: hotfix/api-auth-race-condition
+```
+
+### Step 2: Implement Minimal Fix
+
+**Rules:**
+- Fix ONLY the broken thing
+- No cleanup, no refactoring
+- No "improvements" while you're there
+- Keep the diff as small as possible
+
+```bash
+# Make your fix
+# ...edit files...
+
+# Verify quality gates — run configured commands from orbital.config.json
+# Run commands.typeCheck, commands.lint, commands.test (skip any that are null)
+```
+
+### Step 3: Create PR to Main
+
+```bash
+# Push hotfix branch
+git push -u origin hotfix/brief-description
+
+# Create PR directly to main
+gh pr create --base main \
+  --title "hotfix: brief description of fix" \
+  --body "## Emergency Hotfix
+
+**Issue:** [Brief description of production issue]
+
+**Root Cause:** [What caused it]
+
+**Fix:** [What this PR does]
+
+## Verification
+
+- [ ] Fix verified locally
+- [ ] Quality gates pass
+- [ ] Minimal changes only
+
+## Post-Merge
+
+- [ ] Monitor production logs
+- [ ] Backport to staging
+- [ ] Document in lessons-learned.md"
+```
+
+### Step 4: Fast-Track Review and Merge
+
+```bash
+# Check CI
+gh pr checks
+
+# If CI passes and fix is verified, merge
+# Use MERGE commit (not squash) for main
+gh pr merge --merge
+```
+
+### Step 5: Verify Production
+
+```bash
+# Wait 3 min for deploy
+
+# Health check (read healthChecks.production from orbital.config.json, skip if not configured)
+# curl -s <healthChecks.production URL> | jq
+
+# Watch logs using your deployment platform's CLI
+```
+
+### Step 6: Backport to Staging (Gitflow Only)
+
+**Skip this step if `BRANCHING_MODE=trunk`** (no staging branch in trunk mode).
+
+**Critical:** Staging must stay in sync with main.
+
+```bash
+# Get the merge commit SHA from main
+git checkout main
+git pull origin main
+HOTFIX_SHA=$(git rev-parse HEAD)
+
+# Switch to staging
+git checkout staging
+git pull origin staging
+
+# Cherry-pick the hotfix
+git cherry-pick $HOTFIX_SHA
+
+# Push to staging
+git push origin staging
+```
+
+If cherry-pick has conflicts:
+```bash
+# Resolve conflicts
+git add .
+git cherry-pick --continue
+
+# Or if too messy, create a regular PR
+git cherry-pick --abort
+git checkout -b backport/hotfix-description
+# ... apply fix manually ...
+gh pr create --base staging
+```
+
+---
+
+## Hotfix Checklist
+
+```
+Pre-Merge:
+[ ] Hotfix branches from main (not staging)
+[ ] Fix is minimal - no extras
+[ ] Quality gates pass
+[ ] CI checks pass
+
+Post-Merge:
+[ ] Production health verified
+[ ] Issue confirmed resolved
+[ ] Backported to staging
+[ ] Documented in lessons-learned.md
+[ ] Team notified
+```
+
+---
+
+## Post-Mortem
+
+After the emergency is handled:
+
+1. **Document what happened** in `.claude/lessons-learned.md`
+2. **Identify root cause** - why wasn't this caught on staging?
+3. **Create follow-up ticket** - proper fix if hotfix was a band-aid
+4. **Update monitoring** - add alerting for this scenario
+
+Template for lessons-learned.md:
+```markdown
+## [Date] Hotfix: [Title]
+
+**Issue:** What broke
+**Impact:** Who was affected, for how long
+**Root Cause:** Why it happened
+**Fix:** What we did
+**Prevention:** How to prevent similar issues
+```
+
+---
+
+## Common Hotfix Scenarios
+
+| Scenario | Approach |
+|----------|----------|
+| API returning 500s | Add error handling, return graceful error |
+| Database query timeout | Add index, simplify query |
+| Rate limit too aggressive | Increase limit temporarily |
+| Environment variable wrong | Fix in deployment platform dashboard (no deploy needed) |
+| Critical business logic bug | Minimal targeted fix, revert if necessary |
+
+---
+
+## Related
+
+- `/git-production` — Production release PR
+- `/git-staging` — Staging PR workflow

package/templates/skills/git-main/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: git-main
+description: Push or PR scope work to the main branch. Mode-aware - detects trunk vs worktree branching from workflow manifest.
+user-invocable: true
+---
+
+# /git-main — Push/PR to Main
+
+Push or create a PR to merge scope work into the main branch.
+
+## Workflow
+
+### Step 0: Detect Branching Mode
+
+```bash
+BRANCHING_MODE=$(grep '^WORKFLOW_BRANCHING_MODE=' .claude/config/workflow-manifest.sh 2>/dev/null | cut -d'"' -f2)
+[ -z "$BRANCHING_MODE" ] && BRANCHING_MODE="trunk"
+```
+
+### Step 1: Record Session ID
+
+1. Run: `bash .claude/hooks/get-session-id.sh` — capture the UUID output
+2. For each scope in `scopes/completed/`:
+   - Append session UUID to `sessions.pushToMain` in frontmatter
+
+### Step 2: Check Current Branch
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+```
+
+### Step 3: Execute (Mode-Dependent)
+
+#### Trunk Mode (`BRANCHING_MODE=trunk`)
+
+**If on `main`:**
+```bash
+git push origin main
+```
+
+**If on a feature branch:**
+- Ask the user: "You're on branch `$CURRENT_BRANCH`. Create a PR to main, or merge directly?"
+  - **PR**: `gh pr create --base main --title "scope(NNN): title" --body "..."`
+  - **Direct merge**: `git checkout main && git merge $CURRENT_BRANCH && git push origin main`
+
+#### Worktree Mode (`BRANCHING_MODE=worktree`)
+
+Always on a feature branch in worktree mode:
+```bash
+gh pr create --base main \
+  --title "scope(NNN): title" \
+  --body "## Summary
+Merges scope NNN work into main.
+
+## Scopes
+- NNN: title"
+```
+
+### Step 4: Scope Transition
+
+For each completed scope being pushed:
+```bash
+bash .claude/hooks/scope-transition.sh --from completed --to main --scope NNN
+```
+
+### Step 5: Signal Completion
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_main"}' --scope "NNN"
+```
+
+## Batch Support
+
+When `BATCH_SCOPE_IDS` and `MERGE_MODE` env vars are set:
+
+```bash
+MERGE_MODE=${MERGE_MODE:-push}  # push, pr, or direct
+```
+
+- **push**: `git push origin main`
+- **pr**: `gh pr create --base main`
+- **direct**: `git checkout main && git merge ... && git push origin main`
+
+Transition all scopes in `BATCH_SCOPE_IDS` (comma-separated).

package/templates/skills/git-production/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: git-production
+description: Creates release pull requests from staging to main for production deployment. Use when staging is validated, ready for production release, or creating release PRs.
+user-invocable: true
+---
+
+# /git-production
+
+Workflow for creating a release PR from staging to main.
+
+---
+
+## Prerequisites
+
+**Critical:** This creates a production release. Verify:
+
+- [ ] Changes have been on staging for at least 1 hour
+- [ ] Staging has been manually verified
+- [ ] No critical issues reported on staging
+- [ ] Appropriate deployment window (avoid peak hours)
+- [ ] Rollback plan identified
+
+---
+
+## Execution
+
+### Step 1: Verify Staging Health
+
+> **Automated:** The `scope-lifecycle-gate.sh` hook records the session UUID
+> and transitions staging scopes to production when BATCH_SCOPE_IDS is set.
+
+```bash
+# Check staging is healthy (read healthChecks.staging from orbital.config.json, skip if not configured)
+# curl -s <healthChecks.staging URL> | jq
+
+# See what will be released
+git fetch origin
+git log origin/main..origin/staging --oneline
+```
+
+**Review these commits carefully.** Understand what's being released.
+
+### Step 2: Scope Status Transition
+
+> **Automated:** The `scope-lifecycle-gate.sh` hook transitions staging scopes to production when BATCH_SCOPE_IDS is set.
+
+### Step 3: Create Release PR
+
+```bash
+# Create the release PR
+gh pr create \
+  --base main \
+  --head staging \
+  --title "release: $(date +%Y-%m-%d) deployment" \
+  --body "## Release Contents
+
+$(git log origin/main..origin/staging --oneline)
+
+## Pre-Release Checklist
+
+- [ ] Staging stable for 1+ hours
+- [ ] Manual verification completed
+- [ ] No critical issues on staging
+- [ ] Rollback plan identified
+
+## Post-Release Verification
+
+- [ ] Health check passes
+- [ ] Version endpoint shows correct commit
+- [ ] No error spikes in logs
+- [ ] Key functionality verified
+
+## Rollback
+
+If issues occur, follow your project's rollback procedure."
+```
+
+### Step 4: Review and Approve
+
+```bash
+# View the PR
+gh pr view --web
+
+# Check CI status
+gh pr checks
+```
+
+**MANUAL STEP:** Get team review/approval if required.
+
+### Step 5: Merge (Triggers Deploy)
+
+```bash
+# Use MERGE commit for production releases (preserves history)
+gh pr merge --merge
+
+# Your CI/CD pipeline auto-deploys main to production (if configured)
+```
+
+### Step 6: Signal Completion
+
+After the merge succeeds, emit the agent completion event if working on a dispatched scope:
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_production"}' --scope "{NNN}"
+```
+
+### Step 7: Verify Production
+
+Wait for deployment to complete (timing depends on your CI/CD pipeline), then:
+
+```bash
+# Health check (read healthChecks.production from orbital.config.json, skip if not configured)
+# curl -s <healthChecks.production URL> | jq
+
+# Version check (read healthChecks.version from orbital.config.json, skip if not configured)
+# curl -s <healthChecks.version URL> | jq
+
+# Watch logs using your deployment platform's CLI
+```
+
+---
+
+## Production Release Checklist
+
+After merge:
+
+- [ ] Health check returns 200 (if configured)
+- [ ] Version matches expected commit (if configured)
+- [ ] No new errors in logs (watch 5 min)
+- [ ] Database migrations completed (if any)
+- [ ] Key functionality verified
+- [ ] Team notified of successful deployment
+
+---
+
+## If Something Goes Wrong
+
+Follow your project's rollback procedure. Common approaches:
+```bash
+# Via your deployment platform's dashboard (fastest)
+# Go to Deployments → Previous deployment → Redeploy
+
+# Or via git revert
+git revert HEAD
+git push origin main
+```
+
+---
+
+## Important Differences: Staging vs Production
+
+| Aspect | Staging PR | Production PR |
+|--------|-----------|---------------|
+| Merge strategy | Squash | Merge (preserves history) |
+| Source | Feature branch | staging branch |
+| Target | staging | main |
+| Review required | Optional | Recommended |
+| Wait after deploy | 3 min | 5+ min monitoring |
+
+---
+
+## Related
+
+- `/git-staging` — Create PR from dev to staging (previous step)
+- `/git-hotfix` — Emergency fix workflow

package/templates/skills/git-staging/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: git-staging
+description: Creates GitHub PR from dev to staging for release visibility and CI gate. Use when dev branch work is ready for staging review.
+user-invocable: true
+---
+
+# /git-staging — GitHub PR from Dev to Staging
+
+Creates a GitHub PR from dev to staging. Staging is a release candidate — the PR provides an audit trail, CI gate, and selective promotion visibility.
+
+## Prerequisites
+
+- Changes merged into dev (via `/git-dev`)
+- Dev branch is up to date with remote
+- No merge conflicts with staging
+
+## Workflow
+
+### Step 1: Scope Transition (local only)
+
+Find scopes in `scopes/dev/`:
+1. For each scope file in `scopes/dev/*.md`:
+   - `mv scopes/dev/{file} scopes/staging/`
+   - Update frontmatter: `status: staging`
+   - Update DASHBOARD: `🚀 **Status**: Staging PR Created`
+
+If BATCH_SCOPE_IDS is set, only transition those specific scopes.
+
+### Step 2: Ensure Remote is Up to Date
+
+```bash
+git push origin dev
+```
+
+### Step 3: Create GitHub PR
+
+```bash
+gh pr create --base staging --head dev \
+  --title "release: <summary of scopes>" \
+  --body "## Summary
+
+- Scope NNN: <title>
+- Scope NNN: <title>
+
+## Changes
+
+<bullet list of key changes>
+
+## Testing
+
+- [ ] Quality gates pass on dev
+- [ ] No regressions in staging tests
+- [ ] Deployment verified healthy
+
+## Checklist
+
+- [ ] No console.log statements
+- [ ] No any types added
+- [ ] Files under 400 lines"
+```
+
+### Step 4: Signal Completion
+
+```bash
+bash .claude/hooks/orbital-emit.sh AGENT_COMPLETED '{"outcome":"success","action":"pr_staging"}' --scope "{NNN}"
+```
+
+### Step 5: Monitor CI
+
+```bash
+gh pr checks
+gh pr view --web
+```
+
+## Output
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  PR created: dev → staging                                   ║
+╠═══════════════════════════════════════════════════════════════╣
+║  PR: #NNN — release: <summary>                               ║
+║  Scopes transitioned: 093, 094 → staging                     ║
+║                                                              ║
+║  Next: Review PR, merge, then /git-production                ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+## If PR Checks Fail
+
+```bash
+# See what failed
+gh pr checks
+
+# Fix locally on dev, push
+git checkout dev
+# ... make fixes ...
+git add <files>
+git commit -m "fix: address CI feedback"
+git push origin dev
+# PR updates automatically
+```
+
+## Batch Support
+
+When dispatched by the batch orchestrator with `BATCH_SCOPE_IDS`:
+- Only transition the specified scope IDs
+- The batch orchestrator tracks completion via `onScopeStatusChanged`
+
+## Related
+
+- `/git-dev` — Merge feature→dev (previous step)
+- `/git-production` — Release PR staging→main (next step)