aboutsummaryrefslogtreecommitdiffstats
path: root/SKILLS_PLAN.md
diff options
context:
space:
mode:
authorClawd <ai@clawd.bot>2026-04-18 14:40:17 -0700
committerClawd <ai@clawd.bot>2026-04-18 14:40:17 -0700
commit778bef5ee6941056e06326d1eaaa6956d7307a85 (patch)
tree23b85f32fb69f85078b3debec08c1353694def6f /SKILLS_PLAN.md
parenteb76b1f6e1697ef170fc45d25e81b21679ea7b0d (diff)
Remove Go implementation — ship is skills-only nowmain
The skills/ directory fully replaces the old Go CLI. Drop all Go source, build files, planning docs, and the stale SECURITY.md (which described the old git-user push-deploy model that no longer exists). Trim .gitignore to match the new tree.
Diffstat (limited to 'SKILLS_PLAN.md')
-rw-r--r--SKILLS_PLAN.md135
1 files changed, 0 insertions, 135 deletions
diff --git a/SKILLS_PLAN.md b/SKILLS_PLAN.md
deleted file mode 100644
index ded2b38..0000000
--- a/SKILLS_PLAN.md
+++ /dev/null
@@ -1,135 +0,0 @@
1# Ship Skills — Reimagining Ship as Claude Skills
2
3## The Idea
4
5Rather than a monolithic CLI that bakes in rigid assumptions, ship becomes a family of
6narrow, composable Claude skills. Each skill knows how to do one thing well. Claude
7provides the reasoning and orchestration. The server is the source of truth.
8
9Skills are completely generic — no hostnames, app names, or passwords baked in. The
10same skills work for anyone. Share them with a friend, point them at a different VPS,
11they just work.
12
13## Shared Configuration
14
15A single static file at `~/.config/ship/config.json` holds the VPS host (and little
16else). All skills read from this file. No vault dependency — works for anyone.
17
18```json
19{
20 "host": "ubuntu@1.2.3.4",
21 "domain": "example.com"
22}
23```
24
25The server itself is the source of truth for everything else — what services are
26running, what ports are allocated, what Caddy configs exist. No local state file that
27can go stale.
28
29## The Skills
30
31### `ship-setup`
32One-time setup. Asks for VPS host if not configured, saves to `~/.config/ship/config.json`,
33SSHes in and installs server dependencies (Caddy, directory structure, etc).
34All other skills depend on this having been run once.
35
36### `ship-status`
37Derives current state entirely from the server at runtime:
38- Running apps → `systemctl list-units --type=service`
39- Ports → `/etc/ship/ports/` or env files
40- Domains → parse Caddy configs in `sites-enabled/`
41- Static sites → list `/var/www/`
42
43No state file needed. Always accurate. Replaces the need for any local tracking.
44
45### `ship-env`
46Read and write env vars with merge semantics. Never overwrites — reads existing file
47first, merges new values on top, writes result. Old vars survive redeployments.
48
49### `ship-caddy`
50Manage per-app Caddyfile config. Knows Caddy syntax. Diffs before writing. Validates
51before reloading. Never regenerates from scratch — only touches what needs changing.
52
53### `ship-service`
54Systemd management. Handles the difference between a new service (enable + start) and
55an existing one (restart). Status, logs, restart, stop — all covered.
56
57### `ship-binary`
58Upload and install a pre-built binary. SCP to `/tmp`, move to `/usr/local/bin/`,
59chmod +x, set up work directory and service user. Calls `ship-service` and `ship-env`
60to complete the deployment.
61
62### `ship-static`
63Rsync a local dist folder to `/var/www/{name}` on the server. Calls `ship-caddy` to
64configure serving.
65
66### `ship-deploy`
67A runbook skill that orchestrates the others in the right order for a full deployment.
68Not imperative code — just a checklist of steps with enough context for Claude to
69reason about what to do. Adapts based on what the user tells it (binary vs static,
70what env vars are needed, etc).
71
72## What the Server Knows
73
74All persistent state lives on the server in conventional locations:
75
76```
77/etc/caddy/sites-enabled/{name}.caddy # per-app Caddy config
78/etc/ship/env/{name}.env # environment variables
79/etc/ship/ports/{name} # allocated port number
80/etc/systemd/system/{name}.service # systemd unit
81/var/www/{name}/ # static site files
82/var/lib/{name}/ # app work directory (binary, data)
83/usr/local/bin/{name} # binary executable
84```
85
86## Why This Is Better Than the CLI
87
88- **Transparent** — Claude tells you what it's about to do before doing it
89- **Flexible** — no rigid assumptions, Claude reasons about edge cases
90- **Mergeable** — env files, Caddy configs never blindly overwritten
91- **Debuggable** — if something goes wrong, just ask Claude to fix it
92- **Shareable** — no app-specific knowledge baked in, works for anyone
93- **No stale state** — server is always the source of truth
94
95## Per-App Notes (Optional)
96
97The server can't know things like "this app needs FOODTRACKER_PASSWORD on redeploy"
98or "this app has SQLite at /var/lib/foodtracker/data/". That's documentation, not
99state. Users can keep these as plain notes in whatever system they prefer — a vault,
100a README, a comment in a script. The skills don't depend on it.
101
102## SQLite Backup
103
104Before swapping a binary, `ship-binary` checks `/var/lib/{name}/` for any `.db` files
105and backs them up to `/var/lib/{name}/backups/{timestamp}.db` before proceeding. Silent
106and automatic — you never lose data from a bad deploy.
107
108## Multi-Host Support
109
110Config supports multiple named hosts. One is marked as default. All skills use the
111default unless told otherwise.
112
113```json
114{
115 "default": "prod",
116 "hosts": {
117 "prod": {
118 "host": "ubuntu@1.2.3.4",
119 "domain": "example.com"
120 },
121 "staging": {
122 "host": "ubuntu@5.6.7.8",
123 "domain": "staging.example.com"
124 }
125 }
126}
127```
128
129Usage is natural — "deploy foodtracker to staging" and Claude picks the right host.
130`ship-setup` can be run multiple times to add new hosts. The default can be changed
131at any time.
132
133## Out of Scope (For Now)
134
135- Health checks — skipping initially, can add later if needed