Docs
Overview
Last Light ships with seven default workflows. Each is a YAML file in
workflows/ that the runner executes phase-by-phase. The harness
itself knows nothing about "build" or "triage" specifically — it just runs
whatever phases a workflow declares.
Workflows fall into three categories based on complexity:
Multi-phase workflows
These run multiple agent sessions in sequence, often with loops and approval gates. Each phase runs in an isolated Docker sandbox with a shared workspace so files persist between phases.
Full Architect → Executor → Reviewer cycle. Plans, implements, reviews, and opens a PR.
Socratic Q&A loop that shapes half-formed ideas into detailed specs through conversation.
Single-phase workflows
Each runs one focused agent session — fast, cheap, and targeted.
Classifies, labels, and responds to new or reopened issues.
Conversational reply when a maintainer comments without requesting a build.
Reads a PR diff and posts structured feedback. Read-only — no code modifications.
Lightweight fix-and-push — no architect or reviewer, just fix the issue and push.
Weekly health report — open/stale issues, PR velocity, action items.
Direct chat
Not a YAML workflow — Slack messages that don't match any of the above intents are handled by the chat skill, which runs the Claude Agent SDK directly in the harness process (no Docker sandbox) for low-latency replies. Each Slack thread maps to one persistent Agent SDK session, so the conversation maintains context across messages.
The LLM classifier routes messages to chat when the intent is conversational — questions, discussion, status checks, and anything that isn't explicitly a build, explore, triage, review, or approval.
How workflows are triggered
| Trigger | Workflows | How it works |
|---|---|---|
| GitHub webhook | issue-triage, pr-review, build, pr-fix, issue-comment | GitHub App sends events to the harness. The router + LLM classifier decides which workflow to run. |
| Slack message | explore, build, triage, review, all others via chat | Natural language in DMs or threads. The classifier extracts intent and repo from the message. |
| Cron schedule | issue-triage, pr-review, repo-health | Periodic scans. Triage and review crons are fallbacks when webhooks aren't configured. |
| CLI | All | npm run cli -- build owner/repo#N or npm run cli -- health owner/repo |
| Dashboard | All (via approval resume) | Approve/reject buttons on paused workflows in the admin dashboard. |
Permission profiles
Each workflow runs in a Docker sandbox with a scoped GitHub token. The permission profile determines what the agent can do:
| Profile | Workflows | Permissions |
|---|---|---|
| repo-write | build, pr-fix | Full read/write — can push commits, create branches, open PRs |
| review-write | pr-review | Can post review comments but not push code |
| issues-write | issue-triage, issue-comment, explore | Can read code, create/edit issues, post comments |
| read | repo-health | Read-only access to repo contents and metadata |