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 an
in-process @earendil-works/pi-ai chat loop (no sandbox spawn)
for low-latency replies. Each Slack thread maps to one persistent pi-ai
conversation, rehydrated from the messaging_messages SQLite
table on every turn, so context holds 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 |