Docs

Build

The build workflow is Last Light's most complex workflow. It runs a full software development cycle: check prerequisites, plan the implementation, write the code, review it independently, fix any issues, and open a pull request. Every step runs in an isolated Docker sandbox with a scoped GitHub token.

Permission profile: repo-write — the agent can push commits, create branches, and open pull requests.

Pipeline

Context phase_0 Guardrails READY / BLOCKED Architect approval gate Executor TDD implement Reviewer loop (max 2) PR open pull request REQUEST_CHANGES

Phases

1. Guardrails

Pre-flight check that verifies the repo has foundational tooling: a test framework, linter, and type checker. Outputs READY or BLOCKED. If blocked, the workflow stops unless the issue has a lastlight:bootstrap label (used for issues that set up the missing tooling).

2. Architect

Clones the repo, reads the issue context, and produces a detailed implementation plan at .lastlight/issue-N/architect-plan.md. Includes problem statement, files to modify with line numbers, and a step-by-step approach.

If the post_architect approval gate is enabled, the workflow pauses here until a maintainer comments @last-light approve or approves via the dashboard.

3. Executor

Implements the architect's plan using TDD: writes failing tests first, then implements until tests pass. Runs the full guardrails suite (test, lint, typecheck) before committing. Pushes to the workflow's branch.

4. Reviewer

Independent code review with no shared context from the executor. Reads only the diff and the plan. Outputs a verdict: APPROVED or REQUEST_CHANGES.

On REQUEST_CHANGES, the runner enters a fix loop: the executor addresses the feedback, then the reviewer re-reviews. This repeats up to 2 cycles. The post_reviewer approval gate can pause before each fix cycle.

5. PR

Creates a pull request from the workflow branch to main. The PR body includes the architect's plan, the reviewer's verdict, and links to the issue.

Triggers

  • GitHub comment: @last-light build this on an issue (classifier detects BUILD intent)
  • Slack: build cliftonc/repo#42
  • CLI: npm run cli -- build owner/repo#N

Model configuration

Each phase can use a different model via the CLAUDE_MODELS env var. Common setup: Opus for architect (planning quality), Sonnet for executor and reviewer (speed), Haiku for guardrails (cost). 

CLAUDE_MODELS='{"architect":"claude-opus-4-6","guardrails":"claude-haiku-4-5-20251001"}'