shortcut

# Shortcut Kanban Integration

Manage tasks and stories on Shortcut.com project boards via API.

## Prerequisites

- Shortcut API token configured via one of:
  - Environment variable: `SHORTCUT_API_TOKEN`
  - File: `~/.config/shortcut/api-token`
- Access to a Shortcut workspace with appropriate permissions

### Setup

1. Get your API token from Shortcut.com (Settings → API Tokens)
2. Store it either:
   - As environment variable: `export SHORTCUT_API_TOKEN="your-token"`
   - In a file: `echo "your-token" > ~/.config/shortcut/api-token && chmod 600 ~/.config/shortcut/api-token`
3. Initialize workflow states for your workspace:
   ```bash
   scripts/shortcut-init-workflow.sh
   ```
   This creates `~/.config/shortcut/workflow-states` with your workspace's actual state IDs.
4. Optionally add to `~/.bashrc` for persistence:
   ```bash
   export SHORTCUT_API_TOKEN=$(cat ~/.config/shortcut/api-token 2>/dev/null | tr -d '\n')
   source ~/.config/shortcut/workflow-states
   ```

## Available Operations

### List Stories

```bash
scripts/shortcut-list-stories.sh [--active|--completed|--all] [--json]
```

Options:
- `--active` - Show only incomplete stories (default)
- `--completed` - Show only completed stories
- `--all` - Include archived stories
- `--json` - Output raw JSON

### Show Story Details

```bash
scripts/shortcut-show-story.sh <story-id>
```

Displays full story information including:
- Story name and status
- Description (if present)
- Checklist items with completion status

### Create Story

```bash
scripts/shortcut-create-story.sh "Story name" [--description "text"] [--type feature|bug|chore]
```

Story types:
- `feature` (default) - New functionality
- `bug` - Bug fix
- `chore` - Maintenance task

### Update Story

```bash
scripts/shortcut-update-story.sh <story-id> [--complete|--todo|--in-progress] [--description "new text"]
```

**Workflow states:** The script uses state IDs from `~/.config/shortcut/workflow-states` (created by `shortcut-init-workflow.sh`)...

# Shortcut Skill for OpenClaw

Manage stories on Shortcut.com kanban boards directly from your OpenClaw agent.

## Features

- **List stories** - View active, completed, or all stories on your board
- **Create stories** - Add new tasks with descriptions and types (feature/bug/chore)
- **Update stories** - Change story status and descriptions

## Installation

```bash
# Install via OpenClaw skills system
openclaw skills install shortcut
```

Or manually:
1. Download `shortcut.skill` from releases
2. Place in your OpenClaw skills directory
3. Restart OpenClaw gateway

## Prerequisites

- Shortcut.com account with API access
- API token from Shortcut.com (Settings → API Tokens)
- Token must have permissions for the workspace(s) you want to manage

## Usage

Once installed, your OpenClaw agent can handle requests like:

- "Add a story to the board: Fix login bug"
- "Show me active stories on Shortcut"
- "Mark story #38 as started"

## Scripts

The skill includes three bash scripts:

- `shortcut-list-stories.sh` - List stories with filters
- `shortcut-create-story.sh` - Create new stories
- `shortcut-update-story.sh` - Update existing stories

All scripts use the Shortcut API v3.

## Configuration

1. Store your Shortcut API token:
   ```bash
   echo "your-token" > ~/.config/shortcut/api-token
   chmod 600 ~/.config/shortcut/api-token
   ```

2. Initialize workflow states for your workspace:
   ```bash
   scripts/shortcut-init-workflow.sh
   ```

This will auto-detect your workspace's workflow state IDs and save them to `~/.config/shortcut/workflow-states`.

## License

MIT

## Author

@catwalksophie