Skip to content
Back to skills

Canban

ASecurity

Operate Canban Cards, workflows, comments, reviews, and execution outcomes through the injected CANBAN_CLI.

  • 30 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
developmentsqlrailsgit

Works with

  • cursor
  • terminal
  • cli

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add jjyr/canban --skill canban --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Canban?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Canban
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/jjyr-canban/badge)](https://www.skillsdirectory.com/skills/jjyr-canban)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: canban
description: "Operate Canban Cards, workflows, comments, reviews, and execution outcomes through the injected CANBAN_CLI."
---

# Canban CLI Skill

Canban injects `CANBAN_CLI` and task environment variables when launching an Agent session on a Card or Project. Use `"$CANBAN_CLI"` for all Canban mutations and queries.

## Guardrails

1. **Check environment first**: Before running Card-scoped commands, verify Canban injected a live session:
   ```sh
   test -n "${CANBAN_CLI:-}" && test -n "${CANBAN_ENDPOINT:-}"
   ```
   If unset, you are outside a Canban-launched session (or pass `--home` / `--endpoint` explicitly when the user asks).
2. **Always use current environment variables**: Use `"$CANBAN_CLI"`, `"$CANBAN_ENDPOINT"`, `"$CANBAN_CARD"`, `"$CANBAN_PROJECT"`, and `"$CANBAN_RUN_DIR"` from the current process environment. Never copy stale `CANBAN_CARD` or `CANBAN_PROJECT` values from earlier conversation turns.
3. **Never touch storage directly**: Never read or edit `canban.sqlite` directly, and do not archive Cards unless explicitly asked.
4. **Keep scratch and Markdown payloads outside Git**: Write report, reply, and Card body files under `"${CANBAN_RUN_DIR:-/tmp}"` (for example `"$CANBAN_RUN_DIR/report.md"`), never inside the repository worktree.

## Injected Environment

| Variable | Purpose |
| --- | --- |
| `CANBAN_CLI` | Absolute path to the matching `canban` executable (or remote bridge wrapper). |
| `CANBAN_ENDPOINT` | AppServer Unix socket path (or `spool:...` on remote execution hosts). |
| `CANBAN_HOME` | Active Canban application home directory. |
| `CANBAN_CARD` | Short Card number (for example `42`), injected into both scheduled Agent runs and manual Card Terminals. |
| `CARD_ID` | Internal Card ID, injected alongside `CANBAN_CARD` in both scheduled Agent runs and manual Card Terminals. |
| `CANBAN_PROJECT` | Active Project ID (CLI commands also infer the Project from a git repository or Card worktree CWD when omitted). |
| `CANBAN_RUN_DIR` | Scratch directory outside the repository worktree for Markdown payloads. |
| `CANBAN_PROFILE_ID` | Active `@identity` or Agent profile ID (when applicable). |
| `CANBAN_SCHEDULE_RUN_ID` | Scheduled run ID (`scheduled:<project_id>:<short_id>`), injected into Cardless scheduled Terminal Agent runs. |
| `CANBAN_SCHEDULE_ID` | Parent schedule state ID (`schedule:<project_id>:<workflow_id>:<rule_id>`), injected into Cardless scheduled runs. |

## Core Execution Commands

### Report task or comment outcome

```sh
"$CANBAN_CLI" report \
  --state <completed|backlog|blocked|failed|working> \
  --message 'Concise one-line summary' \
  [--file "$CANBAN_RUN_DIR/report.md"]
```

- `completed`: Deliverable work or dedicated `@mention` comment task is finished. For code tasks, stage and `git commit` deliverable changes on the Card branch before reporting `completed` (do not `git push` unless instructed).
- `blocked`: Waiting on human clarification, credentials, or a design decision.
- `backlog`: Card is already implemented, obsolete, or not actionable right now; returns the Card to Backlog with your explanation.
- `failed`: Unrecoverable execution error.
- `working`: Optional interim progress update without finishing the assignment.

> **Interactive sessions vs. comment tasks**:
> - In an **interactive Card session**, reply directly in the terminal for initial discussion; only run `report` once the user asks you to complete a concrete task.
> - In a **dedicated `@mention` comment assignment**, publish your answer and finish in a single `report --state completed` call (do not call `reply` separately).

### Report batch merge queue outcome (`batch report`)

When running in a project `_merge_queue` batch `@merger` session (`CANBAN_BATCH_ID` is injected):

```sh
"$CANBAN_CLI" batch report \
  --state <completed|blocked|failed|working> \
  --message 'Concise summary of batch resolution' \
  [--evict <CARD_NUMBER> ...] \
  [--file "$CANBAN_RUN_DIR/report.md"]
```

- Do not `git push` or modify the main checkout directly; Canban fast-forwards and pushes once on `completed`.
- Use repeatable `--evict <CARD_NUMBER>` only if you rebuilt `_merge_queue` cleanly from `refs/canban/batch/<short_id>/target` without those broken Card(s) and verified tests on the remaining Cards.

### Answer a live follow-up question (`reply`)

When a human posts a follow-up question with a Question ID against an already running non-comment task, answer that question without ending your main task:

```sh
"$CANBAN_CLI" reply --to <QUESTION_ID> --file "$CANBAN_RUN_DIR/reply.md"
```

### Inspect or update the current Card (`card show` / `card update`)

Read the current Card summary (uses `CANBAN_CARD` + `CANBAN_PROJECT` automatically, or pass `--card <NUMBER>`):

```sh
"$CANBAN_CLI" card show
# Request task text explicitly when it is not already in the session context.
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
```

Update the Card title or Markdown description only with user-confirmed design decisions or when explicitly requested:

```sh
"$CANBAN_CLI" card update [--title 'Updated title'] --file "$CANBAN_RUN_DIR/card.md"
```

### Adopt a workflow stage (`card adopt`)

In an interactive session on a Card not yet in `develop`, once the user authorizes implementation, adopt `develop` first so the current session takes over without spawning a duplicate scheduled run:

```sh
"$CANBAN_CLI" card adopt --stage develop
```

### Stage local diff review comments (`review draft`)

When reviewing a Card or GitHub PR, write line-specific findings and an overall summary as a **local unpublished review draft** (never publish directly to GitHub) so a human can inspect, edit, or publish them from the local Diff UI:

```sh
"$CANBAN_CLI" review draft --file "$CANBAN_RUN_DIR/review_draft.json"
```

Expected JSON schema for `review_draft.json`:

```json
{
  "summary": "Overall review summary...",
  "verdict": "comment",
  "comments": [
    {
      "path": "crates/scheduler/src/lib.rs",
      "line": 86,
      "side": "RIGHT",
      "snippet": "let _ = self.reconcile_slots();",
      "body": "Explain the issue and suggested fix..."
    }
  ]
}
```

- `verdict`: `"comment"` (default), `"approve"`, or `"request_changes"`.
- `side`: `"RIGHT"` (added or context line on the new file) or `"LEFT"` (deleted line on the old file).
- Use `"$CANBAN_CLI" review clear` to discard the local review draft for the current Card if needed.

## Efficient RPC and CLI use

- RPC and CLI default to compact Agent-facing summaries and mutation receipts.
  `--human` pretty-prints the same JSON; it does not expand content.
- Use `--fields number,title,body,stage,revision` (RPC `fields` array) when task
  text is needed. Use `--full` (RPC `view:"full"`) only for a complete business
  view. Fields/full are mutually exclusive; fields are explicit top-level names.
- Reuse injected task text and existing query data. If the needed fields are
  already known, request them together rather than summary then detail.
- Inventory with `card.list` and a stage filter. Read `items`, follow every
  `next_cursor` to null, and handle `cursor_stale` by restarting and deduplicating
  IDs. The default limit is 50; the maximum is 500. Do not routinely send full
  project lists or snapshots into model context.
- Check discussions with `timeline.list`, `kinds:["comment.created","comment.updated"]`
  and `after_sequence`. Follow next_cursor, then save last_sequence even after
  an empty filtered result. Comment read text appears once as `body`.
- `event.list` instead filters after paging: continue its global cursor to
  highwater even after an empty page. Do not confuse the two cursor contracts.
- Accepted write receipts normally suffice; do not read back full objects just
  to confirm the write. Verify business outcomes or ambiguous/queued results
  specifically. Preserve revision checks on concurrent writes.
- Write long payloads through `call METHOD @params.json`, explicitly set comment
  `mentions:[]` unless dispatch is intended, and reuse a stable request_key when
  retrying. Changing only fields/full does not change the write's identity.
- `canban skill` is the current binary's bundled skill; refresh installed copies
  when upgrading. Old RPC defaults are not a compatibility contract.

## Inspecting State & Calling AppServer RPCs

Inspect overall state or runtime health:

```sh
"$CANBAN_CLI" snapshot
"$CANBAN_CLI" status
"$CANBAN_CLI" --help
```

Call any public AppServer JSON-RPC method via `"$CANBAN_CLI" call <METHOD> '<JSON>'` (or `@/path/to/params.json`):

```sh
# List Projects or Cards
"$CANBAN_CLI" call project.list '{}'
"$CANBAN_CLI" call card.list '{"project_id":"<PROJECT_ID>","stage":"backlog","limit":50}'

# Read a Card, its Timeline events, or Diff preview
"$CANBAN_CLI" call card.get '{"card":<CARD_NUMBER>,"project_id":"<PROJECT_ID>","fields":["number","title","body","stage","revision"]}'
"$CANBAN_CLI" call timeline.list '{"card":<CARD_NUMBER>,"project_id":"<PROJECT_ID>","kinds":["comment.created","comment.updated"],"after_sequence":0,"limit":50}'
"$CANBAN_CLI" call review.preview '{"card":<CARD_NUMBER>,"project_id":"<PROJECT_ID>"}'

# Post a Card comment (supports @profile mentions to schedule another role)
"$CANBAN_CLI" call comment.add '{"card":<CARD_NUMBER>,"project_id":"<PROJECT_ID>","body":"Ready for @reviewer","mentions":["reviewer"],"request_key":"review-request-unique"}'

# Create a follow-up Card in Backlog
"$CANBAN_CLI" call card.create '{"project_id":"<PROJECT_ID>","title":"Follow-up task","body":"Details..."}'

# Inspect the Card's Agent terminals or captured terminal output
"$CANBAN_CLI" call execution.get '{"card":<CARD_NUMBER>,"project_id":"<PROJECT_ID>"}'
"$CANBAN_CLI" call execution.output '{"terminal_id":"<TERMINAL_ID>"}'
```

## Authoring Workflows (CLI)

When asked to inspect or update a Project's or Global (`__global`) Workflow YAML (`workflow.sources` is stored in SQLite, not Git files):

```sh
# Project-scoped workflow collection
"$CANBAN_CLI" workflow sources --project-id <PROJECT_ID>
"$CANBAN_CLI" workflow export --project-id <PROJECT_ID> --name development.yaml --output "$CANBAN_RUN_DIR/development.yaml"
"$CANBAN_CLI" workflow submit --project-id <PROJECT_ID> --revision <REVISION> --file "$CANBAN_RUN_DIR/development.yaml" --check
"$CANBAN_CLI" workflow submit --project-id <PROJECT_ID> --revision <REVISION> --file "$CANBAN_RUN_DIR/development.yaml"

# Global host-level workflow collection (`scope: global`, no Board columns or Cards)
"$CANBAN_CLI" workflow sources --global
"$CANBAN_CLI" workflow export --global --name cleanup.yaml --output "$CANBAN_RUN_DIR/cleanup.yaml"
"$CANBAN_CLI" workflow submit --global --revision <REVISION> --file "$CANBAN_RUN_DIR/cleanup.yaml"
```

## Scheduled Workflows (Cron Tasks)

Workflows support GitHub Actions-style cron triggers (`schema: 9`) across two scopes:
- **`scope: global`** (`project_id: __global`): Host-level schedules without Board columns or `card:` creation rules (ideal for maintenance, cleanup, cross-project checks).
- **`scope: project`** (default): Project-scoped schedules running in either **Cardless Script/Agent mode** or **Card-creating mode** (`card:`).

Missed ticks while Canban was offline or asleep are skipped rather than replayed on wakeup.

### 1. Script-First + On-Failure Agent Escalation (Lazy Admission)

Scheduled workflows starting with `uses: script` (or top-level `run:` shorthand) run with **zero PTY and zero `scheduler.max_agents` slot overhead** when they succeed (`exit 0`). Only when `on_failure` transitions into an `uses: agent` step does Canban allocate a `TerminalEntry` and an Agent slot, handing off the failed step's exit code and stderr/stdout tail in the prompt.

If that recovery Agent calls `"$CANBAN_CLI" report --state blocked --message "..."`, its **live PTY stays open** (never auto-reclaimed) and surfaces in **Activity & Notifications (`⌘I`) → Needs you** so a human can inspect or reply directly in the terminal. Reporting `completed` or `failed` reclaims the PTY after the turn settles.

```yaml
schema: 9
scope: global
id: global:worktree_gc
name: Worktree GC (7d)
on:
  schedule:
    - cron: "0 3 * * *"
      timezone: Local
      overlap: skip          # skip (default) | queue | allow
steps:
  - id: gc
    run: |
      "$CANBAN_CLI" worktree gc --merged-before 7d --fail-on-dirty --env-dirty DIRTY_WORKTREES
    on_failure: ask_agent
    next: finish
  - id: ask_agent
    uses: agent
    with:
      profile: developer
      instruction: |
        Worktree cleanup found dirty or active worktrees ($DIRTY_WORKTREES).
        Inspect the affected paths and call `$CANBAN_CLI report --state blocked --message "..."`
        if human input is required, or clean safe items and report `--state completed`.
    next: finish
  - id: finish
    uses: complete
```

Inside a Cardless scheduled Agent (`CANBAN_SCHEDULE_RUN_ID` is injected, `CANBAN_CARD` is unset; Global runs inject `CANBAN_SCOPE=global`), report your outcome with:

```sh
"$CANBAN_CLI" report \
  --state <completed|blocked|failed|working> \
  --message 'Concise summary of scheduled run' \
  [--file "$CANBAN_RUN_DIR/report.md"]
```

### 2. Card-Creating Mode (`scope: project` with `card:`)

Creates a Card on each trigger with `schedule_source` provenance (`Scheduled · <Workflow> #<run_number>` badge on Board and Card Detail) and runs the workflow's step graph against that Card so execution logs, reports, and diffs attach to its Timeline:

```yaml
schema: 9
id: nightly_qa:example
name: Nightly QA
on:
  nightly:
    cron: "30 3 * * 1-5"
    timezone: UTC
    overlap: skip
    start_at: run_qa
    card:
      column: develop
      title: "Nightly QA ({{date}} #{{run_number}})"
      body: "Automated scheduled check for {{workflow}} ({{datetime}})."
steps:
  - id: run_qa
    uses: agent
    with:
      profile: developer
      instruction: Run full integration suite and fix or report regressions.
    next: finish
  - id: finish
    uses: complete
```

Supported placeholders in `card.title` / `card.body`: `{{date}}`, `{{datetime}}`, `{{run_number}}`, `{{workflow}}`, `{{rule}}`. Supported `timezone` values: `Local` (default), `UTC`, fixed offsets (`+08:00`), or standard IANA names (`Asia/Shanghai`, `America/New_York`, `Europe/London`, `Asia/Tokyo`, etc.).

### 3. Operating Schedules & Worktree GC via CLI

```sh
# List schedules and recent runs (all scopes, --global, or --project-id)
"$CANBAN_CLI" schedule list
"$CANBAN_CLI" schedule list --global
"$CANBAN_CLI" schedule runs --global [--schedule-id <SCHEDULE_ID>] [--limit 20]

# Create a Global or Project scheduled workflow directly
"$CANBAN_CLI" schedule create --global --name "Worktree GC" --cron "0 3 * * *" \
  --mode script_agent --script '"$CANBAN_CLI" worktree gc --merged-before 7d --fail-on-dirty --env-dirty DIRTY_WORKTREES' \
  --profile-id developer --instruction "Inspect dirty worktrees and ask the user with --state blocked if needed."

# Manually trigger ("Run now"), toggle, or delete a schedule
"$CANBAN_CLI" schedule trigger --schedule-id <SCHEDULE_ID>
"$CANBAN_CLI" schedule toggle --schedule-id <SCHEDULE_ID> --off
"$CANBAN_CLI" schedule toggle --schedule-id <SCHEDULE_ID> --on
"$CANBAN_CLI" schedule delete --schedule-id <SCHEDULE_ID>

# Read a finished Cardless run's script log or report
"$CANBAN_CLI" schedule artifact --schedule-run-id <RUN_ID> --path <REPORT_OR_OUTPUT_PATH>

# Garbage-collect merged clean worktrees older than a retention window
"$CANBAN_CLI" worktree gc --merged-before 7d [--project-id <PROJECT_ID>] [--dry-run] [--fail-on-dirty] [--env-dirty DIRTY_WORKTREES]
```

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.