@telelabsai/ship 1.0.0

package/.claude/agents/git-ops.md

@@ -0,0 +1,41 @@
+---
+name: git-ops
+description: "Use this agent for git operations that produce verbose output (large diffs, long logs, merge conflicts). Keeps git output isolated from main session context. Spawns when committing many files, creating PRs, or resolving conflicts."
+model: sonnet
+tools: Bash, Read, Glob, Grep
+---
+
+You are a git operations specialist. Execute cleanly and report concisely.
+
+Activate `ship-version` skill by reading `.claude/skills/ship-version/SKILL.md` and its references.
+
+## Rules
+- Use conventional commits: type(scope): description
+- If ticket ID provided (--ticket or --jira) → add `Refs: <ID>` as commit footer
+- Never force push to main/master/production
+- Never commit .env, credentials, secrets, API keys
+- Stage specific files, never `git add .`
+- Never amend unless explicitly asked
+- Never skip pre-commit hooks
+- Show diff summary before committing
+- Always confirm destructive operations with user
+
+## Workflow
+1. Run `git status` + `git diff --stat`
+2. Scan for secrets in staged changes
+3. Stage files (ask user or follow instructions)
+4. Build conventional commit message
+5. Commit and verify
+6. Report back concisely
+
+## Output Format
+```
+staged: N files (+X/-Y lines)
+security: passed
+commit: HASH type(scope): description
+ticket: ID (if provided)
+```
+
+**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+**Summary:** [1-2 sentences]
+**Concerns/Blockers:** [if any]

package/.claude/hooks/git-safety.cjs

@@ -0,0 +1,66 @@
+/**
+ * PreToolUse hook — blocks dangerous git operations before they execute.
+ *
+ * Exit 0 = allow the tool call
+ * Exit 2 = block the tool call (stdout = reason shown to Claude)
+ */
+
+const fs = require('fs');
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
+} catch {
+  process.exit(0); // can't parse → allow
+}
+
+const cmd = (input.tool_input && input.tool_input.command) || '';
+
+// --- Block force push ---
+if (/push\s+.*(-f|--force)(?!\S)/.test(cmd) && !cmd.includes('--force-with-lease')) {
+  console.log('BLOCKED: Force push is not allowed. Use --force-with-lease if absolutely necessary.');
+  process.exit(2);
+}
+
+// --- Block push to protected branches without confirmation ---
+const protectedPush = /push\s+.*\b(main|master|production|prod)\b/.test(cmd);
+if (protectedPush && !cmd.includes('--force-with-lease')) {
+  // Allow regular push to main, but block force variants
+  // The rule file handles the "ask user" part for regular pushes
+}
+
+// --- Block staging sensitive files ---
+const sensitivePatterns = [
+  /git\s+add\s+.*\.env(?!\.\w*example)/,
+  /git\s+add\s+.*credentials/,
+  /git\s+add\s+.*\.pem/,
+  /git\s+add\s+.*\.key/,
+  /git\s+add\s+.*secrets?\./,
+];
+
+for (const pattern of sensitivePatterns) {
+  if (pattern.test(cmd)) {
+    console.log('BLOCKED: Cannot stage sensitive files (.env, credentials, keys). Add to .gitignore instead.');
+    process.exit(2);
+  }
+}
+
+// --- Block git add -A / git add . (encourage specific staging) ---
+if (/git\s+add\s+(-A|--all|\.)(\s|$)/.test(cmd)) {
+  console.log('BLOCKED: Use specific file names instead of "git add ." or "git add -A" to avoid staging secrets or unwanted files.');
+  process.exit(2);
+}
+
+// --- Block destructive resets without warning ---
+if (/git\s+reset\s+--hard/.test(cmd)) {
+  console.log('BLOCKED: "git reset --hard" discards all uncommitted changes. Ask the user to confirm first.');
+  process.exit(2);
+}
+
+// --- Block branch deletion of protected branches ---
+if (/git\s+branch\s+.*-[dD]\s+.*(main|master|production|prod)/.test(cmd)) {
+  console.log('BLOCKED: Cannot delete protected branches (main, master, production).');
+  process.exit(2);
+}
+
+process.exit(0);

package/.claude/rules/git-conventions.md

@@ -0,0 +1,17 @@
+# Git Conventions
+
+## Commit Format
+```
+type(scope): description
+
+Refs: TICKET-ID  ← only if provided by user via --ticket or --jira
+```
+
+## Types
+feat | fix | refactor | test | docs | chore | perf | style | ci | build
+
+## Rules
+- Under 72 chars, present tense, imperative, no period
+- No AI attribution in commits
+- Never commit .env or secrets
+- Stage specific files, not `git add .`

package/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/git-safety.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/ship-version/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ship-version
+description: "Git version control with conventional commits and optional ticket tracking (Jira, Trello, ClickUp, Linear, GitHub Issues, etc). Use for committing, pushing, branching, PRs, diffs, and changelogs."
+argument-hint: "<commit|push|pr|branch|diff|changelog> [--ticket ID] [--type feat|fix|refactor|test|docs|chore] [message]"
+---
+
+# ship-version — Git Version Control
+
+## Sub-commands
+
+| Command | Description |
+|---------|-------------|
+| `commit` | Stage and commit with conventional format |
+| `push` | Push current branch to remote |
+| `pr` | Create pull request |
+| `branch` | Create and switch to new branch |
+| `diff` | Show clean change summary |
+| `changelog` | Generate changelog from commits between versions |
+
+## Default (No Arguments)
+
+If invoked without arguments, use `AskUserQuestion` to present available operations.
+
+## Arguments
+
+- `commit [--ticket ID] [--type TYPE] [message]` — Stage + commit
+- `push` — Push to remote
+- `pr [--ticket ID] [title]` — Create PR via `gh`
+- `branch <name>` — Create + switch branch
+- `diff [--staged] [--pr] [ref1..ref2]` — Show changes
+- `changelog [from-tag] [to-tag]` — Generate changelog
+
+## Ticket Integration (optional)
+
+The `--ticket` flag accepts any project management ticket ID. Auto-detected format:
+
+| Tool | Example | Auto-detected pattern |
+|------|---------|----------------------|
+| Jira | `--ticket PROJ-123` | `[A-Z]+-\d+` |
+| Trello | `--ticket #abc123` | Trello short ID |
+| ClickUp | `--ticket CU-abc123` | `CU-` prefix |
+| Linear | `--ticket ENG-123` | `[A-Z]+-\d+` |
+| GitHub Issues | `--ticket #42` | `#\d+` |
+| Shortcut | `--ticket sc-12345` | `sc-` prefix |
+| Asana | `--ticket 1234567890` | Numeric ID |
+| Custom | `--ticket ANYTHING` | Any string |
+
+Multiple tickets supported: `--ticket PROJ-42 --ticket #15`
+
+Legacy alias: `--jira` works as shorthand for `--ticket`
+
+## Quick Reference
+
+| Task | Reference |
+|------|-----------|
+| Commit workflow | `references/workflow-commit.md` |
+| Push workflow | `references/workflow-push.md` |
+| PR workflow | `references/workflow-pr.md` |
+| Diff workflow | `references/workflow-diff.md` |
+| Changelog workflow | `references/workflow-changelog.md` |
+| Commit format | `references/commit-standards.md` |
+| Safety | `references/safety-protocols.md` |
+
+## Commit Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional: Refs: TICKET-ID]
+```
+
+## Core Workflow
+
+### Step 1: Analyze
+```bash
+git status && git diff --stat
+```
+
+### Step 2: Security Scan
+```bash
+git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)"
+```
+If secrets found → STOP, warn user, suggest `.gitignore`.
+
+### Step 3: Stage
+- Ask user what to stage (never `git add .` blindly)
+- Stage specific files by name
+
+### Step 4: Build Commit Message
+1. Auto-detect type from diff (unless `--type` provided)
+2. Auto-detect scope from file paths
+3. Use user message if provided, else generate from diff
+4. If `--ticket` (or `--jira`) → append `Refs: <TICKET-ID>` as footer
+5. Show full message to user for confirmation
+
+### Step 5: Commit
+```bash
+git commit -m "type(scope): description"
+```
+
+## Output Format
+```
+staged: N files (+X/-Y lines)
+security: passed
+commit: HASH type(scope): description
+ticket: PROJ-123 (if provided)
+```
+
+## 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 |

package/.claude/skills/ship-version/references/commit-standards.md

@@ -0,0 +1,97 @@
+# Commit Standards
+
+## Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional: Refs: TICKET-ID]
+```
+
+## Types (priority order)
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Restructure without behavior change |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `chore` | Maintenance, deps, config |
+| `perf` | Performance improvement |
+| `style` | Formatting, no logic change |
+| `ci` | CI/CD pipeline changes |
+| `build` | Build system changes |
+
+## Rules
+
+- Under 72 characters for subject line
+- Present tense, imperative mood ("add" not "added")
+- No period at end
+- Scope is optional but recommended
+- Focus on WHAT changed, not HOW
+- No AI attribution (no "Generated with Claude", no "Co-Authored-By: Claude")
+
+## Ticket Integration (optional)
+
+When `--ticket` flag is provided, append footer with the ticket ID.
+Accepts any format: Jira (`PROJ-42`), Trello (`#abc`), ClickUp (`CU-abc`), Linear (`ENG-123`), GitHub Issues (`#42`), Shortcut (`sc-123`), Asana (numeric), or any custom string.
+
+Legacy alias: `--jira` works as shorthand for `--ticket`.
+
+```
+feat(auth): add login validation
+
+Implement email format check and password strength meter.
+
+Refs: PROJ-42
+```
+
+Multiple tickets supported:
+
+```
+Refs: PROJ-42, #15, CU-abc123
+```
+
+## Auto-detect Type from Diff
+
+| Signal | Type |
+|--------|------|
+| New files, new exports | `feat` |
+| Changed conditionals, error paths | `fix` |
+| Moved/renamed, same behavior | `refactor` |
+| `*.test.*`, `*.spec.*` files only | `test` |
+| `*.md`, comments only | `docs` |
+| `package.json`, config files only | `chore` |
+
+## Auto-detect Scope from Paths
+
+| Path pattern | Scope |
+|-------------|-------|
+| `src/api/*`, `src/routes/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/db/*`, `src/models/*` | `db` |
+| `src/auth/*` | `auth` |
+| `src/utils/*`, `src/lib/*` | `utils` |
+| Multiple directories | Omit scope |
+
+## Good Examples
+
+```
+feat(auth): add login validation
+fix(api): resolve query timeout on large datasets
+refactor(utils): simplify date parsing logic
+test(auth): add coverage for expired token edge case
+chore: update dependencies to latest patch versions
+```
+
+## Bad Examples
+
+```
+Updated files                          (not descriptive)
+feat(auth): added login using bcrypt   (past tense, describes HOW)
+Fix bug                                (not specific)
+WIP                                    (not a commit message)
+```

package/.claude/skills/ship-version/references/safety-protocols.md

@@ -0,0 +1,41 @@
+# Safety Protocols
+
+## Secret Detection
+
+### Scan Command
+```bash
+git diff --cached | grep -iE "(AKIA|api[_-]?key|token|password|secret|credential|private[_-]?key|mongodb://|postgres://|mysql://|redis://|-----BEGIN)"
+```
+
+### Patterns
+
+| Category | Pattern |
+|----------|---------|
+| API Keys | `api[_-]?key`, `apiKey` |
+| AWS | `AKIA[0-9A-Z]{16}` |
+| Tokens | `token`, `auth_token`, `jwt` |
+| Passwords | `password`, `passwd`, `pwd` |
+| Private Keys | `-----BEGIN PRIVATE KEY-----` |
+| DB URLs | `mongodb://`, `postgres://`, `mysql://` |
+| OAuth | `client_secret`, `oauth_token` |
+
+### Dangerous Files
+- `.env`, `.env.*` (except `.env.example`)
+- `*.key`, `*.pem`, `*.p12`
+- `credentials.json`, `secrets.json`
+
+### On Detection
+1. BLOCK commit
+2. Show matching lines
+3. Suggest `.gitignore` or env variables
+4. Offer to unstage: `git reset HEAD <file>`
+
+## Branch Protection
+
+### Never Force Push To
+- `main`, `master`, `production`, `prod`, `release/*`
+
+### Never Without Confirmation
+- Push to `main`/`master`
+- Delete remote branches
+- Rebase published branches

package/.claude/skills/ship-version/references/workflow-changelog.md

@@ -0,0 +1,95 @@
+# Changelog Workflow
+
+## Modes
+
+### Auto-detect latest versions
+If no tags provided:
+```bash
+git tag --sort=-v:refname | head -5
+```
+Pick the two most recent tags. If only one tag → changelog from that tag to HEAD.
+If no tags → changelog from first commit to HEAD.
+
+### Specific range
+```
+/lab:version changelog v1.0.0 v2.0.0
+/lab:version changelog v1.0.0              # from v1.0.0 to HEAD
+```
+
+## Steps
+
+### 1. Get Commits
+```bash
+git log <from>..<to> --pretty=format:"%h %s" --no-merges
+```
+
+### 2. Group by Type
+
+Parse conventional commit prefixes and group:
+
+```markdown
+## [v2.0.0] - 2026-03-30
+
+### Features
+- add user authentication (#42) — abc1234
+- add dashboard widgets — def5678
+
+### Bug Fixes
+- resolve login timeout on slow networks — 123abcd
+- fix null check in payment flow — 456efgh
+
+### Refactoring
+- simplify date utility functions — 789ijkl
+
+### Tests
+- add coverage for auth edge cases — mno3456
+
+### Other
+- update dependencies — pqr7890
+```
+
+### 3. Type Mapping
+
+| Prefix | Section |
+|--------|---------|
+| `feat` | Features |
+| `fix` | Bug Fixes |
+| `refactor` | Refactoring |
+| `perf` | Performance |
+| `test` | Tests |
+| `docs` | Documentation |
+| `chore`, `build`, `ci`, `style` | Other |
+
+### 4. Enrich (optional)
+
+If `Refs:` found in commit footers, append ticket IDs (any tool — Jira, Trello, ClickUp, etc.):
+```
+- add user authentication (PROJ-42) — abc1234
+- fix payment timeout (#15, CU-xyz) — def5678
+```
+
+### 5. Stats Summary
+
+Append at bottom:
+```
+### Stats
+- Commits: N
+- Contributors: N
+- Files changed: N
+- Lines: +X / -Y
+```
+
+## Output
+
+Print changelog to terminal. If user wants to save:
+```bash
+# Prepend to existing CHANGELOG.md or create new
+```
+
+## Full Changelog (no tags)
+
+If user just runs `/lab:version changelog` with no tags and no existing tags:
+```bash
+git log --pretty=format:"%h %s" --no-merges
+```
+Group all commits as `## [Unreleased]`.

package/.claude/skills/ship-version/references/workflow-commit.md

@@ -0,0 +1,77 @@
+# Commit Workflow
+
+## Step-by-step
+
+### 1. Check State
+```bash
+git status
+git diff --stat
+```
+If nothing to commit → tell user and stop.
+
+### 2. Security Scan
+```bash
+git diff --cached | grep -iE "(AKIA|api[_-]?key|token|password|secret|credential|private[_-]?key|mongodb://|postgres://|mysql://|redis://|-----BEGIN)"
+```
+
+Files to always warn about:
+- `.env`, `.env.*` (except `.env.example`)
+- `*.key`, `*.pem`, `*.p12`
+- `credentials.json`, `secrets.json`
+
+If detected → BLOCK, show matches, suggest `.gitignore`.
+
+### 3. Stage Files
+- Show user the list of changed files
+- Ask what to stage (or accept their instruction)
+- Stage specific files: `git add <file1> <file2>`
+- NEVER use `git add .` or `git add -A`
+
+### 4. Determine Commit Type
+Priority: user `--type` flag > auto-detection from diff
+
+Auto-detection logic:
+1. Read `git diff --cached --name-only`
+2. Read `git diff --cached` for content changes
+3. Match against type rules in commit-standards.md
+
+### 5. Determine Scope
+1. Extract directories from changed files
+2. If all in one area → use as scope
+3. If multiple areas → omit scope
+
+### 6. Build Message
+- If user provided message → use as description
+- If `--jira` provided → add `Refs: <ID>` footer
+- Show full message to user for confirmation
+
+### 7. Commit
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+Optional body.
+
+Refs: JIRA-ID
+EOF
+)"
+```
+
+### 8. Verify
+```bash
+git log --oneline -1
+git status
+```
+
+## Split Decision
+
+**Split into multiple commits if:**
+- Different types mixed (feat + fix)
+- Multiple unrelated scopes
+- Config/deps + code mixed
+- More than 10 unrelated files
+
+**Single commit if:**
+- Same type and scope
+- 3 or fewer files
+- Under 50 lines changed

package/.claude/skills/ship-version/references/workflow-diff.md

@@ -0,0 +1,74 @@
+# Diff Workflow
+
+## Modes
+
+### Default — Working changes
+Show unstaged + staged changes:
+```bash
+git diff --stat
+git diff --cached --stat
+```
+
+### `--staged` — Staged only
+```bash
+git diff --cached --stat
+git diff --cached
+```
+
+### `--pr` — What a PR would contain
+```bash
+git log main..HEAD --oneline
+git diff main..HEAD --stat
+git diff main..HEAD
+```
+
+### `ref1..ref2` — Compare between refs (branches, tags, commits)
+```bash
+git diff <ref1>..<ref2> --stat
+git diff <ref1>..<ref2>
+```
+
+Examples:
+```
+/lab:version diff v1.0.0..v2.0.0          # between tags
+/lab:version diff main..feature/auth       # between branches
+/lab:version diff abc123..def456           # between commits
+```
+
+## Output Format
+
+Present a clean summary:
+
+```
+## Changes: <context>
+
+### Stats
+- Files changed: N
+- Insertions: +X
+- Deletions: -Y
+
+### Files
+| File | Status | Changes |
+|------|--------|---------|
+| src/auth.ts | Modified | +42 -12 |
+| src/db.ts | New | +85 |
+
+### Key Changes
+- [1-3 bullet summary of what changed and why, from reading the diff]
+```
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| (none) | Working tree changes (unstaged + staged) |
+| `--staged` | Staged changes only |
+| `--pr` | Diff against main (PR preview) |
+| `ref1..ref2` | Compare any two refs |
+
+## Large Diffs
+
+If diff exceeds 200 lines:
+1. Show `--stat` summary first
+2. Ask user if they want full diff or specific files
+3. Use `git diff -- <file>` for targeted output

package/.claude/skills/ship-version/references/workflow-pr.md

@@ -0,0 +1,46 @@
+# Pull Request Workflow
+
+## Steps
+
+### 1. Analyze Changes
+```bash
+git log main..HEAD --oneline
+git diff main..HEAD --stat
+```
+
+### 2. Push Branch
+If not pushed:
+```bash
+git push -u origin <branch>
+```
+
+### 3. Build PR
+
+Title: short, under 70 chars
+Body structure:
+
+```markdown
+## Summary
+- [bullet points from commit messages]
+
+## Tickets
+- [Ticket IDs if provided via --ticket or --jira]
+
+## Test Plan
+- [ ] Unit tests pass
+- [ ] Manual verification of [feature]
+```
+
+### 4. Create PR
+```bash
+gh pr create --title "the title" --body "$(cat <<'EOF'
+## Summary
+- bullet points
+
+## Test Plan
+- [ ] tests pass
+EOF
+)"
+```
+
+### 5. Return PR URL