@slaw-ai/server 2026.611.0

package/skills/slaw/scripts/slaw-upload-artifact.sh

@@ -0,0 +1,371 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  slaw-upload-artifact.sh FILE [options]
+
+Uploads a generated file from the current workspace to the current Slaw
+issue, then creates an attachment-backed artifact work product by default.
+
+Required environment for live uploads:
+  SLAW_API_URL, SLAW_API_KEY, SLAW_SQUAD_ID, SLAW_TASK_ID, SLAW_RUN_ID
+
+Options:
+  --issue-id ID          Issue id to attach to (default: SLAW_TASK_ID)
+  --squad-id ID        Squad id (default: SLAW_SQUAD_ID)
+  --title TEXT           Work product title (default: file basename)
+  --summary TEXT         Work product summary
+  --content-type TYPE    Override detected upload content type
+  --status STATUS        Work product status (default: ready_for_review)
+  --no-work-product      Only upload the issue attachment
+  --no-primary           Do not mark the artifact work product primary for its type
+  --output FORMAT        markdown or json (default: markdown)
+  --dry-run              Print resolved upload settings without calling the API
+  --help, -h             Show this help
+
+Examples:
+  scripts/slaw-upload-artifact.sh dist/demo.mp4 \
+    --title "Demo video render" \
+    --summary "MP4 render for board review"
+
+  scripts/slaw-upload-artifact.sh out/walkthrough.webm \
+    --title "Walkthrough video" \
+    --content-type video/webm
+EOF
+}
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    printf 'Missing required command: %s\n' "$1" >&2
+    exit 1
+  fi
+}
+
+json_bool() {
+  if [[ "${1:-0}" == "1" ]]; then
+    printf 'true'
+  else
+    printf 'false'
+  fi
+}
+
+detect_content_type() {
+  local path="$1"
+  local lower
+  lower="$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')"
+
+  case "$lower" in
+    *.mp4|*.m4v) printf 'video/mp4' ;;
+    *.webm) printf 'video/webm' ;;
+    *.mov|*.qt) printf 'video/quicktime' ;;
+    *.png) printf 'image/png' ;;
+    *.jpg|*.jpeg) printf 'image/jpeg' ;;
+    *.gif) printf 'image/gif' ;;
+    *.webp) printf 'image/webp' ;;
+    *.svg) printf 'image/svg+xml' ;;
+    *.pdf) printf 'application/pdf' ;;
+    *.txt|*.log) printf 'text/plain' ;;
+    *.md|*.markdown) printf 'text/markdown' ;;
+    *.json) printf 'application/json' ;;
+    *.csv) printf 'text/csv' ;;
+    *.html|*.htm) printf 'text/html' ;;
+    *.zip) printf 'application/zip' ;;
+    *)
+      if command -v file >/dev/null 2>&1; then
+        file --brief --mime-type "$path"
+      else
+        printf 'application/octet-stream'
+      fi
+      ;;
+  esac
+}
+
+request_json() {
+  local method="$1"
+  local url="$2"
+  local body="${3:-}"
+  local response_file
+  local status_code
+
+  response_file="$(mktemp)"
+  if [[ -n "$body" ]]; then
+    status_code="$(
+      curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
+        "$url" \
+        -H "Authorization: Bearer $SLAW_API_KEY" \
+        -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+        -H 'Content-Type: application/json' \
+        --data-binary "$body"
+    )"
+  else
+    status_code="$(
+      curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
+        "$url" \
+        -H "Authorization: Bearer $SLAW_API_KEY" \
+        -H "X-Slaw-Run-Id: $SLAW_RUN_ID"
+    )"
+  fi
+
+  if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
+    printf 'Request failed (%s): %s\n' "$status_code" "$url" >&2
+    cat "$response_file" >&2
+    printf '\n' >&2
+    rm -f "$response_file"
+    exit 1
+  fi
+
+  cat "$response_file"
+  rm -f "$response_file"
+}
+
+upload_file() {
+  local url="$1"
+  local path="$2"
+  local content_type="$3"
+  local escaped_path
+  local response_file
+  local status_code
+
+  escaped_path="${path//\\/\\\\}"
+  escaped_path="${escaped_path//\"/\\\"}"
+  response_file="$(mktemp)"
+  status_code="$(
+    curl -sS -X POST -w '%{http_code}' -o "$response_file" \
+      "$url" \
+      -H "Authorization: Bearer $SLAW_API_KEY" \
+      -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+      -F "file=@\"${escaped_path}\";type=${content_type}"
+  )"
+
+  if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
+    printf 'Upload failed (%s): %s\n' "$status_code" "$url" >&2
+    cat "$response_file" >&2
+    printf '\n' >&2
+    rm -f "$response_file"
+    exit 1
+  fi
+
+  cat "$response_file"
+  rm -f "$response_file"
+}
+
+file_path=""
+issue_id="${SLAW_TASK_ID:-}"
+squad_id="${SLAW_SQUAD_ID:-}"
+title=""
+summary=""
+content_type=""
+status="ready_for_review"
+create_work_product=1
+is_primary=1
+output_format="markdown"
+dry_run=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --issue-id)
+      issue_id="${2:-}"
+      shift 2
+      ;;
+    --squad-id)
+      squad_id="${2:-}"
+      shift 2
+      ;;
+    --title)
+      title="${2:-}"
+      shift 2
+      ;;
+    --summary)
+      summary="${2:-}"
+      shift 2
+      ;;
+    --content-type)
+      content_type="${2:-}"
+      shift 2
+      ;;
+    --status)
+      status="${2:-}"
+      shift 2
+      ;;
+    --no-work-product)
+      create_work_product=0
+      shift
+      ;;
+    --no-primary)
+      is_primary=0
+      shift
+      ;;
+    --output)
+      output_format="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --*)
+      printf 'Unknown argument: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      if [[ -n "$file_path" ]]; then
+        printf 'Unexpected positional argument: %s\n' "$1" >&2
+        usage >&2
+        exit 1
+      fi
+      file_path="$1"
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$file_path" ]]; then
+  printf 'Missing file path.\n' >&2
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$file_path" ]]; then
+  printf 'Artifact file does not exist: %s\n' "$file_path" >&2
+  exit 1
+fi
+
+if [[ "$output_format" != "markdown" && "$output_format" != "json" ]]; then
+  printf 'Unsupported output format: %s\n' "$output_format" >&2
+  exit 1
+fi
+
+require_command curl
+require_command jq
+
+if [[ -z "$title" ]]; then
+  title="$(basename "$file_path")"
+fi
+
+if [[ -z "$content_type" ]]; then
+  content_type="$(detect_content_type "$file_path")"
+fi
+
+if [[ "$dry_run" == "1" ]]; then
+  create_work_product_json="$(json_bool "$create_work_product")"
+  is_primary_json="$(json_bool "$is_primary")"
+  jq -n \
+    --arg file "$file_path" \
+    --arg issueId "$issue_id" \
+    --arg squadId "$squad_id" \
+    --arg title "$title" \
+    --arg summary "$summary" \
+    --arg contentType "$content_type" \
+    --arg status "$status" \
+    --argjson createWorkProduct "$create_work_product_json" \
+    --argjson isPrimary "$is_primary_json" \
+    '{file: $file, issueId: $issueId, squadId: $squadId, title: $title, summary: $summary, contentType: $contentType, status: $status, createWorkProduct: $createWorkProduct, isPrimary: $isPrimary}'
+  exit 0
+fi
+
+if [[ -z "${SLAW_API_URL:-}" || -z "${SLAW_API_KEY:-}" || -z "${SLAW_RUN_ID:-}" ]]; then
+  printf 'Missing SLAW_API_URL, SLAW_API_KEY, or SLAW_RUN_ID.\n' >&2
+  exit 1
+fi
+
+if [[ -z "$issue_id" || -z "$squad_id" ]]; then
+  printf 'Missing issue or squad id. Pass --issue-id/--squad-id or set SLAW_TASK_ID/SLAW_SQUAD_ID.\n' >&2
+  exit 1
+fi
+
+api_base="${SLAW_API_URL%/}/api"
+attachment="$(
+  upload_file \
+    "$api_base/squads/$squad_id/issues/$issue_id/attachments" \
+    "$file_path" \
+    "$content_type"
+)"
+
+work_product="null"
+if [[ "$create_work_product" == "1" ]]; then
+  is_primary_json="$(json_bool "$is_primary")"
+  attachment_id="$(jq -r '.id // empty' <<<"$attachment")"
+  byte_size="$(jq -r '.byteSize // 0' <<<"$attachment")"
+  content_path="$(jq -r '.contentPath // empty' <<<"$attachment")"
+  open_path="$(jq -r '.openPath // .contentPath // empty' <<<"$attachment")"
+  download_path="$(jq -r '.downloadPath // (if .contentPath then (.contentPath + "?download=1") else "" end)' <<<"$attachment")"
+  original_filename="$(jq -r '.originalFilename // empty' <<<"$attachment")"
+
+  if [[ -z "$attachment_id" || -z "$content_path" || -z "$download_path" ]]; then
+    printf 'Upload response did not include attachment path metadata.\n' >&2
+    printf '%s\n' "$attachment" >&2
+    exit 1
+  fi
+
+  work_product_payload="$(
+    jq -nc \
+      --arg title "$title" \
+      --arg summary "$summary" \
+      --arg status "$status" \
+      --arg runId "$SLAW_RUN_ID" \
+      --arg attachmentId "$attachment_id" \
+      --arg contentType "$content_type" \
+      --argjson byteSize "$byte_size" \
+      --arg contentPath "$content_path" \
+      --arg openPath "$open_path" \
+      --arg downloadPath "$download_path" \
+      --arg originalFilename "$original_filename" \
+      --argjson isPrimary "$is_primary_json" \
+      '{
+        type: "artifact",
+        provider: "slaw",
+        title: $title,
+        status: $status,
+        reviewState: "none",
+        isPrimary: $isPrimary,
+        healthStatus: "unknown",
+        summary: (if $summary == "" then null else $summary end),
+        createdByRunId: $runId,
+        metadata: {
+          attachmentId: $attachmentId,
+          contentType: $contentType,
+          byteSize: $byteSize,
+          contentPath: $contentPath,
+          openPath: $openPath,
+          downloadPath: $downloadPath,
+          originalFilename: (if $originalFilename == "" then null else $originalFilename end)
+        }
+      }'
+  )"
+
+  work_product="$(
+    request_json \
+      POST \
+      "$api_base/issues/$issue_id/work-products" \
+      "$work_product_payload"
+  )"
+fi
+
+if [[ "$output_format" == "json" ]]; then
+  jq -n --argjson attachment "$attachment" --argjson workProduct "$work_product" \
+    '{attachment: $attachment, workProduct: $workProduct}'
+  exit 0
+fi
+
+content_path="$(jq -r '.contentPath // empty' <<<"$attachment")"
+download_path="$(jq -r '.downloadPath // (if .contentPath then (.contentPath + "?download=1") else "" end)' <<<"$attachment")"
+attachment_id="$(jq -r '.id // empty' <<<"$attachment")"
+work_product_id="$(jq -r '.id // empty' <<<"$work_product")"
+
+printf 'Uploaded artifact\n\n'
+printf -- '- Attachment: [%s](%s)\n' "$title" "$content_path"
+printf -- '- Download: [%s](%s)\n' "$title" "$download_path"
+printf -- '- Attachment ID: `%s`\n' "$attachment_id"
+if [[ -n "$work_product_id" ]]; then
+  printf -- '- Work product ID: `%s`\n' "$work_product_id"
+fi
+printf '\nFinal comment snippet:\n\n'
+printf -- '- Artifact: [%s](%s)\n' "$title" "$content_path"

package/skills/slaw-converting-plans-to-tasks/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: slaw-converting-plans-to-tasks
+description: >
+  The Slaw way of converting a plan into executable tasks. Use whenever
+  you are asked to plan, scope, or break down work inside a Slaw squad.
+  Industry-agnostic guidance on how to translate a plan into assigned issues
+  with the right specialty, dependencies, and parallelization so Slaw's
+  executor can pick up the work — it does not prescribe a plan format. Pair
+  with the `slaw` skill, which covers the mechanics of writing the plan
+  document and reassigning the issue.
+---
+
+# Slaw — Converting Plans to Tasks
+
+A companion skill for turning a plan into executable Slaw work. It does **not** dictate a plan structure — bring whatever format fits the work and the user's preference. It tells you _how_ to translate that plan into issues so that the rest of Slaw works for you.
+
+For the **mechanics** of recording a plan (issue document with key `plan`, comment links, approval gating, who to reassign back to), follow the _Planning_ section of the `slaw` skill. This skill covers planning method, not the API surface.
+
+## When you're asked to plan
+
+- **Plan deeply.** Capture as much real detail as you have: goals, constraints, unknowns, success criteria, risks. A shallow plan becomes rework downstream — assignees can only act on what they can read.
+- **Know your team.** Before assigning anything, look up the squad's agents and their specialties (reporting lines, role descriptions, prior work). Don't default work to yourself when a better-suited agent exists; don't assign to a name you haven't checked.
+- **Assign for specialty.** Hand each piece of work to the agent most relevant to it. If no one fits, call that out — a hire, a tool, an external dependency, a board decision — instead of papering over the gap.
+- **Take responsibility.** Specialty-matching cuts both ways: when _you_ are the best-suited agent for a piece of work, assign it to yourself instead of reflexively delegating. Don't hand off to avoid load.
+- **Use the dependency tree.** Slaw's executor automatically starts any assigned task with no open blockers. Express every concrete deliverable as an issue, and wire real blockers via `blockedByIssueIds` (not prose like "blocked by X"). When `done`, dependents auto-wake.
+- **Order, then parallelize.** Sequence work by real dependencies, not by personal preference. Independent branches of the graph should start in parallel. Unlike humans, most agents allow concurrent runs, so you can assign parallel work to the same agent.
+- **Enough is enough.** Plans exist to unblock execution, not replace it. If the next step is small and clear, just do it or allow the plan to stand on its own. Re-planning a plan, or splitting work that one agent could finish in the time it took to break it up, is procrastination — ship something.
+
+## Quick checklist before you publish a plan
+
+- [ ] Enough detail that assignees can act without re-asking.
+- [ ] Every concrete deliverable is an issue (or named as a known follow-up).
+- [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default.
+- [ ] Each issue's real blockers are declared via `blockedByIssueIds`.
+- [ ] Independent branches can start in parallel.
+- [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.
+
+## What this skill is not
+
+- Not a plan template. Use any format — prose, outline, table, RACI, Gantt, whatever fits.
+- Not software-development–specific. The same rules apply to marketing, research, ops, design, hiring, finance, etc.
+- Not a replacement for the `slaw` skill's planning mechanics. Use both.

package/skills/slaw-create-agent/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: slaw-create-agent
+description: >
+  Create new agents in Slaw with governance-aware hiring. Use when you need
+  to inspect adapter configuration options, compare existing agent configs,
+  draft a new agent prompt/config, and submit a hire request.
+---
+
+# Slaw Create Agent Skill
+
+Use this skill when you are asked to hire/create an agent.
+
+## Preconditions
+
+You need either:
+
+- operator access, or
+- agent permission `can_create_agents=true` in your squad
+
+If you do not have this permission, escalate to your Squad Lead or operator.
+
+## Workflow
+
+### 1. Confirm identity and squad context
+
+```sh
+curl -sS "$SLAW_API_URL/api/agents/me" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+### 2. Discover adapter configuration for this Slaw instance
+
+```sh
+curl -sS "$SLAW_API_URL/llms/agent-configuration.txt" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+# Then the specific adapter you plan to use, e.g. claude_local:
+curl -sS "$SLAW_API_URL/llms/agent-configuration/claude_local.txt" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+### 3. Compare existing agent configurations
+
+```sh
+curl -sS "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/agent-configurations" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+Note naming, icon, reporting-line, and adapter conventions the squad already follows.
+
+### 4. Choose the instruction source (required)
+
+This is the single most important decision for hire quality. Pick exactly one path:
+
+- **Exact template** — the role matches an entry in the template index. Use the matching file under `references/agents/` as the starting point.
+- **Adjacent template** — no exact match, but an existing template is close (for example, a "Backend Engineer" hire adapted from `coder.md`, or a "Content Designer" adapted from `uxdesigner.md`). Copy the closest template and adapt deliberately: rename the role, rewrite the role charter, swap domain lenses, and remove sections that do not fit.
+- **Generic fallback** — no template is close. Use the baseline role guide to construct a new `AGENTS.md` from scratch, filling in each recommended section for the specific role.
+
+Template index and when-to-use guidance:
+`skills/slaw-create-agent/references/agent-instruction-templates.md`
+
+Generic fallback for no-template hires:
+`skills/slaw-create-agent/references/baseline-role-guide.md`
+
+State which path you took in your hire-request comment so the operator can see the reasoning.
+
+### 5. Discover allowed agent icons
+
+```sh
+curl -sS "$SLAW_API_URL/llms/agent-icons.txt" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+### 6. Draft the new hire config
+
+- role / title / name
+- icon (required in practice; pick from `/llms/agent-icons.txt`)
+- reporting line (`reportsTo`)
+- adapter type
+- `desiredSkills` from the squad skill library when this role needs installed skills on day one
+- if any `desiredSkills` or adapter settings expand browser access, external-system reach, filesystem scope, or secret-handling capability, justify each one in the hire comment
+- adapter and runtime config aligned to this environment
+- leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
+- if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
+- capabilities
+- managed instructions bundle (`AGENTS.md`) for adapters that support it; avoid durable `promptTemplate` config
+- for coding or execution agents, include the Slaw execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and squad boundaries
+- instruction text such as `AGENTS.md` built from step 4; for local managed-bundle adapters, send this as top-level `instructionsBundle.files["AGENTS.md"]`. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
+- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
+
+### 7. Review the draft against the quality checklist
+
+Before submitting, walk the draft-review checklist end-to-end and fix any item that does not pass:
+`skills/slaw-create-agent/references/draft-review-checklist.md`
+
+### 8. Submit hire request
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/agent-hires" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Engineering Lead",
+    "role": "engineering_lead",
+    "title": "Engineering Lead",
+    "icon": "crown",
+    "reportsTo": "<squad_lead-agent-id>",
+    "capabilities": "Owns technical roadmap, architecture, staffing, execution",
+    "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+    "adapterType": "codex_local",
+    "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+    "instructionsBundle": {"files": {"AGENTS.md": "You are the Engineering Lead..."}},
+    "runtimeConfig": {"heartbeat": {"enabled": false, "wakeOnDemand": true}},
+    "sourceIssueId": "<issue-id>"
+  }'
+```
+
+### 9. Handle governance state
+
+- if the response has `approval`, the hire is `pending_approval`
+- monitor and discuss on the approval thread
+- when the operator approves, you will be woken with `SLAW_APPROVAL_ID`; read linked issues and close/comment follow-up
+
+```sh
+curl -sS "$SLAW_API_URL/api/approvals/<approval-id>" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+curl -sS -X POST "$SLAW_API_URL/api/approvals/<approval-id>/comments" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"body":"## Engineering Lead hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-ref>](/agents/<agent-url-key-or-id>)\n- Source issue: [<issue-ref>](/issues/<issue-identifier-or-id>)\n\nUpdated prompt and adapter config per operator feedback."}'
+```
+
+If the approval already exists and needs manual linking to the issue:
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/issues/<issue-id>/approvals" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"approvalId":"<approval-id>"}'
+```
+
+After approval is granted, run this follow-up loop:
+
+```sh
+curl -sS "$SLAW_API_URL/api/approvals/$SLAW_APPROVAL_ID" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+curl -sS "$SLAW_API_URL/api/approvals/$SLAW_APPROVAL_ID/issues" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+For each linked issue, either:
+- close it if the approval resolved the request, or
+- comment in markdown with links to the approval and next actions.
+
+## References
+
+- Template index and how to apply a template: `skills/slaw-create-agent/references/agent-instruction-templates.md`
+- Individual role templates: `skills/slaw-create-agent/references/agents/`
+- Generic baseline role guide (no-template fallback): `skills/slaw-create-agent/references/baseline-role-guide.md`
+- Pre-submit draft-review checklist: `skills/slaw-create-agent/references/draft-review-checklist.md`
+- Endpoint payload shapes and full examples: `skills/slaw-create-agent/references/api-reference.md`