@telelabsai/ship 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +55 -154
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -3,12 +3,7 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@telelabsai/ship.svg)](https://www.npmjs.com/package/@telelabsai/ship)
4
4
  [![license](https://img.shields.io/npm/l/@telelabsai/ship.svg)](https://github.com/telelabs-ai/ship/blob/main/LICENSE)
5
5
 
6
- **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.
7
-
8
- ```
9
- idea → plan → code → test → review → commit → push → PR → deploy
10
- Ship handles this ──────────────────────────→
11
- ```
6
+ **Ship helps you go from code to production.** Conventional commits, ticket tracking, changelogs, safety guardrails, and more all from one command.
12
7
 
13
8
  ## Installation
14
9
 
@@ -16,6 +11,8 @@ idea → plan → code → test → review → commit → push → PR → deploy
16
11
  npm install -g @telelabsai/ship
17
12
  ```
18
13
 
14
+ Requires [Node.js](https://nodejs.org) 18+ and [Claude Code](https://claude.ai/code).
15
+
19
16
  ## Quick Start
20
17
 
21
18
  ```bash
@@ -25,66 +22,23 @@ ship init
25
22
  # Or start fresh
26
23
  ship new my-app
27
24
 
28
- # Use from terminal (delegates to Claude Code)
29
- ship version commit --ticket PROJ-42 "add auth"
30
-
31
- # Or inside Claude Code directly
32
- claude
33
- /ship-version commit --ticket PROJ-42 "add auth"
25
+ # Start using it
26
+ ship version commit --ticket PROJ-42 "add user auth"
34
27
  ```
35
28
 
36
- Both paths use the same skill. One source of truth.
29
+ ## Commands
37
30
 
38
- ## CLI
31
+ ### Project Setup
39
32
 
40
33
  ```bash
41
- # Project setup
42
- ship init Add Ship to current directory
43
- ship init --dir ./my-app Add Ship to specific directory
44
- ship new <name> Create new project with Ship config
45
- ship update Update .claude/ to latest version
46
- ship update --force Update without asking
47
-
48
- # Skills (routes to Claude Code)
49
- ship version commit Conventional commits with ticket tracking
50
- ship version diff --pr Preview what a PR would contain
51
- ship version push Push to remote safely
52
- ship version pr Create pull request
53
- ship version changelog Auto-generate changelog
54
- ship version branch <name> Create and switch branch
55
- ship plan "add auth" Plan implementation (coming soon)
56
- ship test Run tests (coming soon)
57
- ship review Code review (coming soon)
58
- ship deploy staging Deploy (coming soon)
34
+ ship init # Add Ship to current directory
35
+ ship init --dir ./my-app # Add Ship to specific directory
36
+ ship new <name> # Create new project with Ship config
37
+ ship update # Update to latest Ship version
38
+ ship update --force # Update without asking
59
39
  ```
60
40
 
61
- 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.
62
-
63
- ## How It Works
64
-
65
- Ship adds a `.claude/` directory to your project with four layers:
66
-
67
- | Layer | What it does | When it loads |
68
- |-------|-------------|---------------|
69
- | **Skills** | Step-by-step workflows you invoke | On demand (`/ship-version commit`) |
70
- | **Agents** | Isolated AI subprocesses for heavy tasks | When needed (large diffs, PRs) |
71
- | **Rules** | Conventions Claude always follows | Every message |
72
- | **Hooks** | Code-level guardrails | Automatically (blocks secrets, force push) |
73
-
74
- ```
75
- .claude/
76
- ├── skills/ Slash-command workflows
77
- ├── agents/ Subagent definitions
78
- ├── rules/ Always-loaded instructions
79
- ├── hooks/ Lifecycle automation
80
- └── settings.json Configuration
81
- ```
82
-
83
- ## Skills
84
-
85
- ### ship-version — Git Version Control
86
-
87
- Conventional commits, ticket tracking, security scanning, changelogs.
41
+ ### Git Version Control
88
42
 
89
43
  ```bash
90
44
  # Commit
@@ -100,33 +54,44 @@ ship version diff --pr # preview PR diff
100
54
  ship version diff v1.0.0..v2.0.0 # between tags
101
55
 
102
56
  # Changelog
103
- ship version changelog # auto-detect from tags
57
+ ship version changelog # auto-generate from tags
104
58
  ship version changelog v1.0.0 v2.0.0 # specific range
105
59
 
106
60
  # Push / PR / Branch
107
- ship version push # push current branch
108
- ship version pr --ticket PROJ-42 "Add auth" # create PR with ticket
61
+ ship version push # push to remote safely
62
+ ship version pr --ticket PROJ-42 "Add auth" # create pull request
109
63
  ship version branch feature/user-auth # create + switch
110
64
  ```
111
65
 
112
- ### Ticket Tracking
66
+ ### Coming Soon
67
+
68
+ ```bash
69
+ ship plan "add auth" # Implementation planning
70
+ ship test # Test runner with coverage
71
+ ship review # Code review
72
+ ship deploy staging # Deployment workflows
73
+ ship fix "login bug" # Structured bug fixing
74
+ ship docs # Documentation management
75
+ ```
76
+
77
+ ## Ticket Tracking
113
78
 
114
79
  Works with any project management tool:
115
80
 
116
- | Tool | Example |
117
- |------|---------|
118
- | Jira | `--ticket PROJ-123` |
119
- | ClickUp | `--ticket CU-abc123` |
120
- | Linear | `--ticket ENG-123` |
121
- | GitHub Issues | `--ticket #42` |
122
- | Trello | `--ticket #abc123` |
123
- | Shortcut | `--ticket sc-12345` |
124
- | Asana | `--ticket 1234567890` |
125
- | Custom | `--ticket ANYTHING` |
81
+ | Tool | Example |
82
+ | ------------- | --------------------- |
83
+ | Jira | `--ticket PROJ-123` |
84
+ | ClickUp | `--ticket CU-abc123` |
85
+ | Linear | `--ticket ENG-123` |
86
+ | GitHub Issues | `--ticket #42` |
87
+ | Trello | `--ticket #abc123` |
88
+ | Shortcut | `--ticket sc-12345` |
89
+ | Asana | `--ticket 1234567890` |
90
+ | Custom | `--ticket ANYTHING` |
126
91
 
127
92
  Multiple tickets: `--ticket PROJ-42 --ticket #15`
128
93
 
129
- ### Commit Format
94
+ ## Commit Format
130
95
 
131
96
  ```
132
97
  type(scope): description
@@ -138,94 +103,30 @@ Refs: TICKET-ID
138
103
 
139
104
  Types: `feat` | `fix` | `refactor` | `test` | `docs` | `chore` | `perf` | `style` | `ci` | `build`
140
105
 
141
- ## Safety
142
-
143
- Ship includes automatic guardrails that can't be bypassed:
144
-
145
- | Guardrail | What it prevents |
146
- |-----------|-----------------|
147
- | Secret detection | Blocks committing `.env`, API keys, credentials |
148
- | Force push block | Prevents `git push --force` to any branch |
149
- | Blind staging block | Prevents `git add .` / `git add -A` |
150
- | Hard reset block | Prevents `git reset --hard` without confirmation |
151
- | Branch protection | Prevents deleting main/master/production |
106
+ ## Safety Guardrails
152
107
 
153
- ## Extending Ship
108
+ Ship automatically prevents common mistakes:
154
109
 
155
- ### Add a skill
110
+ | Guardrail | What it prevents |
111
+ | ------------------- | ------------------------------------------------ |
112
+ | Secret detection | Blocks committing `.env`, API keys, credentials |
113
+ | Force push block | Prevents `git push --force` |
114
+ | Blind staging block | Prevents `git add .` / `git add -A` |
115
+ | Hard reset block | Prevents `git reset --hard` without confirmation |
116
+ | Branch protection | Prevents deleting main/master/production |
156
117
 
157
- ```bash
158
- mkdir -p .claude/skills/ship-deploy
159
- ```
160
-
161
- ```yaml
162
- # .claude/skills/ship-deploy/SKILL.md
163
- ---
164
- name: ship-deploy
165
- description: "Deploy to staging or production."
166
- argument-hint: "<staging|production>"
167
- ---
168
-
169
- # Instructions here...
170
- ```
171
-
172
- Now `ship deploy staging` works — both from terminal and inside Claude Code.
173
-
174
- ### Add an agent
175
-
176
- ```yaml
177
- # .claude/agents/my-agent.md
178
- ---
179
- name: my-agent
180
- description: "When to use this agent."
181
- model: sonnet
182
- tools: Bash, Read, Edit, Glob, Grep
183
- ---
184
-
185
- Instructions here...
186
- ```
187
-
188
- ### Add a rule
189
-
190
- ```markdown
191
- # .claude/rules/my-rule.md
192
- - Always use TypeScript strict mode
193
- - Never use `any` type
194
- ```
195
-
196
- Rules load every message. Keep them short.
118
+ ## How It Works
197
119
 
198
- ### Add a hook
120
+ Ship is powered by [Claude Code](https://claude.ai/code). Every `ship <command>` delegates to an AI skill that understands your codebase, analyzes diffs, and executes the right git workflow.
199
121
 
200
- ```js
201
- // .claude/hooks/my-hook.cjs
202
- const input = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
203
- // Exit 0 = allow, Exit 2 = block (stdout = reason)
204
- process.exit(0);
205
- ```
122
+ You can also use skills directly inside Claude Code:
206
123
 
207
- Wire in `.claude/settings.json`:
208
- ```json
209
- { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [
210
- { "type": "command", "command": "node .claude/hooks/my-hook.cjs" }
211
- ]}]}}
124
+ ```bash
125
+ claude
126
+ /ship-version commit --ticket PROJ-42 "add auth"
212
127
  ```
213
128
 
214
- ## Roadmap
215
-
216
- - [x] `ship-version` — Git version control
217
- - [ ] `ship-plan` — Implementation planning
218
- - [ ] `ship-test` — Test runner with coverage
219
- - [ ] `ship-review` — Code review
220
- - [ ] `ship-fix` — Structured bug fixing
221
- - [ ] `ship-deploy` — Deployment workflows
222
- - [ ] `ship-docs` — Documentation management
223
- - [ ] `ship-secure` — Security scanning
224
-
225
- ## Requirements
226
-
227
- - [Node.js](https://nodejs.org) 18+
228
- - [Claude Code](https://claude.ai/code) (for skill execution)
129
+ For details on the internals (agents, skills, rules, hooks), see [ARCHITECTURE.md](ARCHITECTURE.md).
229
130
 
230
131
  ## Links
231
132
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@telelabsai/ship",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "AI-powered development toolkit. Ship code faster with pre-configured agents, skills, rules, and hooks for Claude Code.",
5
5
  "bin": {
6
6
  "ship": "cli/bin.js"