jig-dev 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# jig-dev
+
+AI-powered spec-to-task decomposition and execution. Jig transforms high-level feature specifications into structured, executable tasks for AI coding agents.
+
+## Install
+
+### Quick start (no install)
+
+```bash
+npx jig-dev init
+# or
+bunx jig-dev init
+```
+
+### Global install
+
+```bash
+npm install -g jig-dev
+# or
+bun add -g jig-dev
+```
+
+Then run:
+
+```bash
+jig init
+```
+
+## Usage
+
+### Initialize a project
+
+```bash
+jig init
+```
+
+Jig detects your framework, creates the `.jig/` directory, and sets up your project.
+
+### Bootstrap from existing code
+
+```bash
+jig bootstrap
+```
+
+Scans your codebase and generates feature specifications automatically.
+
+### Work with specs
+
+```bash
+jig spec list              # List all specs
+jig spec show <name>       # View a spec
+jig spec new <name>        # Create a new spec
+```
+
+### Decompose and execute
+
+```bash
+jig decompose <spec>       # Break spec into tasks
+jig tasks <spec>           # List tasks for a spec
+jig run <spec> <task>      # Execute a task via Claude Code
+jig verify <spec> <task>   # Run verification gates
+jig status                 # View project status
+```
+
+### Cloud sync
+
+```bash
+jig auth login             # Authenticate
+jig sync                   # Sync with cloud
+```
+
+## How it works
+
+1. **Write specs** -- Describe features in markdown with intent, acceptance criteria, and constraints
+2. **Decompose** -- Jig breaks specs into executable tasks with file scopes and verification gates
+3. **Execute** -- Claude Code runs tasks autonomously, guided by rich context
+4. **Verify** -- Automated verification gates confirm each task meets its criteria
+
+## Deploying the MCP Server
+
+The hosted MCP server runs on Fly.io at `mcp.usejig.dev`.
+
+### Deploy
+
+```bash
+fly deploy
+```
+
+Deploys use **blue-green strategy**: the new instance boots and passes health checks before traffic switches over. Active SSE connections on the old instance are closed gracefully (in-flight requests finish, then transports close).
+
+### How graceful shutdown works
+
+1. Fly.io sends `SIGTERM` to the old instance (forwarded by `dumb-init`).
+2. The server stops accepting new connections.
+3. All active MCP transports are closed (SSE streams end cleanly with `retry: 3000ms` header).
+4. In-flight requests have up to 55 seconds to complete (Fly.io `kill_timeout` is 60s).
+5. Clients that lose their SSE stream will auto-reconnect within 3 seconds using the `retry` interval.
+6. If the old session ID is unknown to the new instance, clients re-initialize per the MCP spec (HTTP 404 triggers new `InitializeRequest`).
+
+### Monitoring
+
+```bash
+# Check server health
+curl https://mcp.usejig.dev/health
+
+# View active sessions and uptime
+fly ssh console -C "curl -s localhost:8080/health"
+
+# Stream logs during deploy
+fly logs
+```
+
+### Configuration
+
+Key settings in `fly.toml`:
+- `deploy.strategy = "bluegreen"` -- zero-downtime traffic switch
+- `http_service.min_machines_running = 1` -- always-on
+- `experimental.kill_timeout = "60s"` -- drain window before SIGKILL
+- `http_service.http_options.idle_timeout = 300` -- 5-minute idle timeout for SSE
+
+SSE settings in `src/mcp/hosted.ts`:
+- `retryInterval: 3000` -- clients retry SSE connection after 3 seconds
+- `eventStore: InMemoryEventStore` -- enables mid-session SSE resumption via `Last-Event-ID`
+- Keepalive comments every 15 seconds prevent Fly.io proxy timeout
+
+## Requirements
+
+- Node.js 18+ or Bun 1.0+
+- Claude Code CLI (for task execution)
+
+## License
+
+MIT