huskies/README.md

# Storkit

A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend.

## Getting started with Claude Code

The fastest way to use storkit is from a Claude Code terminal session.

```bash
# Install the binary (or build from source — see below)
storkit init --port 3000
```

This scaffolds a `.storkit/` directory in your project with the pipeline structure, `project.toml` config, and an `.mcp.json` that lets Claude Code discover storkit's MCP tools automatically.

From there, Claude can create stories, start agents, check status, and manage the full pipeline via MCP tools — no web UI required.

## Web UI

Storkit also ships an embedded React frontend. Once the server is running, open `http://localhost:3000` to see the pipeline board, agent status, and chat interface.

## Chat transports

Storkit can be controlled via bot commands in **Matrix**, **WhatsApp**, and **Slack**. Configure a transport in `.storkit/bot.toml` — see the example files:

- `.storkit/bot.toml.matrix.example`
- `.storkit/bot.toml.whatsapp-meta.example`
- `.storkit/bot.toml.whatsapp-twilio.example`
- `.storkit/bot.toml.slack.example`

## Prerequisites

- Rust (2024 edition)
- Node.js and npm
- Docker (for Linux cross-compilation and container deployment)
- `cross` (`cargo install cross`) for Linux static builds

## Building for production

```bash
cargo build --release
```

The release binary embeds the frontend via `rust-embed`. Output: `target/release/storkit`.

For a static Linux binary (musl, zero dynamic deps):

```bash
cross build --release --target x86_64-unknown-linux-musl
```

Docker:

```bash
docker compose -f docker/docker-compose.yml build
```

## Running in development

```bash
# Run tests
script/test

# Run the server
cargo run -- --port 3000

# In another terminal, run the frontend dev server
cd frontend && npm install && npm run dev
```

Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example` for transport setup.

## Releasing

Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).

```bash
script/release 0.7.1
```

This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.

## License

GPL-3.0. See [LICENSE](LICENSE).