zdev-skill 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, January 2026
+
+ Copyright (C) 2026 5hanth
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

package/README.md

@@ -0,0 +1,76 @@
+# zdev-skill
+
+Agent skill for [zdev](https://github.com/5hanth/zdev) — multi-agent worktree development environment.
+
+## What is this?
+
+This skill teaches AI coding agents (Claude Code, Clawdbot, etc.) how to use `zdev` for managing isolated development environments with git worktrees, automatic port allocation, and public preview URLs.
+
+## Installation
+
+### Claude Code
+
+```bash
+npx add-skill 5hanth/zdev-skill
+```
+
+Then in Claude Code:
+```
+/zdev
+```
+
+### Clawdbot
+
+Add to your Clawdbot skills directory:
+```bash
+git clone https://github.com/5hanth/zdev-skill ~/.clawdbot/skills/zdev
+```
+
+### Other Agents
+
+Copy the contents of [SKILL.md](./SKILL.md) into your agent's system prompt or context.
+
+## Usage
+
+Once installed, prompt your agent:
+
+```
+Use zdev to create a new TanStack Start project called my-app with Convex backend.
+```
+
+```
+Use zdev to start a worktree for add-auth feature on ./my-project
+```
+
+```
+Run zdev list to show what's currently running.
+```
+
+```
+Use zdev clean to remove the add-auth worktree after the PR is merged.
+```
+
+## What the Agent Learns
+
+- `zdev create` — Scaffold new TanStack Start projects
+- `zdev init` — Initialize existing projects
+- `zdev start` — Create isolated worktrees with auto port allocation
+- `zdev list` — Check running worktrees
+- `zdev stop` — Stop servers
+- `zdev clean` — Remove worktrees after PR merge
+- `zdev config` — Configure Traefik for public URLs
+
+## Requirements
+
+- [zdev](https://github.com/5hanth/zdev) CLI installed
+- [Bun](https://bun.sh) runtime
+
+## Related
+
+- [zdev](https://github.com/5hanth/zdev) — The CLI tool
+- [Clawdbot](https://docs.clawd.bot) — AI agent platform
+- [Claude Code](https://claude.ai) — Anthropic's coding agent
+
+## License
+
+[WTFPL](https://en.wikipedia.org/wiki/WTFPL)

package/SKILL.md

@@ -0,0 +1,148 @@
+# zdev Skill
+
+Use `zdev` to manage isolated development environments when working on features. Each feature gets its own git worktree, ports, and optional public preview URL.
+
+## Prerequisites
+
+- `zdev` CLI installed (`bunx zdev` or `bun add -g zdev`)
+- Vite-based frontend project (Convex backend is optional, auto-detected)
+
+## Creating a New Project
+
+```bash
+# Basic TanStack Start project
+zdev create my-app
+
+# With Convex backend
+zdev create my-app --convex
+
+# Flat structure (no monorepo)
+zdev create my-app --flat
+```
+
+Creates:
+- TanStack Start app with clean routes
+- `.zdev/setup.sh` for worktree setup
+- Agentation for UI feedback (dev only)
+
+## Initializing an Existing Project
+
+```bash
+zdev init /path/to/project
+```
+
+Creates `.zdev/project.json` with project metadata.
+
+## Configuration
+
+First-time setup (or to change settings):
+
+```bash
+zdev config --set devDomain=dev.example.com
+zdev config --set traefikConfigDir=/etc/traefik/dynamic
+zdev config --list
+```
+
+## Before Starting Any Feature
+
+```bash
+# Check what's already running
+zdev list
+```
+
+If your feature already exists, just `cd` to the worktree path shown.
+
+## Starting a New Feature
+
+```bash
+# Start feature with public URL
+zdev start <feature-name> -p /path/to/project
+
+# Start without public URL (local only)
+zdev start <feature-name> -p /path/to/project --local
+
+# Start with seed data (Convex projects)
+zdev start <feature-name> -p /path/to/project --seed
+
+# Use different base branch
+zdev start <feature-name> -p /path/to/project --base-branch main
+```
+
+After starting:
+1. `.zdev/setup.sh` runs automatically (installs deps, etc.)
+2. Note the worktree path (e.g., `~/.zdev/worktrees/project-feature`)
+3. Note the local URL (e.g., `http://localhost:5173`)
+4. Note the public URL if available (e.g., `https://project-feature.dev.example.com`)
+5. `cd` to the worktree path to begin work
+
+## While Working
+
+You're in an isolated git worktree with its own:
+- Branch (`feature/<name>`)
+- Node modules
+- Convex dev instance (if applicable)
+- Port allocation
+
+Work normally. Commit often. Push when ready for review.
+
+```bash
+git add .
+git commit -m "description"
+git push -u origin feature/<name>
+```
+
+## Stopping Work (End of Session)
+
+```bash
+# Stop servers but keep worktree (resume later)
+zdev stop <feature-name> -p /path/to/project --keep
+
+# Or just leave it running if you'll be back soon
+```
+
+## Resuming Work
+
+```bash
+# Check status
+zdev list
+
+# If stopped, restart
+zdev start <feature-name> -p /path/to/project
+
+# If already running, just cd to the worktree
+cd ~/.zdev/worktrees/project-feature
+```
+
+## After PR is Merged
+
+```bash
+# Clean up completely
+zdev clean <feature-name> -p /path/to/project
+```
+
+This removes the worktree, Traefik route, and port allocation.
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Create new project | `zdev create NAME` |
+| Init existing project | `zdev init PATH` |
+| Configure | `zdev config --list` |
+| See what's running | `zdev list` |
+| Start feature | `zdev start NAME -p PATH` |
+| Stop (keep files) | `zdev stop NAME -p PATH --keep` |
+| Stop (full) | `zdev stop NAME -p PATH` |
+| Remove after merge | `zdev clean NAME -p PATH` |
+
+## Troubleshooting
+
+**"Feature already exists"** → It's already running. Use `zdev list` to find the worktree path.
+
+**"Failed to create worktree: invalid reference"** → Use `--base-branch master` or the correct branch name.
+
+**Port conflict** → Specify a port: `zdev start NAME --port 5200`
+
+**No public URL** → Run `zdev config --set devDomain=dev.example.com` first.
+
+**Convex not working** → Run `bunx convex dev` once in the main project first to select a Convex project.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "zdev-skill",
+  "version": "0.1.0",
+  "description": "Agent skill for zdev - multi-agent worktree development",
+  "license": "WTFPL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/5hanth/zdev-skill"
+  },
+  "keywords": [
+    "clawdbot",
+    "agent",
+    "skill",
+    "zdev",
+    "worktree",
+    "convex",
+    "vite"
+  ],
+  "files": [
+    "SKILL.md",
+    "README.md"
+  ]
+}