@telelabsai/ship 1.0.0

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

@@ -0,0 +1,35 @@
+# Push Workflow
+
+## Steps
+
+### 1. Pre-check
+```bash
+git status
+git branch --show-current
+```
+Warn if uncommitted changes exist.
+
+### 2. Check Remote Tracking
+```bash
+git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null
+```
+- If tracking exists → `git push`
+- If no tracking → `git push -u origin <branch>`
+
+### 3. Handle Errors
+
+| Error | Action |
+|-------|--------|
+| Rejected (non-fast-forward) | Suggest `git pull --rebase` then push |
+| Permission denied | Tell user to check remote access |
+| Remote not found | Suggest `git remote add origin <url>` |
+
+### 4. Confirm
+```bash
+git log --oneline origin/<branch>..HEAD
+```
+Show what was pushed.
+
+## Safety
+- Never force push (`--force` or `-f`)
+- Never push to `main`/`master`/`production` without user confirmation

package/CLAUDE.md

@@ -0,0 +1,17 @@
+# CLAUDE.md
+
+## Project
+Ship — AI-powered development toolkit by TeleLabs AI.
+
+## Commands
+- Lint: `npm run lint`
+- Test: `npm test`
+- Build: `npm run build`
+
+## Skills
+- `/ship-version` — Git version control (commit, push, pr, branch, diff, changelog)
+
+## Rules
+- Use conventional commits with optional ticket ID (--ticket for Jira, Trello, ClickUp, etc.)
+- Never commit secrets or .env files
+- Run lint before committing

package/README.md

@@ -0,0 +1,239 @@
+# Ship
+
+[![npm version](https://img.shields.io/npm/v/@telelabsai/ship.svg)](https://www.npmjs.com/package/@telelabsai/ship)
+[![license](https://img.shields.io/npm/l/@telelabsai/ship.svg)](https://github.com/telelabs-ai/ship/blob/main/LICENSE)
+
+**Ship helps you go from code to production.** AI-powered agents, skills, and guardrails that plug into Claude Code — so you spend less time on process and more time building.
+
+```
+idea → plan → code → test → review → commit → push → PR → deploy
+                    Ship handles this ──────────────────────────→
+```
+
+## Installation
+
+```bash
+npm install -g @telelabsai/ship
+```
+
+## Quick Start
+
+```bash
+# Add Ship to any project
+ship init
+
+# Or start fresh
+ship new my-app
+
+# Use from terminal (delegates to Claude Code)
+ship version commit --ticket PROJ-42 "add auth"
+
+# Or inside Claude Code directly
+claude
+/ship-version commit --ticket PROJ-42 "add auth"
+```
+
+Both paths use the same skill. One source of truth.
+
+## CLI
+
+```bash
+# Project setup
+ship init                       Add Ship to current directory
+ship init --dir ./my-app        Add Ship to specific directory
+ship new <name>                 Create new project with Ship config
+ship update                     Update .claude/ to latest version
+ship update --force             Update without asking
+
+# Skills (routes to Claude Code)
+ship version commit             Conventional commits with ticket tracking
+ship version diff --pr          Preview what a PR would contain
+ship version push               Push to remote safely
+ship version pr                 Create pull request
+ship version changelog          Auto-generate changelog
+ship version branch <name>      Create and switch branch
+ship plan "add auth"            Plan implementation (coming soon)
+ship test                       Run tests (coming soon)
+ship review                     Code review (coming soon)
+ship deploy staging             Deploy (coming soon)
+```
+
+Any `ship <skill>` command translates to `claude -p "/ship-<skill>"`. When new skills are added, they work from the terminal immediately — no CLI update needed.
+
+## How It Works
+
+Ship adds a `.claude/` directory to your project with four layers:
+
+| Layer | What it does | When it loads |
+|-------|-------------|---------------|
+| **Skills** | Step-by-step workflows you invoke | On demand (`/ship-version commit`) |
+| **Agents** | Isolated AI subprocesses for heavy tasks | When needed (large diffs, PRs) |
+| **Rules** | Conventions Claude always follows | Every message |
+| **Hooks** | Code-level guardrails | Automatically (blocks secrets, force push) |
+
+```
+.claude/
+├── skills/          Slash-command workflows
+├── agents/          Subagent definitions
+├── rules/           Always-loaded instructions
+├── hooks/           Lifecycle automation
+└── settings.json    Configuration
+```
+
+## Skills
+
+### ship-version — Git Version Control
+
+Conventional commits, ticket tracking, security scanning, changelogs.
+
+```bash
+# Commit
+ship version commit                              # auto-detect type + scope
+ship version commit "add login page"             # custom message
+ship version commit --type fix "null check"      # explicit type
+ship version commit --ticket PROJ-42 "user auth" # with ticket ref
+
+# Diff
+ship version diff                                # working tree changes
+ship version diff --staged                       # staged only
+ship version diff --pr                           # preview PR diff
+ship version diff v1.0.0..v2.0.0                # between tags
+
+# Changelog
+ship version changelog                           # auto-detect from tags
+ship version changelog v1.0.0 v2.0.0            # specific range
+
+# Push / PR / Branch
+ship version push                                # push current branch
+ship version pr --ticket PROJ-42 "Add auth"     # create PR with ticket
+ship version branch feature/user-auth            # create + switch
+```
+
+### Ticket Tracking
+
+Works with any project management tool:
+
+| Tool | Example |
+|------|---------|
+| Jira | `--ticket PROJ-123` |
+| ClickUp | `--ticket CU-abc123` |
+| Linear | `--ticket ENG-123` |
+| GitHub Issues | `--ticket #42` |
+| Trello | `--ticket #abc123` |
+| Shortcut | `--ticket sc-12345` |
+| Asana | `--ticket 1234567890` |
+| Custom | `--ticket ANYTHING` |
+
+Multiple tickets: `--ticket PROJ-42 --ticket #15`
+
+### Commit Format
+
+```
+type(scope): description
+
+[optional body]
+
+Refs: TICKET-ID
+```
+
+Types: `feat` | `fix` | `refactor` | `test` | `docs` | `chore` | `perf` | `style` | `ci` | `build`
+
+## Safety
+
+Ship includes automatic guardrails that can't be bypassed:
+
+| Guardrail | What it prevents |
+|-----------|-----------------|
+| Secret detection | Blocks committing `.env`, API keys, credentials |
+| Force push block | Prevents `git push --force` to any branch |
+| Blind staging block | Prevents `git add .` / `git add -A` |
+| Hard reset block | Prevents `git reset --hard` without confirmation |
+| Branch protection | Prevents deleting main/master/production |
+
+## Extending Ship
+
+### Add a skill
+
+```bash
+mkdir -p .claude/skills/ship-deploy
+```
+
+```yaml
+# .claude/skills/ship-deploy/SKILL.md
+---
+name: ship-deploy
+description: "Deploy to staging or production."
+argument-hint: "<staging|production>"
+---
+
+# Instructions here...
+```
+
+Now `ship deploy staging` works — both from terminal and inside Claude Code.
+
+### Add an agent
+
+```yaml
+# .claude/agents/my-agent.md
+---
+name: my-agent
+description: "When to use this agent."
+model: sonnet
+tools: Bash, Read, Edit, Glob, Grep
+---
+
+Instructions here...
+```
+
+### Add a rule
+
+```markdown
+# .claude/rules/my-rule.md
+- Always use TypeScript strict mode
+- Never use `any` type
+```
+
+Rules load every message. Keep them short.
+
+### Add a hook
+
+```js
+// .claude/hooks/my-hook.cjs
+const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+// Exit 0 = allow, Exit 2 = block (stdout = reason)
+process.exit(0);
+```
+
+Wire in `.claude/settings.json`:
+```json
+{ "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [
+  { "type": "command", "command": "node .claude/hooks/my-hook.cjs" }
+]}]}}
+```
+
+## Roadmap
+
+- [x] `ship-version` — Git version control
+- [ ] `ship-plan` — Implementation planning
+- [ ] `ship-test` — Test runner with coverage
+- [ ] `ship-review` — Code review
+- [ ] `ship-fix` — Structured bug fixing
+- [ ] `ship-deploy` — Deployment workflows
+- [ ] `ship-docs` — Documentation management
+- [ ] `ship-secure` — Security scanning
+
+## Requirements
+
+- [Node.js](https://nodejs.org) 18+
+- [Claude Code](https://claude.ai/code) (for skill execution)
+
+## Links
+
+- **Website:** [telelabs.ai](https://telelabs.ai)
+- **Email:** [tele@telelabs.ai](mailto:tele@telelabs.ai)
+- **LinkedIn:** [linkedin.com/company/telelabsai](https://linkedin.com/company/telelabsai)
+- **Issues:** [github.com/telelabs-ai/ship/issues](https://github.com/telelabs-ai/ship/issues)
+
+## License
+
+MIT — [TeleLabs AI](https://telelabs.ai)

package/cli/__tests__/cli.test.js

@@ -0,0 +1,155 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const { existsSync, rmSync, readFileSync } = require('fs');
+const { join, resolve } = require('path');
+
+const CLI = resolve(__dirname, '..', 'bin.js');
+const TMP = resolve(__dirname, '..', '..', '.test-output');
+
+// Helper: run CLI command and return stdout
+function run(args) {
+  return execSync(`node ${CLI} ${args}`, { encoding: 'utf8', cwd: TMP });
+}
+
+describe('ship CLI', () => {
+  before(() => {
+    // Clean up any leftover test output
+    if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+  });
+
+  after(() => {
+    if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+  });
+
+  describe('--help', () => {
+    it('shows help text', () => {
+      const out = execSync(`node ${CLI} --help`, { encoding: 'utf8' });
+      assert.match(out, /Ship/);
+      assert.match(out, /ship init/);
+      assert.match(out, /ship new/);
+      assert.match(out, /telelabs\.ai/);
+    });
+
+    it('shows help with -h alias', () => {
+      const out = execSync(`node ${CLI} -h`, { encoding: 'utf8' });
+      assert.match(out, /ship init/);
+    });
+
+    it('shows help when no args', () => {
+      const out = execSync(`node ${CLI}`, { encoding: 'utf8' });
+      assert.match(out, /ship init/);
+    });
+  });
+
+  describe('--version', () => {
+    it('prints version number', () => {
+      const out = execSync(`node ${CLI} --version`, { encoding: 'utf8' }).trim();
+      assert.match(out, /^\d+\.\d+\.\d+$/);
+    });
+
+    it('works with -v alias', () => {
+      const out = execSync(`node ${CLI} -v`, { encoding: 'utf8' }).trim();
+      assert.match(out, /^\d+\.\d+\.\d+$/);
+    });
+  });
+
+  describe('skill delegation', () => {
+    it('delegates unknown commands to Claude Code as skills', () => {
+      // Any non-builtin command gets routed to Claude Code as /ship-<command>
+      // This will fail if Claude Code is not installed, which is expected in CI
+      try {
+        execSync(`node ${CLI} foobar`, { encoding: 'utf8', timeout: 5000 });
+      } catch (err) {
+        // Expected: either Claude not installed or skill not found
+        assert.ok(
+          err.stderr.includes('Claude Code') || err.status !== 0,
+          'Should attempt to delegate to Claude Code'
+        );
+      }
+    });
+  });
+
+  describe('ship new', () => {
+    const projectDir = join(TMP, 'test-new-project');
+
+    before(() => {
+      if (existsSync(TMP)) rmSync(TMP, { recursive: true });
+      execSync(`mkdir -p ${TMP}`);
+    });
+
+    it('creates project directory with .claude/', () => {
+      execSync(`node ${CLI} new ${projectDir}`, { encoding: 'utf8' });
+      assert.ok(existsSync(projectDir));
+      assert.ok(existsSync(join(projectDir, '.claude')));
+    });
+
+    it('copies all expected files', () => {
+      // Agents
+      assert.ok(existsSync(join(projectDir, '.claude', 'agents', 'git-ops.md')));
+      // Skills
+      assert.ok(existsSync(join(projectDir, '.claude', 'skills', 'ship-version', 'SKILL.md')));
+      // Rules
+      assert.ok(existsSync(join(projectDir, '.claude', 'rules', 'git-conventions.md')));
+      // Hooks
+      assert.ok(existsSync(join(projectDir, '.claude', 'hooks', 'git-safety.cjs')));
+      // Settings
+      assert.ok(existsSync(join(projectDir, '.claude', 'settings.json')));
+      // CLAUDE.md
+      assert.ok(existsSync(join(projectDir, 'CLAUDE.md')));
+    });
+
+    it('copies skill references', () => {
+      const refs = join(projectDir, '.claude', 'skills', 'ship-version', 'references');
+      assert.ok(existsSync(join(refs, 'commit-standards.md')));
+      assert.ok(existsSync(join(refs, 'workflow-commit.md')));
+      assert.ok(existsSync(join(refs, 'workflow-push.md')));
+      assert.ok(existsSync(join(refs, 'workflow-pr.md')));
+      assert.ok(existsSync(join(refs, 'workflow-diff.md')));
+      assert.ok(existsSync(join(refs, 'workflow-changelog.md')));
+      assert.ok(existsSync(join(refs, 'safety-protocols.md')));
+    });
+
+    it('customizes CLAUDE.md with project name', () => {
+      const content = readFileSync(join(projectDir, 'CLAUDE.md'), 'utf8');
+      assert.match(content, /test-new-project/);
+      assert.match(content, /powered by Ship/);
+    });
+
+    it('fails if project already exists', () => {
+      assert.throws(
+        () => execSync(`node ${CLI} new ${projectDir}`, { encoding: 'utf8' }),
+        /already exists/
+      );
+    });
+
+    it('fails without project name', () => {
+      assert.throws(
+        () => execSync(`node ${CLI} new`, { encoding: 'utf8' }),
+        /project name required/
+      );
+    });
+  });
+
+  describe('ship init', () => {
+    const initDir = join(TMP, 'test-init-project');
+
+    before(() => {
+      execSync(`mkdir -p ${initDir}`);
+    });
+
+    it('scaffolds .claude/ into existing directory', () => {
+      execSync(`node ${CLI} init --dir ${initDir}`, { encoding: 'utf8' });
+      assert.ok(existsSync(join(initDir, '.claude')));
+      assert.ok(existsSync(join(initDir, '.claude', 'settings.json')));
+      assert.ok(existsSync(join(initDir, 'CLAUDE.md')));
+    });
+
+    it('fails if .claude/ already exists', () => {
+      assert.throws(
+        () => execSync(`node ${CLI} init --dir ${initDir}`, { encoding: 'utf8' }),
+        /already exists/
+      );
+    });
+  });
+});

package/cli/bin.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+const { resolve } = require('path');
+const { execSync, spawn } = require('child_process');
+const args = process.argv.slice(2);
+const command = args[0];
+
+const HELP = `
+  Ship — AI-powered development toolkit by TeleLabs AI
+
+  Usage:
+    ship init [--dir <path>]    Scaffold .claude/ into a project
+    ship new <name>             Create new project with Ship config
+    ship update [--force]       Update .claude/ to latest Ship version
+    ship <skill> [args]         Run a Ship skill via Claude Code
+    ship --version              Show version
+    ship --help                 Show this help
+
+  Skills (any ship-* skill installed in .claude/skills/):
+    ship version commit         → /ship-version commit
+    ship version diff --pr      → /ship-version diff --pr
+    ship plan "add auth"        → /ship-plan add auth
+    ship deploy staging         → /ship-deploy staging
+    ship test                   → /ship-test
+    ship review                 → /ship-review
+
+  Examples:
+    ship init
+    ship new my-app
+    ship update
+    ship version commit --ticket PROJ-42 "add auth"
+    ship plan "implement user dashboard"
+
+  Requires: Claude Code (https://claude.ai/code)
+  https://telelabs.ai
+`;
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (command === 'init') {
+  const init = require('./commands/init.js');
+  const dirIdx = args.indexOf('--dir');
+  const targetDir = dirIdx !== -1 ? resolve(args[dirIdx + 1]) : process.cwd();
+  init(targetDir);
+} else if (command === 'new') {
+  const newProject = require('./commands/new.js');
+  const projectName = args[1];
+  if (!projectName) {
+    console.error('  Error: project name required. Usage: ship new <name>');
+    process.exit(1);
+  }
+  newProject(projectName);
+} else if (command === 'update') {
+  const update = require('./commands/update.js');
+  const force = args.includes('--force');
+  update(process.cwd(), force);
+} else {
+  // Generic skill routing: ship <skill> [args] → claude -p "/ship-<skill> [args]"
+  delegateToClaude(args);
+}
+
+/**
+ * Delegates any non-builtin command to Claude Code as a skill invocation.
+ * `ship version commit --ticket X` → `claude -p "/ship-version commit --ticket X"`
+ *
+ * @param {string[]} cliArgs - All arguments after `ship`
+ */
+function delegateToClaude(cliArgs) {
+  // Check Claude Code is installed
+  try {
+    execSync('claude --version', { stdio: 'pipe' });
+  } catch {
+    console.error('  Error: Claude Code is not installed.');
+    console.error('  Install it at: https://claude.ai/code');
+    process.exit(1);
+  }
+
+  // Build skill prompt: ship version commit → /ship-version commit
+  const skill = cliArgs[0];
+  const rest = cliArgs.slice(1).join(' ');
+  const prompt = `/ship-${skill}${rest ? ' ' + rest : ''}`;
+
+  const claude = spawn('claude', ['-p', prompt], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+
+  claude.on('close', (code) => process.exit(code || 0));
+  claude.on('error', (err) => {
+    console.error(`  Error running Claude Code: ${err.message}`);
+    process.exit(1);
+  });
+}

package/cli/commands/init.js

@@ -0,0 +1,49 @@
+const { resolve, join } = require('path');
+const { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+
+// Source: .claude/ and CLAUDE.md from the package root (single source of truth)
+const PKG_ROOT = resolve(__dirname, '..', '..');
+const SOURCE_CLAUDE_DIR = join(PKG_ROOT, '.claude');
+const SOURCE_CLAUDE_MD = join(PKG_ROOT, 'CLAUDE.md');
+
+module.exports = function init(targetDir) {
+  const targetClaude = join(targetDir, '.claude');
+  const targetClaudeMd = join(targetDir, 'CLAUDE.md');
+
+  // Safety: warn if .claude/ already exists
+  if (existsSync(targetClaude)) {
+    console.error('  .claude/ already exists in this directory.');
+    console.error('  Use --force to overwrite (not yet implemented).');
+    console.error('  Skipping to avoid losing your customizations.');
+    process.exit(1);
+  }
+
+  // Ensure target directory exists
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Copy .claude/ directory
+  cpSync(SOURCE_CLAUDE_DIR, targetClaude, { recursive: true });
+  console.log('  .claude/ scaffolded');
+
+  // Copy CLAUDE.md (only if it doesn't exist)
+  if (!existsSync(targetClaudeMd)) {
+    // Read and customize the template CLAUDE.md
+    let claudeMd = readFileSync(SOURCE_CLAUDE_MD, 'utf8');
+
+    // Replace project name placeholder with directory name
+    const projectName = targetDir.split('/').pop();
+    claudeMd = claudeMd.replace(
+      'Ship — AI-powered development toolkit by TeleLabs AI.',
+      `${projectName} — powered by Ship (TeleLabs AI).`
+    );
+
+    writeFileSync(targetClaudeMd, claudeMd);
+    console.log('  CLAUDE.md created');
+  } else {
+    console.log('  CLAUDE.md already exists, skipped');
+  }
+
+  console.log('\n  Ship initialized. Run "claude" to start.\n');
+};

package/cli/commands/new.js

@@ -0,0 +1,18 @@
+const { resolve, join } = require('path');
+const { existsSync, mkdirSync } = require('fs');
+const init = require('./init.js');
+
+module.exports = function newProject(name) {
+  const targetDir = resolve(process.cwd(), name);
+
+  if (existsSync(targetDir)) {
+    console.error(`  Error: "${name}" already exists.`);
+    process.exit(1);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  console.log(`\n  Creating ${name}/\n`);
+
+  // Scaffold Ship config into the new directory
+  init(targetDir);
+};